1 vin.feature_bank

vin.feature_bank

Feature-bank containers and pooling helpers for VIN readers.

This package owns actor-visible point-descriptor payloads, multiview sampling, permutation-invariant reductions, compression labels, and source-role checks.

1.1 Classes

Name Description
FeaturePoolingResult Weighted point descriptors pooled over logged observations.
PointFeatureBank Feature bank derived from logged actor-visible observations.
PointQueryPool Permutation-invariant descriptor statistics for a masked point query.

1.1.1 FeaturePoolingResult

vin.feature_bank.FeaturePoolingResult(
    features,
    valid_mask,
    valid_frame_count,
    weight_sum,
)

Weighted point descriptors pooled over logged observations.

1.1.1.1 Attributes

Name Description
features Tensor["B N_p C", float32] weighted descriptor mean per point.
valid_mask Tensor["B N_p", bool] points supported by at least one frame.
valid_frame_count Tensor["B N_p", int64] valid logged frames per point.
weight_sum Tensor["B N_p", float32] pooling-weight sum before epsilon.

1.1.2 PointFeatureBank

vin.feature_bank.PointFeatureBank(
    points_world,
    features,
    valid_mask,
    valid_frame_count,
    weight_sum,
    per_frame_valid,
    source_frame_indices,
    feature_source,
    source_role='actor_visible',
    compression_id='raw',
    point_support=None,
)

Feature bank derived from logged actor-visible observations.

The dataclass validates provenance at construction but is not frozen; callers that require immutable cache records must enforce immutability at the storage boundary.

Descriptor values are learned-source-local rather than globally comparable. feature_source and compression_id are human-readable provenance labels, not content hashes. Persistent EVL-derived banks must be paired by their cache owner with source-config and checkpoint hashes.

1.1.2.1 Attributes

Name Description
points_world Tensor["B N_p 3", float32] world-frame point coordinates in metres.
features Tensor["B N_p C", float32] logged-view descriptors pooled per point.
valid_mask Tensor["B N_p", bool] mask for points with descriptor support.
valid_frame_count Tensor["B N_p", int64] valid logged-frame samples per point.
weight_sum Tensor["B N_p", float32] pooling-weight sum before epsilon.
per_frame_valid Tensor["B T N_p", bool] per-frame projection-valid mask.
source_frame_indices Tensor["B T", int64] logged source-frame indices.
feature_source Approved actor-visible source label; not a checkpoint content hash.
source_role Provenance role; actor banks accept only "actor_visible".
compression_id Descriptor compression label; not a projection-matrix content hash.
point_support Optional point/sample weights broadcast by the multiview pooler.

1.1.2.2 Methods

Name Description
validate_actor_visible Reject oracle, GT, future-candidate, or unapproved feature sources.
1.1.2.2.1 validate_actor_visible
vin.feature_bank.PointFeatureBank.validate_actor_visible()

Reject oracle, GT, future-candidate, or unapproved feature sources.

1.1.3 PointQueryPool

vin.feature_bank.PointQueryPool(mean, maximum, std, count, valid_mask)

Permutation-invariant descriptor statistics for a masked point query.

1.1.3.1 Attributes

Name Description
mean Tensor["B C", float32] selected-point descriptor mean.
maximum Tensor["B C", float32] selected-point elementwise maximum.
std Tensor["B C", float32] selected-point population deviation.
count Tensor["B", int64] selected-point count.
valid_mask Tensor["B", bool] non-empty query-support mask.

1.2 Functions

Name Description
compress_point_features Apply an explicit descriptor compression transform.
pool_multiview_point_features Pool per-frame point descriptors with projection-valid weights.
pool_point_query Compute permutation-invariant masked point-pool summaries.
sample_logged_image_features_at_world_points Sample logged image features at semidense or fused world points.
validate_actor_feature_provenance Validate that a feature source can be consumed by actor-side models.

1.2.1 compress_point_features

vin.feature_bank.compress_point_features(
    features,
    *,
    projection=None,
    output_dim=None,
)

Apply an explicit descriptor compression transform.

1.2.1.1 Parameters

