Skip to content

MemoryImage

Jump to bottom
Yegor Pelykh edited this page Feb 5, 2024 · 3 revisions

MemoryImage

A MemoryImage is a container for MemoryImageData and other various metadata representing an image in memory.

The MemoryImage class implements the interface Iterable<Pixel> interface, so it allows iteration through all the pixels in an image, for example, in a for...of loop.

Constructors

constructor

constructor(opt?: MemoryImageCreateOptions)

Creates a new instance of MemoryImage.

If called without parameters, an empty instance is created, with no size data and no the image data.

Parameters:

  • width: the width of the image. Type: number.
  • height: the height of the image. Type: number.
  • loopCount (optional): how many times should the animation loop (0 means forever). Default is 0. Type: number.
  • frameType (optional): the meaning of the frame sequence. Default is FrameType.sequence. Type: FrameType.
  • frameDuration (optional): how long each frame should be displayed, in milliseconds. Default is 0. Type: number.
  • frameIndex (optional): the index of this image in the parent animations frame list. Default is 0. Type: number.
  • backgroundColor (optional): the suggested background color to clear the canvas with. Default is undefined. Type: Color.
  • format (optional): the format of the image pixels. Type: Format.
  • numChannels (optional): the number of color channels for the image. Type: number.
  • withPalette (optional): specifies whether a palette should be created. Type: boolean.
  • paletteFormat (optional): image palette format. Type: Format.
  • palette (optional): the palette of the image. Type: Palette.
  • exifData (optional): the EXIF metadata for the image. Type: ExifData.
  • iccProfile (optional): the ICC profile data of this image. Type: IccProfile.
  • textData (optional): the text data of this image. Type: Map<string, string>.

from

public static from(
    other: MemoryImage,
    skipAnimation = false,
    skipPixels = false
  ): MemoryImage

Creates a copy of the given other MemoryImage.

Parameters:

  • other: another instance of MemoryImage to make a copy of. Type: MemoryImage.
  • skipAnimation (optional): if true, the frames will not be copied. Default is false. Type: boolean.
  • skipPixels (optional): if true, no pixels will be copied in the image data, all pixels will be empty. Default is false. Type: boolean.

fromBytes

public static fromBytes(opt: MemoryImageFromBytesOptions): MemoryImage

Parameters:

  • bytes: bytes of the image data buffer. Type: ArrayBufferLike.
  • width: the width of the image. Type: number.
  • height: the height of the image. Type: number.
  • byteOffset (optional): byte offset from which to start reading bytes from the raw data when creating the MemoryImage object. Type: number.
  • rowStride (optional): the length in bytes of a row of pixels in the image data buffer. Default is calculated depending on width, numChannels and format. Type: number.
  • channelOrder (optional): channel order of the image. Default is ChannelOrder.rgba or ChannelOrder.rgb or ChannelOrder.red or ChannelOrder.grayAlpha (depends on numChannels) Type: ChannelOrder.
  • loopCount (optional): how many times should the animation loop (0 means forever). Default is 0. Type: number.
  • frameType (optional): the meaning of the frame sequence. Default is FrameType.sequence. Type: FrameType.
  • frameDuration (optional): how long each frame should be displayed, in milliseconds. Default is 0. Type: number.
  • frameIndex (optional): the index of this image in the parent animations frame list. Default is 0. Type: number.
  • backgroundColor (optional): the suggested background color to clear the canvas with. Default is undefined. Type: Color.
  • format (optional): 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]. Type: Format.
  • numChannels (optional): the number of pixel channels in the bytes data. Default is 3. Type: number.
  • withPalette (optional): specifies whether a palette should be created. Type: boolean.
  • paletteFormat (optional): image palette format. Type: Format.
  • palette (optional): the palette of the image. Type: Palette.
  • exifData (optional): the EXIF metadata for the image. Type: ExifData.
  • iccProfile (optional): the ICC profile data of this image. Type: IccProfile.
  • textData (optional): the text data of this image. Type: Map<string, string>.

Properties

format

The format of the image pixels.

Type: Format.

Access: Read-only.

hasPalette

Indicates whether this image has a palette.

Type: boolean.

Access: Read-only.

palette

The palette if the image has one, undefined otherwise.

