Table of Contents

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