1 CandidateSamplingResult

pose_generation.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,
    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.

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

1.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.
shell_poses cam2world poses for all sampled candidates (pre-pruning).
shell_offsets_ref Sampled offsets in the sampling frame for the full shell (pre-pruning).
sampling_pose World <- sampling pose used to draw centers, gravity-aligned when enabled.
strategy_id Full-shell candidate strategy ids aligned with mask_valid.
position_id Full-shell position-family ids aligned with mask_valid.
mixture_id Full-shell mixture component ids aligned with mask_valid.
sampler_probability Full-shell sampler probabilities aligned with mask_valid.
component_name Optional per-shell component names aligned with mask_valid.

1.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 World <- camera poses for valid candidates.
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.2.1 to_serializable

pose_generation.CandidateSamplingResult.to_serializable()

Serialize this result into a cache-friendly CPU payload.

1.2.2 from_serializable

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

Reconstruct one result from a serialized payload.

1.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.2.2.2 Returns

Name Type Description
'CandidateSamplingResult' Reconstructed candidate-sampling result.

1.2.3 poses_world_cam

pose_generation.CandidateSamplingResult.poses_world_cam(device=None)

World <- camera poses for valid candidates.

1.2.4 candidate_shell_indices

pose_generation.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.2.4.1 Parameters

Name Type Description Default
device torch.device | None Optional destination device for the returned indices. None

1.2.4.2 Returns

Name Type Description
torch.Tensor Tensor["N"] integer indices into the full sampled shell.

1.2.4.3 Raises

Name Type Description
ValueError If views cannot be mapped unambiguously to the full candidate shell.

1.2.5 get_offsets_and_dirs_ref

pose_generation.CandidateSamplingResult.get_offsets_and_dirs_ref(
    display_rotate=False,
)

Offsets and forward directions in the physical reference frame.

1.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.2.5.2 Returns

Name Type Description
tuple[torch.Tensor, torch.Tensor] Tuple (offsets, dirs) with shapes (N,3) each.