1 pose_generation.candidate_generation

pose_generation.candidate_generation

Candidate pose generation with modular sampling and pruning rules.

This module implements a clear three-stage pipeline:

1. Sample directions + radii around the latest pose using either area-uniform or forward-biased spherical distributions in the rig frame.
2. Construct roll-free camera poses that look away from the last pose while keeping the camera x-axis horizontal in the world frame.
3. Prune candidates via rule objects (mesh clearance, collision, free space). Rules may optionally emit diagnostics such as per-candidate mesh distances.

All poses are expressed as efm3d.aria.pose.PoseTW in the VIO world frame (LUF camera convention: x=left, y=up, z=forward).

CandidateViewGenerator returns compact valid views for rendering and keeps the full sampled shell as masks/diagnostics. Mixture generation should wrap this single-family generator rather than changing its ordering semantics.

This module owns the single-family generator, its config factory, sampling orchestration, and assembly of CandidateSamplingResult. Direction and orientation primitives, pruning-rule implementations, mixture concatenation, rendering, and actor/oracle action selection belong to sibling subsystems.

1.1 Theory

Sampling uses a physical reference pose and, by default, a gravity-aligned sampling pose. Center samples are transformed into world-frame candidate poses, then pruned without compacting the full shell. Feasibility is a hard mask contract:

\[ c_i\in B_{\mathrm{occ}},\qquad \min_{x\in\mathcal{M}_{GT}}\lVert c_i-x\rVert_2>d_{\min}, \]

with optional motion bounds

\[ \lVert o_i\rVert_2\le d_{\max},\quad |\Delta h_i|\le h_{\max},\quad \max(0,-o_{i,z})\le b_{\max}. \]

Collision, bounds, and motion failures stay in masks and reason codes. Invalid candidates are not converted into low-RRI labels.

1.2 Classes

Name	Description
CandidateViewGenerator	Generate candidate PoseTW around a reference rig pose using composeable and modular rules.
CandidateViewGeneratorConfig	Configuration for sampling and pruning candidate camera poses around a reference frame.

1.2.1 CandidateViewGenerator

pose_generation.candidate_generation.CandidateViewGenerator(
    config,
    *,
    mesh_query=None,
    _center_config=None,
    _gaze_config=None,
    _center_count=None,
)

Generate candidate PoseTW around a reference rig pose using composeable and modular rules.

This class orchestrates the full candidate generation process:

• positional sampling via PositionSampler,
• orientation construction via OrientationBuilder, and
• rule-based pruning via FreeSpaceRule, MinDistanceToMeshRule and PathCollisionRule.

A persistent generator retains its most recent safely versioned prepared mesh query across generation calls. A query supplied to the constructor is request-local: the first generation call consumes it directly, then later calls return to normal acquisition and invalidation.

1.2.1.1 Methods

Name	Description
generate_from_typed_sample	Generate candidates using an EfmSnippetView sample.
generate	Sample candidate poses around reference_pose and apply pruning rules.
generate_from_centers	Orient and validate an explicit candidate-centre table.

1.2.1.1.1 generate_from_typed_sample

pose_generation.candidate_generation.CandidateViewGenerator.generate_from_typed_sample(
    sample,
    frame_index=None,
    runtime_context=None,
)

Generate candidates using an EfmSnippetView sample.

1.2.1.1.1.1 Parameters

Name	Type	Description	Default
sample	EfmSnippetView	Snippet view with trajectory and mesh.	required
frame_index	int | None	Optional frame index to extract the reference pose instead of using the final pose. 0 <= frame_index < F where is the number of frames in the snippet; F = sample.get_camera(self.config.camera_label).num_frames.	None
runtime_context	CandidateGenerationRuntimeContext | None	Optional target/runtime context accepted for interface compatibility with mixture generators. The single-family generator reads target state directly from the config.	None

1.2.1.1.2 generate

pose_generation.candidate_generation.CandidateViewGenerator.generate(
    reference_pose,
    gt_mesh,
    mesh_verts,
    mesh_faces,
    camera_calib_template,
    occupancy_extent,
    runtime_context=None,
    seed=None,
)

Sample candidate poses around reference_pose and apply pruning rules.

Samples candidate positions and orientations, wraps them in a CandidateContext, runs all configured rules, and returns CandidateSamplingResult.

1.2.1.1.2.1 Parameters

Name	Type	Description	Default
reference_pose	PoseTW	World<-reference PoseTW used as the physical rig pose. When align_to_gravity is enabled, a gravity-aligned copy of this pose defines the sampling frame (stored in CandidateSamplingResult.sampling_pose).	required
gt_mesh	trimesh.Trimesh	Ground-truth trimesh.Trimesh in the world frame for pruning.	required
mesh_verts	torch.Tensor	Tensor['V, 3'] mesh vertices aligned with gt_mesh.	required
mesh_faces	torch.Tensor	Tensor['F, 3'] integer vertex indices defining mesh faces.	required
camera_calib_template	CameraTW	CameraTW whose intrinsics/metadata are cloned for each candidate; its pose block is overwritten with candidate extrinsics.	required
occupancy_extent	torch.Tensor	Tensor['6'] world-space AABB used by FreeSpaceRule.	required
runtime_context	CandidateGenerationRuntimeContext | None	Optional target/runtime context accepted for interface compatibility with mixture generators. The single-family generator reads target state directly from the config.	None

1.2.1.1.2.2 Returns

Name	Type	Description
	CandidateSamplingResult	CandidateSamplingResult holding the valid candidate CameraTW, reference pose, shell
	CandidateSamplingResult	poses, masks and optional debug statistics.