Type: Palette | undefined.

Access: Read-only.

numChannels

The number of color channels for the image.

Type: number.

Access: Read-only.

hasAnimation

Indicates whether this image is animated. An image is considered animated if it has more than one frame, as the first image in the frames list is the image itself.

Type: boolean.

Access: Read-only.

numFrames

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.

Type: number.

Access: Read-only.

exifData

The EXIF metadata for the image.

Type: ExifData.

Access: Read/Write.

maxChannelValue

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.

Type: number.

Access: Read-only.

maxIndexValue

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.

Type: number.

Access: Read-only.

supportsPalette

Indicates whether this image supports using a palette.

Type: boolean.

Access: Read-only.

width

The width of the image in pixels.

Type: number.

Access: Read-only.

height

The height of the image in pixels.

Type: number.

Access: Read-only.

formatType

The general type of the format, whether it's uint data, int data, or float data (regardless of precision).

Type: FormatType.

Access: Read-only.

isValid

Indicates whether this image is valid and has data.

Type: boolean.

Access: Read-only.

buffer

The ArrayBufferLike of the image storage data or undefined if not initialized.

Type: ArrayBufferLike | undefined.

Access: Read-only.

byteLength

The length in bytes of the image data buffer.

Type: number.

Access: Read-only.

rowStride

The length in bytes of a row of pixels in the image data buffer.

Type: number.

Access: Read-only.

isLdrFormat

Indicates whether this image is a Low Dynamic Range (regular) image.

Type: boolean.

Access: Read-only.

isHdrFormat

Indicates whether this image is a High Dynamic Range image.

Type: boolean.

Access: Read-only.

bitsPerChannel

The number of bits per color channel.

Type: number.

Access: Read-only.

hasAlpha

Indicates whether this MemoryImage has an alpha channel.

Type: boolean.

Access: Read-only.

iccProfile

The ICC profile data of this image.

Type: IccProfile | undefined.

Access: Read/Write.

textData

The text data of this image.

Type: Map<string, string> | undefined.

Access: Read-only.

backgroundColor

The suggested background color to clear the canvas with.

Type: Color | undefined.

Access: Read/Write.

loopCount

How many times should the animation loop (0 means forever).

Type: number.

Access: Read/Write.

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.

Type: FrameType.

Access: Read/Write.

frames

The array of sub-frames for the image, if it is an animation. An image is considered animated if it has more than one frame, as the first frame will be the image itself.

Type: MemoryImage[].

Access: Read-only.

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.

Type: number.

Access: Read/Write.

frameIndex

Index of this image in the parent animations frame list.

Type: number.

Access: Read-only.

Methods

addFrame

addFrame(image?: MemoryImage): MemoryImage

Add a frame to the animation of this MemoryImage.

Parameters:

  • image (optional): the MemoryImage to add.

Returns the frame that was added.

getFrame

getFrame(index: number): MemoryImage

Get a frame from this image. If the MemoryImage is not animated, this MemoryImage will be returned; otherwise the particular frame will be returned.

Parameters:

  • index (optional): the frame index.

Returns the frame by specified index.

clone

clone(opt?: MemoryImageCloneOptions): MemoryImage

Create a copy of this image.

Parameters:

  • skipAnimation (optional): if true, the frames will not be copied. Default is false.
  • skipPixels (optional): if true, no pixels will be copied in the image data, all pixels will be empty. Default is false.

Returns the copy of this image.

hasExtraChannel

hasExtraChannel(name: string): boolean

Returns whether the image has an extra channel with the specified name.

Parameters:

  • name: the channel name.

Returns whether the image has an extra channel with the specified name.

getExtraChannel

getExtraChannel(name: string): MemoryImageData | undefined

Returns the extra channel by the specified name, or undefined if not found.

Parameters:

  • name: the channel name.

Returns the extra channel by the specified name.

setExtraChannel

setExtraChannel(name: string, data?: MemoryImageData): void

Sets the extra channel by the specified name, or delete existing extra channel if data is undefined.

Parameters:

  • name: the channel name.
  • data (optional): extra channel image data. If not specified, then the channel with the specified name will be deleted. Default is undefined.

Returns nothing.

getRange

