imagescript 3.0.0 → 3.2.0

package/dist/image.d.ts

@@ -1,5 +1,6 @@
 import { BinaryData } from './util/mem.js';
 import { TextLayout } from './text-layout.js';
+import { Metadata } from './metadata.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 */
@@ -12,14 +13,84 @@ export type SVGScaleMode = 1 | 2 | 3;
 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 {
+    /** The x position to place the source at, if the options are the second argument. Default: `0` */
+    x?: number;
+    /** The y position to place the source at, if the options are the second argument. Default: `0` */
+    y?: number;
     /** Opacity of the source (0..1). Default: `1` */
     opacity?: number;
     /** How the colors are mixed. Default: `'normal'` */
     mode?: BlendMode;
 }
+/** Options of {@link Image.scale}, {@link Image.resize}, {@link Image.contain}, {@link Image.fit} and {@link Image.cover} */
+export interface ResizeOptions {
+    /** The resizing mode. Default: {@link Image.RESIZE_BILINEAR} */
+    mode?: ResizeMode;
+}
+/**
+ * Options of {@link Image.opacity}, {@link Image.red}, {@link Image.green}, {@link Image.blue}, {@link Image.lightness}
+ * and {@link Image.saturation}
+ */
+export interface AdjustOptions {
+    /** Whether to set the value (true) or scale the current one (false). Default: `false` */
+    absolute?: boolean;
+}
+/** Options of {@link Image.sharpen} */
+export interface SharpenOptions {
+    /** How strongly to sharpen (0 does nothing). Default: `1` */
+    amount?: number;
+    /** The radius of the blur the image is compared with (larger values sharpen coarser details). Default: `1` */
+    radius?: number;
+}
+/** Options of {@link Image.encode} */
+export interface PNGEncodeOptions {
+    /** The compression level (0-9). Default: `1` */
+    compression?: number;
+    /** Metadata to include, see {@link Metadata} */
+    metadata?: Metadata;
+}
+/** Options of {@link Image.encodeJPEG} */
+export interface JPEGEncodeOptions {
+    /** The JPEG quality (1-100), chroma subsampling is disabled above 90. Default: `90` */
+    quality?: number;
+    /** Metadata to include, see {@link Metadata} */
+    metadata?: Metadata;
+}
+/** Options of {@link Image.encodeWebP} and {@link Image.encodeTGA} */
+export interface EncodeOptions {
+    /** Metadata to include, see {@link Metadata} */
+    metadata?: Metadata;
+}
+/** Options of {@link Image.roundCorners} */
+export interface RoundCornersOptions {
+    /** The radius of the corners. Default: a quarter of the smaller side */
+    radius?: number;
+}
+/** Options of {@link Image.fisheye} */
+export interface FisheyeOptions {
+    /** The distortion strength (exponent of the radial mapping), higher values bulge the center more. Default: `2` */
+    strength?: number;
+}
+/** Options of {@link Image.renderSVG} */
+export interface SVGOptions {
+    /** The scale, or the width or height in pixels, see `mode`. Default: `1` */
+    size?: number;
+    /**
+     * What `size` is: one of {@link Image.SVG_MODE_SCALE}, {@link Image.SVG_MODE_WIDTH}, {@link Image.SVG_MODE_HEIGHT}.
+     * Default: {@link Image.SVG_MODE_SCALE}
+     */
+    mode?: SVGScaleMode;
+}
+/** Options of {@link Image.renderText}: the text color and layout, and its style (see {@link TextStyle}) */
+export interface TextOptions extends TextStyle {
+    /** The text color. Default: `0xffffffff` */
+    color?: Color;
+    /** The text layout. Default: `new TextLayout()` */
+    layout?: TextLayout;
+}
 /** Options of {@link Image.decode} */
 export interface DecodeOptions {
-    /** Whether to rotate/mirror JPEGs, TIFFs and PNGs as their orientation tag (Exif or XMP) says. Default: `true` */
+    /** 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} */
@@ -28,6 +99,12 @@ export interface TextStyle {
     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 {
@@ -50,29 +127,26 @@ export interface RotateOptions {
     /** Whether to resize the image so it fits all pixels or just ignore outlying pixels. Default: `true` */
     resize?: boolean;
 }
-/** 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;
+/** Options of {@link Image.trim} */
+export interface TrimOptions {
+    /**
+     * How far (0-1) a pixel's channels may be from the color for it to be trimmed, e.g. for JPEG artifacts or
+     * antialiasing. Default: `0`
+     */
+    tolerance?: number;
+}
+/** 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
+ * @deprecated Use {@link Metadata}, which all encoders take
+ */
+export type PNGMetadata = Metadata;
 /**
  * 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
@@ -224,12 +298,27 @@ export declare class Image {
      * 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 options See {@link ResizeOptions}
+     */
+    scale(factor: number, options?: ResizeOptions): this;
     /**
      * 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 options See {@link ResizeOptions}
+     * @returns The resized image
+     */
+    resize(width: number, height: number, options?: ResizeOptions): this;
     /**
      * Resizes the image to the given dimensions.
      * Use {@link Image.RESIZE_AUTO} as either width or height to automatically preserve the aspect ratio.
@@ -239,6 +328,15 @@ export declare class Image {
      * @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 options See {@link ResizeOptions}
+     * @returns The resized image
+     */
+    contain(width: number, height: number, options?: ResizeOptions): 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.
@@ -248,6 +346,15 @@ export declare class Image {
      * @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 options See {@link ResizeOptions}
+     * @returns The resized image
+     */
+    fit(width: number, height: number, options?: ResizeOptions): 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.
@@ -257,6 +364,15 @@ export declare class Image {
      * @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 options See {@link ResizeOptions}
+     * @returns The resized image
+     */
+    cover(width: number, height: number, options?: ResizeOptions): this;
     /**
      * Resizes the image so it covers the given bounding box, cropping the overflowing edges.
      * Always returns the exact dimensions of the bounding box.
@@ -275,6 +391,15 @@ export declare class Image {
      * @param height The new images height
      */
     crop(x: number, y: number, width: number, height: number): this;
+    /**
+     * Removes borders of one color, e.g. the empty space around rendered text or around a logo on a solid background.
+     * Frames keep their position: their offsets move by the trimmed amount. An image that only has the color stays
+     * unchanged
+     * @param color The border color, by default the color of the top left pixel. Fully transparent pixels count as the
+     *     same color whatever their RGB values
+     * @param options See {@link TrimOptions}
+     */
+    trim(color?: Color, options?: TrimOptions): this;
     /**
      * Draws a box at the specified coordinates (0-based), clipped to the image
      * @param x The x offset
@@ -303,42 +428,84 @@ export declare class Image {
      * @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 options See {@link AdjustOptions}
+     */
+    opacity(opacity: number, options?: AdjustOptions): 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 options See {@link AdjustOptions}
+     */
+    red(factor: number, options?: AdjustOptions): 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 options See {@link AdjustOptions}
+     */
+    green(factor: number, options?: AdjustOptions): 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 options See {@link AdjustOptions}
+     */
+    blue(factor: number, options?: AdjustOptions): 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 options See {@link AdjustOptions}
+     */
+    lightness(value: number, options?: AdjustOptions): 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 options See {@link AdjustOptions}
+     */
+    saturation(value: number, options?: AdjustOptions): 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
+     * @param source The image to place
+     * @param options Position, opacity and blend mode, see {@link CompositeOptions}
+     */
+    composite(source: Image, options?: CompositeOptions): this;
     /**
      * Composites (overlays) the source onto this image at the specified coordinates
      * @param source The image to place
@@ -370,6 +537,11 @@ export declare class Image {
      * @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 options See {@link SharpenOptions}
+     */
+    sharpen(options?: SharpenOptions): 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)
@@ -399,6 +571,16 @@ export declare class Image {
      * 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
@@ -443,11 +625,21 @@ export declare class Image {
      * @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 options See {@link RoundCornersOptions}
+     */
+    roundCorners(options?: RoundCornersOptions): this;
     /**
      * 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 options See {@link FisheyeOptions}
+     */
+    fisheye(options?: FisheyeOptions): this;
     /**
      * Applies a fisheye (barrel distortion) effect
      * @param [strength=2] The distortion strength (exponent of the radial mapping), higher values bulge the center more
@@ -456,29 +648,52 @@ export declare class Image {
     /**
      * 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 options See {@link PNGEncodeOptions}
+     * @return The encoded data
+     */
+    encode(options?: PNGEncodeOptions): Promise<Uint8Array>;
+    /**
+     * Encodes the image into a PNG
      * @param compression The compression level (0-9). Default: `1`
-     * @param metadata Text metadata to include
+     * @param metadata Metadata to include, see {@link Metadata}
      * @return The encoded data
      */
-    encode(compression?: number, metadata?: PNGMetadata): Promise<Uint8Array>;
+    encode(compression?: number, metadata?: Metadata): Promise<Uint8Array>;
     /**
      * Encodes the image into a PNG with compression level 1
-     * @param metadata Text metadata to include
+     * @param metadata Metadata to include, see {@link Metadata}
      * @return The encoded data
      */
-    encode(metadata?: PNGMetadata): Promise<Uint8Array>;
+    encode(metadata?: Metadata): 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>;
+    encodePNG(options?: PNGEncodeOptions): Promise<Uint8Array>;
+    encodePNG(compression?: number, metadata?: Metadata): Promise<Uint8Array>;
+    encodePNG(metadata?: Metadata): Promise<Uint8Array>;
+    /**
+     * Encodes the image into a JPEG
+     * @param options See {@link JPEGEncodeOptions}
+     */
+    encodeJPEG(options?: JPEGEncodeOptions): 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>;
     /**
-     * Decodes an image (PNG, JPEG or TIFF)
+     * Encodes the image as lossless WebP (usually 20-30% smaller than PNG, but slower to encode)
+     * @param options See {@link EncodeOptions}
+     */
+    encodeWebP({ metadata }?: EncodeOptions): Promise<Uint8Array>;
+    /**
+     * Encodes the image as run length encoded TGA (32 bit, or 24 bit if the image is opaque)
+     * @param options See {@link EncodeOptions}
+     */
+    encodeTGA({ metadata }?: EncodeOptions): 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
@@ -502,11 +717,28 @@ export declare class Image {
      * 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 options See {@link SVGOptions}
+     * @return The rendered SVG graphic
+     */
+    static renderSVG(svg: string | BinaryData, options?: SVGOptions): Promise<Image>;
+    /**
+     * Creates a new image from the given SVG
+     * @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 options Color, layout and style, see {@link TextOptions}; the image grows by the outline width on every
+     *     side
+     * @return The rendered text
+     */
+    static renderText(font: BinaryData, size: number, text: string, options?: TextOptions): Promise<Image>;
     /**
      * Creates a new image containing the rendered text.
      * @param font TrueType (ttf/ttc) or OpenType (otf) font buffer to use