image-in-browser
Version:
Package for encoding / decoding images, transforming images, applying filters, drawing primitives on images on the client side (no need for server Node.js)
683 lines (682 loc) • 27.7 kB
TypeScript
/** @format */
import { ChannelOrder } from '../color/channel-order.js';
import { Color } from '../color/color.js';
import { Format, FormatType } from '../color/format.js';
import { Interpolation } from '../common/interpolation.js';
import { ExifData } from '../exif/exif-data.js';
import { FrameType } from './frame-type.js';
import { IccProfile } from './icc-profile.js';
import { MemoryImageData } from './image-data.js';
import { Palette } from './palette.js';
import { Pixel } from './pixel.js';
/**
* Interface for initializing a MemoryImage.
*/
interface MemoryImageInitializeOptions {
/** Width of the image */
width: number;
/** Height of the image */
height: number;
/** Format of the image */
format?: Format;
/** Number of color channels */
numChannels?: number;
/** Whether the image has a palette */
withPalette?: boolean;
/** Format of the palette */
paletteFormat?: Format;
/** Palette of the image */
palette?: Palette;
/** EXIF data of the image */
exifData?: ExifData;
/** ICC profile of the image */
iccProfile?: IccProfile;
}
/**
* Interface for creating a MemoryImage.
*/
export interface MemoryImageCreateOptions extends MemoryImageInitializeOptions {
/** Number of times the animation should loop */
loopCount?: number;
/** Type of the frame */
frameType?: FrameType;
/** Duration of the frame */
frameDuration?: number;
/** Index of the frame */
frameIndex?: number;
/** Background color of the image */
backgroundColor?: Color;
/** Text data associated with the image */
textData?: Map<string, string>;
}
/**
* Interface for creating a MemoryImage from bytes.
*/
export interface MemoryImageFromBytesOptions extends MemoryImageCreateOptions {
/** Byte data of the image */
bytes: ArrayBufferLike;
/** Offset to start reading bytes */
byteOffset?: number;
/** Row stride of the image data */
rowStride?: number;
/** Order of the color channels */
channelOrder?: ChannelOrder;
}
/**
* Interface for cloning a MemoryImage.
*/
export interface MemoryImageCloneOptions {
/** Whether to skip animation frames */
skipAnimation?: boolean;
/** Whether to skip pixel data */
skipPixels?: boolean;
}
/**
* Interface for converting a MemoryImage.
*/
export interface MemoryImageConvertOptions {
/** Format to convert to */
format?: Format;
/** Number of color channels */
numChannels?: number;
/** Alpha value for the new format */
alpha?: number;
/** Whether the new image should have a palette */
withPalette?: boolean;
/** Whether to skip animation frames */
skipAnimation?: boolean;
}
/**
* Interface for color extremes in a MemoryImage.
*/
export interface MemoryImageColorExtremes {
/** Minimum color value */
min: number;
/** Maximum color value */
max: number;
}
/**
* Interface for getting bytes from a MemoryImage.
*/
export interface MemoryImageGetBytesOptions {
/** Order of the color channels */
order?: ChannelOrder;
/** Alpha value for the new format */
alpha?: number;
}
/**
* A MemoryImage is a container for MemoryImageData and other various metadata
* representing an image in memory.
*/
export declare class MemoryImage implements Iterable<Pixel> {
private _data?;
/**
* Gets the image data.
* @returns {MemoryImageData | undefined} The image data.
*/
get data(): MemoryImageData | undefined;
/**
* The format of the image pixels.
*/
get format(): Format;
/**
* Checks if the image has a palette.
* @returns {boolean} True if the image has a palette, otherwise false.
*/
get hasPalette(): boolean;
/**
* Gets the palette of the image.
* @returns {Palette | undefined} The palette of the image.
*/
get palette(): Palette | undefined;
/**
* Sets the palette of the image.
* @param {Palette | undefined} p - The palette to set.
*/
set palette(p: Palette | undefined);
/**
* Gets the number of channels.
* @returns {number} The number of channels.
*/
get numChannels(): number;
/**
* Checks if the image has animation frames.
* @returns {boolean} True if there is more than one frame, otherwise false.
*/
get hasAnimation(): boolean;
/**
* The number of frames in this MemoryImage. A MemoryImage will have at least one
* frame, itself, so it's considered animated if it has more than one
* frame.
* @returns {number} The number of frames.
*/
get numFrames(): number;
private _exifData?;
/**
* The EXIF metadata for the image. If an ExifData hasn't been created
* for the image yet, one will be added.
* @returns {ExifData} The EXIF metadata.
*/
get exifData(): ExifData;
/**
* Sets the EXIF metadata for the image.
* @param {ExifData} exif - The EXIF metadata to set.
*/
set exifData(exif: ExifData);
/**
* The maximum value of a pixel channel, based on the format of the image.
* If the image has a palette, this will be the maximum value of a palette
* color channel. Float format images will have a maxChannelValue of 1,
* though they can have values above that.
* @returns {number} The maximum value of a pixel channel.
*/
get maxChannelValue(): number;
/**
* The maximum value of a palette index, based on the format of the image.
* This differs from maxChannelValue in that it will not be affected by
* the format of the palette.
* @returns {number} The maximum value of a palette index.
*/
get maxIndexValue(): number;
/**
* Indicates whether this image supports using a palette.
* @returns {boolean} True if the image supports using a palette, otherwise false.
*/
get supportsPalette(): boolean;
/**
* The width of the image in pixels.
* @returns {number} The width of the image.
*/
get width(): number;
/**
* The height of the image in pixels.
* @returns {number} The height of the image.
*/
get height(): number;
/**
* The general type of the format, whether it's uint data, int data, or
* float data (regardless of precision).
* @returns {FormatType} The format type.
*/
get formatType(): FormatType;
/**
* Indicates whether this image is valid and has data.
* @returns {boolean} True if the image is valid, otherwise false.
*/
get isValid(): boolean;
/**
* The ArrayBufferLike of the image storage data or undefined if not initialized.
* @returns {ArrayBufferLike | undefined} The buffer of the image data.
*/
get buffer(): ArrayBufferLike | undefined;
/**
* The length in bytes of the image data buffer.
* @returns {number} The byte length of the image data buffer.
*/
get byteLength(): number;
/**
* The length in bytes of a row of pixels in the image buffer.
* @returns {number} The row stride of the image data buffer.
*/
get rowStride(): number;
/**
* Indicates whether this image is a Low Dynamic Range (regular) image.
* @returns {boolean} True if the image is a Low Dynamic Range image, otherwise false.
*/
get isLdrFormat(): boolean;
/**
* Indicates whether this image is a High Dynamic Range image.
* @returns {boolean} True if the image is a High Dynamic Range image, otherwise false.
*/
get isHdrFormat(): boolean;
/**
* The number of bits per color channel.
* @returns {number} The number of bits per color channel.
*/
get bitsPerChannel(): number;
/**
* Indicates whether this MemoryImage has an alpha channel.
* @returns {boolean} True if the image has an alpha channel, otherwise false.
*/
get hasAlpha(): boolean;
/**
* Named non-color channels used by this image.
*/
private _extraChannels?;
private _iccProfile;
/**
* Gets the ICC profile of the image.
* @returns {IccProfile | undefined} The ICC profile of the image.
*/
get iccProfile(): IccProfile | undefined;
/**
* Sets the ICC profile of the image.
* @param {IccProfile | undefined} v - The ICC profile to set.
*/
set iccProfile(v: IccProfile | undefined);
private _textData;
/**
* Gets the text data associated with the image.
* @returns {Map<string, string> | undefined} The text data.
*/
get textData(): Map<string, string> | undefined;
private _backgroundColor?;
/**
* The suggested background color to clear the canvas with.
* @returns {Color | undefined} The background color.
*/
get backgroundColor(): Color | undefined;
/**
* Sets the background color of the image.
* @param {Color | undefined} v - The background color to set.
*/
set backgroundColor(v: Color | undefined);
private _loopCount;
/**
* How many times should the animation loop (0 means forever)
* @returns {number} The loop count.
*/
get loopCount(): number;
/**
* Sets the loop count of the animation.
* @param {number} v - The loop count to set.
*/
set loopCount(v: number);
private _frameType;
/**
* Gets or sets how should the frames be interpreted.
* If the frameType is FrameType.animation, the frames are part
* of an animated sequence. If the frameType is FrameType.page,
* the frames are the pages of a document.
* @returns {FrameType} The frame type.
*/
get frameType(): FrameType;
/**
* Sets the frame type of the image.
* @param {FrameType} v - The frame type to set.
*/
set frameType(v: FrameType);
/**
* The list of sub-frames for the image, if it's an animation. An image
* is considered animated if it has more than one frame, as the first
* frame will be the image itself.
* @returns {MemoryImage[]} The list of sub-frames.
*/
private _frames;
/**
* Gets the frames of the image.
* @returns {MemoryImage[]} The frames of the image.
*/
get frames(): MemoryImage[];
private _frameDuration;
/**
* How long this frame should be displayed, in milliseconds.
* A duration of 0 indicates no delay and the next frame will be drawn
* as quickly as it can.
* @returns {number} The frame duration.
*/
get frameDuration(): number;
/**
* Sets the frame duration of the image.
* @param {number} v - The frame duration to set.
*/
set frameDuration(v: number);
/**
* Index of this image in the parent animations frame list.
* @returns {number} The frame index.
*/
private _frameIndex;
/**
* Gets the frame index of the image.
* @returns {number} The frame index.
*/
get frameIndex(): number;
/**
* Sets the frame index of the image.
* @param {number} v - The frame index to set.
*/
set frameIndex(v: number);
/**
* Constructs a new MemoryImage.
* @param {MemoryImageCreateOptions} [opt] - The options for creating the MemoryImage.
*/
constructor(opt?: MemoryImageCreateOptions);
/**
* Gets the number of pixel colors based on the format.
* @param {Format} format - The format of the image.
* @returns {number} The number of pixel colors.
*/
private static getNumPixelColors;
/**
* Creates a resized MemoryImage from another MemoryImage.
* @param {MemoryImage} other - The other MemoryImage to resize.
* @param {number} width - The width of the new image.
* @param {number} height - The height of the new image.
* @param {boolean} [skipAnimation=false] - Whether to skip animation frames.
* @returns {MemoryImage} The resized MemoryImage.
*/
static fromResized(other: MemoryImage, width: number, height: number, skipAnimation?: boolean): MemoryImage;
/**
* Creates a copy of the given **other** MemoryImage.
*/
static from(other: MemoryImage, skipAnimation?: boolean, skipPixels?: boolean): MemoryImage;
/**
* Create an image from raw data in **bytes**.
*
* **format** defines the data type of pixel channel values. _Format.uint8_
* is the most typical format for images, where each pixel value is an
* unsigned byte with values in the range [0, 255].
*
* **rowStride** is the row stride, in bytes, of the source data **bytes**.
* This may be different than the rowStride of the MemoryImage, as some data
* sources align rows to different byte alignments and include padding.
*
* **byteOffset** can be specified to start reading the **bytes**
* data starting from that value.
*
* **numChannels** can be used to specify the number of pixel channels in the
* **bytes** data, defaulting to 3.
*
* **order** can be used if the source **bytes** has a different channel order
* than RGBA. _ChannelOrder.bgra_ will rearrange the color channels from
* BGRA to what MemoryImage wants, RGBA.
*
*/
static fromBytes(opt: MemoryImageFromBytesOptions): MemoryImage;
/**
* Initializes the memory image with the provided options.
*
* @param {MemoryImageInitializeOptions} opt - The options for initializing the memory image.
* @param {Format} [opt.format] - The format of the image. Defaults to `Format.uint8`.
* @param {number} [opt.numChannels] - The number of channels in the image. Defaults to 3.
* @param {boolean} [opt.withPalette] - Whether to use a palette. Defaults to `false`.
* @param {Format} [opt.paletteFormat] - The format of the palette. Defaults to `Format.uint8`.
* @param {ICCProfile} [opt.iccProfile] - The ICC profile for the image.
* @param {ExifData} [opt.exifData] - The EXIF data for the image.
* @param {Palette} [opt.palette] - The palette for the image.
* @param {number} opt.width - The width of the image.
* @param {number} opt.height - The height of the image.
*/
private initialize;
/**
* Creates image data based on the specified parameters.
*
* @param {number} width - The width of the image.
* @param {number} height - The height of the image.
* @param {Format} format - The format of the image data.
* @param {number} numChannels - The number of channels in the image data.
* @param {Palette} [palette] - Optional palette for indexed formats.
*/
private createImageData;
/**
* Creates a palette based on the specified format and palette format.
*
* @param {Format} format - The format of the image.
* @param {Format} paletteFormat - The format of the palette to be created.
* @param {number} numChannels - The number of color channels in the palette.
* @returns {Palette | undefined} A Palette object of the specified format, or undefined if the format is not supported.
* @throws {LibError} If the palette format is unknown.
*/
private createPalette;
/**
* Adds a frame to the current image sequence.
* If no image is provided, a new MemoryImage is created from the current instance.
*
* @param {MemoryImage} [image] - The image to be added as a frame. If not provided, a new MemoryImage is created.
* @returns {MemoryImage} The added or newly created MemoryImage.
*/
addFrame(image?: MemoryImage): MemoryImage;
/**
* Retrieves the frame at the specified index.
*
* @param {number} index - The index of the frame to retrieve.
* @returns {MemoryImage} The MemoryImage object at the specified index.
*/
getFrame(index: number): MemoryImage;
/**
* Creates a clone of the current MemoryImage instance.
*
* @param {MemoryImageCloneOptions} [opt] - Optional parameters for cloning.
* @param {boolean} [opt.skipAnimation=false] - If true, skips cloning the animation data.
* @param {boolean} [opt.skipPixels=false] - If true, skips cloning the pixel data.
* @returns {MemoryImage} A new MemoryImage instance that is a clone of the current instance.
*/
clone(opt?: MemoryImageCloneOptions): MemoryImage;
/**
* Checks if an extra channel with the given name exists.
*
* @param {string} name - The name of the channel to check.
* @returns {boolean} Returns true if the extra channel exists, otherwise false.
*/
hasExtraChannel(name: string): boolean;
/**
* Retrieves the extra channel data by its name.
*
* @param {string} name - The name of the extra channel to retrieve.
* @returns {MemoryImageData | undefined} The data of the extra channel if it exists, otherwise undefined.
*/
getExtraChannel(name: string): MemoryImageData | undefined;
/**
* Sets or removes an extra channel with the given name and data.
*
* @param {string} name - The name of the extra channel.
* @param {MemoryImageData} [data] - Optional. The data to be associated with the extra channel. If undefined, the extra channel will be removed.
*/
setExtraChannel(name: string, data?: MemoryImageData): void;
/**
* Retrieves an iterator for a range of pixels within the specified rectangular area.
*
* @param {number} x - The x-coordinate of the top-left corner of the rectangular area.
* @param {number} y - The y-coordinate of the top-left corner of the rectangular area.
* @param {number} width - The width of the rectangular area.
* @param {number} height - The height of the rectangular area.
* @returns {Iterator<Pixel>} An iterator for the pixels within the specified range.
*/
getRange(x: number, y: number, width: number, height: number): Iterator<Pixel>;
/**
* Converts the image storage data to a Uint8Array.
*
* @returns {Uint8Array} The Uint8Array representation of the image storage data.
*/
toUint8Array(): Uint8Array;
/**
* Retrieves the byte representation of the image.
*
* @param {MemoryImageGetBytesOptions} [opt] - Optional parameters for getting bytes.
* @param {string} [opt.order] - The order of the channels.
* @param {boolean} [opt.alpha] - Whether to include the alpha channel.
* @returns {Uint8Array} The byte array representation of the image.
*/
getBytes(opt?: MemoryImageGetBytesOptions): Uint8Array;
/**
* Remaps the color channels of the pixels based on the specified order.
*
* @param {ChannelOrder} order - The desired channel order to remap the pixels to.
*
* The method supports the following channel orders:
*
* For 4-channel images (RGBA):
* - ChannelOrder.abgr: Swaps RGBA to ABGR.
* - ChannelOrder.argb: Swaps RGBA to ARGB.
* - ChannelOrder.bgra: Swaps RGBA to BGRA.
*
* For 3-channel images (RGB):
* - ChannelOrder.bgr: Swaps RGB to BGR.
*/
remapChannels(order: ChannelOrder): void;
/**
* Checks if the given coordinates (x, y) are within the bounds of the defined width and height.
*
* @param {number} x - The x-coordinate to check.
* @param {number} y - The y-coordinate to check.
* @returns {boolean} True if the coordinates are within bounds, false otherwise.
*/
isBoundsSafe(x: number, y: number): boolean;
/**
* Retrieves a color based on the provided RGBA values with the format
* and number of channels of the image.
*
* @param {number} r - The red component of the color (0-255).
* @param {number} g - The green component of the color (0-255).
* @param {number} b - The blue component of the color (0-255).
* @param {number} [a] - The optional alpha component of the color (0-255). If not provided, a default value may be used.
* @returns {Color} The color object corresponding to the provided RGBA values. If the color cannot be retrieved, a default color is returned.
*/
getColor(r: number, g: number, b: number, a?: number): Color;
/**
* Retrieves the pixel at the specified coordinates.
*
* @param {number} x - The x-coordinate of the pixel.
* @param {number} y - The y-coordinate of the pixel.
* @param {Pixel} [pixel] - Optional. An existing Pixel object to populate with the pixel data.
* @returns {Pixel} The pixel at the specified coordinates, or UndefinedPixel if the data is not available.
*/
getPixel(x: number, y: number, pixel?: Pixel): Pixel;
/**
* Retrieves a pixel from the specified coordinates safely.
* If the coordinates are out of bounds, it returns an UndefinedPixel.
*
* @param {number} x - The x-coordinate of the pixel.
* @param {number} y - The y-coordinate of the pixel.
* @param {Pixel} [pixel] - An optional pixel object to be populated with the pixel data.
* @returns {Pixel} The pixel at the specified coordinates, or UndefinedPixel if out of bounds.
*/
getPixelSafe(x: number, y: number, pixel?: Pixel): Pixel;
/**
* Retrieves a pixel from the image, ensuring the coordinates are clamped within the image boundaries.
*
* @param {number} x - The x-coordinate of the pixel.
* @param {number} y - The y-coordinate of the pixel.
* @param {Pixel} [pixel] - Optional. An existing Pixel object to populate with the pixel data.
* @returns {Pixel} The Pixel object at the clamped coordinates.
*/
getPixelClamped(x: number, y: number, pixel?: Pixel): Pixel;
/**
* Retrieves the pixel index at the specified (x, y) coordinates.
*
* @param {number} x - The x-coordinate of the pixel.
* @param {number} y - The y-coordinate of the pixel.
* @returns {number} The index of the pixel, truncated to an integer. Returns 0 if the index is undefined.
*/
getPixelIndex(x: number, y: number): number;
/**
* Retrieves the interpolated pixel color at the specified coordinates.
*
* @param {number} fx - The x-coordinate.
* @param {number} fy - The y-coordinate.
* @param {Interpolation} [interpolation=Interpolation.linear] - The interpolation method to use (default is Interpolation.linear).
* @returns {Color} The interpolated color at the specified coordinates.
* @throws {LibError} If an unknown interpolation mode is provided.
*/
getPixelInterpolate(fx: number, fy: number, interpolation?: Interpolation): Color;
/**
* Retrieves the color of a pixel using bilinear interpolation.
*
* @param {number} fx - The x-coordinate of the pixel in floating-point.
* @param {number} fy - The y-coordinate of the pixel in floating-point.
* @returns {Color} The interpolated color at the specified coordinates.
*/
getPixelLinear(fx: number, fy: number): Color;
/**
* Performs cubic interpolation to get the color of a pixel at a given floating-point coordinate.
*
* @param {number} fx - The x-coordinate of the pixel in floating-point.
* @param {number} fy - The y-coordinate of the pixel in floating-point.
* @returns {Color} The interpolated color at the given coordinates.
*/
getPixelCubic(fx: number, fy: number): Color;
/**
* Sets the pixel at the specified (x, y) coordinates to the given color or pixel.
*
* @param {number} x - The x-coordinate of the pixel.
* @param {number} y - The y-coordinate of the pixel.
* @param {Color | Pixel} c - The color or pixel to set. Can be an instance of Color or Pixel.
*/
setPixel(x: number, y: number, c: Color | Pixel): void;
/**
* Sets the pixel index at the specified (x, y) coordinates.
*
* @param {number} x - The x-coordinate of the pixel.
* @param {number} y - The y-coordinate of the pixel.
* @param {number} i - The index value to set for the pixel.
*/
setPixelIndex(x: number, y: number, i: number): void;
/**
* Set the red (or index) color channel of a pixel.
*
* @param {number} x - The x-coordinate of the pixel.
* @param {number} y - The y-coordinate of the pixel.
* @param {number} i - The intensity value for the red color channel.
*/
setPixelR(x: number, y: number, i: number): void;
/**
* Sets the RGB value of a specific pixel in the image data.
*
* @param {number} x - The x-coordinate of the pixel.
* @param {number} y - The y-coordinate of the pixel.
* @param {number} r - The red component of the pixel (0-255).
* @param {number} g - The green component of the pixel (0-255).
* @param {number} b - The blue component of the pixel (0-255).
*/
setPixelRgb(x: number, y: number, r: number, g: number, b: number): void;
/**
* Sets the RGBA value of a specific pixel in the image data.
*
* @param {number} x - The x-coordinate of the pixel.
* @param {number} y - The y-coordinate of the pixel.
* @param {number} r - The red component of the pixel (0-255).
* @param {number} g - The green component of the pixel (0-255).
* @param {number} b - The blue component of the pixel (0-255).
* @param {number} a - The alpha (transparency) component of the pixel (0-255).
*/
setPixelRgba(x: number, y: number, r: number, g: number, b: number, a: number): void;
/**
* Clears the current data with an optional color.
*
* @param {Color} [color] - The optional color to clear the data with.
*/
clear(color?: Color): void;
/**
* Convert this image to a new format or number of channels.
* If the new number of channels is 4 and the current image does
* not have an alpha channel, then the given alpha value will be used
* to set the new alpha channel. If alpha is not provided, then the
* maxChannelValue will be used to set the alpha. If withPalette is
* true, and to target format and numChannels has fewer than 256 colors,
* then the new image will be converted to use a palette.
*
* @param {MemoryImageConvertOptions} opt - Options for the image conversion.
* @param {Format} [opt.format] - The target format for the image.
* @param {number} [opt.numChannels] - The number of channels for the image.
* @param {number} [opt.alpha] - The alpha value to use if adding an alpha channel.
* @param {boolean} [opt.withPalette] - Whether to use a palette for the image.
* @param {boolean} [opt.skipAnimation] - Whether to skip animation frames.
* @returns {MemoryImage} The converted memory image.
*/
convert(opt: MemoryImageConvertOptions): MemoryImage;
/**
* Add text metadata to the image.
* @param {Map<string, string>} data - A map containing key-value pairs of text metadata.
*/
addTextData(data: Map<string, string>): void;
/**
* Calculates the minimum and maximum color channel values from the image.
*
* @returns {MemoryImageColorExtremes} An object containing the minimum and maximum color channel values.
*/
getColorExtremes(): MemoryImageColorExtremes;
/**
* Returns a string representation of the image.
* The string includes the class name and the values of width, height, format, and number of channels.
*
* @returns {string} A string representation of the object.
*/
toString(): string;
/**
* Returns an iterator for the Pixel data.
*
* @returns {Iterator<Pixel>} An iterator for the Pixel data.
*/
[Symbol.iterator](): Iterator<Pixel>;
}
export {};