1 data_handling.vin_store

data_handling.vin_store

Immutable VIN offline-store contracts, adapters, and actor views.

Import specialized manifest, reader, writer, and batch contracts from their leaf modules; this package root intentionally exports only the stable snippet view predicates.

1.1 Package guide

aria_nbv.data_handling.vin_store persists expensive one-step evidence as an indexed, manifest-bound, immutable dataset. It is the source substrate for one-step VIN training, rollout generation, QH actor joins, and inspection.

For available stores and cross-store discovery, see the dataset store overview.

1.2 Store Layout

vin_offline/
  manifest.json
  sample_index.jsonl
  splits/
    all.npy
    train.npy
    val.npy
  shards/
    shard-000000/
      numeric_blocks.zarr/
      records.msgpack
      records_offsets.npy

The manifest binds format version, source configuration, materialized blocks, feature provenance, and shard identities. sample_index.jsonl maps stable global rows to scene, snippet, split, shard, and shard-local row. Readers reject unsupported versions and never migrate or repair a store in place.

1.3 Build and Inspect

cd aria_nbv
uv run nbv-build-offline \
  --config-path ../.configs/build_vin_offline_81286.toml \
  --dry-run
uv run nbv-build-offline \
  --config-path ../.configs/build_vin_offline_81286.toml

uv run nbv-offline-info summary --store vin_offline
uv run nbv-offline-info tree --store vin_offline
uv run nbv-offline-info samples --store vin_offline --split train --limit 5

The writer owns manifests, indices, split arrays, shards, and optional records. If the destination already exists, choose a new output path unless deliberately replacing a disposable smoke store.

1.4 Actor-only root increments

Set VinOfflineWriterConfig.preparation_mode="actor_only" to prepare a new immutable V11 root store without constructing the scene RRI labeler or generating, rendering, or unprojecting scene candidates. This capability retains the same actor semidense/trajectory substrate, eight compact EVL numeric blocks and their source qualification, detected OBB actor inputs, and GT OBB label assets. The reference pose retains the existing configured camera-frame resolution and clockwise yaw convention. GT boxes remain privileged assets, not actor inputs.

The manifest must declare vin.root_capability="actor_only_v1"; actor-only shards contain no oracle.* blocks. return_format="sample" exposes sample.oracle=None. These roots support rollout generation and actor joins; return_format="vin_batch" and scene-label inspection fail explicitly because there are no one-step scene labels. The original scene-labelled V10 mode remains the default and existing V10 manifests, payloads and lineage hashes are unchanged.

Each increment uses a new destination. This mode does not mutate or append into an existing immutable store. Learned EVL neck tensors are not newly introduced: this mode preserves the current compact evidence contract.

1.5 Read Samples

from pathlib import Path

from aria_nbv.data_handling import VinOfflineDatasetConfig
from aria_nbv.data_handling.vin_store.store import VinOfflineStoreConfig
from aria_nbv.utils import Stage

dataset = VinOfflineDatasetConfig(
    store=VinOfflineStoreConfig(store_dir=Path("vin_offline")),
    split=Stage.TRAIN,
    return_format="sample",
    load_backbone=True,
    load_candidates=True,
).setup_target()

sample = dataset[0]

Use return_format="vin_batch" for the one-step training DTO. QH joins use VinOfflineStoreReader.read_actor_snippet() internally and deliberately decode only actor-visible blocks needed by QhActorTensors.

1.6 Ownership

Module Responsibility
format Manifest, index, shard, and materialized-block schema.
writer Atomic construction of new immutable stores.
store Strict read-only manifest, split, and shard access.
dataset User-facing indexed dataset and return-format selection.
batch One-step VIN training DTOs.
views Actor-visible typed snippet projection.
diagnostics / inventory Read-only summaries and coverage.
info_cli Human- and JSON-readable store inspection.

Detailed tensor fields and lifecycle failures live in public docstrings and the generated API reference.

1.7 Verification

cd aria_nbv
uv run ruff check aria_nbv/data_handling/vin_store
uv run pytest tests/data_handling/test_vin_offline_store.py
uv run pytest tests/data_handling/test_public_api_contract.py

1.8 Classes

Name Description
VinSnippetView Minimal actor-visible snippet payload for VIN batching.

1.8.1 VinSnippetView

data_handling.vin_store.VinSnippetView(
    points_world,
    lengths,
    t_world_rig,
    t_world_snippet,
)

Minimal actor-visible snippet payload for VIN batching.

1.8.1.1 Attributes

Name Type Description
points_world Tensor Tensor["K_pad 3+C", float32] collapsed semidense points. Base columns are XYZ; optional extras include inverse distance uncertainty and observation count. Rows after lengths are NaN padding.
lengths Tensor Tensor["1", int64] or Tensor["B", int64] valid point counts for unbatched or batched payloads.
t_world_rig PoseTW PoseTW["F 12"] historical world-from-rig poses.

1.8.1.2 Methods

Name Description
to Move the VIN snippet tensors to the requested device and dtype.
1.8.1.2.1 to
data_handling.vin_store.VinSnippetView.to(device, *, dtype=None)

Move the VIN snippet tensors to the requested device and dtype.

Additional attribute identifiers: t_world_snippet

1.9 Functions

Name Description
is_vin_snippet_view_instance Return whether value exposes the structural VIN snippet interface.

1.9.1 is_vin_snippet_view_instance

data_handling.vin_store.is_vin_snippet_view_instance(value)

Return whether value exposes the structural VIN snippet interface.

Back to top