Image Extension - Spiral Docs

The default CLI session registers implemented image primitives for JPEG data:

Surface	Status	Purpose
`spql.image.Jpeg`	Implemented	Lazy JPEG handle over a Blob source.
`spql.image.JpegBytes`	Implemented	Materialized encoded JPEG bytes.
`spql.image.Exif`	Implemented, unstable	Parsed EXIF summary value.
`spql.viz.ImageView`	Implemented	Image preview value backed by a Blob source.
Dataset discovery table functions	Experimental	See the planned section below.

JPEG Handles

Construct a lazy JPEG handle from a Blob:


SELECT spql.image.jpeg(spql.io.blob('file:///tmp/photo.jpg', mime_type => 'image/jpeg')) AS photo;

spql.image.jpeg(source) expects a spql.io.Blob. It wraps the source and does not read bytes immediately.

JPEG Bytes

Construct materialized JPEG bytes from a binary column:


SELECT spql.image.jpeg_bytes(encoded_jpeg) AS photo_bytes
FROM photos;

Read a Blob source as materialized JPEG bytes:


SELECT spql.image.read_jpeg(source_blob) AS photo_bytes
FROM photos;

spql.image.read_jpeg is an async scalar function. It validates that the bytes begin with a JPEG SOI marker.

EXIF

Read an EXIF summary from a lazy JPEG handle:


SELECT spql.image.exif(spql.image.jpeg(source_blob)) AS exif
FROM photos;

Read EXIF from materialized JPEG bytes:


SELECT spql.image.exif(photo_bytes) AS exif
FROM photos;

The current EXIF summary storage contains:

Field	Meaning
`byte_len`	Length of the EXIF APP1 payload.
`camera_make`	Camera make when present.
`camera_model`	Camera model when present.
`created_at`	EXIF original timestamp when present.
`orientation`	EXIF orientation value `1..8` when present.
`gps_present`	Whether any GPS EXIF fields were present.

For lazy JPEG handles, spql.image.exif rewrites to an internal async prefix read and scans at most the first MiB of the Blob. For JpegBytes, EXIF parsing is synchronous over the materialized bytes.

Preview

The image plugin registers a default visualization coercion from Jpeg to spql.viz.ImageView. Materialized JpegBytes values must be externalized into spql.io.Blob before they can use the Blob-backed ImageView path. The current egui provider renders length-1 ImageView arrays and supports JPEG MIME data.

Planned Dataset Functions

Experimental: Contact Us

This surface is directional and may change before public release. Contact Spiral if you want to use it in an early workflow.

Image dataset discovery table functions are not public runtime APIs yet. The intended shape is:

Function	Purpose
`images.scan(path)`	Discover images below a local path, object-store prefix, or manifest.
`images.manifest(path)`	Read an explicit manifest with ids, paths, labels, splits, and metadata.
`images.decode(image_ref)`	Materialize image bytes or tensors for a bounded result.
`images.thumbnails(image_ref)`	Produce lightweight preview artifacts.

These names are preview names. The current binder supports positional and named table-function arguments, but these image dataset functions are not registered yet.