1 rollouts.inspection.selected_motion

rollouts.inspection.selected_motion

Selected-camera motion and target-relative angular novelty reductions.

This module describes factual selected trajectories from canonical rollout stores. It deliberately keeps angular occupancy, physical-camera motion, and mesh-clearance evidence separate: none is a proxy for observed target-surface coverage or human movement dynamics.

1.1 Classes

Name	Description
SelectedMotionFrames	Normalized factual selected-step and rollout-level motion tables.

1.1.1 SelectedMotionFrames

rollouts.inspection.selected_motion.SelectedMotionFrames(steps, rollouts)

Normalized factual selected-step and rollout-level motion tables.

1.1.1.1 Attributes

Name	Description
steps	One row per factual selected acquisition.
rollouts	One row per factual rollout with complete selected-motion summaries.

1.2 Functions

Name	Description
empty_selected_motion_frames	Return the canonical selected-motion schemas with no observations.
selected_motion_store_frames	Reduce one validated store to selected motion and angular novelty.

1.2.1 empty_selected_motion_frames

rollouts.inspection.selected_motion.empty_selected_motion_frames()

Return the canonical selected-motion schemas with no observations.

1.2.2 selected_motion_store_frames

rollouts.inspection.selected_motion.selected_motion_store_frames(
    reader,
    *,
    azimuth_bins=36,
    elevation_bins=18,
    min_intervening_steps=2,
)

Reduce one validated store to selected motion and angular novelty.

A selected camera centre :math:c_t^W is expressed relative to the fixed target centre :math:o^W in target-object coordinates,

.. math::

d_t^e = (R_W^e)(c_t^W-oW).

Its unit direction is assigned to the same equal-solid-angle S² grid used by s2_target_direction_histogram. An angular revisit occurs when the current selected acquisition occupies a prior selected bin with at least min_intervening_steps other selected acquisitions between them. The root camera is not inserted as a selected acquisition. Rollouts with no factual acquisitions retain a rollout summary with zero support counts and unavailable conditional fractions; target pose geometry is not required when no target-relative direction is computed. A rollout with factual steps requires a finite target pose with valid SO(3) rotation.

Translation and rotation come from the physical world-from-camera poses. Rotation is the geodesic SO(3) increment, not a yaw-only diagnostic. Clearance values are the persisted selected-candidate measurements. These quantities describe geometry only: without timestamps they are not speed, acceleration, jerk, or human-motion realism, and angular occupancy does not establish visible-surface coverage.

1.2.2.1 Parameters

Name	Type	Description	Default
reader	RolloutZarrStoreReader	Validated read-only rollout store.	required
azimuth_bins	int	Positive number of target-frame azimuth cells.	36
elevation_bins	int	Positive number of uniform target-frame z cells.	18
min_intervening_steps	int	Minimum number of selected acquisitions strictly between two visits to the same angular cell.	2

1.2.2.2 Returns

Name	Type	Description
	SelectedMotionFrames	Selected-step rows and rollout summaries with explicit denominators.

1.2.2.3 Raises

Name	Type	Description
	ValueError	If configuration or persisted selected-row identities are inconsistent.