Class Image

An RGBA image; provides the codecs and the manipulation functions. Methods that change the image modify it in place and return it, so calls can be chained

Hierarchy (View Summary)

Constructors

constructor

Accessors

bitmap height RESIZE_AREA RESIZE_AUTO RESIZE_BICUBIC RESIZE_BILINEAR RESIZE_NEAREST_NEIGHBOR SVG_MODE_HEIGHT SVG_MODE_SCALE SVG_MODE_WIDTH width

Methods

[iterator] averageColor blue blur brightness clone colorToRGB colorToRGBA composite contain contrast cover crop cropCircle decode dominantColor drawBox drawCircle encode encodeJPEG encodePNG fill fisheye fit flip gamma getPixelAt getRGBAAt gradient green greyscale hslaToColor hslToColor hueShift invert invertLightness invertValue iterateWithColors lightness opacity red renderSVG renderText resize rgbaToColor rgbaToHSLA rgbToColor rotate roundCorners saturation scale sepia setPixelAt sharpen

Constructors

constructor

  • new Image(width: number, height: number): Image

    Creates a new image with the given dimensions

    Parameters

    • width: number
    • height: number

    Returns Image

Accessors

bitmap

  • get bitmap(): Uint8ClampedArray

    The image's RGBA pixel data. It can be replaced by any 8-bit array with width * height * 4 bytes (it is used as is, without copying)

    Returns Uint8ClampedArray

  • set bitmap(
        bitmap: Uint8Array<ArrayBufferLike> | Uint8ClampedArray<ArrayBufferLike>,
    ): void

    Replaces the pixel data, the array has to hold width * height * 4 bytes

    Parameters

    • bitmap: Uint8Array<ArrayBufferLike> | Uint8ClampedArray<ArrayBufferLike>

    Returns void

height

StaticRESIZE_AREA

  • get RESIZE_AREA(): "RESIZE_AREA"

    Area averaging (box filter): every output pixel is the average of the source pixels it covers. Meant for shrinking

    Returns "RESIZE_AREA"

StaticRESIZE_AUTO

  • get RESIZE_AUTO(): -1

    Used for automatically preserving an images aspect ratio when resizing.

    Returns -1

StaticRESIZE_BICUBIC

  • get RESIZE_BICUBIC(): "RESIZE_BICUBIC"

    Bicubic (Catmull-Rom) resizing, sharper than bilinear, especially when enlarging

    Returns "RESIZE_BICUBIC"

StaticRESIZE_BILINEAR

  • get RESIZE_BILINEAR(): "RESIZE_BILINEAR"

    Bilinear resizing (the default). When shrinking, the filter widens with the scale factor, so every source pixel contributes

    Returns "RESIZE_BILINEAR"

StaticRESIZE_NEAREST_NEIGHBOR

StaticSVG_MODE_HEIGHT

StaticSVG_MODE_SCALE

StaticSVG_MODE_WIDTH

width

Methods

[iterator]

  • "[iterator]"(): Generator<[x: number, y: number], void, undefined>

    Yields an [x, y] array for every pixel in the image (0-based)

    Returns Generator<[x: number, y: number], void, undefined>

    Yields

    The coordinates of the pixel ([x, y])

averageColor

  • averageColor(): number

    Gets the average color of the image, weighting each pixel by its opacity

    Returns number

    The average color (fully opaque), black for fully transparent images

blue

  • blue(factor: number, absolute?: boolean): this

    Scales or sets the blue channel

    Parameters

    • factor: number

      The factor to multiply the channel with (>= 0, results are clamped), or the value (0..1) to set it to

    • absolute: boolean = false

      Whether to scale the current value (false) or set every pixel's blue channel to factor * 255 (true)

    Returns this

