1 rollouts.inspection.geometry

rollouts.inspection.geometry

Typed proposal, trajectory, frustum, and spherical geometry projections.

1.1 Classes

Name	Description
GeometryFrame	One normalized Z-up frame used by a geometry projection.
GeometryIssue	Explicit exclusion or truncation affecting a geometry projection.
GeometryPoint	One candidate or factual trajectory point in a normalized frame.
GeometryProjection	Presentation-free candidate geometry with auditable frames and issues.
InitialTargetBevCandidate	One persisted candidate camera in a rollout’s fixed initial BEV frame.
InitialTargetBevFrame	One fixed initial root-camera-to-target bird’s-eye frame.
InitialTargetBevFrustum	Calibrated selected-camera corner rays in one fixed initial BEV frame.
InitialTargetBevProjection	Presentation-free fixed-initial-camera BEV evidence from canonical Zarr.
ProposalAlignment	Yaw-only frame used to compare per-step candidate proposal support.
S2DirectionHistogram	Complete factual selected-action directions in target-object coordinates.

1.1.1 GeometryFrame

rollouts.inspection.geometry.GeometryFrame(
    frame_id,
    rollout_row_id,
    step_row_id,
    step_index,
    origin_kind,
    expansion_pose_source,
    scale_kind,
    alignment,
    scale_m,
    initial_scale_m,
    target_x,
    target_y,
    target_z,
    reference_axis_x,
    reference_axis_y,
    reference_axis_z,
    target_axis_x,
    target_axis_y,
    target_axis_z,
    rig_target_yaw_error_deg=None,
    target_elevation_deg=None,
)

One normalized Z-up frame used by a geometry projection.

1.1.2 GeometryIssue

rollouts.inspection.geometry.GeometryIssue(
    code,
    message,
    rollout_row_id=None,
    step_row_id=None,
)

Explicit exclusion or truncation affecting a geometry projection.

1.1.3 GeometryPoint

rollouts.inspection.geometry.GeometryPoint(
    frame_id,
    role,
    rollout_row_id,
    step_row_id,
    step_index,
    candidate_row_id,
    path_order,
    actor_action,
    selected,
    position,
    strategy,
    mixture,
    x,
    y,
    z,
    displacement_m,
    normalization_distance_m,
    initial_target_distance_m,
    normalized_radius=0.0,
    target_facing_error_deg=None,
    camera_forward_x=None,
    camera_forward_y=None,
    camera_forward_z=None,
)

One candidate or factual trajectory point in a normalized frame.

1.1.4 GeometryProjection

rollouts.inspection.geometry.GeometryProjection(
    view,
    points,
    frames,
    issues,
    truncated=False,
)

Presentation-free candidate geometry with auditable frames and issues.

1.1.4.1 Methods

Name	Description
point_rows	Return serializable point mappings for reporting and plotting clients.
frame_rows	Return serializable frame mappings for anchor rendering clients.

1.1.4.1.1 point_rows

rollouts.inspection.geometry.GeometryProjection.point_rows()

Return serializable point mappings for reporting and plotting clients.

1.1.4.1.2 frame_rows

rollouts.inspection.geometry.GeometryProjection.frame_rows()

Return serializable frame mappings for anchor rendering clients.

1.1.5 InitialTargetBevCandidate

rollouts.inspection.geometry.InitialTargetBevCandidate(
    frame_id,
    rollout_row_id,
    step_row_id,
    step_index,
    candidate_row_id,
    actor_action,
    selected,
    position,
    strategy,
    mixture,
    x_m,
    y_m,
    z_m,
    x_over_dh,
    y_over_dh,
    z_over_dh,
    camera_forward_x,
    camera_forward_y,
    camera_forward_z,
)

One persisted candidate camera in a rollout’s fixed initial BEV frame.

1.1.6 InitialTargetBevFrame

rollouts.inspection.geometry.InitialTargetBevFrame(
    frame_id,
    rollout_row_id,
    horizontal_distance_m,
    root_camera_xyz_m,
    root_reference_xyz_m,
    target_xyz_m,
    target_extents_m,
    target_rotation_local,
)

