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.

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`	bytes	Raw image bytes as a `bytes` object.

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

Common Object Methods

to_string()

Returns a display string for the object.

Item	Description
Syntax	`value.to_string()`
Arguments	none
Returns	string

Example:

text = value.to_string();

clone()

Returns a new image_data object with a separate copy of the image.

Item	Description
Syntax	`image_data.clone()`
Arguments	none
Returns	image_data object

Example:

img = image_data().load("picture.png");
copy = img.clone();

Methods

load(filePath)

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

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

Returns: image_data object.

Example:

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. The output format is selected from the file extension.

Argument	Type	Description
`filePath`	string	Output file path.

Returns: boolean-style number.

Supported save extensions:

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

Example:

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

clear()

Clears the image.

Item	Description
Syntax	`image_data.clear()`
Arguments	none
Returns	image_data object

Example:

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

create(width, height, channels, data)

Creates an image from raw bytes.

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

Returns: image_data object.

Example:

raw = bytes();
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.

Argument	Type	Description
`width`	number	Image width in pixels.
`height`	number	Image height in pixels.
`channels`	number	Number of channels per pixel.
`data`	bytes	Raw image bytes.
`format`	string	Byte layout name.

Returns: image_data object.

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.

Example:

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

Previous: File Format I/O

Next: image_stream

Sidebar

Table of Contents

image_data

Constructor

image_data()

Properties

Common Object Methods

to_string()

clone()

Methods

load(filePath)

save(filePath)

clear()

create(width, height, channels, data)

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

User Tools

Site Tools

Sidebar

Table of Contents

image_data

Constructor

image_data()

Properties

Common Object Methods

to_string()

clone()

Methods

load(filePath)

save(filePath)

clear()

create(width, height, channels, data)

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

Page Tools