1 pose_generation

pose_generation

Finite-candidate generation contracts.

The package owns the thesis action space: every NBV decision is a finite table of candidate camera poses, validity masks, reason codes, and provenance fields. CandidateSamplingResult.views is the compact valid table used for rendering and scoring; mask_valid, shell_poses, strategy ids, mixture ids, and sampler probabilities stay aligned to the full sampled shell so invalid actions remain auditable instead of becoming low-RRI samples.

Target-conditioned candidate generation adds a runtime-only actor-visible target context. TARGET_POINT candidates must use the selected observed/predicted target center, not GT geometry. Counterfactual transitions and oracle rollout scorers live in aria_nbv.rollouts.

1.1 Package guide

aria_nbv.pose_generation owns the finite action table presented to NBV scorers: candidate camera poses, full-shell validity and rejection reasons, sampling-family provenance, and the compact valid table consumed downstream. It does not own depth rendering, RRI labels, rollout transitions, or policy selection.

1.2 Reuse this package

Start from the public package facade instead of creating a second pose sampler:

• CandidateViewGeneratorConfig configures one candidate family;
• CandidateMixtureViewGeneratorConfig composes fixed-count center and gaze families while preserving their provenance;
• CandidateGenerationRuntimeContext supplies actor-visible target context for target-conditioned families; and
• CandidateSamplingResult carries both the compact valid poses and the full-shell masks, indices, probabilities, and reason data needed for audits.

The opt-in DistanceScaledTargetOrbitCenterConfig preserves the target-orbit family while recomputing its bilateral angle bank from the current horizontal standoff and a per-step chord budget. Ordinary TargetOrbitCenterConfig authoring remains fixed-angle and unchanged.

Both generator configs follow the config-as-factory pattern. For a typed EFM snippet, use the existing runtime entry point:

from aria_nbv.pose_generation import CandidateMixtureViewGeneratorConfig

generator = CandidateMixtureViewGeneratorConfig().setup_target()
candidates = generator.generate_from_typed_sample(snippet, runtime_context=context)

Use CandidateViewGeneratorConfig when one sampling family is the intended scientific contract. Use the mixture config for rollout action support and experiments that compare or combine multiple proposal families. Public source docstrings define the exact frames, tensor shapes, configuration fields, and failure behavior.

1.3 Consumers and boundaries

The principal composition paths are the oracle label pipeline, the rollout dataset pipeline, and the counterfactual replay engine. Rendering consumes CandidateSamplingResult.views and maps rendered rows back to the full shell; Oracle modules own privileged scoring, and rollout modules own state transitions and selected actions.

Reusable frame and prepared-mesh computations belong to aria_nbv.geometry. Keep target context actor-visible: observed or predicted target centers may guide proposals, while GT geometry remains Oracle evidence. Plotting helpers in plotting.py inspect the owned candidate contracts; they do not define a second candidate population.

1.4 Proof

From aria_nbv/, run the narrowest relevant seam:

uv run pytest tests/pose_generation/test_pose_generation.py \
  tests/pose_generation/test_candidate_mixture.py \
  tests/pose_generation/test_target_shell.py

Include the owning Oracle or rollout test when changing a composed workflow.

1.5 Classes

Name	Description
CandidateGenerationRuntimeContext	Runtime-only context for target-conditioned candidate generation.
CandidateMixtureComponentConfig	Configure one center table and its ordered gaze variants.
CandidateMixtureViewGenerator	Generate a fixed-size candidate table from multiple sampling families.
CandidateMixtureViewGeneratorConfig	Config-as-factory for fixed-count mixed candidate tables.
CandidatePositionMode	Spatial prior used to turn raw sphere samples into candidate centers.
CandidateSamplingResult	Immutable result of candidate sampling and rule-based pruning.
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.
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.5.1 CandidateGenerationRuntimeContext

pose_generation.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.5.1.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.5.2 CandidateMixtureComponentConfig

pose_generation.CandidateMixtureComponentConfig()

Configure one center table and its ordered gaze variants.

1.5.2.1 Attributes

Name	Description
name	Stable component name retained as provenance for the first gaze.
count	Number of attempted centers sampled once before gaze expansion.
center	Complete positional proposal configuration for the shared center table.
gazes	Ordered gaze variants; row order is gaze-major within this component.

1.5.2.2 Methods

Name	Description
with_count	Return a fully revalidated component with a replacement count.

1.5.2.2.1 with_count

pose_generation.CandidateMixtureComponentConfig.with_count(count)

Return a fully revalidated component with a replacement count.

1.5.3 CandidateMixtureViewGenerator

pose_generation.CandidateMixtureViewGenerator(config)

Generate a fixed-size candidate table from multiple sampling families.

The generator retains one safely versioned prepared mesh query across requests. Each request lends that query to every component as request-local state, including paired-view components, without extending its lifetime.

1.5.3.1 Attributes

Name	Description
config	Return a detached copy of the authoring snapshot used by this runtime.

1.5.3.2 Methods

Name	Description
generate_from_typed_sample	Generate mixed candidates from an EFM snippet.
generate	Generate one concatenated full-shell candidate table.

1.5.3.2.1 generate_from_typed_sample

pose_generation.CandidateMixtureViewGenerator.generate_from_typed_sample(
    sample,
    frame_index=None,
    runtime_context=None,
)

Generate mixed candidates from an EFM snippet.