One fixed initial root-camera-to-target bird’s-eye frame.

The origin is the physical root camera. The local x axis follows the initial horizontal camera-to-target bearing, y points world-horizontal left, and z is world up. horizontal_distance_m is the sole normalization denominator, so the target has normalized horizontal coordinates (1, 0) without discarding its metric height.

1.1.7 InitialTargetBevFrustum

rollouts.inspection.geometry.InitialTargetBevFrustum(
    frame_id,
    rollout_row_id,
    step_row_id,
    step_index,
    candidate_row_id,
    mixture,
    center_xyz_m,
    center_xyz_over_dh,
    corner_rays_local,
)

Calibrated selected-camera corner rays in one fixed initial BEV frame.

1.1.8 InitialTargetBevProjection

rollouts.inspection.geometry.InitialTargetBevProjection(
    view,
    frames,
    candidates,
    selected_frusta,
    issues,
    truncated=False,
)

Presentation-free fixed-initial-camera BEV evidence from canonical Zarr.

1.1.9 ProposalAlignment

rollouts.inspection.geometry.ProposalAlignment()

Yaw-only frame used to compare per-step candidate proposal support.

1.1.10 S2DirectionHistogram

rollouts.inspection.geometry.S2DirectionHistogram(
    movement_counts,
    view_direction_counts,
    movement_projection,
    movement_projection_normalized_lengths,
    movement_projection_rollout_row_ids,
    movement_projection_step_indices,
    view_direction_projection,
    view_direction_projection_rollout_row_ids,
    view_direction_projection_step_indices,
    frustum_counts,
    frustum_projection,
    frustum_projection_rollout_row_ids,
    frustum_projection_step_indices,
    movement_count,
    view_direction_count,
    frustum_count,
    frustum_missing_calibration_count,
    frustum_mean_fov_solid_angle_sr,
    frustum_mean_target_surface_fraction_approx,
    frustum_union_target_surface_fraction_approx,
    movement_skipped_zero_count,
    rollout_count,
    store_rollout_count,
    source_sample_count,
    source_snippet_count,
    source_scene_count,
    target_count,
    selected_step_count,
    azimuth_bins,
    elevation_bins,
    projection_limit,
    issues,
)

Complete factual selected-action directions in target-object coordinates.

The movement channel retains one selected transition per factual rollout step. If p_{t-1} and p_t are camera centres in world metres, and R_W^e is the target-object-to-world rotation, the recorded direction is

\[ \widehat{\boldsymbol{\delta}}_{j,t}^e = \frac{(R_W^e)^\mathsf{T}(p_t-p_{t-1}) / r_e} {\lVert (R_W^e)^\mathsf{T}(p_t-p_{t-1}) / r_e \rVert_2}, \qquad r_e=(a_x a_y a_z)^{1/3}. \]

(a_x, a_y, a_z) are the target OBB semi-axis lengths, obtained by halving the persisted full extents. Their geometric mean defines a geometric-mean semi-axis scale, so it does not privilege one OBB axis. The final movement direction is scale invariant, but retaining r_e also exposes the dimensionless transition length used by target-relative translation descriptors. View directions use the selected camera’s local +Z optical axis, transformed by (R_W^e)^T and normalized in the same target frame.

The frustum channel is different from the two direction channels. It places the proxy surface point x^e=r_e d^e at every equal-area bin centre, transforms x^e-c_{j,t}^e into the selected camera, and tests the persisted pinhole image rectangle. A bin contributes only when the proxy surface normal faces the camera and the projected point is in front of and inside the calibrated image. Thus frustum_counts measures geometric field-of-view support on a target-centred proxy sphere whose radius is the geometric-mean semi-axis scale. It is not occlusion-aware and must not be reported as measured target-mesh visibility.