getRange(
    x: number,
    y: number,
    width: number,
    height: number,
  ): Iterator<Pixel>

Returns a pixel iterator for iterating over a rectangular range of pixels in the image.

Parameters:

  • x: the X coordinate of the first pixel in the image where the region to iterate starts from.
  • y: the Y coordinate of the first pixel in the image where the region to iterate starts from.
  • width: the width of the region to iterate, in pixels.
  • height: the height of the region to iterate, in pixels.

Returns iterator to iterate over the specified range of pixels.

toUint8Array

toUint8Array(): Uint8Array

Get a Uint8Array view of the image storage data.

Returns bytes of the image data.

toUint8Array

getBytes(order?: ChannelOrder): Uint8Array

Similar to toUint8Array, but will convert the channels of the image pixels to the given order. If that happens, the returned bytes will be a copy and not a direct view of the image data. If the number of channels needed by order differs from what the image has, the bytes will come from a converted image. If the converted image needs an alpha channel added, then you can use the alpha argument to specify the value of the added alpha channel.

Parameters:

  • order (optional): the channel order. If not specified, the result will be exactly the same as from toUint8Array method.
  • alpha (optional): the value of the alpha channel (if the converted image needs an alpha channel added)

Returns bytes of the image data.

remapChannels

remapChannels(order: ChannelOrder): void

Remap the color channels to the given order. Normally MemoryImage color channels are stored in RGBA order for 4 channel images, and RGB order for 3 channel images. This method lets you re-arrange the color channels in-place without needing to clone the image for preparing image data for external usage that requires alternative channel ordering.

Parameters:

  • order: the channel order.

Returns nothing.

isBoundsSafe

isBoundsSafe(x: number, y: number): boolean

Returns true if the given pixel coordinates is within the dimensions of the image.

Parameters:

  • x: the X coordinate of pixel.
  • y: the Y coordinate of pixel.

Returns whether the given pixel coordinates is within the dimensions of the image.

getColor

getColor(r: number, g: number, b: number, a?: number): Color

Create a Color object with the format and number of channels of the image.

Parameters:

  • r: the red channel of the created Color.
  • g: the green channel of the created Color.
  • b: the blue channel of the created Color.
  • a (optional): the alpha channel of the created Color.

Returns new Color.

getPixel

getPixel(x: number, y: number, pixel?: Pixel): Pixel

Get the Pixel at the given coordinates x,y. If pixel is provided, it will be updated and returned rather than allocating a new Pixel.

Parameters:

  • x: the X coordinate of pixel.
  • y: the Y coordinate of pixel.
  • pixel: Pixel to update its data. If not provided, a new Pixel instance will be created.

Returns Pixel from the given coordinates.

getPixelSafe

getPixelSafe(x: number, y: number, pixel?: Pixel): Pixel

Get the pixel from the given x,y coordinate. If the pixel coordinates are out of bounds, PixelUndefined instance is returned.

Parameters:

  • x: the X coordinate of pixel.
  • y: the Y coordinate of pixel.
  • pixel: Pixel to update its data. If not provided, a new Pixel instance will be created.

Returns Pixel from the given coordinates or PixelUndefined if the coordinates are out of bounds.

getPixelSafe

getPixelSafe(x: number, y: number, pixel?: Pixel): Pixel

Get the pixel from the given x,y coordinate. If the pixel coordinates are out of bounds, PixelUndefined instance is returned.

Parameters:

  • x: the X coordinate of pixel.
  • y: the Y coordinate of pixel.
  • pixel: Pixel to update its data. If not provided, a new Pixel instance will be created.

Returns Pixel from the given coordinates.

getPixelClamped

getPixelClamped(x: number, y: number, pixel?: Pixel): Pixel

Get the pixel from the given x, y coordinate. If the pixel coordinates are out of range of the image, they will be clamped to the resolution.

Parameters:

  • x: the X coordinate of pixel.
  • y: the Y coordinate of pixel.
  • pixel: Pixel to update its data. If not provided, a new Pixel instance will be created.

Returns Pixel from the given coordinates.

getPixelInterpolate

getPixelInterpolate(
    fx: number,
    fy: number,
    interpolation = Interpolation.linear
  ): Color

Get the pixel using the given interpolation type for non-integer pixel coordinates.

