1 pose_generation.types

pose_generation.types

Type definitions for finite candidate pose generation.

Candidate generation separates the full sampled shell from the compact valid table. The full shell carries invalidity masks, reason codes, strategy provenance, and optional diagnostics; compact valid views are the actions an actor or oracle selector may actually choose. Any dataset writer that trains a finite-action value model must apply the valid mask before argmax, softmax, loss targets, and bootstrap maximization.

Direction sampling happens on \(\mathbb{S}^2\). Orientation encodings such as R6D describe candidate pose rows; accumulated target visibility is a separate actor-visible directional-memory feature, not an orientation representation.

This module owns the sampling/position/collision enums and the runtime-context, candidate-context, and sampling-result DTOs shared across generators, rules, renderers, and stores. It defines representation and alignment invariants only; sampling algorithms, validity decisions, rendering, and scoring live in their respective modules.

1.1 Classes

Name Description
CandidateContext Mutable full-shell state passed between sampling and pruning rules.
CandidateGenerationRuntimeContext Runtime-only context for target-conditioned candidate generation.
CandidatePositionMode Spatial prior used to turn raw sphere samples into candidate centers.
CandidateSamplingResult Immutable result of candidate sampling and rule-based pruning.
CollisionBackend Backend used for point-distance and reference-path collision tests.
SamplingStrategy Angular sampling strategy for candidate directions on S^2.
ViewDirectionMode Base orientation family applied after candidate centers are sampled.

1.1.1 CandidateContext

pose_generation.types.CandidateContext(
    cfg,
    reference_pose,
    sampling_pose,
    gt_mesh,
    mesh_verts,
    mesh_faces,
    occupancy_extent,
    camera_calib_template,
    shell_poses,
    centers_world,
    shell_offsets_ref,
    mask_valid,
    mesh_query=None,
    rule_masks=dict(),
    debug=dict(),
)

Mutable full-shell state passed between sampling and pruning rules.

shell_poses, centers_world, shell_offsets_ref, and mask_valid are aligned over the full candidate shell of size N, including candidates that later become invalid. Pruning rules must update mask_valid and may store same-shape diagnostic masks in rule_masks; they must not compact rows.

views are not stored here because compact valid camera views are built only after pruning. This separation lets rollout writers preserve invalid candidates with reason codes while exposing only valid actions to policies.

1.1.1.1 Attributes

Name Description
cfg Generation policy shared by all rules in this pruning pass.
reference_pose Physical world-from-reference rig PoseTW with logical shape (12,).
sampling_pose Possibly gravity-aligned world-from-sampling pose, logical shape (12,).
gt_mesh Oracle ASE mesh in world-frame metres, used only for candidate validity.
mesh_verts Source-device world-frame mesh vertices Tensor["V 3", float] in metres.
mesh_faces Source-device triangle indices Tensor["F 3", int64] into mesh_verts.
occupancy_extent World bounds Tensor["6", float] ordered xmin/xmax/ymin/ymax/zmin/zmax.
camera_calib_template Physical Aria calibration copied onto compact candidate camera rows.
shell_poses Full-shell world-from-camera poses with logical shape (N, 12).
centers_world Full-shell camera centers Tensor["N 3", float] in world metres.
shell_offsets_ref Full-shell LUF sampling offsets Tensor["N 3", float] in metres.
mask_valid Cumulative action-validity mask Tensor["N", bool] over the full shell.
mesh_query Prepared mesh-query state shared by distance and collision rules.
rule_masks Named cumulative validity masks, each Tensor["N", bool].
debug Optional full-shell diagnostics aligned with N where applicable.

1.1.1.2 Methods

Name Description
record_mask Store a copy of the cumulative validity mask for diagnostics.
invalidate Apply a rejection mask (True = reject) to the current validity mask.
mark_debug Attach debug tensors in a consistent shape (clone kept to avoid side-effects).
1.1.1.2.1 record_mask
pose_generation.types.CandidateContext.record_mask(name, mask)

Store a copy of the cumulative validity mask for diagnostics.

1.1.1.2.2 invalidate
pose_generation.types.CandidateContext.invalidate(reject_mask)

Apply a rejection mask (True = reject) to the current validity mask.

