image-in-browser/lib/draw/draw.d.ts

Package for encoding / decoding images, transforming images, applying filters, drawing primitives on images on the client side (no need for server Node.js)

/** @format */
import { Channel } from '../color/channel.js';
import { Color } from '../color/color.js';
import { Line } from '../common/line.js';
import { Point } from '../common/point.js';
import { Rectangle } from '../common/rectangle.js';
import { MemoryImage } from '../image/image.js';
import { BlendMode } from './blend-mode.js';
/**
 * Options for drawing a line using Xiaolin Wu's algorithm.
 */
interface DrawLineWuOptions {
    /** The image to draw on. */
    image: MemoryImage;
    /** The line to draw. */
    line: Line;
    /** The color to use for drawing. */
    color: Color;
    /** The channel to use for masking. */
    maskChannel?: Channel;
    /** The mask image. */
    mask?: MemoryImage;
}
/**
 * Options for drawing a line.
 */
export interface DrawLineOptions extends DrawLineWuOptions {
    /** Whether to use antialiasing. */
    antialias?: boolean;
    /** The thickness of the line. */
    thickness?: number;
}
/**
 * Options for drawing a circle.
 */
export interface DrawCircleOptions {
    /** The image to draw on. */
    image: MemoryImage;
    /** The center point of the circle. */
    center: Point;
    /** The radius of the circle. */
    radius: number;
    /** The color to use for drawing. */
    color: Color;
    /** Whether to use antialiasing. */
    antialias?: boolean;
    /** The mask image. */
    mask?: MemoryImage;
    /** The channel to use for masking. */
    maskChannel?: Channel;
}
/**
 * Options for drawing a pixel.
 */
export interface DrawPixelOptions {
    /** The image to draw on. */
    image: MemoryImage;
    /** The position of the pixel. */
    pos: Point;
    /** The color to use for drawing. */
    color: Color;
    /** The filter color to apply. */
    filter?: Color;
    /** The alpha value to use. */
    alpha?: number;
    /** The blend mode to use. */
    blend?: BlendMode;
    /** Whether to use linear blending. */
    linearBlend?: boolean;
    /** The mask image. */
    mask?: MemoryImage;
    /** The channel to use for masking. */
    maskChannel?: Channel;
}
/**
 * Options for drawing a polygon.
 */
export interface DrawPolygonOptions {
    /** The image to draw on. */
    image: MemoryImage;
    /** The vertices of the polygon. */
    vertices: Point[];
    /** The color to use for drawing. */
    color: Color;
    /** Whether to use antialiasing. */
    antialias?: boolean;
    /** The thickness of the polygon's edges. */
    thickness?: number;
    /** The channel to use for masking. */
    maskChannel?: Channel;
    /** The mask image. */
    mask?: MemoryImage;
}
/**
 * Options for drawing a rectangle.
 */
export interface DrawRectOptions {
    /** The image to draw on. */
    image: MemoryImage;
    /** The rectangle to draw. */
    rect: Rectangle;
    /** The color to use for drawing. */
    color: Color;
    /** The thickness of the rectangle's edges. */
    thickness?: number;
    /** The radius for rounded corners. */
    radius?: number;
    /** The channel to use for masking. */
    maskChannel?: Channel;
    /** The mask image. */
    mask?: MemoryImage;
}
/**
 * Options for filling a circle.
 */
export interface FillCircleOptions {
    /** The image to draw on. */
    image: MemoryImage;
    /** The center point of the circle. */
    center: Point;
    /** The radius of the circle. */
    radius: number;
    /** The color to use for filling. */
    color: Color;
    /** Whether to use antialiasing. */
    antialias?: boolean;
    /** The channel to use for masking. */
    maskChannel?: Channel;
    /** The mask image. */
    mask?: MemoryImage;
}
/**
 * Options for flood filling an area.
 */