Here j identifies the factual rollout chain and t its zero-based persisted decision step. The corresponding camera-forward direction is \widehat{\boldsymbol{v}}_{j,t}^e. Projection provenance retains both indices, so presentation clients can encode common rollout heritage by colour and common acquisition time by marker style without inferring either identity from array order.

movement_counts and view_direction_counts have shape ndarray["Z A", int64]. Z bins target-frame z uniformly and A bins azimuth uniformly; because dΩ=dφ dz, every cell has equal solid angle. The two *_projection arrays are bounded, deterministic display samples only; the count arrays always include the complete factual selected-action population.

1.2 Functions

Name	Description
initial_target_bev_geometry	Project complete candidate shells in a fixed initial camera frame.
proposal_support_geometry	Project complete candidate shells around their factual expansion poses.
rollout_trajectory_geometry	Project factual selected trajectories in one initial target-aligned frame.
s2_direction_bin_indices	Assign one target-frame direction to an equal-solid-angle S² cell.
s2_target_direction_histogram	Aggregate factual movement and camera-forward directions on S².
target_aligned_z_up_basis	Return the canonical world Z-up basis whose first axis faces the target.

1.2.1 initial_target_bev_geometry

rollouts.inspection.geometry.initial_target_bev_geometry(
    reader,
    *,
    rollout_row_ids=None,
    max_candidates=50000,
)

Project complete candidate shells in a fixed initial camera frame.

For rollout :math:r, let :math:c_0^W be the persisted physical root camera centre and :math:o^W the target centre. The horizontal baseline is

\[ d_{h,0}=\left\|(o^W-c_0^W)_{xy}\right\|_2. \]

One world-Z-up basis is built from that baseline and reused for every candidate at every factual step. Metric coordinates and coordinates divided by :math:d_{h,0} are both retained. This fixed frame intentionally differs from proposal_support_geometry, whose origin and three-dimensional scale change at each expansion, and from rollout_trajectory_geometry, whose origin is the corrected reference rig.

Selected frusta use the step-aligned selected-depth calibration persisted in canonical Zarr. Missing legacy root-camera poses or missing/mismatched calibration remain explicit issues; neither is replaced with a rig pose or another step’s camera.

1.2.2 proposal_support_geometry

rollouts.inspection.geometry.proposal_support_geometry(
    reader,
    *,
    alignment=ProposalAlignment.TARGET_ALIGNED_Z_UP,
    rollout_row_ids=None,
    step_row_ids=None,
    max_candidates=50000,
)

Project complete candidate shells around their factual expansion poses.

Step zero uses the persisted rollout root; later steps use the preceding factual selected pose. Coordinates are divided by that expansion pose’s current 3D target distance, then yaw-aligned while preserving world Z-up.

A step filter still walks preceding factual steps so a requested later shell retains its persisted previous-selected expansion pose. Candidate limits count only shells admitted by both rollout and step filters.

1.2.3 rollout_trajectory_geometry

rollouts.inspection.geometry.rollout_trajectory_geometry(
    reader,
    *,
    rollout_row_ids=None,
)

Project factual selected trajectories in one initial target-aligned frame.

1.2.4 s2_direction_bin_indices

rollouts.inspection.geometry.s2_direction_bin_indices(
    direction,
    *,
    azimuth_bins,
    elevation_bins,
)

Assign one target-frame direction to an equal-solid-angle S² cell.

The azimuth coordinate :math:\phi=\operatorname{atan2}(y,x) is split uniformly over :math:[-\pi,\pi). The vertical coordinate is the unit direction’s :math:z value rather than polar angle. Because spherical area satisfies :math:d\Omega=d\phi\,dz, every returned cell has equal solid angle. This is the same binning used by s2_target_direction_histogram.

1.2.4.1 Parameters

Name	Type	Description	Default
direction	`NDArray`[`np`.`floating`[Any]]	Finite nonzero target-frame three-vector. Unit length is not required; normalization is owned by this interface.	required
azimuth_bins	int	Positive number of azimuth cells.	required
elevation_bins	int	Positive number of uniform-`z` cells.	required