1.5.3.2.2 generate

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

Generate one concatenated full-shell candidate table.

1.5.4 CandidateMixtureViewGeneratorConfig

pose_generation.CandidateMixtureViewGeneratorConfig()

Config-as-factory for fixed-count mixed candidate tables.

1.5.4.1 Attributes

Name	Description
target_type	Return the fixed-count mixed candidate generator runtime type.
base	Base generator settings shared by all mixture components.
components	Ordered mixture components. Full-shell row order follows this list.
total_count	Total full-shell candidate budget across mixture components.
device	Return the resolved device shared by all mixture components.
camera_label	Base camera label used for typed-snippet generation.

1.5.4.2 Methods

Name	Description
upper_bound_free_shell	Build the explicit legacy free-shell upper-bound ablation config.
rich_local_five_family	Build the previous five-family local sampler for ablation runs.
paired_center_gaze_family	Build a 60-row sampler with paired target and forward gaze hypotheses.
radial_target_backtrack_family	Build the radial/backtrack rollout-diversity sampler.

1.5.4.2.1 upper_bound_free_shell

pose_generation.CandidateMixtureViewGeneratorConfig.upper_bound_free_shell(
    count=60,
)

Build the explicit legacy free-shell upper-bound ablation config.

1.5.4.2.2 rich_local_five_family

pose_generation.CandidateMixtureViewGeneratorConfig.rich_local_five_family()

Build the previous five-family local sampler for ablation runs.

1.5.4.2.3 paired_center_gaze_family

pose_generation.CandidateMixtureViewGeneratorConfig.paired_center_gaze_family()

Build a 60-row sampler with paired target and forward gaze hypotheses.

1.5.4.2.4 radial_target_backtrack_family

pose_generation.CandidateMixtureViewGeneratorConfig.radial_target_backtrack_family(
)

Build the radial/backtrack rollout-diversity sampler.

This preset mirrors .configs/historical/build_rollouts_v1_diverse.toml: most rows probe radial-towards, radial-away, and revisit-backtrack action families, with a small target-point anchor group for continuity with the target-conditioned default sampler. It is a named data-generation profile only; CandidateMixtureViewGeneratorConfig() keeps the historical 60-row default.

1.5.5 CandidatePositionMode

pose_generation.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.5.6 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,
    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.5.6.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.5.6.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.5.6.2.1 to_serializable

pose_generation.CandidateSamplingResult.to_serializable()

Serialize this result into a cache-friendly CPU payload.

1.5.6.2.2 from_serializable

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

Reconstruct one result from a serialized payload.

1.5.6.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.5.6.2.2.2 Returns

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

1.5.6.2.3 poses_world_cam

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

Name	Type	Description	Default
device	torch.device | None	Destination device; defaults to the camera table’s device.	None

1.5.6.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.5.6.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.5.6.2.4.1 Parameters

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

1.5.6.2.4.2 Returns

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

1.5.6.2.4.3 Raises

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

1.5.6.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.5.6.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.5.6.2.5.2 Returns

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

1.5.7 CandidateViewGenerator

pose_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.5.7.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.5.7.1.1 generate_from_typed_sample

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

Generate candidates using an EfmSnippetView sample.

1.5.7.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.5.7.1.2 generate

pose_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.5.7.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.5.7.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.5.7.1.3 generate_from_centers

pose_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.5.8 CandidateViewGeneratorConfig

pose_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.5.8.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.5.8.2 Methods

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

1.5.8.2.1 set_debug

pose_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.

1.5.9 CollisionBackend

pose_generation.CollisionBackend()

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

1.5.10 SamplingStrategy

pose_generation.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.5.10.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.5.11 ViewDirectionMode

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

1.6 Functions

Name	Description
candidate_position_id	Return the stable integer provenance id for a position family.
candidate_strategy_id	Return the stable integer provenance id for a view-direction family.
stats_to_markdown_table	Convert nested stats dict into a GitHub-flavoured Markdown table.
summarise_dirs_ref	Summarize azimuth/elevation of LUF directions Tensor["N 3"].
summarise_offsets_ref	Summarize radii and angles for LUF offsets Tensor["N 3"] in metres.

1.6.1 candidate_position_id

pose_generation.candidate_position_id(position_mode)

Return the stable integer provenance id for a position family.

1.6.2 candidate_strategy_id

pose_generation.candidate_strategy_id(strategy)

Return the stable integer provenance id for a view-direction family.

1.6.3 stats_to_markdown_table

pose_generation.stats_to_markdown_table(stats, *, header=None)

Convert nested stats dict into a GitHub-flavoured Markdown table.

1.6.3.1 Parameters

Name	Type	Description	Default
stats	dict[str, dict[str, float]]	Mapping like {"radius_m": {"min": .., "max": .., ...}}.	required
header	str | None	Optional table title inserted as a preceding bold line.	None

1.6.3.2 Returns

Name	Type	Description
	str	Markdown string containing a table with columns metric \| min \| max \| mean \| std.

1.6.4 summarise_dirs_ref

pose_generation.summarise_dirs_ref(dirs_ref)

Summarize azimuth/elevation of LUF directions Tensor["N 3"].

1.6.5 summarise_offsets_ref

pose_generation.summarise_offsets_ref(offsets_ref)

Summarize radii and angles for LUF offsets Tensor["N 3"] in metres.