Image Data

Image Data

`image_data` stores one static image in memory. It can load an image file, create an image from raw bytes, expose image metadata, and save supported image formats.

`image_data` is cloneable. `clone()` returns a copy of the image.

Constructor

image_data()

Creates an empty image object.

img = image_data();
print(img.valid);       // false

Properties

Property	Type	Description
`valid`	boolean	`true` when the object contains a valid image.
`width`	number	Image width in pixels.
`height`	number	Image height in pixels.
`channels`	number	Number of color channels in the raw image data.
`format`	string	Source image format, such as `png`, `jpeg`, `gif`, `webp`, `svg`, `bmp`, or `unknown`.
`data_size`	number	Size of the raw image data in bytes.
`error`	string	Last image error message.
`data`	data_array	Raw image bytes as a `data_array`.

img = image_data().load("picture.png");
print(img.width);
print(img.height);

Methods

load(filePath)

Loads an image from `filePath` and returns the image object.

Arguments:

Argument	Description
`filePath`	Path to an image file. Profile paths are resolved by the host application.

img = image_data().load("images/logo.png");
if (img.valid)
{
    print(img.width, " x ", img.height);
}
else
{
    print(img.error);
}

save(filePath)

Saves the image and returns `true` on success. The output format is selected from the file extension.

Supported save extensions:

Extension	Format
`.png`	PNG
`.jpg`, `.jpeg`	JPEG
`.webp`	WebP

img = image_data().load("input.png");
ok = img.save("output.webp");

clear()

Clears the image and returns the image object.

img.clear();
print(img.valid);       // false

create(width, height, channels, data)

Creates an image from raw bytes in a `data_array` and returns the image object.

Arguments:

Argument	Description
`width`	Image width in pixels.
`height`	Image height in pixels.
`channels`	Number of channels per pixel.
`data`	A `data_array` containing exactly `width * height * channels` bytes.

raw = data_array();
raw.add_u8(255); raw.add_u8(0); raw.add_u8(0);
img = image_data().create(1, 1, 3, raw);
img.save("red.png");

create(width, height, channels, data, format)

Creates an image from raw bytes and specifies the byte layout.

Supported `format` values:

Format	Description
`gray`	Grayscale bytes.
`rgb`	Red, green, blue order.
`rgba`	Red, green, blue, alpha order.
`bgr`	Blue, green, red order; converted to RGB.
`bgra`	Blue, green, red, alpha order; converted to RGBA.

raw = data_array();
raw.add_u8(0); raw.add_u8(0); raw.add_u8(255);
img = image_data().create(1, 1, 3, raw, "bgr");

Previous: data_array

Next: Image stream

Table of Contents