export interface FillFloodOptions {
    /** The image to draw on. */
    image: MemoryImage;
    /** The starting point for the flood fill. */
    start: Point;
    /** The color to use for filling. */
    color: Color;
    /** The threshold for color comparison. */
    threshold?: number;
    /** Whether to compare alpha values. */
    compareAlpha?: boolean;
    /** The channel to use for masking. */
    maskChannel?: Channel;
    /** The mask image. */
    mask?: MemoryImage;
}
/**
 * Options for creating a mask using flood fill.
 */
export interface MaskFloodOptions {
    /** The image to draw on. */
    image: MemoryImage;
    /** The starting point for the flood fill. */
    start: Point;
    /** The threshold for color comparison. */
    threshold?: number;
    /** Whether to compare alpha values. */
    compareAlpha?: boolean;
    /** The value to fill the mask with. */
    fillValue?: number;
}
/**
 * Options for filling a polygon.
 */
export interface FillPolygonOptions {
    /** The image to draw on. */
    image: MemoryImage;
    /** The vertices of the polygon. */
    vertices: Point[];
    /** The color to use for filling. */
    color: Color;
    /** The channel to use for masking. */
    maskChannel?: Channel;
    /** The mask image. */
    mask?: MemoryImage;
}
/**
 * Options for filling a rectangle.
 */
export interface FillRectOptions {
    /** The image to draw on. */
    image: MemoryImage;
    /** The rectangle to fill. */
    rect: Rectangle;
    /** The color to use for filling. */
    color: Color;
    /** The radius for rounded corners. */
    radius?: number;
    /** Whether to use alpha blending. */
    alphaBlend?: boolean;
    /** The mask image. */
    mask?: MemoryImage;
    /** The channel to use for masking. */
    maskChannel?: Channel;
}
/**
 * Options for filling an image.
 */
export interface FillOptions {
    /** The image to fill. */
    image: MemoryImage;
    /** The color to use for filling. */
    color: Color;
    /** The channel to use for masking. */
    maskChannel?: Channel.luminance;
    /** The mask image. */
    mask?: MemoryImage;
}
/**
 * Options for compositing an image.
 */
export interface CompositeImageOptions {
    /** The destination image. */
    dst: MemoryImage;
    /** The source image. */
    src: MemoryImage;
    /** The x-coordinate in the destination image. */
    dstX?: number;
    /** The y-coordinate in the destination image. */
    dstY?: number;
    /** The width of the destination area. */
    dstW?: number;
    /** The height of the destination area. */
    dstH?: number;
    /** The x-coordinate in the source image. */
    srcX?: number;
    /** The y-coordinate in the source image. */
    srcY?: number;
    /** The width of the source area. */
    srcW?: number;
    /** The height of the source area. */
    srcH?: number;
    /** The blend mode to use. */
    blend?: BlendMode;
    /** Whether to use linear blending. */
    linearBlend?: boolean;
    /** Whether to center the source image in the destination image. */
    center?: boolean;
    /** The mask image. */
    mask?: MemoryImage;
    /** The channel to use for masking. */
    maskChannel?: Channel;
}
/**
 * Abstract class for drawing operations.
 */
