1 data_handling.vin_store.dataset

data_handling.vin_store.dataset

Runtime views over the strict immutable VIN offline dataset.

The VIN offline store is the frozen one-step substrate for current ARIA-NBV training and diagnostics. It materializes ASE/EFM snippets into shard-local numeric blocks plus optional MessagePack diagnostics, then exposes either:

• VinOfflineSample for diagnostics, Rerun/Streamlit inspection, rollout-root generation, and live attachment of raw snippets or meshes; or
• VinOracleBatch for Lightning/VIN training.

The store is intentionally strict: readers accept the current V10 scene-labelled or explicitly qualified V11 actor-only stores, split membership comes from file-backed arrays, and sample_index.jsonl owns scene/snippet coverage. Rebuild stale stores with nbv-build-offline; do not patch manifests, split arrays, or shard payloads by hand.

1.1 Classes

Name	Description
VinOfflineDataset	Map-style random-access dataset backed by the immutable VIN offline store.
VinOfflineDatasetConfig	Configuration for reading immutable VIN offline datasets.
VinOfflineOracleBlock	Expose fixed-width oracle labels for one immutable VIN source row.
VinOfflineSample	Canonical root sample for diagnostics and rollout generation.

1.1.1 VinOfflineDataset

data_handling.vin_store.dataset.VinOfflineDataset(config)

Map-style random-access dataset backed by the immutable VIN offline store.

1.1.1.1 Attributes

Name	Description
is_map_style	Whether the dataset supports random access and batching.

1.1.1.2 Methods

Name	Description
get_by_scene_snippet	Look up one sample by (scene_id, snippet_id).

1.1.1.2.1 get_by_scene_snippet

data_handling.vin_store.dataset.VinOfflineDataset.get_by_scene_snippet(
    scene_id,
    snippet_id,
)

Look up one sample by (scene_id, snippet_id).

1.1.1.2.1.1 Parameters

Name	Type	Description	Default
scene_id	str	ASE scene identifier.	required
snippet_id	str	ASE snippet identifier.	required

1.1.1.2.1.2 Returns

Name	Type	Description
	VinOfflineSample | None	Matching offline sample or None.

1.1.2 VinOfflineDatasetConfig

data_handling.vin_store.dataset.VinOfflineDatasetConfig()

Configuration for reading immutable VIN offline datasets.

1.1.2.1 Attributes

Name	Description
target_type	Return VinOfflineDataset for config-as-factory construction.
paths	Project path resolver.
store	Immutable VIN offline dataset location.
split	Lifecycle stage to expose; None selects every stored row.
limit	Optional cap on the number of exposed samples.
simplification	Optional fraction of the split to expose for debugging.
include_efm_snippet	Whether to attach a live raw EFM snippet.
include_gt_mesh	Whether the live raw snippet loader should attach GT meshes.
load_backbone	Whether to decode cached backbone outputs.
load_candidates	Whether to decode cached candidate-sampling payloads.
backbone_keep_fields	Optional allowlist of backbone fields to materialize.
load_depths	Whether to decode cached candidate depth maps.
load_candidate_pcs	Whether to decode cached candidate point clouds.
load_gt_obbs	Whether to decode compact GT OBB blocks.
load_detected_obbs	Whether to decode compact detected OBB blocks.
load_trajectory_metadata	Whether to decode compact trajectory timing/gravity blocks.
return_format	Whether to return full offline samples or model-facing VIN batches.
map_location	Device used for returned tensors.
verbosity	Verbosity level for dataset diagnostics.

1.1.3 VinOfflineOracleBlock

data_handling.vin_store.dataset.VinOfflineOracleBlock(
    candidate_poses_world_cam,
    candidate_count,
    rri,
    pm_dist_before,
    pm_dist_after,
    pm_acc_before,
    pm_comp_before,
    pm_acc_after,
    pm_comp_after,
    p3d_cameras,
)

Expose fixed-width oracle labels for one immutable VIN source row.

