1 data_handling

data_handling

Canonical data contracts for ASE/EFM snippets and derived NBV stores.

aria_nbv.data_handling owns the typed boundary between upstream ASE/ATEK/EFM payloads and the training/evaluation objects consumed by ARIA-NBV. The public surface exposes:

  • EfmSnippetView and stream-specific views for camera images, calibration, trajectory poses, semidense points, OBBs, GT annotations, and optional meshes;
  • VinSnippetView and VinOracleBatch for VIN-style one-step RRI scoring;
  • strict immutable VIN offline-store readers/writers;
  • oracle target-task sampling for rollout/data-generation labels;
  • actor-visible target selection for diagnostics and deployable-policy studies.

The central safety contract is actor/oracle separation. Observed EVL/MPS/OBB evidence is actor-visible; ASE meshes, GT OBBs, target crops, and oracle labels are supervision/evaluation assets. Invalid samples, targets, or candidates must be represented with masks and reason codes rather than low RRI values.

1.1 Attributes

Name Description
OFFLINE_DATASET_VERSION Version of the immutable VIN offline dataset format.
ORACLE_TARGET_TASK_SOURCE Source label for oracle target-task rows sampled from GT OBBs.
TARGET_INVALID_REASON_CODES Version-1 target invalidity reason bit positions.
TARGET_INVALID_REASON_VERSION Version label for TARGET_INVALID_REASON_CODES.
VinDatasetSourceConfig Canonical split-aware VIN dataset-source union used by Lightning.

1.2 Classes

Name Description
AseEfmDataset Iterable dataset yielding EfmSnippetView with optional GT mesh.
AseEfmDatasetConfig Configuration for AseEfmDataset.
EfmCameraView Zero-copy camera stream view in EFM schema (images, calibration, timing, optional depth).
EfmGTView Ground-truth annotations (EFM schema) for a snippet.
EfmObbView Snippet-level oriented bounding boxes in the EFM ObbTW layout.
EfmPointsView Padded semi-dense SLAM point cloud view with per-frame metadata.
EfmSnippetView Typed wrapper over an EFM-formatted sample plus optional mesh.
EfmTrajectoryView World-frame rig trajectory aligned to snippet frames.
VinSnippetView Minimal snippet payload for VIN v2 batching.
MeshProcessSpec Specification that uniquely defines a processed mesh artifact.
ProcessedMesh Container for processed mesh and cached tensors.
CompactObbBlock Collatable numeric OBB payload used by training and diagnostics.
CompactTrajectoryBlock Trajectory metadata persisted alongside VIN snippet poses.
VinOracleBatch Single-snippet VIN training batch produced from an oracle label run.
VinOracleDatasetBase Shared interface for datasets that yield VinOracleBatch.
VinOfflineDataset Map-style random-access dataset backed by the immutable VIN offline store.
VinOfflineDatasetConfig Configuration for reading immutable VIN offline datasets.
VinOfflineSample Canonical root sample for diagnostics and rollout generation.
NumericSummary Finite-value summary for one numeric diagnostic series.
VinOfflineBackboneDiagnostic Streaming numeric summary for one stored backbone field.
VinOfflineBlockDiagnostic Render-ready manifest summary for one stored offline block.
VinOfflineCoverageSceneDiagnostic Per-scene raw-dataset coverage against one immutable offline store.
VinOfflineCoverageStats Raw-dataset coverage summary for one immutable VIN offline store.
VinOfflineDatasetStats Store-level diagnostics for an immutable VIN offline dataset.
VinOfflineMemoryDiagnostic Estimated per-sample runtime memory for one offline-store component.
VinOfflineSampleDiagnostic Per-row sanity summary for one sampled VIN offline record.
VinOfflineIndexRecord Global sample-index entry for VIN offline random access.
VinOfflineManifest Top-level manifest for one immutable VIN offline dataset.
VinOfflineMaterializedBlocks Materialized block flags for a VIN offline dataset.
VinOfflineStoreConfig Filesystem configuration for one immutable VIN offline dataset.
OfflineVisualInventory Summary of required and optional visual payloads for one offline sample.
OfflineVisualInventoryError Raised when an offline sample is missing required visual-inventory fields.
VinOfflineWriter Build immutable VIN offline datasets from raw ASE/EFM snippets.
VinOfflineWriterConfig Configuration for building immutable VIN offline datasets from raw snippets.
ActorVisibleTargetSelector Select top-K target OBBs from actor-visible snippet evidence.
OracleTargetTaskRow One oracle target-task row for rollout/data-generation labeling.
OracleTargetTaskSampler Sample oracle GT target tasks for rollout/data-generation labeling.
OracleTargetTaskSamplerConfig Configuration for OracleTargetTaskSampler.
OracleTargetTaskSamplingResult Oracle target-task pool and seeded capped sample for one snippet.
OracleTargetTaskSweepCell Coverage count for one oracle identity-threshold cell.
TargetCandidateRow One actor-visible target candidate and its oracle audit fields.
TargetSelectionPolicy Supported top-K target selection policies.
TargetSelectionResult Ranked target table and selected top-K rows for one snippet.
TargetSelectorConfig Configuration for ActorVisibleTargetSelector.
TargetSourceMode Selector source protocol.
TargetTaskIdentityStatus Identity-gate status for oracle target-task rows.
VinOfflineSourceConfig Configuration for the immutable VIN offline dataset source.
VinOracleOnlineDataset Iterable dataset yielding VinOracleBatch with online oracle labels.
VinOracleOnlineDatasetConfig Configuration for online oracle VIN datasets.

1.3 Functions

Name Description
infer_semidense_bounds Infer snippet world-space AABB from semidense metadata or points.
is_efm_snippet_view_instance Return whether value behaves like an EfmSnippetView.
is_vin_snippet_view_instance Return whether value behaves like a VinSnippetView.
load_or_process_mesh Crop/simplify a mesh once and persist the result on disk.
build_vin_snippet_view Build a VIN snippet view from an EFM snippet using the canonical adapter.
empty_vin_snippet Return an empty VIN snippet view.
collect_vin_offline_dataset_coverage Compare raw ASE tar-header coverage against an immutable VIN store.
collect_vin_offline_dataset_stats Collect coverage, shape, RRI, and memory diagnostics for a VIN store.
collect_offline_visual_inventory Collect visual diagnostics for a VinOfflineSample.
flush_prepared_samples_to_shard Materialize a list of prepared rows into one immutable shard.
prepare_vin_offline_sample Normalize one oracle-labelled snippet into offline row blocks.
target_gt_obb_world Resolve the matched GT target OBB in world coordinates.