1.2.4.2 Returns

Name	Type	Description
	tuple[int, int]	`(elevation_index, azimuth_index)` in row-major histogram order.

1.2.4.3 Raises

Name	Type	Description
	ValueError	If the bin counts or direction violate the contract.

1.2.5 s2_target_direction_histogram

rollouts.inspection.geometry.s2_target_direction_histogram(
    reader,
    *,
    azimuth_bins=36,
    elevation_bins=18,
    projection_limit=2000,
)

Aggregate factual movement and camera-forward directions on S².

The reducer reads only each factual rollout root and its referenced selected candidate shells; it never materializes the full candidate table. For a target object frame e, selected camera centres are transformed with (R_W^e)^T. Consecutive translations are normalized by the geometric mean of the target OBB semi-axes before their unit-sphere projection, while the selected camera local +Z optical axis supplies the view direction. The calibrated-frustum channel evaluates which points of the corresponding target-centred geometric-mean-scale proxy sphere are front-facing and project inside each selected pinhole camera.

1.2.5.1 Parameters

Name	Type	Description	Default
reader	RolloutZarrStoreReader	Validated read-only rollout store.	required
azimuth_bins	int	Positive number of uniform target-frame azimuth bins.	`36`
elevation_bins	int	Positive number of uniform target-frame `z` bins. Uniform `z` rather than uniform polar angle gives equal-solid- angle S² cells.	`18`
projection_limit	int	Maximum deterministic reservoir samples retained per channel for a Plotly point overlay. Counts remain complete.	`2000`

1.2.5.2 Returns

Name	Type	Description
	S2DirectionHistogram	`S2DirectionHistogram` containing complete equal-solid-angle count
	S2DirectionHistogram	grids, bounded target-frame projection samples, and explicit exclusions.

1.2.5.3 Notes

A degenerate movement has no direction and is counted separately. Missing, non-rigid, or non-positive target OBB geometry excludes only that rollout and leaves the reason visible to presentation clients.

1.2.6 target_aligned_z_up_basis

rollouts.inspection.geometry.target_aligned_z_up_basis(target_delta)

Return the canonical world Z-up basis whose first axis faces the target.