The leading candidate width N_store is the writer’s persisted budget; only [:candidate_count] is valid. RRI and point-mesh fields are GT-mesh-derived supervision, never actor-visible policy inputs. Candidate poses preserve EFM’s world-from-sensor convention.

1.1.3.1 Attributes

Name	Description
candidate_poses_world_cam	PoseTW["N_store 12"] candidate world←camera transforms; translation is metres.
candidate_count	Valid prefix length inside every N_store candidate-aligned field.
rri	Tensor["N_store", float32] dimensionless oracle RRI; padded tail is invalid.
pm_dist_before	Tensor["N_store", float32] pre-view bidirectional error in square metres.
pm_dist_after	Tensor["N_store", float32] post-view bidirectional error in square metres.
pm_acc_before	Tensor["N_store", float32] pre-view point-to-mesh error in square metres.
pm_comp_before	Tensor["N_store", float32] pre-view mesh-to-point error in square metres.
pm_acc_after	Tensor["N_store", float32] post-view point-to-mesh error in square metres.
pm_comp_after	Tensor["N_store", float32] post-view mesh-to-point error in square metres.
p3d_cameras	PyTorch3D camera batch aligned one-to-one with the N_store candidate rows.

1.1.4 VinOfflineSample

data_handling.vin_store.dataset.VinOfflineSample(
    sample_key,
    scene_id,
    snippet_id,
    vin_snippet,
    reference_pose_world_rig,
    oracle,
    root_capability='scene_labelled_v10',
    sample_index=-1,
    split=Stage.TRAIN,
    source_shard_id=None,
    source_shard_row=None,
    candidates=None,
    backbone_out=None,
    depths=None,
    candidate_pcs=None,
    efm_snippet_view=None,
    gt_obbs=None,
    detected_obbs=None,
    trajectory=None,
)

Canonical root sample for diagnostics and rollout generation.

VinOfflineSample is intentionally richer than VinOracleBatch: it keeps sample-index lineage, optional raw snippet/mesh attachments, and diagnostic blocks needed to regenerate counterfactual candidates. Model training still goes through VinOracleBatch, while rollout writers consume this sample shape and carry its source shard fields into standalone rollout stores.

Numeric VIN/oracle blocks and lineage are reader-owned immutable data. efm_snippet_view is a worker-local live ATEK/EFM attachment; rich EVL, depth, point-cloud, and OBB payloads are decoded only when requested.

1.1.4.1 Attributes

Name	Description
sample_key	Stable compact ASE/ATEK sample key, independent of split iteration order.
scene_id	ASE scene identifier used for GT-mesh pairing and source lineage.
snippet_id	ATEK WebDataset sample identifier normalized to the compact public form.
vin_snippet	Actor-visible MPS/EFM point and trajectory substrate decoded from numeric blocks.
reference_pose_world_rig	PoseTW["12"] world←rig transform defining the actor-visible reference frame.
oracle	GT-mesh-derived scene labels, or None for explicitly actor-only V11 roots.
root_capability	Validated root capability; missing scene labels are intentional only for actor-only roots.
sample_index	Global zero-based sample index from sample_index.jsonl.
split	Lifecycle stage decoded from sample_index.jsonl.
source_shard_id	VIN offline shard id that stores this immutable source row.
source_shard_row	Zero-based row offset inside source_shard_id used for rollout lineage.
candidates	Optional regenerated/stored candidate metadata; not required by VIN training.
backbone_out	Optional actor-visible EVL evidence tied to serialized backbone config.
depths	Optional oracle-rendered candidate depths and masks for diagnostics.
candidate_pcs	Optional world-frame point clouds backprojected from oracle candidate depths.
efm_snippet_view	Worker-local live ATEK/EFM view; loaded on demand and never copied into the store.
gt_obbs	Optional ASE GT OBB label/evaluation payload; never an actor-visible target input.
detected_obbs	Optional actor-visible EVL detected boxes decoded from persisted blocks.
trajectory	Optional MPS/EFM pose timestamps and world-frame gravity metadata.