Name Type Description Default
features Tensor Tensor[..., C] point descriptors. required
projection Tensor | None Optional Tensor["C D"] projection matrix. None
output_dim int | None Optional leading channel count when using a simple slice. None

1.2.1.2 Returns

Name Type Description
Tensor Compressed descriptors.

1.2.2 pool_multiview_point_features

vin.feature_bank.pool_multiview_point_features(
    sampled_features,
    valid_mask,
    *,
    point_weights=None,
    eps=1e-06,
)

Pool per-frame point descriptors with projection-valid weights.

1.2.2.1 Parameters

Name Type Description Default
sampled_features Tensor Tensor["B T N C"] sampled logged-frame features. required
valid_mask Tensor Tensor["B T N", bool] projection-valid samples. required
point_weights Tensor | None Optional weights shaped N, T, B N, B T, T N, or B T N. Typical values encode point uncertainty, support, recency, or logged-view quality. None
eps float Positive denominator guard. 1e-06

1.2.2.2 Returns

Name Type Description
FeaturePoolingResult Weighted means and validity diagnostics.

1.2.3 pool_point_query

vin.feature_bank.pool_point_query(point_features, point_mask, *, eps=1e-06)

Compute permutation-invariant masked point-pool summaries.

Mean, maximum, population standard deviation, and count are symmetric in the N_p axis. Jointly permuting point_features and point_mask therefore leaves every output unchanged. This is set-permutation invariance, not a graph-isomorphism contract; no edges or message passing are constructed here.

1.2.3.1 Parameters

Name Type Description Default
point_features Tensor Tensor["B N_p C", float32] point descriptors. required
point_mask Tensor Tensor["B N_p", bool] points included in the query. required
eps float Positive denominator guard for mean and std. 1e-06

1.2.3.2 Returns

Name Type Description
PointQueryPool Mean, max, std, count, and empty-support mask.

1.2.4 sample_logged_image_features_at_world_points

vin.feature_bank.sample_logged_image_features_at_world_points(
    points_world,
    feat2d,
    cameras,
    t_world_camera,
    point_weights=None,
    source_frame_indices=None,
    feature_source='efm3d_feat2d_upsampled',
    source_role='actor_visible',
    compression_projection=None,
    compression_output_dim=None,
    compression_id='raw',
    eps=1e-06,
    warn=False,
)

Sample logged image features at semidense or fused world points.

1.2.4.1 Parameters

Name Type Description Default
points_world Tensor Tensor["N_p 3", float32] or Tensor["B N_p 3", float32] world-frame points in metres. required
feat2d Tensor Logged Tensor["B T C H W", float32] or Tensor["T C H W", float32] feature maps. required
cameras CameraTW CameraTW with shape B T or T. required
t_world_camera PoseTW PoseTW with shape B T or T. required
point_weights Tensor | None Optional point/sample weights for pooling. None
source_frame_indices Tensor | None Optional frame ids shaped B T or T. None
feature_source str Approved actor-visible source label. This label does not replace model-config or checkpoint hashes for persisted banks. 'efm3d_feat2d_upsampled'
source_role str Actor/oracle provenance role. 'actor_visible'
compression_projection Tensor | None Optional projection matrix for descriptors. None
compression_output_dim int | None Optional slice dimension for descriptors. None
compression_id str Stable compression label; content-address the projection separately when durable identity matters. 'raw'
eps float Positive denominator guard. 1e-06
warn bool Forward low-validity warnings from EFM3D sample_images. False

1.2.4.2 Returns

Name Type Description
PointFeatureBank Actor-visible point descriptors and provenance masks.

1.2.5 validate_actor_feature_provenance

vin.feature_bank.validate_actor_feature_provenance(
    feature_source,
    source_role='actor_visible',
)

Validate that a feature source can be consumed by actor-side models.

1.2.5.1 Parameters

Name Type Description Default
feature_source str Stable source id such as "efm3d_feat2d_upsampled". required
source_role str Provenance role. Actor inputs currently accept only "actor_visible". 'actor_visible'

1.2.5.2 Raises

Name Type Description
ValueError If the source is oracle/GT/counterfactual-only evidence.

1.2.5.3 Notes

Validation is label-based. Passing this check does not authenticate a config, checkpoint, compression projection, or cached tensor payload.

Back to top