# rollouts.inspection.geometry { #aria_nbv.rollouts.inspection.geometry } `rollouts.inspection.geometry` Typed proposal, trajectory, frustum, and spherical geometry projections. ## Classes | Name | Description | | --- | --- | | [GeometryFrame](#aria_nbv.rollouts.inspection.geometry.GeometryFrame) | One normalized Z-up frame used by a geometry projection. | | [GeometryIssue](#aria_nbv.rollouts.inspection.geometry.GeometryIssue) | Explicit exclusion or truncation affecting a geometry projection. | | [GeometryPoint](#aria_nbv.rollouts.inspection.geometry.GeometryPoint) | One candidate or factual trajectory point in a normalized frame. | | [GeometryProjection](#aria_nbv.rollouts.inspection.geometry.GeometryProjection) | Presentation-free candidate geometry with auditable frames and issues. | | [InitialTargetBevCandidate](#aria_nbv.rollouts.inspection.geometry.InitialTargetBevCandidate) | One persisted candidate camera in a rollout's fixed initial BEV frame. | | [InitialTargetBevFrame](#aria_nbv.rollouts.inspection.geometry.InitialTargetBevFrame) | One fixed initial root-camera-to-target bird's-eye frame. | | [InitialTargetBevFrustum](#aria_nbv.rollouts.inspection.geometry.InitialTargetBevFrustum) | Calibrated selected-camera corner rays in one fixed initial BEV frame. | | [InitialTargetBevProjection](#aria_nbv.rollouts.inspection.geometry.InitialTargetBevProjection) | Presentation-free fixed-initial-camera BEV evidence from canonical Zarr. | | [ProposalAlignment](#aria_nbv.rollouts.inspection.geometry.ProposalAlignment) | Yaw-only frame used to compare per-step candidate proposal support. | | [S2DirectionHistogram](#aria_nbv.rollouts.inspection.geometry.S2DirectionHistogram) | Complete factual selected-action directions in target-object coordinates. | ### GeometryFrame { #aria_nbv.rollouts.inspection.geometry.GeometryFrame } ```python rollouts.inspection.geometry.GeometryFrame( frame_id, rollout_row_id, step_row_id, step_index, origin_kind, expansion_pose_source, scale_kind, alignment, scale_m, initial_scale_m, target_x, target_y, target_z, reference_axis_x, reference_axis_y, reference_axis_z, target_axis_x, target_axis_y, target_axis_z, rig_target_yaw_error_deg=None, target_elevation_deg=None, ) ``` One normalized Z-up frame used by a geometry projection. ### GeometryIssue { #aria_nbv.rollouts.inspection.geometry.GeometryIssue } ```python rollouts.inspection.geometry.GeometryIssue( code, message, rollout_row_id=None, step_row_id=None, ) ``` Explicit exclusion or truncation affecting a geometry projection. ### GeometryPoint { #aria_nbv.rollouts.inspection.geometry.GeometryPoint } ```python rollouts.inspection.geometry.GeometryPoint( frame_id, role, rollout_row_id, step_row_id, step_index, candidate_row_id, path_order, actor_action, selected, position, strategy, mixture, x, y, z, displacement_m, normalization_distance_m, initial_target_distance_m, normalized_radius=0.0, target_facing_error_deg=None, camera_forward_x=None, camera_forward_y=None, camera_forward_z=None, ) ``` One candidate or factual trajectory point in a normalized frame. ### GeometryProjection { #aria_nbv.rollouts.inspection.geometry.GeometryProjection } ```python rollouts.inspection.geometry.GeometryProjection( view, points, frames, issues, truncated=False, ) ``` Presentation-free candidate geometry with auditable frames and issues. #### Methods | Name | Description | | --- | --- | | [point_rows](#aria_nbv.rollouts.inspection.geometry.GeometryProjection.point_rows) | Return serializable point mappings for reporting and plotting clients. | | [frame_rows](#aria_nbv.rollouts.inspection.geometry.GeometryProjection.frame_rows) | Return serializable frame mappings for anchor rendering clients. | ##### point_rows { #aria_nbv.rollouts.inspection.geometry.GeometryProjection.point_rows } ```python rollouts.inspection.geometry.GeometryProjection.point_rows() ``` Return serializable point mappings for reporting and plotting clients. ##### frame_rows { #aria_nbv.rollouts.inspection.geometry.GeometryProjection.frame_rows } ```python rollouts.inspection.geometry.GeometryProjection.frame_rows() ``` Return serializable frame mappings for anchor rendering clients. ### InitialTargetBevCandidate { #aria_nbv.rollouts.inspection.geometry.InitialTargetBevCandidate } ```python rollouts.inspection.geometry.InitialTargetBevCandidate( frame_id, rollout_row_id, step_row_id, step_index, candidate_row_id, actor_action, selected, position, strategy, mixture, x_m, y_m, z_m, x_over_dh, y_over_dh, z_over_dh, camera_forward_x, camera_forward_y, camera_forward_z, ) ``` One persisted candidate camera in a rollout's fixed initial BEV frame. ### InitialTargetBevFrame { #aria_nbv.rollouts.inspection.geometry.InitialTargetBevFrame } ```python rollouts.inspection.geometry.InitialTargetBevFrame( frame_id, rollout_row_id, horizontal_distance_m, root_camera_xyz_m, root_reference_xyz_m, target_xyz_m, target_extents_m, target_rotation_local, ) ``` One fixed initial root-camera-to-target bird's-eye frame. The origin is the physical root camera. The local ``x`` axis follows the initial horizontal camera-to-target bearing, ``y`` points world-horizontal left, and ``z`` is world up. ``horizontal_distance_m`` is the sole normalization denominator, so the target has normalized horizontal coordinates ``(1, 0)`` without discarding its metric height. ### InitialTargetBevFrustum { #aria_nbv.rollouts.inspection.geometry.InitialTargetBevFrustum } ```python rollouts.inspection.geometry.InitialTargetBevFrustum( frame_id, rollout_row_id, step_row_id, step_index, candidate_row_id, mixture, center_xyz_m, center_xyz_over_dh, corner_rays_local, ) ``` Calibrated selected-camera corner rays in one fixed initial BEV frame. ### InitialTargetBevProjection { #aria_nbv.rollouts.inspection.geometry.InitialTargetBevProjection } ```python rollouts.inspection.geometry.InitialTargetBevProjection( view, frames, candidates, selected_frusta, issues, truncated=False, ) ``` Presentation-free fixed-initial-camera BEV evidence from canonical Zarr. ### ProposalAlignment { #aria_nbv.rollouts.inspection.geometry.ProposalAlignment } ```python rollouts.inspection.geometry.ProposalAlignment() ``` Yaw-only frame used to compare per-step candidate proposal support. ### S2DirectionHistogram { #aria_nbv.rollouts.inspection.geometry.S2DirectionHistogram } ```python rollouts.inspection.geometry.S2DirectionHistogram( movement_counts, view_direction_counts, movement_projection, movement_projection_normalized_lengths, movement_projection_rollout_row_ids, movement_projection_step_indices, view_direction_projection, view_direction_projection_rollout_row_ids, view_direction_projection_step_indices, frustum_counts, frustum_projection, frustum_projection_rollout_row_ids, frustum_projection_step_indices, movement_count, view_direction_count, frustum_count, frustum_missing_calibration_count, frustum_mean_fov_solid_angle_sr, frustum_mean_target_surface_fraction_approx, frustum_union_target_surface_fraction_approx, movement_skipped_zero_count, rollout_count, store_rollout_count, source_sample_count, source_snippet_count, source_scene_count, target_count, selected_step_count, azimuth_bins, elevation_bins, projection_limit, issues, ) ``` Complete factual selected-action directions in target-object coordinates. The movement channel retains one selected transition per factual rollout step. If ``p_{t-1}`` and ``p_t`` are camera centres in world metres, and ``R_W^e`` is the target-object-to-world rotation, the recorded direction is $$ \widehat{\boldsymbol{\delta}}_{j,t}^e = \frac{(R_W^e)^\mathsf{T}(p_t-p_{t-1}) / r_e} {\lVert (R_W^e)^\mathsf{T}(p_t-p_{t-1}) / r_e \rVert_2}, \qquad r_e=(a_x a_y a_z)^{1/3}. $$ ``(a_x, a_y, a_z)`` are the target OBB semi-axis lengths, obtained by halving the persisted full extents. Their geometric mean defines a geometric-mean semi-axis scale, so it does not privilege one OBB axis. The final movement direction is scale invariant, but retaining ``r_e`` also exposes the dimensionless transition length used by target-relative translation descriptors. View directions use the selected camera's local ``+Z`` optical axis, transformed by ``(R_W^e)^T`` and normalized in the same target frame. The frustum channel is different from the two direction channels. It places the proxy surface point ``x^e=r_e d^e`` at every equal-area bin centre, transforms ``x^e-c_{j,t}^e`` into the selected camera, and tests the persisted pinhole image rectangle. A bin contributes only when the proxy surface normal faces the camera and the projected point is in front of and inside the calibrated image. Thus ``frustum_counts`` measures geometric field-of-view support on a target-centred proxy sphere whose radius is the geometric-mean semi-axis scale. It is not occlusion-aware and must not be reported as measured target-mesh visibility. Here ``j`` identifies the factual rollout chain and ``t`` its zero-based persisted decision step. The corresponding camera-forward direction is ``\widehat{\boldsymbol{v}}_{j,t}^e``. Projection provenance retains both indices, so presentation clients can encode common rollout heritage by colour and common acquisition time by marker style without inferring either identity from array order. ``movement_counts`` and ``view_direction_counts`` have shape ``ndarray["Z A", int64]``. ``Z`` bins target-frame ``z`` uniformly and ``A`` bins azimuth uniformly; because ``dΩ=dφ dz``, every cell has equal solid angle. The two ``*_projection`` arrays are bounded, deterministic display samples only; the count arrays always include the complete factual selected-action population. ## Functions | Name | Description | | --- | --- | | [initial_target_bev_geometry](#aria_nbv.rollouts.inspection.geometry.initial_target_bev_geometry) | Project complete candidate shells in a fixed initial camera frame. | | [proposal_support_geometry](#aria_nbv.rollouts.inspection.geometry.proposal_support_geometry) | Project complete candidate shells around their factual expansion poses. | | [rollout_trajectory_geometry](#aria_nbv.rollouts.inspection.geometry.rollout_trajectory_geometry) | Project factual selected trajectories in one initial target-aligned frame. | | [s2_direction_bin_indices](#aria_nbv.rollouts.inspection.geometry.s2_direction_bin_indices) | Assign one target-frame direction to an equal-solid-angle S² cell. | | [s2_target_direction_histogram](#aria_nbv.rollouts.inspection.geometry.s2_target_direction_histogram) | Aggregate factual movement and camera-forward directions on S². | | [target_aligned_z_up_basis](#aria_nbv.rollouts.inspection.geometry.target_aligned_z_up_basis) | Return the canonical world Z-up basis whose first axis faces the target. | ### initial_target_bev_geometry { #aria_nbv.rollouts.inspection.geometry.initial_target_bev_geometry } ```python rollouts.inspection.geometry.initial_target_bev_geometry( reader, *, rollout_row_ids=None, max_candidates=50000, ) ``` Project complete candidate shells in a fixed initial camera frame. For rollout :math:`r`, let :math:`c_0^W` be the persisted physical root camera centre and :math:`o^W` the target centre. The horizontal baseline is $$ d_{h,0}=\left\|(o^W-c_0^W)_{xy}\right\|_2. $$ One world-Z-up basis is built from that baseline and reused for every candidate at every factual step. Metric coordinates and coordinates divided by :math:`d_{h,0}` are both retained. This fixed frame intentionally differs from `proposal_support_geometry`, whose origin and three-dimensional scale change at each expansion, and from `rollout_trajectory_geometry`, whose origin is the corrected reference rig. Selected frusta use the step-aligned selected-depth calibration persisted in canonical Zarr. Missing legacy root-camera poses or missing/mismatched calibration remain explicit issues; neither is replaced with a rig pose or another step's camera. ### proposal_support_geometry { #aria_nbv.rollouts.inspection.geometry.proposal_support_geometry } ```python rollouts.inspection.geometry.proposal_support_geometry( reader, *, alignment=ProposalAlignment.TARGET_ALIGNED_Z_UP, rollout_row_ids=None, step_row_ids=None, max_candidates=50000, ) ``` Project complete candidate shells around their factual expansion poses. Step zero uses the persisted rollout root; later steps use the preceding factual selected pose. Coordinates are divided by that expansion pose's current 3D target distance, then yaw-aligned while preserving world Z-up. A step filter still walks preceding factual steps so a requested later shell retains its persisted previous-selected expansion pose. Candidate limits count only shells admitted by both rollout and step filters. ### rollout_trajectory_geometry { #aria_nbv.rollouts.inspection.geometry.rollout_trajectory_geometry } ```python rollouts.inspection.geometry.rollout_trajectory_geometry( reader, *, rollout_row_ids=None, ) ``` Project factual selected trajectories in one initial target-aligned frame. ### s2_direction_bin_indices { #aria_nbv.rollouts.inspection.geometry.s2_direction_bin_indices } ```python rollouts.inspection.geometry.s2_direction_bin_indices( direction, *, azimuth_bins, elevation_bins, ) ``` Assign one target-frame direction to an equal-solid-angle S² cell. The azimuth coordinate :math:`\phi=\operatorname{atan2}(y,x)` is split uniformly over :math:`[-\pi,\pi)`. The vertical coordinate is the unit direction's :math:`z` value rather than polar angle. Because spherical area satisfies :math:`d\Omega=d\phi\,dz`, every returned cell has equal solid angle. This is the same binning used by :func:`s2_target_direction_histogram`. #### Parameters {.doc-section .doc-section-parameters} | Name | Type | Description | Default | |----------------|--------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------|------------| | direction | [NDArray](`numpy.typing.NDArray`)\[[np](`numpy`).[floating](`numpy.floating`)\[[Any](`typing.Any`)\]\] | Finite nonzero target-frame three-vector. Unit length is not required; normalization is owned by this interface. | _required_ | | azimuth_bins | [int](`int`) | Positive number of azimuth cells. | _required_ | | elevation_bins | [int](`int`) | Positive number of uniform-``z`` cells. | _required_ | #### Returns {.doc-section .doc-section-returns} | Name | Type | Description | |--------|------------------------------------------------|--------------------------------------------------------------------| | | [tuple](`tuple`)\[[int](`int`), [int](`int`)\] | ``(elevation_index, azimuth_index)`` in row-major histogram order. | #### Raises {.doc-section .doc-section-raises} | Name | Type | Description | |--------|----------------------------|------------------------------------------------------| | | [ValueError](`ValueError`) | If the bin counts or direction violate the contract. | ### s2_target_direction_histogram { #aria_nbv.rollouts.inspection.geometry.s2_target_direction_histogram } ```python rollouts.inspection.geometry.s2_target_direction_histogram( reader, *, azimuth_bins=36, elevation_bins=18, projection_limit=2000, ) ``` Aggregate factual movement and camera-forward directions on S². The reducer reads only each factual rollout root and its referenced selected candidate shells; it never materializes the full candidate table. For a target object frame ``e``, selected camera centres are transformed with ``(R_W^e)^T``. Consecutive translations are normalized by the geometric mean of the target OBB semi-axes before their unit-sphere projection, while the selected camera local ``+Z`` optical axis supplies the view direction. The calibrated-frustum channel evaluates which points of the corresponding target-centred geometric-mean-scale proxy sphere are front-facing and project inside each selected pinhole camera. #### Parameters {.doc-section .doc-section-parameters} | Name | Type | Description | Default | |------------------|------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------|------------| | reader | [RolloutZarrStoreReader](`aria_nbv.rollouts.storage.RolloutZarrStoreReader`) | Validated read-only rollout store. | _required_ | | azimuth_bins | [int](`int`) | Positive number of uniform target-frame azimuth bins. | `36` | | elevation_bins | [int](`int`) | Positive number of uniform target-frame ``z`` bins. Uniform ``z`` rather than uniform polar angle gives equal-solid- angle S² cells. | `18` | | projection_limit | [int](`int`) | Maximum deterministic reservoir samples retained per channel for a Plotly point overlay. Counts remain complete. | `2000` | #### Returns {.doc-section .doc-section-returns} | Name | Type | Description | |--------|--------------------------------------------------------------------------------------|--------------------------------------------------------------------------| | | [S2DirectionHistogram](`aria_nbv.rollouts.inspection.geometry.S2DirectionHistogram`) | `S2DirectionHistogram` containing complete equal-solid-angle count | | | [S2DirectionHistogram](`aria_nbv.rollouts.inspection.geometry.S2DirectionHistogram`) | grids, bounded target-frame projection samples, and explicit exclusions. | #### Notes {.doc-section .doc-section-notes} A degenerate movement has no direction and is counted separately. Missing, non-rigid, or non-positive target OBB geometry excludes only that rollout and leaves the reason visible to presentation clients. ### target_aligned_z_up_basis { #aria_nbv.rollouts.inspection.geometry.target_aligned_z_up_basis } ```python rollouts.inspection.geometry.target_aligned_z_up_basis(target_delta) ``` Return the canonical world Z-up basis whose first axis faces the target.