class Image extends Object
Captures, loads, creates, draws, transforms, searches and saves images across platforms.
This class is exported by the KS module.
Note: This class is experimental: it and its nested types may change or be removed without deprecation. See #Warn Experimental.
Picture := Image(Source)
Creates an image from a file path, another Image or a native bitmap handle.
Picture := Image.Create(Width, Height , Background, Scale)
Creates an ARGB canvas. If Background is omitted or blank, the canvas is fully transparent. Scale optionally sets the drawing scale.
Picture := Image.FromBuffer(Data, Width, Height , BytesPerPixel := 4)
Creates an image from tightly packed pixel bytes. One byte per pixel represents 8-bit grayscale; four bytes represent RGBA. This is the inverse of GetPixelData.
Picture := Image.FromFile(Path , Width, Height, IconNumber)
Loads an image from a file. Optional dimensions resize the loaded image; IconNumber selects an icon resource where applicable.
Picture := Image.FromBitmap(Handle)
Copies an image from a native bitmap handle.
Picture := Image.FromClipboard()
Copies the image currently held by the clipboard. Returns an empty string if the clipboard contains no image. This is an alias of the Clipboard.Image getter; to put an image on the clipboard, assign to that property.
Picture := Image.FromDesktop()
Captures the whole virtual desktop.
Note: On Linux, screen and window capture factories require keysharp-desktop, the ScreenCapture grant and a backend which supports the requested capture. See Linux Platform Support.
Picture := Image.FromMonitor(MonitorNumber)
Captures one monitor.
Picture := Image.FromRect(X, Y, Width, Height)
Captures a screen rectangle in absolute screen coordinates. Pixel CoordMode does not affect these coordinates.
Picture := Image.FromWindow(WinTitle , Options, WinText, ExcludeTitle, ExcludeText)
Captures the matching window. The included decorations and ability to capture an occluded window depend on the backend. On X11 without the Composite extension, an occluded window may not be captured correctly. For window capture on each Wayland desktop, see Linux Platform Support.
Options can be a mode string or an object with a Mode property, such as {Mode: "FullContent", Decorations: true}. Omitting Options or Mode selects "FullContent". Mode names are case-insensitive; any other value, including an empty string, throws ValueError.
| Mode | Windows capture technique |
|---|---|
"BitBlt" | Copies the window pixels using BitBlt. |
"BitBltOpaque" | Temporarily turns off window transparency, then uses BitBlt. |
"PrintWindow" | Asks the window to draw itself using PrintWindow. |
"PrintWindowOpaque" | Temporarily turns off window transparency, then uses PrintWindow. |
"FullContent" | Uses PrintWindow with PW_RENDERFULLCONTENT for hardware-accelerated windows. This is the default. |
On Linux and macOS, the mode is validated but ignored. {Decorations: false}, the default, requests client-area-only capture on a platform which can honor it, such as KWin. Other platforms ignore this property.
A color can be a name such as "Red", an opaque 0xRRGGBB value, or a 0xAARRGGBB value with alpha. To preserve a fully transparent 00 alpha, pass an eight-digit string or the color name "Transparent"; a numeric 0x00RRGGBB is indistinguishable from an opaque RGB value. A string which is neither a color name nor a number, and a NaN or infinite number, raises a ValueError when the method is called.
Fonts use the same two arguments as Gui.SetFont: an Options string of sSize plus optional bold, italic, underline, strike, norm, wWeight or qQuality tokens (such as "s16 bold italic"), and a separate FontName. The options are checked when DrawText or MeasureText is called, and an unrecognized option throws ValueError; pass the text color as DrawText's Color parameter, not a c option. A size is in points at 96 DPI, whatever resolution the image carries, so text drawn on a loaded or copied image has the size MeasureText reports.
Options can also be a Font object. An explicit FontName overrides the object's Name; FontName itself does not accept a Font object. DrawText uses the object's opaque Color when its separate Color argument is omitted. Sizes must be finite and greater than zero. Weights are approximated to normal below 700 and bold from 700 upward. Rendering quality is supported on Windows as described by Font.Quality; non-default quality on other platforms raises Error.
Brush := Image.Brush.LinearGradient(X1, Y1, X2, Y2, StartColor, EndColor)
Creates an immutable linear-gradient brush. Color changes along the vector from the first point to the second and is padded with the nearest endpoint color beyond it. The two points must differ.
Brush := Image.Brush.RadialGradient(CenterX, CenterY, RadiusX, RadiusY, CenterColor, EdgeColor)
Creates an immutable radial-gradient brush centered on an ellipse. Both radii must be positive. The edge color is padded beyond the ellipse. Gradient coordinates are logical drawing coordinates and follow the complete drawing transform with the geometry.
Path := Image.Path(FillRule := "EvenOdd")
Creates reusable vector geometry. FillRule is "EvenOdd" or "NonZero", case-insensitively, and controls filling and clipping. Path methods are chainable.
| Method | Effect |
|---|---|
MoveTo(X, Y) | Starts a figure. |
LineTo(X, Y) | Adds a line to the active figure. |
CubicTo(ControlX1, ControlY1, ControlX2, ControlY2, X, Y) | Adds a cubic Bézier curve. |
ArcTo(X, Y, Width, Height, StartAngle, SweepAngle) | Adds an elliptical arc, connecting it to the active figure when necessary. Angles are degrees from the ellipse's rightmost point and positive angles run clockwise. |
Close() | Closes and ends the active figure. |
AddRect(X, Y, Width, Height) | Adds a closed rectangle. |
AddRoundRect(X, Y, Width, Height, Radius) | Adds a closed rounded rectangle; Radius is clamped to the available range. |
AddEllipse(X, Y, Width, Height) | Adds a closed ellipse. |
AddPolygon(Points) | Adds a closed polygon from an Array of {X, Y} objects. Coordinates are copied when called. |
AddPath(OtherPath [, Transform]) | Copies another path, optionally through a Transform object. |
Clear() | Removes all geometry while retaining the fill rule. |
Clone() | Returns independently mutable geometry with the same fill rule and active figure. |
LineTo and CubicTo require an active figure. Filling and clipping implicitly close open figures, while stroking closes only a figure ended with Close(). Non-positive helper dimensions and a zero-sweep arc add nothing. A non-empty polygon needs at least three points.
Transform for AddPath has the form {ScaleX, ScaleY, OffsetX, OffsetY, SkewX, SkewY}. Omitted properties use the identity values 1, 1, 0, 0, 0, 0. The source path and descriptor are captured when AddPath is called.
Drawing methods are chainable and are applied lazily.
| Method | Effect |
|---|---|
Clear([Color]) | Clears the canvas, optionally to a color. |
DrawLine(X1, Y1, X2, Y2 [, Color, Thickness]) | Draws a line. |
DrawRect(X, Y, Width, Height [, Color, Thickness]) | Draws a rectangle outline. |
FillRect(X, Y, Width, Height [, Color]) | Fills a rectangle. |
DrawRoundRect(X, Y, Width, Height, Radius [, Color, Thickness]) | Draws a rounded-rectangle outline. |
FillRoundRect(X, Y, Width, Height, Radius [, Color]) | Fills a rounded rectangle. |
DrawEllipse(X, Y, Width, Height [, Color, Thickness]) | Draws an ellipse outline. |
FillEllipse(X, Y, Width, Height [, Color]) | Fills an ellipse. |
DrawPath(Path [, Color, Thickness]) | Strokes a path with a solid color or gradient Brush. Strokes are centered with flat caps and miter joins. |
FillPath(Path [, Color]) | Fills a path with a solid color or gradient Brush. |
DrawText(Text, X, Y [, Color, Options, FontName]) | Draws text using the font convention above. Color can also be a gradient Brush. |
DrawImage(Picture [, X, Y, Width, Height]) | Draws another image, optionally at the supplied position and size. |
MeasureText(Text [, Options, FontName]) | Returns a {Width, Height} object with the size the text would occupy when drawn. |
Matrix := Picture.Transform
Picture.Transform := {ScaleX: 1, ScaleY: 1, OffsetX: 0, OffsetY: 0, SkewX: 0, SkewY: 0}
Controls the affine coordinate system used by drawing. The getter returns a detached object containing all six coefficients. Assignment changes only supplied own data properties, so Picture.Transform := {OffsetX: 20} preserves the other five.
TransformedX = ScaleX * X + SkewX * Y + OffsetX TransformedY = SkewY * X + ScaleY * Y + OffsetY
The complete matrix must remain finite and nonsingular. Assign all six identity values shown above to reset it.
Picture.Clip(Path) Picture.Clip()
Intersects the current clip with Path, captured through the current Transform. Later transform changes do not move an existing clip. Calling Clip with no argument resets clipping; clipping with an empty Path instead produces an empty clip.
State := Picture.SaveState() Picture.RestoreState(State)
SaveState captures Transform and Clip. RestoreState restores that snapshot, which can be reused but belongs only to the Image which created it.
Path, shape, text and DrawImage methods capture drawing state when called. Clear ignores drawing state and clears the whole bitmap without resetting it. MeasureText, pixel access, search and the raster operations below use untransformed coordinates.
Note: Vector rendering is unverified on Linux and macOS.
Transform methods queue a lazy operation and return the Image so calls can be chained.
| Method | Effect |
|---|---|
Scale(Factor [, FactorY]) | Scales proportionally, or independently by axis. |
Resize(Width, Height) | Resizes to absolute dimensions. Make either one dimension negative to preserve aspect ratio from the other. |
Rotate(Angle [, Background]) | Rotates by degrees. |
Flip([Horizontal]) | Flips the image. |
Crop(X, Y, Width, Height) | Crops to a rectangle. |
Grayscale() | Converts color to grayscale: each pixel's red, green and blue become Round(0.299 * R + 0.587 * G + 0.114 * B), with a half rounded up, and its alpha is kept. |
Alpha(Factor) | Multiplies each pixel's alpha by a value clamped to 0 through 1. |
Brightness(Amount) | Adjusts brightness by a value clamped to -1 through 1. |
Contrast(Amount) | Adjusts contrast by a value clamped to -1 through 1. |
| Method | Effect |
|---|---|
Copy() | Returns an independent copy. |
Save(Filename) | Applies pending operations and writes the image to a file. |
ToBitmap() | Applies pending operations and returns a native bitmap handle, which on Windows keeps the image's transparency. |
ToClr() | Applies pending operations and returns the underlying toolkit bitmap as a Clr object. |
Show([Title, Wait]) | Shows a preview window. If Wait is non-zero, blocks until it closes. |
GetPixel(X, Y) | Returns the full 0xAARRGGBB pixel value. |
SetPixel(X, Y, Color) | Sets a pixel from an RGB or ARGB color. |
Copy() copies the pixels and image metadata, with identity drawing state and no clip. Calling Clone() on an Image throws an Error.
ToClr() hands out the live underlying bitmap, not a copy: it goes stale once the image is next transformed or disposed.
Data := Picture.GetPixelData(BytesPerPixel := 4, Buffer)
Returns a tightly packed Buffer. Use 4 for RGBA or 1 for grayscale.
With one byte per pixel, luminance uses the same 0.299 * R + 0.587 * G + 0.114 * B calculation as Grayscale(), with a half rounded up. It is calculated with (299 * R + 587 * G + 114 * B + 500) // 1000 integer arithmetic. Alpha does not affect the luminance byte.
If Buffer is specified, the data is written into it and it is returned. It can be a Buffer or any object with Ptr and Size properties, and must hold at least Width * Height * BytesPerPixel bytes; bytes beyond that are left unchanged.
Picture.SetPixelData(Data , BytesPerPixel := 4)
Overwrites the image from a tightly packed Buffer. Use 4 for RGBA or 1 for grayscale. BytesPerPixel matches GetPixelData and FromBuffer, so Picture.SetPixelData(Picture.GetPixelData()) round-trips.
Searches compare RGB values and ignore alpha. Each method takes an optional region as flat X, Y, Width, Height parameters; each region parameter defaults independently, with an omitted origin meaning 0 and an omitted size running to the far edge, so Search(Needle, 100, 100) scans from (100, 100) to the bottom-right corner. Regions are clamped to the image and returned coordinates remain absolute image pixels.
Match := Picture.Search(Needle , X, Y, Width, Height, Variation, Trans, Direction)
Finds one sub-image. On success, returns {X, Y} for its top-left; on failure, returns an empty string. Variation is the per-channel tolerance and is clamped to 0 through 255. Trans specifies a needle color which matches any color. Direction chooses which match wins and defaults to "TopLeft". Names are case-insensitive; any other value, including an empty string, throws ValueError.
| Direction | Match order |
|---|---|
"TopLeft" | Rows from top to bottom, each from left to right. |
"TopRight" | Rows from top to bottom, each from right to left. |
"BottomLeft" | Rows from bottom to top, each from left to right. |
"BottomRight" | Rows from bottom to top, each from right to left. |
"LeftTop" | Columns from left to right, each from top to bottom. |
"LeftBottom" | Columns from left to right, each from bottom to top. |
"RightTop" | Columns from right to left, each from top to bottom. |
"RightBottom" | Columns from right to left, each from bottom to top. |
"Center" | Nearest the center of the search region first. |
Matches := Picture.SearchAll(Needle , X, Y, Width, Height, Variation, Trans, Direction)
Returns every match as an Array of {X, Y} objects, ordered by Direction, with the same names and default as Search. If none are found, the array is empty.
Match := Picture.SearchPixel(Color , X, Y, Width, Height, Variation, Direction)
Finds the first matching pixel. On success, returns {X, Y, Color}, where Color is the actual full ARGB pixel value; on failure, returns an empty string. Direction selects the scan's starting corner: "TopLeft" (the default), "TopRight", "BottomLeft" or "BottomRight". Names are case-insensitive; any other value, including an empty string, throws ValueError.
| Property | Description |
|---|---|
OriginX, OriginY | Read-only screen origin recorded by a capture factory. |
ScaleX, ScaleY | Read-only HiDPI pixel scale used to map image positions back to screen coordinates. |
Rotate and Flip invalidate the screen-origin mapping, and Rotate also invalidates the scale mapping: the affected properties then return an empty string.
Picture.SetOrigin(X, Y , ScaleX, ScaleY)
Re-anchors the screen mapping: sets the origin and, optionally, the pixel scale (ScaleY defaults to ScaleX). Use it to give a FromBuffer or file image a screen position, or to restore the mapping after Rotate or Flip invalidated it.
Using an Image after it has been disposed throws an exception.
An Image is not synchronized. Two RealThreads using the same image at the same time can corrupt it and hang the script; finish with an image before passing it to another real thread, or give each thread its own.
#Import "Ks" { Image }
Image.FromRect(100, 100, 640, 480)
.Grayscale()
.Resize(320, -1)
.Save("capture.png")
#Import "Ks" { Image }
Badge := Image.Path().AddRoundRect(4, 4, 152, 52, 14)
Fill := Image.Brush.LinearGradient(4, 4, 156, 56, "DodgerBlue", "MidnightBlue")
Picture := Image.Create(160, 60)
Picture.FillPath(Badge, Fill)
.DrawPath(Badge, "White", 2)
.DrawText("Ready", 48, 18, "White", "s16 bold")
.Save("badge.png")
Overlay, ImageSearch, PixelSearch, Clipboard, Platform Support