Visual data, from compressed sources to model inputs.

Spiral gives video, images, annotations, embeddings, and model outputs a shared data model. Query a clip, crop, track, or semantic slice; Spiral plans the native reads, preserves visual semantics, and materializes the result where the model needs it.

Visual source specimen · H.264 in MP4

Native visual plugins

Video, image, annotation, and embedding plugins expose samples, timestamps, tiles, geometry, and indexes to the same query planner.

Transform-aware semantics

Crop, resize, resample, and augmentation operations update pixels, boxes, masks, keypoints, tracks, and time together.

Accelerator materialization

Decode, color conversion, transforms, packing, and host-to-device movement form one planned path to CPU or GPU tensors.

01 · The visual project

A visual dataset has more than pixels.

A frame can carry a timestamp, camera identity, boxes, masks, tracks, captions, embeddings, quality scores, and predictions. Spiral models those as related collections, so a query can move from one representation to another without losing the source, coordinate system, or revision that gives it meaning.

framestrackscaptionsembeddingspredictions

visual
└── street_scene
    ├── media[]
    ├── frames[]
    ├── annotations
    │   ├── boxes[]
    │   ├── masks[]
    │   └── tracks[]
    ├── embeddings[]
    └── model_outputs[]

Spiral's readers expose visual structure without forcing one canonical ingest layout. The source stays immutable while new annotations, indexes, and model outputs become queryable siblings.

02 · Access patterns

Different visual requests require different reads.

Playback is only one access pattern. A training job may sample a dense clip, retrieve sparse frames, follow an object track, or search embeddings before touching the source pixels. Spiral turns each logical request into the native work it requires.

Request	Spiral plans	Materialized result
Dense clip	Contiguous samples, one bounded decode, temporal resampling	T × C × H × W tensor
Sparse frames	Timestamp lookup, merged decode closures, coalesced ranges	N images with source timestamps
Tracked crops	Annotation predicate, source join, frame decode, geometric crop	Object chips, track IDs, and lineage
Semantic slice	Embedding search, metadata filter, ranked source selection	Frames or clips ready for review or training

03 · Visual semantics

Transforms update the image and its meaning.

A crop or horizontal flip changes more than pixels. Spiral represents visual transforms as operations over the frame and its coordinate-bound annotations, then records the graph and random seed with the sample. Boxes, masks, keypoints, and tracks stay aligned with the tensor they describe.

Transform preview

Pixels and geometry share the same transform graph.

bus-5572bus-8529bus-left

Source · 1600 × 900

bus-5572bus-8529bus-left

Tensor · 640 × 480

Pixels

crop · resize · normalize

Annotations

clip · remap x/y · retain IDs

Manifest

crop_4x3 · flip_x=false

04 · Native planning

Compressed media has a physical plan.

Spiral's video plugin reads MP4 sample tables, maps requested timestamps to presentation frames, expands codec dependencies, and coalesces the required object-store ranges. The execution path can then choose CPU or hardware decode, fuse visual transforms, and place the batch in accelerator memory.

Trace a real MP4 from query to tensor

01
Resolve outputs
Frames, clips, crops, color space, shape, and device.
02
Expand dependencies
Container indexes, codec closure, source joins, and byte ranges.
03
Execute transforms
Decode, color conversion, resize, augmentation, and packing.
04
Place the batch
CPU, pinned host memory, or the target accelerator.

05 · Physical layouts

One source can support several useful layouts.

Spiral keeps the original media as the source of truth, then builds lineage-preserving views for the workloads that justify them: shorter video dependency chains, frame indexes, thumbnails, packed crops, embeddings, or model-ready shards. Storage policy can follow observed queries instead of a one-time ingest decision.

Immutable source

Preserve the recording

Original bytes, timestamps, codec structure, and acquisition lineage.

30 fps · 300 frames · 1.88 MB

4 fps variant

Downsample the timeline

Fewer output frames and more frequent random-access points for a different request shape.

4 fps · 40 frames · 2.33 MB

Query-oriented transcode

Shorten dependency paths

A different frame graph can trade storage for less repeated decode work.

30 fps · 300 frames · 2.66 MB

The 4 fps variant contains 87% fewer frames and is still larger than the source. Spiral's materializer optimizes for the requested access path, decode work, quality, and reuse, not file size alone.

06 · From predicate to batch

A visual query can remain reproducible to the tensor.

Spiral resolves a project revision, finds candidate scenes and annotations, plans native reads, applies a versioned transform graph, and materializes the batch. The output manifest preserves what was selected, how it changed, and which source bytes produced it.

project.asof(revision)
  .visual.search("bus at an intersection")
  .where(tracks.label == "bus")
  .sample(clip="4s", fps=8)
  .transform(crop="track", resize=[224, 224],
             augment={ flip_x: 0.5, seed })
  .to_tensor(batch=128, device="cuda")

Batch manifest

project: vision-lab@8c1d
sources: 12 MP4 objects · 184 ranges
selection: bus tracks · 128 clips
transform: visual-224-v6 · seed 41902
output: [128, 32, 3, 224, 224] · fp16
placement: cuda:0 · contiguous

Talk to us