Skip to content

Public API Reference

The supported Python surface is split by ownership. Heavy model and native runtimes remain lazy until their factories—or a ReID-enabled tracker adapter's live embedding path—are invoked.

Structures

One canonical RGB frame.

image is an unbatched, CPU-contiguous torch.uint8 tensor in RGB channel-first layout: [3, height, width]. Construction never casts, moves, or copies the supplied tensor.

image_size property 

image_size: tuple[int, int]

Return (height, width).

Axis-aligned xyxy boxes stored as float32[N, 4].

Oriented cxcywha boxes stored as float32[N, 5].

Angles are expressed in radians and intentionally remain unwrapped.

Full-frame boolean masks stored as bool[N, H, W].

image_size property 

image_size: tuple[int, int]

Return (height, width).

Detection rows and optional row-aligned perception enrichments.

select 

select(indices: Tensor) -> Detections

Select or reorder rows while preserving every aligned field.

to_aabb_rows 

to_aabb_rows() -> Tensor

Serialize AABB detections as [x1,y1,x2,y2,score,class] float32 rows.

to_obb_rows 

to_obb_rows() -> Tensor

Serialize OBB detections as [cx,cy,w,h,angle,score,class] float32 rows.

with_embeddings 

with_embeddings(embeddings: Tensor) -> Detections

Return a detection batch enriched with aligned appearance vectors.

with_instance_ids 

with_instance_ids(
    instance_ids: tuple[str, ...],
) -> Detections

Return a detection batch carrying stable row-aligned instance IDs.

with_masks 

with_masks(masks: MaskBatch) -> Detections

Return a detection batch enriched with aligned full-frame masks.

Tracker outputs with optional full-frame masks aligned to track rows.

select 

select(indices: Tensor) -> Tracks

Select or reorder rows while preserving track-aligned masks.

to_aabb_rows 

to_aabb_rows() -> Tensor

Serialize AABB tracks as [x1,y1,x2,y2,id,score,class,det_idx] float32 rows.

to_obb_rows 

to_obb_rows() -> Tensor

Serialize OBB tracks as [cx,cy,w,h,angle,id,score,class,det_idx] float32 rows.

with_masks 

with_masks(masks: MaskBatch) -> Tracks

Return track rows carrying aligned full-frame masks.

Pipelines

Progressively enrich batches of canonical detections.

enrich 

enrich(
    frames: Sequence[Frame],
    detections: Sequence[Detections],
    requirements: TrackerRequirements = TrackerRequirements(),
) -> list[Detections]

Attach requested and tracker-required payloads to existing detections.

process 

process(frames: Sequence[Frame]) -> list[Detections]

Detect and enrich an ordered frame batch according to requested outputs.

Run perception and tracking for one caller-owned frame at a time.

reset 

reset() -> None

Reset tracker and sequence-order state for a new stream.

step 

step(frame: Frame) -> PipelineResult

Detect objects and advance the pipeline by one frame.

step_detections 

step_detections(
    frame: Frame, detections: Detections
) -> PipelineResult

Advance tracking from caller-supplied detections after required enrichment.

Optional enrichments requested from a perception pipeline.

The enriched detections and tracks produced for one frame.

Dataset loader

One canonical sample loaded from a materialized build.

Bases: Sequence[DatasetSample]

Read a versioned build and join optional data by stable instance key.

Parameters:

  • build (str | Path) –

    Explicit path to the immutable dataset build.

  • split (str | None, default: None ) –

    Optional exact split filter.

  • load_images (bool, default: False ) –

    Decode image references into canonical :class:Frames.

  • load_masks (bool, default: False ) –

    Decode the keyed bit-packed mask table.

  • load_embeddings (bool, default: False ) –

    Load the keyed embedding table.