img

blur returns a copy blurred like a Gaussian blur with a standard deviation of radius pixels, as CSS blur() is; 0 leaves it as it is. Pixels past the edges repeat the edge, so edges don't fade, and transparency blurs without dark fringes. It takes the same time for any radius. Throws ValueError for a radius outside 0-1000.

bounds returns the region {x, y, width, height} this frame of an animation changed, with x, y its top-left pixel (1, 1 is the image's top-left corner). For any other image it is the whole image, {x: 1, y: 1, width, height}, so pic.crop(pic.bounds()) is always valid.

brightness returns a copy with every color multiplied by amount: 1 leaves it as it is, 0 is black and 2 twice as bright (clipped at white). Throws ValueError for an amount outside 0-1000.

circle draws a circle around center, {x, y}, with radius in pixels, in place. It takes rectangle's options except radius. Throws ValueError for a malformed center, a negative radius or an invalid option.

clone returns an independent copy, keeping the color profile and frame details.

close releases the image's pixels. Closing twice does nothing; any other method of a closed image throws StateError.

colorProfile returns the embedded ICC color profile, or null when the image has none.

contrast returns a copy with every color moved away from middle gray by amount: 1 leaves it as it is, 0 is solid gray and 2 doubles the contrast. Throws ValueError for an amount outside 0-1000.

crop returns a copy of the rectangle {x, y, width, height} of this image, in pixels with x, y its top-left pixel (1, 1 is the image's top-left corner); the image itself is unchanged. pic.crop(pic.bounds()) is the whole image, or for an animation frame the part that frame changed. Throws ValueError when a key is missing or not a whole number, or the rectangle is empty or reaches outside the image.

delay returns how long this frame of an animation is shown, in milliseconds. It is 0 for a still image and for a frame whose file sets no delay.

draw paints source onto this image with source's top-left pixel at pixel x, y, in place: at 1, 1 their corners line up, and 0 or less puts part of source off the left or top edge. Options: blend (default "over"), opacity, width, height and filter. Throws ValueError for an invalid option, TypeError for a null source and StateError when either image is closed.

drawPath draws path, from img.path or img.parsePath, in place. Each subpath is filled as if closed, by the nonzero rule; the outline follows the path as drawn, closing only subpaths that path.close() closed. It takes rectangle's options except radius. Throws ValueError for an invalid option and TypeError for a null path.

ellipse draws an ellipse around center, {x, y}, with radii {x, y} in pixels, in place. It takes rectangle's options except radius. Throws ValueError for a malformed center or radii, or an invalid option.

encode returns the image encoded as format: "png", "jpeg" (or "jpg"), "gif", "bmp" or "tiff" (or "tif"). PNG and JPEG embed the color profile. GIF keeps the exact colors of images with up to 256 of them, and otherwise dithers to a fixed palette; pixels under 50% opacity become transparent. Options: quality (JPEG only, 1-100, default 90).

Fails with UnsupportedError for WebP, AVIF, HEIC, JPEG XL, ICO and QOI, which can't be encoded. Throws ValueError for an unknown format or a quality outside 1-100.

fill sets every pixel to color, in place, replacing what was there (transparency included) rather than blending. color is "#rrggbb", "#rrggbbaa", a CSS name such as "white", {r, g, b, a}, an *img.Gradient or an *img.Pattern. Throws ValueError for an invalid color.

flipX returns a copy mirrored left to right.

flipY returns a copy mirrored top to bottom.

grayscale returns a gray copy, each pixel's luminance as CSS grayscale(1) computes it; alpha is kept.

height returns the height in pixels.

hueRotate returns a copy with every color's hue turned by degrees around the color wheel, as CSS hue-rotate() does; 0 and 360 leave it as it is. Throws ValueError for a non-finite angle.

index returns this frame's position in its file, counting from 1. It is 1 for an image that isn't one of several.

invert returns a copy with every color inverted (255 - channel); alpha is kept.

line draws a straight line from {x, y} to {x, y}, in place. Options: color, lineWidth, lineCap, dash, dashOffset, opacity, blend and antialias. Throws ValueError for a malformed point or option and StateError when the image is closed.

mapPixels returns a copy where each pixel is fn(color, x, y): color is the pixel as {r, g, b, a} with 0-255 channels and x, y its position, 1, 1 for the top-left pixel as in pixel and setPixel. fn returns the new color, in any form a color can take, or null to keep the pixel. It calls fn once per pixel, so it suits small images and per-pixel effects the filters don't cover; it takes about a second per megapixel. Throws ValueError when fn returns an invalid color and TypeError when fn is null.

mask multiplies this image's alpha by mask's, in place, so the image shows only where mask is opaque. Options: channel is "alpha" (the default) or "luminance", which uses mask's brightness times its alpha, so white shows and black hides. Throws ValueError unless mask is the same size as this image, and StateError when either is closed.

opacity returns a copy with every pixel's alpha multiplied by amount: 1 leaves it as it is and 0 makes it transparent. Throws ValueError for an amount outside 0-1.

orient returns a copy turned and flipped so that an image stored with EXIF orientation 1-8 displays upright; the image itself is unchanged. Use it with img.info(data).orientation, or decode with {autoOrient: true}. Throws ValueError for an orientation outside 1-8.

pixel returns the color at pixel x, y (1, 1 is the top-left one) as "#rrggbb" when it is opaque and "#rrggbbaa" otherwise, the form colors.stringify uses; every fully transparent pixel is "#00000000". Throws ValueError when the point is outside the image.

pixelate returns a copy made of size x size pixel blocks, each the average color of the pixels under it, counting from the top-left corner; 1 leaves the image as it is. Throws ValueError for a size below 1.

pixels returns a copy of every pixel as bytes, four per pixel (red, green, blue, alpha, each 0-255, not premultiplied), row by row from the top-left corner, so pixel x, y starts at byte ((y - 1) * width + x - 1) * 4 + 1 of the 1-based array.

polygon draws the closed shape through points (an array of {x, y}), in place; it may cross itself, and where it overlaps itself is inside (the nonzero rule). It takes rectangle's options except radius. Throws ValueError for a malformed point or option.

polyline draws connected straight lines through points (an array of {x, y}), in place, with lineJoin ("miter", the default, "round" or "bevel") and miterLimit (default 10) shaping the corners; it takes line's other options. Throws ValueError for a malformed point or option.

rectangle draws {x, y, width, height} in place. Options: fill, stroke, radius and the outline options line uses. Throws ValueError for a malformed rectangle, a negative size or an invalid option.

resize returns a copy scaled to width x height pixels; the image itself is unchanged. Pass 0 for one side to keep the aspect ratio. Options: filter is "lanczos" (the default, sharpest), "bicubic", "mitchell", "bilinear" (faster) or "nearest" (blocky, for pixel art); fit is "fill" (the default: exactly width x height), "contain" (as large as fits inside width x height, keeping the aspect ratio) or "cover" (fills width x height exactly, keeping the aspect ratio and cropping the overflow evenly). Throws ValueError for negative sizes, both sides 0, a result over 100 megapixels, or an unknown option value.

rotate returns a copy turned clockwise by degrees; the image itself is unchanged. Multiples of 90 are exact; other angles enlarge the copy to fit the turned image and leave its corners transparent. Throws ValueError for a non-finite angle.

saturate returns a copy with its colors' saturation scaled by amount, as CSS saturate() does: 1 leaves it as it is, 0 is gray and 2 is twice as vivid. Throws ValueError for an amount outside 0-1000.

save encodes the image and writes it to path, choosing the format from the file extension (.png, .jpg, .jpeg, .gif, .bmp, .tif or .tiff) unless the format option names one. Options: format, and quality (JPEG only, 1-100, default 90).

Fails with NotFoundError, PermissionError or IOError when the file can't be written, and UnsupportedError as encode does. Throws ValueError when the format can't be told from path or is unknown.

setColorProfile replaces the ICC color profile that encode and save embed, in place; empty bytes remove it. Throws ValueError when profile isn't an ICC profile or is over 8 MB.

setPixel sets pixel x, y (1, 1 is the top-left one) to color ("#rrggbb", "#rrggbbaa", a CSS name such as "red", or {r, g, b, a}), in place, replacing it rather than blending. Throws ValueError for a point outside the image or an invalid color.

setPixels replaces every pixel, in place, with data laid out as pixels() returns it. Throws ValueError unless data is exactly width * height * 4 bytes.

sharpen returns a copy sharpened with an unsharp mask: each color moves away from its blurred neighbourhood by amount, so 0 leaves the image as it is and 1 is a strong sharpen. Options: radius, the blur's standard deviation in pixels (default 1); larger radii sharpen coarser detail. Alpha is kept. Throws ValueError for an amount outside 0-100 or a radius outside 0-1000.

size returns the image's {width, height} in pixels. The record also carries the deprecated keys w and h, the same values under the names img.Image.size used before.

text draws text with its top-left corner at {x, y}, in place. "\n" starts a new line. Options: font (default "sans"), size (default 16), color, align, baseline, maxWidth, lineHeight, opacity, blend and antialias. Throws ValueError for a malformed point or option.

threshold returns a black and white copy: white where a pixel's luminance is at least level (0-1), black elsewhere. Alpha is kept. Throws ValueError for a level outside 0-1.

tint returns a copy with every color mixed toward color by amount: 0 leaves it as it is and 1 gives every pixel color's red, green and blue (scaled by color's own alpha). Alpha is kept. Throws ValueError for an invalid color or an amount outside 0-1.

toDataURL returns the image encoded as a data URL such as "data:image/png;base64,...", for HTML, CSS or an <img> tag. Options: format ("png", the default, "jpeg", "gif", "bmp" or "tiff") and quality (JPEG only, 1-100, default 90). Fails and throws as encode does.

width returns the width in pixels.

arc adds an arc of the circle around center, {x, y}, with radius in pixels, joined to the current point by a straight line, as a canvas arc() does. Angles are degrees, with 0 pointing right and 90 pointing down (clockwise on screen). Options: start (default 0), end (default 360) and counterclockwise (default false, sweeping clockwise from start to end). A sweep of 360 degrees or more draws the whole circle. Throws ValueError for a negative radius or a non-finite angle. Returns the path.

arcTo adds an arc with radius (pixels) that rounds the corner at control: it is tangent to the line from the current point to control and to the line from control to point (both {x, y}), joined to the current point by a straight line, as a canvas arcTo() does. The path then continues from where the arc ends, not from point. Throws ValueError for a negative radius. Returns the path.

bounds returns the smallest rectangle {x, y, width, height} holding the path's lines and curves, or null when the path draws nothing.

circle adds a circle around center, {x, y}, with radius in pixels, as a closed subpath. Throws ValueError for a negative radius. Returns the path.

clone returns an independent copy of the path.

close joins the current point back to the start of the subpath with a straight line, so an outline turns the corner there instead of ending in caps. Returns the path.

cubicTo adds a cubic Bézier curve from the current point, pulled toward control1 and then control2, to point (all {x, y}). Returns the path.

ellipse adds an ellipse around center, {x, y}, with radii {x, y} in pixels, as a closed subpath. Throws ValueError for negative radii. Returns the path.

lineTo adds a straight line from the current point to point, {x, y} (starting the subpath there when the path is empty). Returns the path.

moveTo starts a new subpath at point, {x, y}. Returns the path.

quadTo adds a quadratic Bézier curve from the current point, pulled toward control, to point (both {x, y}). Returns the path.

rect adds the rectangle rect, {x, y, width, height}, as a closed subpath. Options: radius rounds the corners (pixels, default 0). Throws ValueError for a malformed rectangle or a negative size. Returns the path.

rotate turns everything already in the path clockwise by degrees around 1, 1 (the image's top-left corner), or around the center option, {x, y}. Throws ValueError for a non-finite angle. Returns the path.

scale stretches everything already in the path by x horizontally and y vertically, away from 1, 1 (the image's top-left corner) or from the center option, {x, y}; negative factors mirror it. Throws ValueError for a non-finite factor. Returns the path.

translate moves everything already in the path by x, y pixels. Throws ValueError for a non-finite distance. Returns the path.

colorAt returns the gradient's color at offset (0-1 between its first and last stop, outside that range as spread says) as "#rrggbb", or "#rrggbbaa" when it isn't opaque, for picking colors from a scale. Throws ValueError for a non-finite offset.

name returns the font's full name from its name table, such as "Go Regular" or "DejaVu Sans Bold".

a returns the color's alpha channel, 0 (transparent) to 255 (opaque).

b returns the color's blue channel, 0 to 255.

g returns the color's green channel, 0 to 255.

r returns the color's red channel, 0 to 255.

withAlpha returns a copy of the color with alpha a, from 0 (fully transparent) to 255 (opaque): img.rgb(255, 0, 0).withAlpha(128) is a half-transparent red. Throws ValueError for an alpha outside that range.