Images
Decode and encode display-oriented images, inspect properties, and read JPEG metadata.
Scalar Functions
| Function | Summary |
|---|---|
spql.image.channels | Return an Image's channel count. |
spql.image.decode | Decode a Blob or EncodedImage into display-oriented Image pixels. |
spql.image.encode | Encode an Image into an EncodedImage. |
spql.image.from_blob | Construct an EncodedImage from a Blob without reading bytes. |
spql.image.from_tensor | Construct an Image from an HWC u8 Tensor with three or four channels. |
spql.image.has_alpha | Return whether an Image has an alpha channel. |
spql.image.height | Return an Image's height in pixels. |
spql.image.mean_luminance | Mean linear relative luminance of all displayed image pixels. |
spql.image.resize | Resize an Image using the selected physical backend. |
spql.image.to_rgb | Convert a Yuv420Image to a packed sRGB Image for image operations and AI. |
spql.image.to_tensor | Convert an Image to a variable-shape Tensor. |
spql.image.width | Return an Image's width in pixels. |
spql.image.channels
Return an Image's channel count.
- Kind:
scalar function - Volatility:
immutable
spql.image.channels(image) -> u8?Parameters
| Name | Required | Type | Description |
|---|---|---|---|
image | yes | spql.Image? | Image to inspect for dimensions or pixel format. |
spql.image.decode
Decode a Blob or EncodedImage into display-oriented Image pixels.
- Kind:
scalar function - Volatility:
immutable
spql.image.decode(blob, format?) -> spql.Image?Supports JPEG and PNG, applies encoded orientation and preserves alpha as straight RGBA8; images without alpha produce RGB8. Null inputs or sources return null. Inline bytes need no storage service; URI-backed blobs read through the execution host's authorized storage access. Whole reads validate declared size and digest. Invalid images or formats fail the call.
Parameters
| Name | Required | Type | Description |
|---|---|---|---|
blob | yes | spql.Blob? | Blob or EncodedImage containing the encoded image payload. |
format | no | utf8? | Optional jpeg, jpg or png format override. A null value sniffs the bytes; when omitted, an EncodedImage's stored format is used. |
spql.image.decode(image, format?) -> spql.Image?Supports JPEG and PNG, applies encoded orientation and preserves alpha as straight RGBA8; images without alpha produce RGB8. Null inputs or sources return null. Inline bytes need no storage service; URI-backed blobs read through the execution host's authorized storage access. Whole reads validate declared size and digest. Invalid images or formats fail the call.
Parameters
| Name | Required | Type | Description |
|---|---|---|---|
image | yes | spql.EncodedImage? | Blob or EncodedImage containing the encoded image payload. |
format | no | utf8? | Optional jpeg, jpg or png format override. A null value sniffs the bytes; when omitted, an EncodedImage's stored format is used. |
spql.image.encode
Encode an Image into an EncodedImage.
- Kind:
scalar function - Volatility:
immutable
spql.image.encode(image, format) -> spql.EncodedImage?The initial encoder supports jpeg and png and stores the encoded bytes in an inline Blob.
Parameters
| Name | Required | Type | Description |
|---|---|---|---|
image | yes | spql.Image? | Decoded image pixels to encode. |
format | yes | utf8? | Output encoding: jpeg, jpg or png. |
spql.image.from_blob
Construct an EncodedImage from a Blob without reading bytes.
- Kind:
scalar function - Volatility:
immutable
spql.image.from_blob(source, format?) -> spql.EncodedImage?Parameters
| Name | Required | Type | Description |
|---|---|---|---|
source | yes | spql.Blob? | Blob containing the encoded image payload. |
format | no | utf8? | Optional encoded format such as jpeg or png. |
spql.image.from_tensor
Construct an Image from an HWC u8 Tensor with three or four channels.
- Kind:
scalar function - Volatility:
immutable
spql.image.from_tensor(tensor) -> spql.Image?Parameters
| Name | Required | Type | Description |
|---|---|---|---|
tensor | yes | spql.Tensor? | Tensor whose shape and layout describe the image pixels. |
spql.image.has_alpha
Return whether an Image has an alpha channel.
- Kind:
scalar function - Volatility:
immutable
spql.image.has_alpha(image) -> bool?Parameters
| Name | Required | Type | Description |
|---|---|---|---|
image | yes | spql.Image? | Image to inspect for dimensions or pixel format. |
spql.image.height
Return an Image's height in pixels.
- Kind:
scalar function - Volatility:
immutable
spql.image.height(image) -> u32?Parameters
| Name | Required | Type | Description |
|---|---|---|---|
image | yes | spql.Image? | Image to inspect for dimensions or pixel format. |
spql.image.mean_luminance
Mean linear relative luminance of all displayed image pixels.
- Kind:
scalar function - Volatility:
immutable
spql.image.mean_luminance(image, 'color_assumption'?) -> f64?Returns dimensionless luminance relative to reference white. RGB Image values use their sRGB display contract; alpha is ignored, not composited. YUV420 requires BT.709 primaries, a BT.709 matrix, full or limited range, and BT.709, sRGB, or linear transfer metadata. A named assumption fills absent metadata only; incompatible metadata is rejected. Transfer decoding precedes the BT.709 luminance weighting. Coded padding is excluded, chroma is shared by each 2x2 block, and reconstructed RGB is clipped to the reference gamut. Null and zero-size images return null. This is neither encoded luma nor arithmetic RGB mean, and does not measure lux or absolute luminance.
Parameters
| Name | Required | Type | Description |
|---|---|---|---|
image | yes | spql.Image?, spql.Yuv420Image? | Image or Yuv420Image to measure. |
color_assumption | no | utf8? | For missing YUV color metadata only: bt709_limited, bt709_full, srgb_bt709_limited, or srgb_bt709_full. Omit to require complete supported metadata. |
spql.image.resize
Resize an Image using the selected physical backend.
- Kind:
scalar function - Volatility:
immutable
spql.image.resize(image, 1, 1, 'method'?) -> spql.Image?Parameters
| Name | Required | Type | Description |
|---|---|---|---|
image | yes | spql.Image? | Image to resize to the requested pixel dimensions. |
width | yes | u32? | A non-null, non-zero dimension in pixels. |
height | yes | u32? | A non-null, non-zero dimension in pixels. |
method | no | utf8 | Interpolation method: nearest or bilinear. |
spql.image.to_rgb
Convert a Yuv420Image to a packed sRGB Image for image operations and AI.
- Kind:
scalar function - Volatility:
immutable
spql.image.to_rgb(image, 'color_assumption'?) -> spql.Image?Supports full/limited range and BT.709, BT.601 or BT.2020 non-constant-luminance matrices. Supported primaries: bt709, bt470bg, smpte170m, smpte240m, bt2020. Supported transfers: bt709, smpte170m, bt2020-10, bt2020-12, iec61966-2-1, linear, gamma22, gamma28. Converts primaries and transfer to sRGB, clips out-of-gamut RGB, and rounds to 8-bit samples. Excludes coded padding and uses the shared chroma sample for each 2x2 block. Missing metadata fails unless a named assumption supplies an absent field; existing metadata is never overwritten. Unsupported metadata always fails. HDR tone mapping is not supported. Null and zero-size inputs return null. This converts decoded pixels; it does not decode a video or run inference. Color assumptions: bt709_full, bt709_limited, srgb_bt709_full, srgb_bt709_limited, bt601_625_full, bt601_625_limited, bt601_525_full, bt601_525_limited. Omit to require complete metadata.
Parameters
| Name | Required | Type | Description |
|---|---|---|---|
image | yes | spql.Yuv420Image? | Planar Yuv420Image to convert to RGB pixels. |
color_assumption | no | utf8? | Fill absent color metadata with a named profile. See details for supported profiles. |
Returns
A nullable Image with contiguous RGB8 pixels, usable by spql.ai.score.
spql.image.to_tensor
Convert an Image to a variable-shape Tensor.
- Kind:
scalar function - Volatility:
immutable
spql.image.to_tensor(image, 'layout'?, 'normalization'?) -> spql.Tensor?Literal arguments can refine the result type, including its units, shape or element type.
Without options, this is a zero-copy HWC u8 view. Unit normalization produces CHW f32 values in the zero-to-one range. ImageNet normalization additionally applies the standard RGB channel mean and standard deviation. Physical backends can fuse this conversion with image resize and video decode.
Parameters
| Name | Required | Type | Description |
|---|---|---|---|
image | yes | spql.Image? | Image pixels to arrange in the requested tensor layout. |
layout | no | utf8 | Output layout: hwc for none or chw for unit and imagenet. |
normalization | no | utf8 | Pixel normalization: none, unit, or imagenet. |
spql.image.width
Return an Image's width in pixels.
- Kind:
scalar function - Volatility:
immutable
spql.image.width(image) -> u32?Parameters
| Name | Required | Type | Description |
|---|---|---|---|
image | yes | spql.Image? | Image to inspect for dimensions or pixel format. |