Parameters:

  • fx: the X coordinate of pixel.
  • fy: the Y coordinate of pixel.
  • interpolation (optional): the interpolation type that is used to obtain colors in non-integer coordinates. Default is Interpolation.linear.

Returns Pixel from the given coordinates.

getPixelLinear

getPixelLinear(fx: number, fy: number): Color

Get the pixel using linear interpolation for non-integer pixel coordinates.

Parameters:

  • fx: the X coordinate of pixel.
  • fy: the Y coordinate of pixel.

Returns Pixel from the given coordinates.

getPixelCubic

getPixelCubic(fx: number, fy: number): Color

Get the pixel using cubic interpolation for non-integer pixel coordinates.

Parameters:

  • fx: the X coordinate of pixel.
  • fy: the Y coordinate of pixel.

Returns Pixel from the given coordinates.

setPixel

setPixel(x: number, y: number, c: Color | Pixel): void

Set the color of the pixel at the given coordinates to the color of the given Color c.

Parameters:

  • x: the X coordinate of pixel.
  • y: the Y coordinate of pixel.
  • c: the color to be set.

Returns nothing.

setPixelIndex

setPixelIndex(x: number, y: number, i: number): void

Set the index value for palette images, or the red channel otherwise.

Parameters:

  • x: the X coordinate of pixel.
  • y: the Y coordinate of pixel.
  • i: the index in image palette (or red channel value if the image doesn't have palette).

Returns nothing.

setPixelR

setPixelR(x: number, y: number, i: number): void

Set the red (or index) color channel of a pixel.

Parameters:

  • x: the X coordinate of pixel.
  • y: the Y coordinate of pixel.
  • i: the index in image palette (or red channel value if the image doesn't have palette).

Returns nothing.

setPixelRgb

setPixelRgb(
    x: number,
    y: number,
    r: number,
    g: number,
    b: number
  ): void

Set the color of the Pixel at the given coordinates x,y to the given color values r, g, b.

Parameters:

  • x: the X coordinate of pixel.
  • y: the Y coordinate of pixel.
  • r: red channel value.
  • g: green channel value.
  • b: blue channel value.

Returns nothing.

setPixelRgba

setPixelRgba(
    x: number,
    y: number,
    r: number,
    g: number,
    b: number,
    a: number
  ): void

Set the color of the Pixel at the given coordinates x,y to the given color values r, g, b and a.

Parameters:

  • x: the X coordinate of pixel.
  • y: the Y coordinate of pixel.
  • r: red channel value.
  • g: green channel value.
  • b: blue channel value.
  • a: alpha channel value.

Returns nothing.

clear

clear(color?: Color): void

Set all pixels in the image to the given color.

Parameters:

  • color (optional): pixel color. If undefined, the image will be initialized to 0. Default is undefined.

Returns nothing.

convert

convert(opt: MemoryImageConvertOptions): MemoryImage

Convert this image to a new format or number of channels, numChannels. 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.

Parameters:

  • format (optional): format to change in the image. Default is undefined (will not be changed).
  • numChannels (optional): the number of channels to change in the image. 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. Default is undefined (will not be changed).
  • alpha (optional): alpha channel to change in the image. If alpha is undefined, then the maxChannelValue will be used to set the alpha. Default is undefined.
  • withPalette (optional): specifies whether to create a palette. If true, and taking into account the new format and numChannels the image can have a palette, then the new image will be converted to use a palette. Default is false.
  • skipAnimation (optional): if true, then only the first frame will be converted into a new image. Default is false.

Returns nothing.

addTextData

addTextData(data: Map<string, string>): void

Add text metadata to the image.

Parameters:

  • data: text data of type Map<string, string>.

Returns nothing.

getColorExtremes

getColorExtremes(): MemoryImageColorExtremes

Gets the maximum and minimum value among all channels of all pixels in the image.

Returns an object containing the minimum and maximum values in the form { min: number; max: number; }.

toString

toString(): string

Returns a short representation of the basic image data as a string.

Returns a short string representation of the basic image data of the form MemoryImage (w: ${this.width}, h: ${this.height} f: ${Format[this.format]}, ch: ${this.numChannels}).

Clone this wiki locally