1 pose_generation.plotting
pose_generation.plotting
Plot candidate shells, validity diagnostics, and counterfactual rollouts.
This module provides compact plotting functions and Plotly builders for pose axes, validity/rejection masks, directional marginals, and counterfactual path metrics. It owns presentation and color mapping only; candidate generation, rollout state, and score computation remain with their producing modules.
All 3D payloads are interpreted in world or explicitly named reference frames. Plotly conversions detach to CPU and remain presentation-only; candidate masks, poses, and rollout state are never modified by a builder.
1.1 Classes
| Name | Description |
|---|---|
| CandidatePlotBuilder | Fluent, snippet-aware builder for full-shell candidate diagnostics. |
| CounterfactualPlotBuilder | Snippet-aware plotting builder for multi-step counterfactual trajectories. |
1.1.1 CandidatePlotBuilder
pose_generation.plotting.CandidatePlotBuilder(*args, **kwargs)Fluent, snippet-aware builder for full-shell candidate diagnostics.
The builder retains both the compact valid table and full sampled shell so plots can distinguish accepted actions, rejected positions, and rule masks. All cached center arrays have shape Array["N 3", float] in world metres.
1.1.1.1 Attributes
| Name | Description |
|---|---|
| candidate_results | Attached candidate sampling result, including full-shell provenance. |
| candidate_cfg | Optional generation config used to annotate plots and thresholds. |
1.1.1.2 Methods
| Name | Description |
|---|---|
| from_candidates | Create a snippet plot with candidate results already attached. |
| attach_candidate_results | Attach candidate sampling results for plotting. |
| attach_candidate_cfg | Attach candidate config for metadata-aware plotting. |
| add_reference_axes | Add the candidate reference frame axes to the figure. |
| add_candidate_points | Add candidate centers from the compact table or full sampled shell. |
| add_candidate_cloud | Add the default candidate-center cloud and optional reference marker. |
| add_rejected_cloud | Add world-frame centers rejected by any cumulative validity rule. |
| add_min_distance_overlay | Color candidate centers by aligned point-to-mesh distance in metres. |
| add_path_collision_segments | Draw reference-to-candidate segments for full-shell collision rows. |
| rule_rejection_bar | Plot newly rejected row counts for each cumulative pruning mask. |
| add_candidate_frusta | Overlay frusta using the attached candidate results. |
1.1.1.2.1 from_candidates
pose_generation.plotting.CandidatePlotBuilder.from_candidates(
snippet,
candidates,
*,
title,
height=900,
)Create a snippet plot with candidate results already attached.
1.1.1.2.2 attach_candidate_results
pose_generation.plotting.CandidatePlotBuilder.attach_candidate_results(results)Attach candidate sampling results for plotting.
1.1.1.2.3 attach_candidate_cfg
pose_generation.plotting.CandidatePlotBuilder.attach_candidate_cfg(cfg)Attach candidate config for metadata-aware plotting.
1.1.1.2.4 add_reference_axes
pose_generation.plotting.CandidatePlotBuilder.add_reference_axes(
title='Reference frame',
display_rotate=False,
use_sampling_pose=False,
)Add the candidate reference frame axes to the figure.
1.1.1.2.4.1 Notes
Candidate generation applies the Aria rig→LUF convention fix (a 90° rotation about the local +Z/forward axis) to the reference pose before sampling. Applying the same correction again in plotting would double-rotate the reference axes. Therefore, display_rotate defaults to False for When gravity alignment is enabled, candidates are sampled around a gravity-aligned copy of the reference pose. In that case, plotting the sampling pose axes (use_sampling_pose=True) keeps the axes symmetric with the candidate cloud.
1.1.1.2.5 add_candidate_points
pose_generation.plotting.CandidatePlotBuilder.add_candidate_points(
use_valid=True,
color=None,
colorbar_title=None,
name='Candidates',
size=3,
opacity=0.7,
hovertext=None,
mark_reference=False,
reference_symbol='diamond',
)Add candidate centers from the compact table or full sampled shell.
color may be a scalar color or an Array["N", numeric] aligned with the selected rows. Coordinates are world-frame metres.
1.1.1.2.6 add_candidate_cloud
pose_generation.plotting.CandidatePlotBuilder.add_candidate_cloud(
use_valid=True,
color='royalblue',
name='Candidates',
size=4,
opacity=0.7,
mark_reference=True,
)Add the default candidate-center cloud and optional reference marker.
1.1.1.2.7 add_rejected_cloud
pose_generation.plotting.CandidatePlotBuilder.add_rejected_cloud(
color='crimson',
name='Rejected',
size=4,
opacity=0.8,
)Add world-frame centers rejected by any cumulative validity rule.
1.1.1.2.8 add_min_distance_overlay
pose_generation.plotting.CandidatePlotBuilder.add_min_distance_overlay(
distances,
*,
use_valid=False,
)Color candidate centers by aligned point-to-mesh distance in metres.
1.1.1.2.9 add_path_collision_segments
pose_generation.plotting.CandidatePlotBuilder.add_path_collision_segments(
collision_mask,
)Draw reference-to-candidate segments for full-shell collision rows.
1.1.1.2.10 rule_rejection_bar
pose_generation.plotting.CandidatePlotBuilder.rule_rejection_bar()Plot newly rejected row counts for each cumulative pruning mask.
1.1.1.2.11 add_candidate_frusta
pose_generation.plotting.CandidatePlotBuilder.add_candidate_frusta(
scale=1.0,
color='crimson',
name='Frustum',
max_frustums=None,
include_axes=False,
include_center=False,
display_rotate=False,
)Overlay frusta using the attached candidate results.
1.1.1.2.11.1 Notes
display_rotate is a legacy plotting option that applies the same Aria UI-style 90° local +Z rotation (rotate_yaw_cw90). Because candidate generation already applies this convention fix to the reference pose, the default is False to avoid a second roll offset (which becomes very apparent once roll jitter is enabled).
1.1.2 CounterfactualPlotBuilder
pose_generation.plotting.CounterfactualPlotBuilder(*args, **kwargs)Snippet-aware plotting builder for multi-step counterfactual trajectories.
1.1.2.1 Methods
| Name | Description |
|---|---|
| from_rollouts | Create a snippet plot with multi-step rollout trajectories attached. |
| attach_counterfactual_rollouts | Attach rollout trajectories for subsequent plotting calls. |
| add_actor_visible_target_obb | Overlay the actor-visible target OBB used for target-conditioned rollout generation. |
| add_counterfactual_paths | Overlay rollout paths for all attached trajectories. |
| add_counterfactual_selected_frusta | Overlay frusta for the selected poses in each attached trajectory. |
| add_counterfactual_step_shell | Plot one rollout step’s candidate shell within the snippet scene. |
1.1.2.1.1 from_rollouts
pose_generation.plotting.CounterfactualPlotBuilder.from_rollouts(
snippet,
rollouts,
*,
title,
height=900,
)Create a snippet plot with multi-step rollout trajectories attached.
1.1.2.1.2 attach_counterfactual_rollouts
pose_generation.plotting.CounterfactualPlotBuilder.attach_counterfactual_rollouts(
rollouts,
)Attach rollout trajectories for subsequent plotting calls.
1.1.2.1.3 add_actor_visible_target_obb
pose_generation.plotting.CounterfactualPlotBuilder.add_actor_visible_target_obb(
target,
*,
color='#ff2f74',
name='Active target / actor-visible',
width=7,
)Overlay the actor-visible target OBB used for target-conditioned rollout generation.
1.1.2.1.4 add_counterfactual_paths
pose_generation.plotting.CounterfactualPlotBuilder.add_counterfactual_paths(
show_step_markers=True,
line_width=5,
root_color='black',
color_metric='auto',
colorscale='Viridis',
show_metric_colorbar=True,
)Overlay rollout paths for all attached trajectories.
1.1.2.1.5 add_counterfactual_selected_frusta
pose_generation.plotting.CounterfactualPlotBuilder.add_counterfactual_selected_frusta(
scale=0.6,
include_axes=False,
include_center=False,
max_frustums_per_trajectory=None,
display_rotate=False,
)Overlay frusta for the selected poses in each attached trajectory.
1.1.2.1.6 add_counterfactual_step_shell
pose_generation.plotting.CounterfactualPlotBuilder.add_counterfactual_step_shell(
trajectory_index,
step_index,
show_history=True,
show_selected=True,
show_frusta=True,
frustum_scale=0.5,
max_frustums=16,
include_rejected=False,
candidate_color_metric='selection_score',
)Plot one rollout step’s candidate shell within the snippet scene.
1.2 Functions
| Name | Description |
|---|---|
| plot_candidate_centers_simple | Plot candidate centers without requiring a full snippet. |
| plot_candidate_frusta_simple | Plot candidate frusta without requiring a full snippet. |
| plot_counterfactual_paths_simple | Plot rollout paths without requiring a snippet or mesh. |
| plot_counterfactual_step_simple | Plot one rollout step’s candidate shell without requiring a snippet. |
| plot_direction_marginals | Plot azimuth/elevation marginals for LUF unit directions Tensor["N 3"]. |
| plot_direction_polar | Plot azimuth/elevation density of direction vectors. |
| plot_direction_sphere | 3D scatter of directions on the unit sphere. |
| plot_euler_reference | Yaw/pitch/roll of candidate cameras expressed in the reference rig frame. |
| plot_euler_world | Yaw/pitch/roll histograms in world frame for candidate cam poses. |
| plot_min_distance_to_mesh | Binary-coloured candidates: rejected (red, opaque) vs accepted (green, faint). |
| plot_paired_gaze_support | Plot shared candidate centers with their alternative ground-plane gaze rays. |
| plot_path_collision_segments | Plot segments from reference pose to candidates rejected by path-collision rule. |
| plot_position_polar | Plot reference-frame candidate offsets by azimuth and elevation. |
| plot_position_sphere | Plot LUF reference-frame position offsets and optional view directions. |
| plot_proposal_sequence_support | Plot full-shell ground-plane support against deterministic draw order. |
| plot_radius_hist | Plot Euclidean radii of reference-frame offsets in metres. |
| plot_rule_masks | Visualise per-rule pruning on raw samples. |
| plot_rule_rejection_bar | Bar chart of rejection counts per rule using cumulative masks. |
| plot_target_shell_support | Plot attempted target-shell centers, configured support, and gaze rays. |
| plot_view_jitter_support | Plot full-shell yaw/pitch jitter by component and action validity. |
1.2.1 plot_candidate_centers_simple
pose_generation.plotting.plot_candidate_centers_simple(
candidates,
*,
title,
use_valid=True,
)Plot candidate centers without requiring a full snippet.
1.2.2 plot_candidate_frusta_simple
pose_generation.plotting.plot_candidate_frusta_simple(
candidates,
*,
scale,
max_frustums,
)Plot candidate frusta without requiring a full snippet.
1.2.3 plot_counterfactual_paths_simple
pose_generation.plotting.plot_counterfactual_paths_simple(
rollouts,
*,
title='Counterfactual pose rollouts',
show_step_markers=True,
color_metric='auto',
colorscale='Viridis',
show_metric_colorbar=True,
)Plot rollout paths without requiring a snippet or mesh.
1.2.4 plot_counterfactual_step_simple
pose_generation.plotting.plot_counterfactual_step_simple(
trajectory,
*,
step_index,
scale=0.5,
max_frustums=12,
)Plot one rollout step’s candidate shell without requiring a snippet.
1.2.5 plot_direction_marginals
pose_generation.plotting.plot_direction_marginals(
dirs,
bins=60,
*,
fixed_ranges=False,
)Plot azimuth/elevation marginals for LUF unit directions Tensor["N 3"].
1.2.6 plot_direction_polar
pose_generation.plotting.plot_direction_polar(
dirs,
*,
title='Direction distribution (az/elev)',
bins=40,
fixed_ranges=False,
)Plot azimuth/elevation density of direction vectors.
1.2.7 plot_direction_sphere
pose_generation.plotting.plot_direction_sphere(
dirs,
*,
title='Directions on unit sphere',
show_axes=True,
)3D scatter of directions on the unit sphere.
1.2.8 plot_euler_reference
pose_generation.plotting.plot_euler_reference(
candidates,
*,
use_valid=True,
bins=90,
fixed_ranges=True,
)Yaw/pitch/roll of candidate cameras expressed in the reference rig frame.
The reference frame is treated as LUF (x=left, y=up, z=fwd), matching the azimuth/elevation plots shown elsewhere in the diagnostics.
1.2.9 plot_euler_world
pose_generation.plotting.plot_euler_world(
candidates,
*,
use_valid=True,
bins=90,
fixed_ranges=True,
)Yaw/pitch/roll histograms in world frame for candidate cam poses.
1.2.9.1 Notes
These angles are derived from the camera forward/up axes: - yaw: azimuth around world-up (world +Z), computed as atan2(fwd_x, fwd_y) (0 along +Y), - pitch: elevation above the world horizontal plane, computed as asin(fwd_z), - roll: twist around the forward axis relative to the roll-free frame induced by world-up.
1.2.10 plot_min_distance_to_mesh
pose_generation.plotting.plot_min_distance_to_mesh(
snippet,
candidates,
distances,
)Binary-coloured candidates: rejected (red, opaque) vs accepted (green, faint).
1.2.11 plot_paired_gaze_support
pose_generation.plotting.plot_paired_gaze_support(
candidates,
*,
ray_length_m=0.35,
)Plot shared candidate centers with their alternative ground-plane gaze rays.
1.2.12 plot_path_collision_segments
pose_generation.plotting.plot_path_collision_segments(
snippet,
candidates,
collision_mask,
)Plot segments from reference pose to candidates rejected by path-collision rule.
1.2.13 plot_position_polar
pose_generation.plotting.plot_position_polar(
offsets,
*,
title='Offsets from reference pose (az/elev)',
bins=72,
fixed_ranges=True,
)Plot reference-frame candidate offsets by azimuth and elevation.
1.2.13.1 Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| offsets | np.ndarray |
LUF reference-frame offsets Array["N 3", float] in metres. |
required |
| title | str | Figure title. | 'Offsets from reference pose (az/elev)' |
| bins | int | Bin count used independently along both angular axes. | 72 |
| fixed_ranges | bool | Clamp azimuth/elevation displays to their physical ranges. | True |
1.2.14 plot_position_sphere
pose_generation.plotting.plot_position_sphere(
offsets,
*,
title='Positions in rig frame',
show_axes=True,
dirs=None,
dir_scale=None,
)Plot LUF reference-frame position offsets and optional view directions.
offsets and dirs have shape Array["N 3", float]. Offsets are measured in metres; directions are normalized before drawing.
1.2.15 plot_proposal_sequence_support
pose_generation.plotting.plot_proposal_sequence_support(candidates)Plot full-shell ground-plane support against deterministic draw order.
Colour exposes the within-shell sequence index, while marker shape exposes hard validity. This makes clumping, ordering artefacts, and independent proposal replicas visible without conflating them with action selection.
1.2.16 plot_radius_hist
pose_generation.plotting.plot_radius_hist(
offsets,
*,
title='Radius distribution',
bins=40,
)Plot Euclidean radii of reference-frame offsets in metres.
1.2.17 plot_rule_masks
pose_generation.plotting.plot_rule_masks(
snippet,
shell_poses,
masks,
rule_names,
sample_n=500,
)Visualise per-rule pruning on raw samples.
1.2.18 plot_rule_rejection_bar
pose_generation.plotting.plot_rule_rejection_bar(candidates)Bar chart of rejection counts per rule using cumulative masks.
1.2.19 plot_target_shell_support
pose_generation.plotting.plot_target_shell_support(
candidates,
*,
target_center_world,
config,
seed=None,
ray_length_m=0.25,
)Plot attempted target-shell centers, configured support, and gaze rays.
The support curves are derived from config rather than fitted to the samples. Candidate markers retain full-shell validity, while short rays expose the generated camera forward axes in world coordinates.
1.2.20 plot_view_jitter_support
pose_generation.plotting.plot_view_jitter_support(candidates)Plot full-shell yaw/pitch jitter by component and action validity.
The plot is expressed in the local camera frame before composition with the component’s base gaze. Filled circles are valid actor actions; crosses are retained invalid proposals. The dotted rectangle is the resolved sampling envelope, not an empirical confidence interval.