export declare abstract class Draw {
    /**
     * Calculates the circumference points of a circle on a given image.
     *
     * @param {MemoryImage} image - The image on which the circle is to be drawn.
     * @param {Point} center - The center point of the circle.
     * @param {number} radius - The radius of the circle.
     * @returns {Point[]} An array of points representing the circumference of the circle.
     *         Returns an empty array if the radius is negative or if the circle
     *         would be completely outside the bounds of the image.
     */
    private static calculateCircumference;
    /**
     * Draws an anti-aliased circle on the provided image.
     *
     * @param {DrawAntialiasCircleOptions} opt - The options for drawing the circle.
     * @param {MemoryImage} opt.image - The image on which to draw the circle.
     * @param {number} opt.x - The x-coordinate of the circle's center.
     * @param {number} opt.y - The y-coordinate of the circle's center.
     * @param {number} opt.radius - The radius of the circle.
     * @param {Color} opt.color - The color of the circle.
     * @param {CircleQuadrant} [opt.quadrants] - The quadrants of the circle to draw.
     * @param {Channel} [opt.maskChannel] - The mask channel to use.
     * @param {MemoryImage} [opt.mask] - The mask to apply.
     * @returns {MemoryImage} The image with the drawn circle.
     */
    private static drawAntialiasCircle;
    /**
     * Draws a line on an image using Wu's line algorithm, which provides anti-aliased lines.
     *
     * @param {DrawLineWuOptions} opt - The options for drawing the line, including the image, line coordinates, color, and mask options.
     * @returns {MemoryImage} The image with the line drawn on it.
     */
    private static drawLineWu;
    /**
     * Sets the alpha value of a given color.
     *
     * @param {Color} c - The color object whose alpha value is to be set.
     * @param {number} a - The alpha value to set (typically between 0 and 1).
     * @returns {Color} The color object with the updated alpha value.
     */
    private static setAlpha;
    /**
     * Calculates the distance between two colors.
     *
     * @param {number[]} c1 - The first color represented as an array of numbers [R, G, B, A].
     * @param {number[]} c2 - The second color represented as an array of numbers [R, G, B, A].
     * @param {boolean} compareAlpha - A boolean indicating whether to include the alpha channel in the comparison.
     * @returns {number} The distance between the two colors.
     */
    private static colorDistance;
    /**
     * Tests the color distance between a pixel in an image and a reference color.
     *
     * @param {MemoryImage} src - The source image from which the pixel is taken.
     * @param {number} x - The x-coordinate of the pixel.
     * @param {number} y - The y-coordinate of the pixel.
     * @param {number[]} refColor - The reference color to compare against, in LAB color space.
     *                   If it contains an alpha value, it should be included as the fourth element.
     * @param {number} threshold - The threshold distance to determine if the pixel color is sufficiently different from the reference color.
     * @returns {boolean} `true` if the color distance is greater than the threshold, otherwise `false`.
     */
    private static testPixelLabColorDistance;
    /**
     * Fills a rectangular block in the image starting from the specified coordinates.
     * This function uses a flood fill algorithm to fill contiguous areas of the image.
     *
     * @param {MemoryImage} src - The source image to be filled.
     * @param {number} x - The starting x-coordinate for the fill operation.
     * @param {number} y - The starting y-coordinate for the fill operation.
     * @param {FillFloodTestPixel} array - A function that tests if a pixel should be filled.
     * @param {FillFloodMarkPixel} mark - A function that marks a pixel as filled.
     * @param {Uint8Array} visited - A Uint8Array that keeps track of visited pixels.
     */
    private static fill4Core;
    /**
     * Fills a region in the given MemoryImage starting from the specified coordinates (x, y).
     * The function attempts to move as far as possible to the upper-left corner before filling.
     *
     * @param src The source MemoryImage to be filled.
     * @param x The x-coordinate to start filling from.
     * @param y The y-coordinate to start filling from.
     * @param array A function that tests if a pixel should be filled.
     * @param mark A function that marks a pixel as filled.
     * @param visited A Uint8Array that keeps track of visited pixels.
     */
    private static fill4;
    /**
     * Composites an image directly onto another image with optional masking.
     *
     * @param src - The source image to composite from.
     * @param dst - The destination image to composite to.
     * @param dstX - The x-coordinate in the destination image where compositing starts.
     * @param dstY - The y-coordinate in the destination image where compositing starts.
     * @param dstW - The width of the area to composite.
     * @param dstH - The height of the area to composite.
     * @param xCache - A cache of x-coordinates for the source image.
     * @param yCache - A cache of y-coordinates for the source image.
     * @param maskChannel - The channel of the mask image to use for compositing.
     * @param mask - An optional mask image to control compositing.
     */
    private static imgDirectComposite;
    /**
     * Composites an image onto another image at a specified position and size.
     *
     * @param src - The source image to composite from.
     * @param dst - The destination image to composite onto.
     * @param dstX - The x-coordinate in the destination image where the composite starts.
     * @param dstY - The y-coordinate in the destination image where the composite starts.
     * @param dstW - The width of the area in the destination image to composite onto.
     * @param dstH - The height of the area in the destination image to composite onto.
     * @param xCache - An array of x-coordinates for caching.
     * @param yCache - An array of y-coordinates for caching.
     * @param blend - The blend mode to use for compositing.
     * @param linearBlend - Whether to use linear blending.
     * @param maskChannel - The channel to use for masking.
     * @param mask - An optional mask image.
     */
    private static imgComposite;
    /**
     * Draws a circle on the provided image with the specified options.
     *
     * @param {DrawCircleOptions} opt - The options for drawing the circle, including:
     * @param {MemoryImage} opt.image - The image on which to draw the circle.
     * @param {Point} opt.center - The center point of the circle.
     * @param {number} opt.radius - The radius of the circle.
     * @param {Color} opt.color - The color of the circle.
     * @param {MemoryImage} [opt.mask] - An optional mask to apply.
     * @param {Channel} [opt.maskChannel] - The channel of the mask to use (default is luminance).
     * @param {boolean} [opt.antialias] - Whether to apply antialiasing (default is false).
     * @returns {MemoryImage} The image with the drawn circle.
     */
    static drawCircle(opt: DrawCircleOptions): MemoryImage;
    /**
     * Fills a circle on the given image with the specified options.
     *
     * @param {FillCircleOptions} opt - The options for filling the circle.
     * @param {MemoryImage} opt.image - The image to draw on.
     * @param {Point} opt.center - The center point of the circle.
     * @param {number} opt.radius - The radius of the circle.
     * @param {Color} opt.color - The color to fill the circle with.
     * @param {boolean} [opt.antialias=false] - Whether to apply antialiasing (optional, default is false).
     * @param {Channel} [opt.maskChannel=Channel.luminance] - The channel to use for masking (optional, default is luminance).
     * @param {MemoryImage} [opt.mask] - The mask to apply (optional).
     * @returns {MemoryImage} The image with the filled circle.
     */
    static fillCircle(opt: FillCircleOptions): MemoryImage;
    /**
     * Draws a line on the given image based on the provided options.
     *
     * @param {DrawLineOptions} opt The options for drawing the line.
     * @param {MemoryImage} opt.image The image on which the line will be drawn.
     * @param {Line} opt.line The line coordinates.
     * @param {Color} opt.color The color of the line.
     * @param {number} [opt.thickness=1] The thickness of the line.
     * @param {boolean} [opt.antialias=false] Whether to apply antialiasing.
     * @param {Channel} [opt.maskChannel=Channel.luminance] The mask channel to use.
     * @param {MemoryImage} [opt.mask] The mask to apply.
     * @returns {MemoryImage} The modified image with the drawn line.
     */
    static drawLine(opt: DrawLineOptions): MemoryImage;
    /**
     * Draws a pixel on the given image with various blending modes and options.
     *
     * @param {DrawPixelOptions} opt The options for drawing the pixel, including:
     * @param {MemoryImage} opt.image The image to draw on.
     * @param {Position} opt.pos The position to draw the pixel.
     * @param {Color} opt.color The color of the pixel.
     * @param {BlendMode} [opt.blend=BlendMode.alpha] The blending mode to use (default is BlendMode.alpha).
     * @param {boolean} [opt.linearBlend=false] Whether to use linear blending (default is false).
     * @param {MemoryImage} [opt.mask] An optional mask image.
     * @param {Channel} [opt.maskChannel=Channel.luminance] The channel of the mask to use (default is Channel.luminance).
     * @param {Color} [opt.filter] An optional color filter.
     * @param {number} [opt.alpha] An optional alpha value.
     * @returns {MemoryImage} The modified image with the pixel drawn.
     */
    static drawPixel(opt: DrawPixelOptions): MemoryImage;
    /**
     * Draws a polygon on the given image based on the provided options.
     *
     * @param {DrawPolygonOptions} opt The options for drawing the polygon.
     * @param {MemoryImage} opt.image The image on which to draw the polygon.
     * @param {Array<Point>} opt.vertices An array of points representing the vertices of the polygon.
     * @param {Color} opt.color The color to use for the polygon.
     * @param {boolean} [opt.antialias=false] Optional. Whether to apply antialiasing. Defaults to false.
     * @param {number} [opt.thickness=1] Optional. The thickness of the polygon lines. Defaults to 1.
     * @param {Channel} [opt.maskChannel=Channel.luminance] Optional. The channel to use for masking. Defaults to luminance.
     * @param {MemoryImage} [opt.mask] Optional. A mask to apply when drawing.
     * @returns {MemoryImage} The image with the polygon drawn on it.
     */
    static drawPolygon(opt: DrawPolygonOptions): MemoryImage;
    /**
     * Draw a rectangle in the image with the specified options.
     *
     * @param {DrawRectOptions} opt - Options for drawing the rectangle.
     * @param {MemoryImage} opt.image - The image on which to draw the rectangle.
     * @param {Rectangle} opt.rect - The rectangle dimensions and position.
     * @param {Color} opt.color - The color of the rectangle.
     * @param {number} [opt.thickness=1] - The thickness of the rectangle's border. Defaults to 1.
     * @param {number} [opt.radius=0] - The radius for rounded corners. Defaults to 0.
     * @param {Channel} [opt.maskChannel=Channel.luminance] - The channel to use for masking. Defaults to Channel.luminance.
     * @param {MemoryImage} [opt.mask] - An optional mask to apply when drawing.
     * @returns {MemoryImage} The modified image with the drawn rectangle.
     */
    static drawRect(opt: DrawRectOptions): MemoryImage;
    /**
     * Fills an area of an image with a specified color using the flood fill algorithm.
     *
     * @param {FillFloodOptions} opt - Options for the flood fill operation.
     * @param {MemoryImage} opt.image - The image to be filled.
     * @param {Pixel} opt.start - The starting pixel coordinates for the flood fill.
     * @param {Pixel} opt.color - The color to fill the area with.
     * @param {number} [opt.threshold=0] - The color distance threshold for the fill.
     * @param {boolean} [opt.compareAlpha=false] - Whether to compare the alpha channel.
     * @param {Channel} [opt.maskChannel=Channel.luminance] - The channel to use for masking.
     * @param {MemoryImage} [opt.mask] - An optional mask image.
     * @returns {MemoryImage} The modified image after the flood fill operation.
     */
    static fillFlood(opt: FillFloodOptions): MemoryImage;
    /**
     * Fills a polygon on the given image with the specified options.
     *
     * @param {FillPolygonOptions} opt - The options for filling the polygon.
     * @param {MemoryImage} opt.image - The image to draw on.
     * @param {Array<Point>} opt.vertices - An array of points representing the vertices of the polygon.
     * @param {Color} opt.color - The color to fill the polygon with.
     * @param {MemoryImage} [opt.mask] - An optional mask to apply.
     * @param {Channel} [opt.maskChannel] - The channel of the mask to use (default is luminance).
     * @returns {MemoryImage} - The modified image with the polygon filled.
     */
    static fillPolygon(opt: FillPolygonOptions): MemoryImage;
    /**
     * Fills a rectangular area of an image with a specified color, with options for
     * alpha blending, masking, and rounded corners.
     *
     * @param {FillRectOptions} opt - The options for filling the rectangle.
     * @param {MemoryImage} opt.image - The image to be modified.
     * @param {Rectangle} opt.rect - The rectangle area to fill.
     * @param {Color} opt.color - The color to fill the rectangle with.
     * @param {number} [opt.radius] - The radius for rounded corners (optional).
     * @param {boolean} [opt.alphaBlend] - Whether to use alpha blending (optional).
     * @param {MemoryImage} [opt.mask] - An optional mask image to control blending.
     * @param {Channel} [opt.maskChannel] - The channel of the mask image to use (optional).
     * @returns {MemoryImage} - The modified image.
     */
    static fillRect(opt: FillRectOptions): MemoryImage;
    /**
     * Fills the given image with the specified color, optionally using a mask.
     *
     * @param {FillOptions} opt - The options for filling the image.
     * @param {MemoryImage} opt.image - The MemoryImage to be filled.
     * @param {Color} opt.color - The color to fill the image with.
     * @param {MemoryImage} [opt.mask] - (Optional) A mask image to control the fill operation.
     * @param {Channel} [opt.maskChannel] - (Optional) The channel of the mask image to use (default is luminance).
     * @returns {MemoryImage} - The filled MemoryImage.
     */
    static fill(opt: FillOptions): MemoryImage;
    /**
     * Create a mask describing the 4-connected shape containing **start** in the **image**.
     *
     * @param {MaskFloodOptions} opt - Options for the maskFlood function.
     * @param {MemoryImage} opt.image - The image in which the mask will be created.
     * @param {Point} opt.start - The starting point for the flood fill.
     * @param {number} [opt.threshold] - The color distance threshold for the flood fill.
     * @param {boolean} [opt.compareAlpha] - Whether to compare the alpha channel in the color distance calculation.
     * @param {number} [opt.fillValue] - The value to fill the mask with.
     * @returns {Uint8Array} A Uint8Array representing the mask.
     */
    static maskFlood(opt: MaskFloodOptions): Uint8Array;
    /**
     * Overlay the image **src** onto the image **dst**.
     *
     * Specifically, compositeImage will take a rectangular section from **src** with
     * dimensions **srcW** by **srcH** starting at (**srcX**, **srcY**) and place it
     * into a rectangular section of **dst** with dimensions **dstW** by **dstH** starting
     * at (**dstX**, **dstY**).
     *
     * If the source and destination coordinates and dimensions differ, the image fragment
     * will be appropriately stretched or shrunk. The coordinates refer to the upper left corner.
     * This function can also be used to copy regions within the same image (if **dst** is the same as **src**),
     * but overlapping regions may produce unpredictable results.
     *
     * If **center** is true, the **src** will be centered within **dst**.
     *
     * @param {CompositeImageOptions} opt - Options for compositing the image.
     * @param {MemoryImage} opt.dst - The destination image.
     * @param {number} [opt.dstX=0] - The x-coordinate in the destination image.
     * @param {number} [opt.dstY=0] - The y-coordinate in the destination image.
     * @param {number} [opt.srcX=0] - The x-coordinate in the source image.
     * @param {number} [opt.srcY=0] - The y-coordinate in the source image.
     * @param {number} [opt.srcW=opt.src.width] - The width of the source image area.
     * @param {number} [opt.srcH=opt.src.height] - The height of the source image area.
     * @param {number} [opt.dstW] - The width of the destination image area.
     * @param {number} [opt.dstH] - The height of the destination image area.
     * @param {BlendMode} [opt.blend=BlendMode.alpha] - The blending mode to use.
     * @param {boolean} [opt.linearBlend=false] - Whether to use linear blending.
     * @param {boolean} [opt.center=false] - Whether to center the source image in the destination.
     * @param {Channel} [opt.maskChannel=Channel.luminance] - The channel to use for the mask.
     * @param {ImageMask} [opt.mask] - The mask to apply during compositing.
     */
    static compositeImage(opt: CompositeImageOptions): MemoryImage;
}
export {};