boxmot.engine.dataset_variants.cache

Derive immutable caches by selecting frames without rerunning perception.

reuse_cached_build

reuse_cached_build(
    parent_build: Path,
    *,
    parent_catalog: SourceCatalog,
    catalog: SourceCatalog,
    sample_map: Mapping[str, str],
    plan: BuildPlan,
    progress: MaterializationProgressReporter | None = None,
    embedding_metadata: Mapping[str, Any] | None = None,
    target_shard_rows: int = 50000,
) -> Path

Fill a compatible canonical build plan from cached selected frame outputs.

Callers must establish matching perception configuration before reusing a parent. This helper validates source selection and payload availability, then preserves the requested build identity and metadata while executing copied detect/segment/embed outputs through the regular locked materializer.

derive_cached_build

derive_cached_build(
    parent_build: Path,
    *,
    parent_catalog: SourceCatalog,
    catalog: SourceCatalog,
    sample_map: Mapping[str, str],
    build_root: Path,
) -> Path

Publish a validated frame subset with original detections and embeddings.

sample_map maps each derived sample ID to its original sample ID. Both catalogs must describe identical selected image bytes, dimensions, capture timestamps, and taxonomy. The derived catalog owns sequence/frame numbering and ground truth; perception component identities remain those of the parent.