1.1.1.2.3 mark_debug
pose_generation.types.CandidateContext.mark_debug(key, value)

Attach debug tensors in a consistent shape (clone kept to avoid side-effects).

1.1.2 CandidateGenerationRuntimeContext

pose_generation.types.CandidateGenerationRuntimeContext(descriptor=None)

Runtime-only context for target-conditioned candidate generation.

The context carries an actor-safe target descriptor. Missing target context is a configuration error for TARGET_POINT mixture components.

1.1.2.1 Attributes

Name Description
descriptor Sanitized target instruction shared by candidate-generation consumers.
target_center_world Target center in world coordinates, shape (3,).
target_id Stable target identifier for diagnostics.

1.1.3 CandidatePositionMode

pose_generation.types.CandidatePositionMode()

Spatial prior used to turn raw sphere samples into candidate centers.

UPPER_BOUND_FREE_SHELL is the broad ablation prior. The remaining modes bias the finite candidate set toward local continuity, target bearing, balanced attempted target-orbit proposals, configurable target-centric shell support, lateral bypass, short refinement, or controlled backtracking. Feasibility pruning may still remove attempted centers.

1.1.4 CandidateSamplingResult

pose_generation.types.CandidateSamplingResult(
    views,
    reference_pose,
    mask_valid,
    masks,
    shell_poses,
    shell_offsets_ref=None,
    sampling_pose=None,
    strategy_id=None,
    position_id=None,
    mixture_id=None,
    sampler_probability=None,
    component_name=None,
    position_pair_id=None,
    gaze_variant_id=None,
    extras=dict(),
)

Immutable result of candidate sampling and rule-based pruning.

views stores compact valid candidates for rendering and oracle/model scoring. mask_valid, shell_poses, provenance fields, and rule masks stay aligned with the full sampled shell of size N. Use candidate_shell_indices() whenever a compact row index must be joined back to full-shell lineage.

Shapes:

  • views.T_camera_rig: compact valid candidate camera poses in reference coordinates, shape (V, 12);
  • shell_poses: full-shell world<-camera PoseTW payload, shape (N, 12);
  • mask_valid: full-shell actor-action mask, shape (N,);
  • strategy_id, position_id, mixture_id, sampler_probability, and component_name: optional full-shell provenance arrays/tuples aligned with mask_valid;
  • position_pair_id and gaze_variant_id: typed optional paired-gaze provenance arrays aligned with mask_valid, using -1 sentinels.

Invalid candidates remain in the full shell and must receive false training masks and NaN oracle labels rather than low RRI.

1.1.4.1 Attributes

Name Description
views Compact valid candidate cameras; views.T_camera_rig is camera <- reference.
reference_pose World <- physical reference rig pose used to express candidate extrinsics.
mask_valid Full-shell action-validity mask Tensor["N", bool].
masks Cumulative per-rule masks Tensor["N", bool] keyed by rule name.
shell_poses World-from-camera poses for all sampled candidates, logical shape (N, 12).
shell_offsets_ref Optional LUF sampling offsets Tensor["N 3", float] in metres.
sampling_pose World <- sampling pose used to draw centers, gravity-aligned when enabled.
strategy_id Optional full-shell strategy ids Tensor["N", int64].
position_id Optional full-shell position-family ids Tensor["N", int64].
mixture_id Optional full-shell mixture-component ids Tensor["N", int64].
sampler_probability Optional proposal probabilities Tensor["N", float32] in [0, 1].
component_name Optional per-shell component names aligned with mask_valid.
position_pair_id Optional shared-center ids for paired gaze hypotheses; -1 means no pair.
gaze_variant_id Optional gaze variant ids aligned with position_pair_id; ordinary rows use -1.
extras Extensible provenance payload; tensor rows must remain aligned with N.

1.1.4.2 Methods

Name Description
to_serializable Serialize this result into a cache-friendly CPU payload.
from_serializable Reconstruct one result from a serialized payload.
poses_world_cam Return canonical world-from-camera poses aligned with views.
candidate_shell_indices Return full-shell indices aligned with views and labels.
get_offsets_and_dirs_ref Offsets and forward directions in the physical reference frame.
1.1.4.2.1 to_serializable
pose_generation.types.CandidateSamplingResult.to_serializable()