blur

  • blur(radius: number): this

    Blurs the image with a gaussian blur (transparent pixels don't bleed their color)

    Parameters

    • radius: number

      The blur radius: the gaussian's standard deviation in pixels, like CSS' blur()

    Returns this

brightness

  • brightness(factor: number): this

    Multiplies the color channels, e.g. 1.2 makes the image 20% brighter

    Parameters

    • factor: number

      The factor (>= 0, 1 keeps the image)

    Returns this

clone

StaticcolorToRGB

  • colorToRGB(color: number): [r: number, g: number, b: number]

    Converts a color value to an array of RGB values (ignoring the colors alpha)

    Parameters

    • color: number

      The color value to convert

    Returns [r: number, g: number, b: number]

    The RGB values ([R, G, B])

StaticcolorToRGBA

  • colorToRGBA(color: number): [r: number, g: number, b: number, a: number]

    Converts a color value to an array of RGBA values

    Parameters

    • color: number

      The color value to convert

    Returns [r: number, g: number, b: number, a: number]

    The RGBA values ([R, G, B, A])

composite

  • composite(
        source: Image,
        x?: number,
        y?: number,
        options?: CompositeOptions,
    ): this

    Composites (overlays) the source onto this image at the specified coordinates

    Parameters

    • source: Image

      The image to place

    • Optionalx: number = 0

      The x position to place the image at

    • Optionaly: number = 0

      The y position to place the image at

    • options: CompositeOptions = {}

      Opacity and blend mode, see CompositeOptions

    Returns this

contain

  • contain(width: number, height: number, mode?: ResizeMode): this

    Resizes the image so it is contained in the given bounding box. Can return an image with one axis smaller than the given bounding box.

    Parameters

    • width: number

      The width of the bounding box

    • height: number

      The height of the bounding box

    • Optionalmode: ResizeMode = Image.RESIZE_BILINEAR

      The resizing mode to use

    Returns this

    The resized image

contrast

  • contrast(factor: number): this

    Scales the color channels' distance from mid grey, e.g. 1.5 increases the contrast, 0.5 reduces it

    Parameters

    • factor: number

      The factor (>= 0, 1 keeps the image, 0 makes it grey)

    Returns this

cover

  • cover(width: number, height: number, mode?: ResizeMode): this

    Resizes the image so it covers the given bounding box, cropping the overflowing edges. Always returns the exact dimensions of the bounding box.

    Parameters

    • width: number

      The width of the bounding box

    • height: number

      The height of the bounding box

    • Optionalmode: ResizeMode = Image.RESIZE_BILINEAR

      The resizing mode to use

    Returns this

    The resized image

crop

  • crop(x: number, y: number, width: number, height: number): this

    Crops an image to the specified dimensions. The region is clipped to the image, so the result can be smaller than the requested size

    Parameters

    • x: number

      The x offset (0-based)

    • y: number

      The y offset (0-based)

    • width: number

      The new images width

    • height: number

      The new images height

    Returns this

cropCircle

  • cropCircle(options?: CropCircleOptions): this

    Crops the image into a circle with an antialiased edge

    Parameters

    Returns this

  • cropCircle(max?: boolean, feathering?: number): this

    Crops the image into a circle with an antialiased edge

    Parameters

    • Optionalmax: boolean

      Whether to use the larger dimension for the size. Default: false

    • Optionalfeathering: number

      Share of the radius (0..1) over which the edge fades out. Default: 0

    Returns this

Staticdecode

  • decode(input: BinaryData, options?: DecodeOptions): Promise<Image>

    Decodes an image (PNG, JPEG or TIFF)

    Parameters

    • input: BinaryData

      The binary data to decode

    • options: DecodeOptions = {}

      See DecodeOptions. JPEGs, TIFFs and PNGs are rotated/mirrored as their orientation tag (Exif, for PNGs also XMP) says by default: photos taken with a rotated camera are stored sideways

    Returns Promise<Image>

    The decoded image

dominantColor

  • dominantColor(options?: DominantColorOptions): number

    Gets the image's dominant color: the colors are grouped into a few clusters (median cut and k-means), the average color of the largest one is returned

    Parameters

    Returns number

    The image's dominant color (fully opaque); mostly transparent pixels are ignored. If every pixel is ignored as black or white, the filter is dropped

  • dominantColor(
        ignoreBlack?: boolean,
        ignoreWhite?: boolean,
        bwThreshold?: number,
    ): number

    Gets the image's dominant color, see the variant with options

    Parameters

    • OptionalignoreBlack: boolean

      Whether to ignore dark colors (all channels below the threshold). Default: true

    • OptionalignoreWhite: boolean

      Whether to ignore light colors (all channels above 255 minus the threshold). Default: true

    • OptionalbwThreshold: number

      The black/white threshold (0-64, in steps of 4 channel values). Default: 15

    Returns number

    The image's dominant color (fully opaque)

drawBox

  • drawBox(
        x: number,
        y: number,
        width: number,
        height: number,
        color: number | ColorFunction,
    ): this

    Draws a box at the specified coordinates (0-based), clipped to the image

    Parameters

    • x: number

      The x offset

    • y: number

      The y offset

    • width: number

      The box width

    • height: number

      The box height

    • color: number | ColorFunction

      The color to fill the box in with, a function gets coordinates relative to the box

    Returns this

drawCircle

  • drawCircle(
        x: number,
        y: number,
        radius: number,
        color: number | ColorFunction,
    ): this

    Draws an antialiased circle around the center of the specified pixel (0-based)

    Parameters

    • x: number

      The center x position

    • y: number

      The center y position

    • radius: number

      The circles radius in pixels

    • color: number | ColorFunction

      The color, a function gets coordinates relative to the circle's bounding box

    Returns this

encode

  • encode(
        compression?: number,
        metadata?: PNGMetadata,
    ): Promise<Uint8Array<ArrayBufferLike>>

    Encodes the image into a PNG, with the smallest lossless color type (a palette for up to 256 colors, greyscale or RGB, alpha only if needed). Uses the runtime's native zlib when available

    Parameters

    • Optionalcompression: number

      The compression level (0-9). Default: 1

    • Optionalmetadata: PNGMetadata

      Text metadata to include

    Returns Promise<Uint8Array<ArrayBufferLike>>

    The encoded data

  • encode(metadata?: PNGMetadata): Promise<Uint8Array<ArrayBufferLike>>

    Encodes the image into a PNG with compression level 1

    Parameters

    Returns Promise<Uint8Array<ArrayBufferLike>>

    The encoded data

encodeJPEG

  • encodeJPEG(quality?: number): Promise<Uint8Array<ArrayBufferLike>>

    Encodes the image into a JPEG

    Parameters

    • Optionalquality: number = 90

      The JPEG quality to use (1-100), chroma subsampling is disabled above 90

    Returns Promise<Uint8Array<ArrayBufferLike>>

encodePNG

  • encodePNG(
        compression?: number,
        metadata?: PNGMetadata,
    ): Promise<Uint8Array<ArrayBufferLike>>

    Encodes the image into a PNG, an alias of Image.encode

    Parameters

    • Optionalcompression: number
    • Optionalmetadata: PNGMetadata

    Returns Promise<Uint8Array<ArrayBufferLike>>

  • encodePNG(metadata?: PNGMetadata): Promise<Uint8Array<ArrayBufferLike>>

    Encodes the image into a PNG, an alias of Image.encode

    Parameters

    Returns Promise<Uint8Array<ArrayBufferLike>>

fill

fisheye

  • fisheye(strength?: number): this

    Applies a fisheye (barrel distortion) effect

    Parameters

    • Optionalstrength: number = 2

      The distortion strength (exponent of the radial mapping), higher values bulge the center more

    Returns this

fit

  • fit(width: number, height: number, mode?: ResizeMode): this

    Resizes the image so it is contained in the given bounding box, placing it in the center of the given bounding box. Always returns the exact dimensions of the bounding box.

    Parameters

    • width: number

      The width of the bounding box

    • height: number

      The height of the bounding box

    • Optionalmode: ResizeMode = Image.RESIZE_BILINEAR

      The resizing mode to use

    Returns this

    The resized image

flip

  • flip(direction: "horizontal" | "vertical"): this

    Flips / mirrors the image horizontally or vertically

    Parameters

    • direction: "horizontal" | "vertical"

      The direction to flip

    Returns this

gamma

  • gamma(gamma: number): this

    Applies a gamma correction, values above 1 brighten the dark tones, values below 1 darken them

    Parameters

    • gamma: number

      The gamma (> 0, 1 keeps the image)

    Returns this

getPixelAt

  • getPixelAt(x: number, y: number): number

    Gets the pixel color at the specified position (0-based)

    Parameters

    • x: number
    • y: number

    Returns number

    The color value

getRGBAAt

  • getRGBAAt(x: number, y: number): Uint8ClampedArray

    Gets a view of the RGBA components of the pixel at the specified position (0-based)

    Parameters

    • x: number
    • y: number

    Returns Uint8ClampedArray

    The RGBA value

Staticgradient

  • gradient(colors: Record<number, number>): (position: number) => number

    Creates a multi-point gradient generator

    Parameters

    • colors: Record<number, number>

      The gradient points to use (e.g. {0: 0xff0000ff, 1: 0x00ff00ff})

    Returns (position: number) => number

    The gradient generator. The function argument is the position in the gradient (0..1).

green

  • green(factor: number, absolute?: boolean): this

    Scales or sets the green channel

    Parameters

    • factor: number

      The factor to multiply the channel with (>= 0, results are clamped), or the value (0..1) to set it to

    • absolute: boolean = false

      Whether to scale the current value (false) or set every pixel's green channel to factor * 255 (true)

    Returns this

greyscale

  • greyscale(): this

    Converts the image to greyscale by its luma (ITU-R 601, like Pillow), keeping the alpha

    Returns this

StatichslaToColor

  • hslaToColor(h: number, s: number, l: number, a: number): number

    Converts HSLA colors to RGBA colors

    Parameters

    • h: number

      hue (0..1)

    • s: number

      saturation (0..1)

    • l: number

      lightness (0..1)

    • a: number

      opacity (0..1)

    Returns number

    color

StatichslToColor

  • hslToColor(h: number, s: number, l: number): number

    Converts HSL colors to RGBA colors (assuming an opacity of 255)

    Parameters

    • h: number

      hue (0..1)

    • s: number

      saturation (0..1)

    • l: number

      lightness (0..1)

    Returns number

    color

hueShift

  • hueShift(degrees: number): this

    Shifts the images hue

    Parameters

    • degrees: number

      How many degrees to shift the hue by

    Returns this

invert

invertLightness

  • invertLightness(): this

    Inverts the images lightness (HSL), keeping hue and saturation: dark colors become light and vice versa

    Returns this

invertValue

  • invertValue(): this

    Inverts the images value (HSV), keeping hue and saturation: the brightest channel v becomes 255 - v and the others scale along, black becomes white

    Returns this

iterateWithColors

  • iterateWithColors(): Generator<
        [x: number, y: number, color: number],
        void,
        undefined,
    >

    Yields an [x, y, color] array for every pixel in the image (0-based)

    Returns Generator<[x: number, y: number, color: number], void, undefined>

    Yields

    The coordinates and color of the pixel ([x, y, color])

lightness

  • lightness(value: number, absolute?: boolean): this

    Sets the brightness of the image

    Parameters

    • value: number

      The lightness to apply (0..1)

    • absolute: boolean = false

      Whether to scale the current lightness (false) or just set the new lightness (true)

    Returns this

opacity

  • opacity(opacity: number, absolute?: boolean): this

    Sets the images opacity

    Parameters

    • opacity: number

      The opacity to apply (0..1)

    • absolute: boolean = false

      Whether to scale the current opacity (false) or just set the new opacity (true)

    Returns this

red

  • red(factor: number, absolute?: boolean): this

    Scales or sets the red channel

    Parameters

    • factor: number

      The factor to multiply the channel with (>= 0, results are clamped), or the value (0..1) to set it to

    • absolute: boolean = false

      Whether to scale the current value (false) or set every pixel's red channel to factor * 255 (true)

    Returns this

StaticrenderSVG

  • renderSVG(
        svg: string | BinaryData,
        size?: number,
        mode?: SVGScaleMode,
    ): Promise<Image>

    Creates a new image from the given SVG Supports shapes, paths, transforms, use/symbol, CSS styles, gradients, strokes, clip paths, masks and opacity; text, images, filters and patterns are not rendered

    Parameters

    Returns Promise<Image>

    The rendered SVG graphic

StaticrenderText

  • renderText(
        font: BinaryData,
        size: number,
        text: string,
        color?: number,
        layout?: TextLayout,
        style?: TextStyle,
    ): Promise<Image>

    Creates a new image containing the rendered text.

    Parameters

    • font: BinaryData

      TrueType (ttf/ttc) or OpenType (otf) font buffer to use

    • size: number

      Font size in pixels (per em)

    • text: string

      Text to render

    • Optionalcolor: number = 0xffffffff

      Text color to use

    • Optionallayout: TextLayout = ...

      The text layout to use

    • style: TextStyle = {}

      Outline, see TextStyle; the image grows by the outline width on every side

    Returns Promise<Image>

    The rendered text

resize

  • resize(width: number, height: number, mode?: ResizeMode): this

    Resizes the image to the given dimensions. Use Image.RESIZE_AUTO as either width or height to automatically preserve the aspect ratio.

    Parameters

    • width: number

      The new width

    • height: number

      The new height

    • Optionalmode: ResizeMode = Image.RESIZE_BILINEAR

      The resizing mode to use

    Returns this

    The resized image

StaticrgbaToColor

  • rgbaToColor(r: number, g: number, b: number, a: number): number

    Converts RGBA components to an RGBA value, values are rounded and clamped to 0..255

    Parameters

    • r: number

      red (0..255)

    • g: number

      green (0..255)

    • b: number

      blue (0..255)

    • a: number

      alpha (0..255)

    Returns number

    RGBA value

StaticrgbaToHSLA

  • rgbaToHSLA(
        r: number,
        g: number,
        b: number,
        a: number,
    ): [h: number, s: number, l: number, a: number]

    Converts an RGBA value to an array of HSLA values

    Parameters

    • r: number

      {number} (0..255)

    • g: number

      {number} (0..255)

    • b: number

      {number} (0..255)

    • a: number

      {number} (0..255)

    Returns [h: number, s: number, l: number, a: number]

    The HSLA values ([H, S, L, A])

StaticrgbToColor

  • rgbToColor(r: number, g: number, b: number): number

    Converts RGB components to an RGBA value (assuming alpha = 255)

    Parameters

    • r: number

      red (0..255)

    • g: number

      green (0..255)

    • b: number

      blue (0..255)

    Returns number

    RGBA value

rotate

  • rotate(angle: number, options?: RotateOptions): this

    Rotates the image counterclockwise by the given amount of degrees

    Parameters

    Returns this

  • rotate(angle: number, resize?: boolean): this

    Rotates the image counterclockwise by the given amount of degrees

    Parameters

    • angle: number

      The angle to rotate the image for (in degrees)

    • Optionalresize: boolean

      Whether to resize the image so it fits all pixels or just ignore outlying pixels. Default: true

    Returns this

roundCorners

  • roundCorners(radius?: number): this

    Rounds the images corners, with antialiased edges

    Parameters

    • Optionalradius: number = ...

      The radius of the corners

    Returns this

saturation

  • saturation(value: number, absolute?: boolean): this

    Sets the saturation of the image

    Parameters

    • value: number

      The saturation to apply (0..1)

    • absolute: boolean = false

      Whether to scale the current saturation (false) or just set the new saturation (true)

    Returns this

scale

  • scale(factor: number, mode?: ResizeMode): this

    Resizes the image by the given factor

    Parameters

    • factor: number

      The factor to resize the image with

    • Optionalmode: ResizeMode = Image.RESIZE_BILINEAR

      The resizing mode to use

    Returns this

sepia

setPixelAt

  • setPixelAt(x: number, y: number, pixelColor: number): this

    Sets the pixel color for the specified position (0-based)

    Parameters

    • x: number
    • y: number
    • pixelColor: number

    Returns this

sharpen

  • sharpen(amount?: number, radius?: number): this

    Sharpens the image with an unsharp mask: the difference to a blurred copy is amplified

    Parameters

    • Optionalamount: number = 1

      How strongly to sharpen (0 does nothing)

    • Optionalradius: number = 1

      The radius of the blur the image is compared with (larger values sharpen coarser details)

    Returns this

Settings

Member Visibility

On This Page

Constructors
Accessors
Methods