imagescript 1.3.1 → 3.1.0

package/dist/image.d.ts

@@ -0,0 +1,553 @@
+import { BinaryData } from './util/mem.js';
+import { TextLayout } from './text-layout.js';
+/** A color as a 32-bit RGBA integer (`0xRRGGBBAA`) */
+export type Color = number;
+/** Called with a pixel's (0-based) coordinates, returns its color */
+export type ColorFunction = (x: number, y: number) => Color;
+/** Resampling filters for {@link Image.resize} and the other scaling functions, see {@link Image.RESIZE_BILINEAR} etc. */
+export type ResizeMode = 'RESIZE_NEAREST_NEIGHBOR' | 'RESIZE_BILINEAR' | 'RESIZE_BICUBIC' | 'RESIZE_AREA';
+/** How {@link Image.renderSVG} scales: {@link Image.SVG_MODE_SCALE}, {@link Image.SVG_MODE_WIDTH} or {@link Image.SVG_MODE_HEIGHT} */
+export type SVGScaleMode = 1 | 2 | 3;
+/** Blend modes of {@link Image.composite}, named like CSS' mix-blend-mode values */
+export type BlendMode = 'normal' | 'multiply' | 'screen' | 'overlay' | 'darken' | 'lighten' | 'color-dodge' | 'color-burn' | 'hard-light' | 'soft-light' | 'difference' | 'exclusion' | 'add';
+/** Options of {@link Image.composite} */
+export interface CompositeOptions {
+    /** Opacity of the source (0..1). Default: `1` */
+    opacity?: number;
+    /** How the colors are mixed. Default: `'normal'` */
+    mode?: BlendMode;
+}
+/** Options of {@link Image.decode} */
+export interface DecodeOptions {
+    /** Whether to rotate/mirror JPEGs, TIFFs, PNGs and WebPs as their orientation tag (Exif or XMP) says. Default: `true` */
+    applyOrientation?: boolean;
+}
+/** Text style options of {@link Image.renderText} */
+export interface TextStyle {
+    /** Width of an outline around the glyphs in pixels. Default: `0` */
+    strokeWidth?: number;
+    /** Color of the outline. Default: `0x000000ff` */
+    strokeColor?: Color;
+    /**
+     * Whether to run the hinting instructions of TrueType fonts, which align stems and edges with the pixel grid for
+     * crisper text at small sizes (like Windows renders text); the glyphs of hinted fonts are then placed on whole
+     * pixels. Fonts without instructions (and CFF/OpenType outlines) aren't affected. Default: `true`
+     */
+    hinting?: boolean;
+}
+/** Options of {@link Image.cropCircle} */
+export interface CropCircleOptions {
+    /** Whether to use the larger dimension for the size. Default: `false` */
+    max?: boolean;
+    /** Share of the radius (0..1) over which the edge fades out. Default: `0` */
+    feathering?: number;
+}
+/** Options of {@link Image.dominantColor} */
+export interface DominantColorOptions {
+    /** Whether to ignore dark colors (all channels below the threshold). Default: `true` */
+    ignoreBlack?: boolean;
+    /** Whether to ignore light colors (all channels above 255 minus the threshold). Default: `true` */
+    ignoreWhite?: boolean;
+    /** The black/white threshold (0-64, in steps of 4 channel values). Default: `15` */
+    threshold?: number;
+}
+/** Options of {@link Image.rotate} */
+export interface RotateOptions {
+    /** Whether to resize the image so it fits all pixels or just ignore outlying pixels. Default: `true` */
+    resize?: boolean;
+}
+/** Options of {@link Image.colorToAlpha} */
+export interface ColorToAlphaOptions {
+    /** Pixels at most this far from the color (0-1) become fully transparent. Default: 0 */
+    transparencyThreshold?: number;
+    /** Pixels at least this far from the color (0-1) stay fully opaque. Default: 1 */
+    opacityThreshold?: number;
+}
+/** Text metadata written into PNGs by {@link Image.encode} */
+export interface PNGMetadata {
+    /** The image's title */
+    title?: string;
+    /** The image's author */
+    author?: string;
+    /** The image's description */
+    description?: string;
+    /** The image's copyright info */
+    copyright?: string;
+    /** The image's creation time. Default: now */
+    creationTime?: string | number | Date;
+    /** The software used to create the image. Default: `'github.com/matmen/ImageScript vX.X.X'`, `''` leaves it out */
+    software?: string;
+    /** A disclaimer for the image */
+    disclaimer?: string;
+    /** A warning for the image */
+    warning?: string;
+    /** The image's source */
+    source?: string;
+    /** A comment for the image */
+    comment?: string;
+}
+/**
+ * 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
+ */
+export declare class Image {
+    /**
+     * Creates a new image with the given dimensions
+     * @param width
+     * @param height
+     */
+    constructor(width: number, height: number);
+    /**
+     * 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)
+     */
+    get bitmap(): Uint8ClampedArray;
+    /** Replaces the pixel data, the array has to hold width * height * 4 bytes */
+    set bitmap(bitmap: Uint8ClampedArray | Uint8Array);
+    /**
+     * @private
+     */
+    toString(): string;
+    /**
+     * The images width
+     */
+    get width(): number;
+    /**
+     * The images height
+     */
+    get height(): number;
+    /**
+     * Yields an [x, y] array for every pixel in the image (0-based)
+     * @yields The coordinates of the pixel ([x, y])
+     */
+    [Symbol.iterator](): Generator<[x: number, y: number], void, undefined>;
+    /**
+     * Yields an [x, y, color] array for every pixel in the image (0-based)
+     * @yields The coordinates and color of the pixel ([x, y, color])
+     */
+    iterateWithColors(): Generator<[x: number, y: number, color: Color], void, undefined>;
+    /**
+     * Converts RGBA components to an RGBA value, values are rounded and clamped to 0..255
+     * @param r red (0..255)
+     * @param g green (0..255)
+     * @param b blue (0..255)
+     * @param a alpha (0..255)
+     * @returns RGBA value
+     */
+    static rgbaToColor(r: number, g: number, b: number, a: number): Color;
+    /**
+     * Converts RGB components to an RGBA value (assuming alpha = 255)
+     * @param r red (0..255)
+     * @param g green (0..255)
+     * @param b blue (0..255)
+     * @returns RGBA value
+     */
+    static rgbToColor(r: number, g: number, b: number): Color;
+    /**
+     * Converts HSLA colors to RGBA colors
+     * @param h hue (0..1)
+     * @param s saturation (0..1)
+     * @param l lightness (0..1)
+     * @param a opacity (0..1)
+     * @returns color
+     */
+    static hslaToColor(h: number, s: number, l: number, a: number): Color;
+    /**
+     * Converts HSL colors to RGBA colors (assuming an opacity of 255)
+     * @param h hue (0..1)
+     * @param s saturation (0..1)
+     * @param l lightness (0..1)
+     * @returns color
+     */
+    static hslToColor(h: number, s: number, l: number): Color;
+    /**
+     * Converts an RGBA value to an array of HSLA values
+     * @param r {number} (0..255)
+     * @param g {number} (0..255)
+     * @param b {number} (0..255)
+     * @param a {number} (0..255)
+     * @returns The HSLA values ([H, S, L, A])
+     */
+    static rgbaToHSLA(r: number, g: number, b: number, a: number): [h: number, s: number, l: number, a: number];
+    /**
+     * Converts a color value to an array of RGBA values
+     * @param color The color value to convert
+     * @returns The RGBA values ([R, G, B, A])
+     */
+    static colorToRGBA(color: Color): [r: number, g: number, b: number, a: number];
+    /**
+     * Converts a color value to an array of RGB values (ignoring the colors alpha)
+     * @param color The color value to convert
+     * @returns The RGB values ([R, G, B])
+     */
+    static colorToRGB(color: Color): [r: number, g: number, b: number];
+    /**
+     * Gets the pixel color at the specified position (0-based)
+     * @param x
+     * @param y
+     * @returns The color value
+     */
+    getPixelAt(x: number, y: number): Color;
+    /**
+     * Gets a view of the RGBA components of the pixel at the specified position (0-based)
+     * @param x
+     * @param y
+     * @returns The RGBA value
+     */
+    getRGBAAt(x: number, y: number): Uint8ClampedArray;
+    /**
+     * Sets the pixel color for the specified position (0-based)
+     * @param x
+     * @param y
+     * @param pixelColor
+     */
+    setPixelAt(x: number, y: number, pixelColor: Color): this;
+    /**
+     * @callback colorFunction
+     * @param x 0-based x coordinate
+     * @param y 0-based y coordinate
+     * @returns pixel color
+     */
+    /**
+     * Fills the image data with the supplied color
+     * @param color
+     */
+    fill(color: Color | ColorFunction): this;
+    /**
+     * Clones the current image
+     */
+    clone(): Image;
+    /**
+     * Use {@link https://en.wikipedia.org/wiki/Image_scaling#Nearest-neighbor_interpolation Nearest-neighbor} resizing.
+     */
+    static get RESIZE_NEAREST_NEIGHBOR(): 'RESIZE_NEAREST_NEIGHBOR';
+    /**
+     * Bilinear resizing (the default). When shrinking, the filter widens with the scale factor, so every source pixel contributes
+     */
+    static get RESIZE_BILINEAR(): 'RESIZE_BILINEAR';
+    /**
+     * Bicubic (Catmull-Rom) resizing, sharper than bilinear, especially when enlarging
+     */
+    static get RESIZE_BICUBIC(): 'RESIZE_BICUBIC';
+    /**
+     * Area averaging (box filter): every output pixel is the average of the source pixels it covers. Meant for shrinking
+     */
+    static get RESIZE_AREA(): 'RESIZE_AREA';
+    /**
+     * Used for automatically preserving an images aspect ratio when resizing.
+     */
+    static get RESIZE_AUTO(): -1;
+    /**
+     * Resizes the image by the given factor
+     * @param factor The factor to resize the image with
+     * @param [mode=Image.RESIZE_BILINEAR] The resizing mode to use
+     */
+    scale(factor: number, mode?: ResizeMode): this;
+    /**
+     * Resizes the image to the given dimensions.
+     * Use {@link Image.RESIZE_AUTO} as either width or height to automatically preserve the aspect ratio.
+     * @param width The new width
+     * @param height The new height
+     * @param [mode=Image.RESIZE_BILINEAR] The resizing mode to use
+     * @returns The resized image
+     */
+    resize(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.
+     * @param width The width of the bounding box
+     * @param height The height of the bounding box
+     * @param [mode=Image.RESIZE_BILINEAR] The resizing mode to use
+     * @returns The resized image
+     */
+    contain(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.
+     * @param width The width of the bounding box
+     * @param height The height of the bounding box
+     * @param [mode=Image.RESIZE_BILINEAR] The resizing mode to use
+     * @returns The resized image
+     */
+    fit(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.
+     * @param width The width of the bounding box
+     * @param height The height of the bounding box
+     * @param [mode=Image.RESIZE_BILINEAR] The resizing mode to use
+     * @returns The resized image
+     */
+    cover(width: number, height: number, mode?: ResizeMode): 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
+     * @param x The x offset (0-based)
+     * @param y The y offset (0-based)
+     * @param width The new images width
+     * @param height The new images height
+     */
+    crop(x: number, y: number, width: number, height: number): this;
+    /**
+     * Draws a box at the specified coordinates (0-based), clipped to the image
+     * @param x The x offset
+     * @param y The y offset
+     * @param width The box width
+     * @param height The box height
+     * @param color The color to fill the box in with, a function gets coordinates relative to the box
+     */
+    drawBox(x: number, y: number, width: number, height: number, color: Color | ColorFunction): this;
+    /**
+     * Draws an antialiased circle around the center of the specified pixel (0-based)
+     * @param x The center x position
+     * @param y The center y position
+     * @param radius The circles radius in pixels
+     * @param color The color, a function gets coordinates relative to the circle's bounding box
+     */
+    drawCircle(x: number, y: number, radius: number, color: Color | ColorFunction): this;
+    /**
+     * Crops the image into a circle with an antialiased edge
+     * @param options See {@link CropCircleOptions}
+     */
+    cropCircle(options?: CropCircleOptions): this;
+    /**
+     * Crops the image into a circle with an antialiased edge
+     * @param max Whether to use the larger dimension for the size. Default: `false`
+     * @param feathering Share of the radius (0..1) over which the edge fades out. Default: `0`
+     */
+    cropCircle(max?: boolean, feathering?: number): this;
+    /**
+     * Sets the images opacity
+     * @param opacity The opacity to apply (0..1)
+     * @param absolute Whether to scale the current opacity (false) or just set the new opacity (true)
+     */
+    opacity(opacity: number, absolute?: boolean): this;
+    /**
+     * Scales or sets the red channel
+     * @param factor The factor to multiply the channel with (>= 0, results are clamped), or the value (0..1) to set it to
+     * @param absolute Whether to scale the current value (false) or set every pixel's red channel to `factor` * 255 (true)
+     */
+    red(factor: number, absolute?: boolean): this;
+    /**
+     * Scales or sets the green channel
+     * @param factor The factor to multiply the channel with (>= 0, results are clamped), or the value (0..1) to set it to
+     * @param absolute Whether to scale the current value (false) or set every pixel's green channel to `factor` * 255 (true)
+     */
+    green(factor: number, absolute?: boolean): this;
+    /**
+     * Scales or sets the blue channel
+     * @param factor The factor to multiply the channel with (>= 0, results are clamped), or the value (0..1) to set it to
+     * @param absolute Whether to scale the current value (false) or set every pixel's blue channel to `factor` * 255 (true)
+     */
+    blue(factor: number, absolute?: boolean): this;
+    /**
+     * Sets the brightness of the image
+     * @param value The lightness to apply (0..1)
+     * @param absolute Whether to scale the current lightness (false) or just set the new lightness (true)
+     */
+    lightness(value: number, absolute?: boolean): this;
+    /**
+     * Sets the saturation of the image
+     * @param value The saturation to apply (0..1)
+     * @param absolute Whether to scale the current saturation (false) or just set the new saturation (true)
+     */
+    saturation(value: number, absolute?: boolean): this;
+    /**
+     * Composites (overlays) the source onto this image at the specified coordinates
+     * @param source The image to place
+     * @param [x=0] The x position to place the image at
+     * @param [y=0] The y position to place the image at
+     * @param options Opacity and blend mode, see {@link CompositeOptions}
+     */
+    composite(source: Image, x?: number, y?: number, options?: CompositeOptions): this;
+    /**
+     * Inverts the images colors
+     */
+    invert(): this;
+    /**
+     * Inverts the images lightness (HSL), keeping hue and saturation: dark colors become light and vice versa
+     */
+    invertLightness(): 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
+     */
+    invertValue(): this;
+    /**
+     * Shifts the images hue
+     * @param degrees How many degrees to shift the hue by
+     */
+    hueShift(degrees: number): this;
+    /**
+     * Blurs the image with a gaussian blur (transparent pixels don't bleed their color)
+     * @param radius The blur radius: the gaussian's standard deviation in pixels, like CSS' blur()
+     */
+    blur(radius: number): this;
+    /**
+     * Sharpens the image with an unsharp mask: the difference to a blurred copy is amplified
+     * @param [amount=1] How strongly to sharpen (0 does nothing)
+     * @param [radius=1] The radius of the blur the image is compared with (larger values sharpen coarser details)
+     */
+    sharpen(amount?: number, radius?: number): this;
+    /**
+     * Multiplies the color channels, e.g. 1.2 makes the image 20% brighter
+     * @param factor The factor (>= 0, 1 keeps the image)
+     */
+    brightness(factor: number): this;
+    /**
+     * Scales the color channels' distance from mid grey, e.g. 1.5 increases the contrast, 0.5 reduces it
+     * @param factor The factor (>= 0, 1 keeps the image, 0 makes it grey)
+     */
+    contrast(factor: number): this;
+    /**
+     * Applies a gamma correction, values above 1 brighten the dark tones, values below 1 darken them
+     * @param gamma The gamma (> 0, 1 keeps the image)
+     */
+    gamma(gamma: number): this;
+    /**
+     * Converts the image to greyscale by its luma (ITU-R 601, like Pillow), keeping the alpha
+     */
+    greyscale(): this;
+    /**
+     * Applies a sepia tone
+     */
+    sepia(): this;
+    /**
+     * Makes a color transparent, like GIMP's "Color to Alpha": the color is removed from every pixel and replaced by
+     * transparency, so pixels that are partly the color (e.g. antialiased edges against a background) become
+     * semi-transparent instead of keeping a fringe of it.
+     * The color is removed everywhere in the image, not only from a connected background: removing a white
+     * background also makes white areas inside the subject (e.g. eyes in a logo) transparent
+     * @param color The color to remove, by default the color of the top left pixel (e.g. a background)
+     * @param options See {@link ColorToAlphaOptions}
+     */
+    colorToAlpha(color?: Color, options?: ColorToAlphaOptions): this;
+    /**
+     * Gets the average color of the image, weighting each pixel by its opacity
+     * @returns The average color (fully opaque), black for fully transparent images
+     */
+    averageColor(): Color;
+    /**
+     * 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
+     * @param options Which colors to ignore, see {@link DominantColorOptions}
+     * @return 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(options?: DominantColorOptions): Color;
+    /**
+     * Gets the image's dominant color, see {@link Image.dominantColor | the variant with options}
+     * @param ignoreBlack Whether to ignore dark colors (all channels below the threshold). Default: `true`
+     * @param ignoreWhite Whether to ignore light colors (all channels above 255 minus the threshold). Default: `true`
+     * @param bwThreshold The black/white threshold (0-64, in steps of 4 channel values). Default: `15`
+     * @return The image's dominant color (fully opaque)
+     */
+    dominantColor(ignoreBlack?: boolean, ignoreWhite?: boolean, bwThreshold?: number): Color;
+    /**
+     * Rotates the image counterclockwise by the given amount of degrees
+     * @param angle The angle to rotate the image for (in degrees)
+     * @param options See {@link RotateOptions}
+     */
+    rotate(angle: number, options?: RotateOptions): this;
+    /**
+     * Rotates the image counterclockwise by the given amount of degrees
+     * @param angle The angle to rotate the image for (in degrees)
+     * @param resize Whether to resize the image so it fits all pixels or just ignore outlying pixels. Default: `true`
+     */
+    rotate(angle: number, resize?: boolean): this;
+    /**
+     * Flips / mirrors the image horizontally or vertically
+     * @param direction The direction to flip
+     */
+    flip(direction: 'horizontal' | 'vertical'): this;
+    /**
+     * Creates a multi-point gradient generator
+     * @param colors The gradient points to use (e.g. `{0: 0xff0000ff, 1: 0x00ff00ff}`)
+     * @return The gradient generator. The function argument is the position in the gradient (0..1).
+     */
+    static gradient(colors: Record<number, Color>): (position: number) => Color;
+    /**
+     * Rounds the images corners, with antialiased edges
+     * @param [radius=min(width,height)/4] The radius of the corners
+     */
+    roundCorners(radius?: number): this;
+    /**
+     * Applies a fisheye (barrel distortion) effect
+     * @param [strength=2] The distortion strength (exponent of the radial mapping), higher values bulge the center more
+     */
+    fisheye(strength?: number): this;
+    /**
+     * 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
+     * @param compression The compression level (0-9). Default: `1`
+     * @param metadata Text metadata to include
+     * @return The encoded data
+     */
+    encode(compression?: number, metadata?: PNGMetadata): Promise<Uint8Array>;
+    /**
+     * Encodes the image into a PNG with compression level 1
+     * @param metadata Text metadata to include
+     * @return The encoded data
+     */
+    encode(metadata?: PNGMetadata): Promise<Uint8Array>;
+    /**
+     * Encodes the image into a PNG, an alias of {@link Image.encode}
+     */
+    encodePNG(compression?: number, metadata?: PNGMetadata): Promise<Uint8Array>;
+    encodePNG(metadata?: PNGMetadata): Promise<Uint8Array>;
+    /**
+     * Encodes the image into a JPEG
+     * @param [quality=90] The JPEG quality to use (1-100), chroma subsampling is disabled above 90
+     */
+    encodeJPEG(quality?: number): Promise<Uint8Array>;
+    /**
+     * Encodes the image as lossless WebP (usually 20-30% smaller than PNG, but slower to encode)
+     */
+    encodeWebP(): Promise<Uint8Array>;
+    /**
+     * Encodes the image as run length encoded TGA (32 bit, or 24 bit if the image is opaque)
+     */
+    encodeTGA(): Promise<Uint8Array>;
+    /**
+     * Decodes an image (PNG, JPEG, TIFF, WebP or TGA). For APNGs this is the default image; animated WebPs and GIFs
+     * have no single image, decode those with {@link Animation.decode}
+     * @param input The binary data to decode
+     * @param options See {@link 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
+     * @return The decoded image
+     */
+    static decode(input: BinaryData, options?: DecodeOptions): Promise<Image>;
+    /**
+     * Scale the SVG by the given amount. For use with {@link Image.renderSVG}
+     */
+    static get SVG_MODE_SCALE(): 1;
+    /**
+     * Scale the SVG to fit the given width. For use with {@link Image.renderSVG}
+     */
+    static get SVG_MODE_WIDTH(): 2;
+    /**
+     * Scale the SVG to fit the given height. For use with {@link Image.renderSVG}
+     */
+    static get SVG_MODE_HEIGHT(): 3;
+    /**
+     * 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
+     * @param svg The SVG content
+     * @param size The size to use
+     * @param mode The SVG resizing mode to use (one of {@link SVG_MODE_SCALE}, {@link SVG_MODE_WIDTH}, {@link SVG_MODE_HEIGHT})
+     * @return The rendered SVG graphic
+     */
+    static renderSVG(svg: string | BinaryData, size?: number, mode?: SVGScaleMode): Promise<Image>;
+    /**
+     * Creates a new image containing the rendered text.
+     * @param font TrueType (ttf/ttc) or OpenType (otf) font buffer to use
+     * @param size Font size in pixels (per em)
+     * @param text Text to render
+     * @param [color=0xffffffff] Text color to use
+     * @param [layout] The text layout to use
+     * @param style Outline, see {@link TextStyle}; the image grows by the outline width on every side
+     * @return The rendered text
+     */
+    static renderText(font: BinaryData, size: number, text: string, color?: Color, layout?: TextLayout, style?: TextStyle): Promise<Image>;
+}