Serialize this result into a cache-friendly CPU payload.

1.1.4.2.2 from_serializable
pose_generation.types.CandidateSamplingResult.from_serializable(
    payload,
    *,
    device=None,
)

Reconstruct one result from a serialized payload.

1.1.4.2.2.1 Parameters
Name Type Description Default
payload dict[str, Any] Serialized payload produced by to_serializable. required
device torch.device | None Optional destination device for tensors and wrappers. None
1.1.4.2.2.2 Returns
Name Type Description
'CandidateSamplingResult' Reconstructed candidate-sampling result.
1.1.4.2.3 poses_world_cam
pose_generation.types.CandidateSamplingResult.poses_world_cam(device=None)

Return canonical world-from-camera poses aligned with views.

The full shell owns the sampled world poses. Select its corresponding rows directly so rendering and replay use the geometry checked by the feasibility rules. Reconstructing these poses through reference-frame camera extrinsics would amplify rotation roundoff over successive steps: transpose-based inversion assumes exactly orthogonal reference rotations.

1.1.4.2.3.1 Parameters
Name Type Description Default
device torch.device | None Destination device; defaults to the camera table’s device. None
1.1.4.2.3.2 Returns
Name Type Description
PoseTW PoseTW with Tensor["V 12"] storage, preserving shell dtype
PoseTW and row order. Compact valid views and explicit full-shell views
follow PoseTW meth:candidate_shell_indices; empty views return no rows.
1.1.4.2.4 candidate_shell_indices
pose_generation.types.CandidateSamplingResult.candidate_shell_indices(
    device=None,
)

Return full-shell indices aligned with views and labels.

CandidateViewGenerator stores views as the compact valid-candidate table and keeps mask_valid/shell_poses as full-shell diagnostics. Some synthetic diagnostics use full-shell views directly. This helper accepts those two explicit layouts and rejects ambiguous combinations so candidate poses, depth renders, oracle labels, and serialized diagnostics cannot silently drift out of order.

1.1.4.2.4.1 Parameters
Name Type Description Default
device torch.device | None Optional destination device for the returned indices. None
1.1.4.2.4.2 Returns
Name Type Description
torch.Tensor Tensor["N"] integer indices into the full sampled shell.
1.1.4.2.4.3 Raises
Name Type Description
ValueError If views cannot be mapped unambiguously to the full candidate shell.
1.1.4.2.5 get_offsets_and_dirs_ref
pose_generation.types.CandidateSamplingResult.get_offsets_and_dirs_ref(
    display_rotate=False,
)

Offsets and forward directions in the physical reference frame.

1.1.4.2.5.1 Parameters
Name Type Description Default
display_rotate bool If True, apply the visual 90° CW yaw rotation (rotate_yaw_cw90) to match UI plots. Defaults to False so downstream geometry keeps physical Aria frames. False
1.1.4.2.5.2 Returns
Name Type Description
tuple[torch.Tensor, torch.Tensor] Tuple (offsets, dirs) with shapes (N,3) each.

1.1.5 CollisionBackend

pose_generation.types.CollisionBackend()

Backend used for point-distance and reference-path collision tests.

1.1.6 SamplingStrategy

pose_generation.types.SamplingStrategy()

Angular sampling strategy for candidate directions on S^2.

The strategy controls how unit directions on the sphere \(\mathbb{S}^2\) are drawn for both:

  • positional sampling of candidate camera centers (see pose_generation.samplers.PositionSampler), and
  • optional view-direction jitter in the camera frame (see pose_generation.orientations.OrientationBuilder).

1.1.6.1 Attributes

Name Description
UNIFORM_SPHERE Draw directions uniformly on \(\mathbb{S}^2\) using a HypersphericalUniform distribution (constant
FORWARD_POWERSPHERICAL Draw directions from a forward-biased Power Spherical distribution \(\mathcal{PS}(\mu, \kappa)\) centered on

1.1.7 ViewDirectionMode

pose_generation.types.ViewDirectionMode()

Base orientation family applied after candidate centers are sampled.

These modes decide where the camera optical axis points before local jitter: reuse the reference rig, look along the reference-candidate ray, look back toward the reference, or look at an actor-visible target point.

Back to top