1.2.1.1.3 generate_from_centers

pose_generation.candidate_generation.CandidateViewGenerator.generate_from_centers(
    reference_pose,
    centers_world,
    offsets_ref,
    gt_mesh,
    mesh_verts,
    mesh_faces,
    camera_calib_template,
    occupancy_extent,
    seed=None,
)

Orient and validate an explicit candidate-centre table.

This is the paired-proposal seam: several gaze hypotheses may reuse exactly the same world-space centers while orientation jitter and hard validity remain independently auditable per candidate row.

1.2.2 CandidateViewGeneratorConfig

pose_generation.candidate_generation.CandidateViewGeneratorConfig()

Configuration for sampling and pruning candidate camera poses around a reference frame.

Encapsulates the radii/angle sampling envelope, orientation jitter options, collision and free-space filtering, and logging/debug controls used by CandidateViewGenerator.

The config is a Pydantic boundary: device and verbosity are coerced through the shared config helpers, omitted view_kappa inherits positional kappa and omitted per-axis caps keep their field defaults, while explicit None on a view cap selects the shared view_max_angle_deg fallback. is_debug promotes verbosity to VERBOSE. Candidate poses remain physical world/camera geometry in metres; display-only CW90 rotations belong to plotting callers.

1.2.2.1 Attributes

Name	Description
target_type	Factory target for BaseConfig.setup_target.
camera_label	Camera index to use for candidate generation.
num_samples	Number of candidate poses requested after pruning.
oversample_factor	Multiplicative oversampling factor applied before pruning to offset rejections.
max_resamples	Maximum oversampling rounds if pruning removes too many candidates.
align_to_gravity	If True, use a gravity-aligned copy of the reference pose for sampling.
min_radius	Inner radius (metres) of the sampling shell around the reference pose.
max_radius	Outer radius (metres) of the sampling shell around the reference pose.
min_elev_deg	Minimum elevation angle (deg) relative to the world horizontal plane.
max_elev_deg	Maximum elevation angle (deg) relative to the world horizontal plane.
delta_azimuth_deg	Total azimuth spread (deg) around the reference forward direction; 360 unlocks full sphere.
sampling_strategy	Distribution used to draw direction samples in the rig frame.
kappa	Concentration parameter for the forward-biased PowerSpherical sampler.
position_mode	Position-family prior used to sample candidate centers before orientation assignment.
position_target_point_world	Optional actor-visible world-space target center for target-aware position modes.
target_orbit_angles_deg	Partial-orbit angles around the actor-visible target.
min_distance_to_mesh	Minimum clearance (metres) between candidate center and mesh surface.
ensure_collision_free	Apply the selected reference-to-candidate path check when enabled.
ensure_free_space	Constrain candidates to lie inside the snippet occupancy AABB.
collision_backend	Backend for mesh-distance and sampled-clearance or bounded-ray path checks.
ray_subsample	Number of endpoint-inclusive segment samples for PyTorch3D clearance checks.
step_clearance	PyTorch3D clearance threshold in metres; non-positive values disable path checks.
enforce_motion_realism	Whether to reject candidates violating egocentric local-motion bounds.
max_step_distance_m	Maximum allowed candidate-center displacement from the reference pose.
max_height_delta_m	Maximum absolute world-up displacement from the reference pose.
max_backward_step_m	Maximum allowed backward displacement in the reference frame.
max_yaw_delta_deg	Maximum allowed candidate forward-axis yaw change from the reference pose.
mesh_samples	Optional number of mesh samples used by mesh-distance rules when applicable.
device	Geometry tensor device resolved under PYTORCH3D_BACKEND policy.
verbosity	Verbosity level for logging (0=quiet, 1=normal, 2=verbose).
is_debug	Enable debug logging and force verbose output when True.
collect_rule_masks	Store per-rule boolean masks in the sampling result for diagnostics.
collect_debug_stats	Allow rules to emit extra tensors (e.g., distances) in CandidateSamplingResult.extras.
reference_frame_index	Optional camera frame index to use as reference pose; None defaults to the final pose.
view_direction_mode	Base orientation strategy for candidates.
view_sampling_strategy	Optional view-direction sampler in the base camera frame (legacy path).
view_kappa	Concentration for PowerSpherical view sampler; defaults to positional kappa when None.
view_max_angle_deg	Fallback cap (deg) applied to both azimuth and elevation jitter when per-axis caps are unset.
view_max_azimuth_deg	Maximum horizontal deviation (deg, +/-) from the base direction.
view_max_elevation_deg	Maximum vertical deviation (deg, +/-) from the base direction.
view_roll_jitter_deg	Symmetric roll jitter (deg) around the sampled forward axis in camera frame.
view_target_point_world	Optional world-space target for TARGET_POINT mode (shape (3,)).
seed	Optional deterministic seed for candidate sampling.
min_elev_rad	Return the lower candidate elevation bound in radians.
max_elev_rad	Return the upper candidate elevation bound in radians.
delta_azimuth_rad	Return the candidate azimuth span in radians.
requires_mesh_query	Return whether an enabled pruning rule needs prepared mesh state.

1.2.2.2 Methods

Name	Description
set_debug	Resolve debug verbosity and inherited view-jitter defaults.

1.2.2.2.1 set_debug

pose_generation.candidate_generation.CandidateViewGeneratorConfig.set_debug()

Resolve debug verbosity and inherited view-jitter defaults.

view_kappa=None inherits the positional kappa. Explicit None on either per-axis view cap selects view_max_angle_deg; omitting those fields instead preserves their distinct 60/30-degree field defaults. This normalization happens once during model construction so generator code can consume concrete values without branch-dependent defaults.