1 pose_generation.candidate_generation_rules

pose_generation.candidate_generation_rules

Mask-preserving pruning rules for finite candidate pose generation.

Rules inspect the full sampled shell and update its aligned boolean validity mask in place. They never compact candidate rows, which preserves provenance and makes invalid actions distinguishable from merely low-value actions.

This module provides the Rule protocol, shared rule base, and concrete mesh-clearance, path-collision, motion-realism, and free-space checks. Candidate generation owns rule ordering and mask aggregation; renderers and RRI scorers consume the resulting valid set but do not reinterpret rejected rows as scores.

1.1 Classes

Name	Description
FreeSpaceRule	Restrict candidate centers to a world-space AABB.
MinDistanceToMeshRule	Reject candidates whose centers are too close to the GT mesh.
MotionRealismRule	Reject candidates that violate local egocentric motion bounds.
PathCollisionRule	Reject candidates whose straight-line path fails the selected mesh check.
Rule	Protocol for one full-shell, mask-preserving candidate validity rule.
RuleBase	Shared utilities for pruning rules (logging and mask helpers).

1.1.1 FreeSpaceRule

pose_generation.candidate_generation_rules.FreeSpaceRule(config)

Restrict candidate centers to a world-space AABB.

1.1.2 MinDistanceToMeshRule

pose_generation.candidate_generation_rules.MinDistanceToMeshRule(config)

Reject candidates whose centers are too close to the GT mesh.

For each candidate center $c_i$ and mesh $\mathcal{M}$, this rule computes the distance

\[ d_i = \min_{x \in \mathcal{M}} \lVert c_i - x \rVert_2 \]

and rejects candidates with $d_i \leq \text{min_distance_to_mesh}$.

When cfg.collect_debug_stats is True, the per-candidate distances are stored as ctx.debug['min_distance_to_mesh'] for later analysis.

1.1.3 MotionRealismRule

pose_generation.candidate_generation_rules.MotionRealismRule(config)

Reject candidates that violate local egocentric motion bounds.

1.1.4 PathCollisionRule

pose_generation.candidate_generation_rules.PathCollisionRule(config)

Reject candidates whose straight-line path fails the selected mesh check.

The two backend families intentionally implement different checks. The PyTorch3D backend samples point-to-surface clearance at ray_subsample evenly spaced positions, including both segment endpoints. It can therefore reject a near miss, but a thin obstacle between samples can go undetected. Trimesh and PyEmbree cast a bounded ray and reject ray-surface intersections reported by the backend; they do not apply step_clearance as a swept-path radius. For every backend, a non-positive step_clearance disables the rule.

The method:

Returns early if no mesh is available or the step clearance is non-positive.
Constructs a ray from the reference position to each candidate center.
Depending on config.collision_backend:
- CollisionBackend.P3D: discretise each segment into ray_subsample points, compute distances via point_mesh_distance, and mark collisions where any sample falls below step_clearance.
- CollisionBackend.TRIMESH / CollisionBackend.PYEMBREE: cast rays with maximum distance equal to the segment length and use the ray engine’s intersects_any result to identify bounded ray-surface intersections.
Records the boolean collision mask in ctx.debug['path_collision_mask'] when debug stats are enabled.
Calls CandidateContext.invalidate to apply the collision mask as a rejection mask.

1.1.5 Rule

pose_generation.candidate_generation_rules.Rule()

Protocol for one full-shell, mask-preserving candidate validity rule.

1.1.6 RuleBase

pose_generation.candidate_generation_rules.RuleBase(config)

Shared utilities for pruning rules (logging and mask helpers).

1.1.6.1 Methods

Name	Description
warn_once	Emit at most one backend-fallback warning per rule instance.

1.1.6.1.1 warn_once

pose_generation.candidate_generation_rules.RuleBase.warn_once(message)

Emit at most one backend-fallback warning per rule instance.

# pose_generation.candidate_generation_rules { #aria_nbv.pose_generation.candidate_generation_rules } `pose_generation.candidate_generation_rules` Mask-preserving pruning rules for finite candidate pose generation. Rules inspect the full sampled shell and update its aligned boolean validity mask in place. They never compact candidate rows, which preserves provenance and makes invalid actions distinguishable from merely low-value actions. This module provides the :class:`Rule` protocol, shared rule base, and concrete mesh-clearance, path-collision, motion-realism, and free-space checks. Candidate generation owns rule ordering and mask aggregation; renderers and RRI scorers consume the resulting valid set but do not reinterpret rejected rows as scores. ## Classes | Name | Description | | --- | --- | | [FreeSpaceRule](#aria_nbv.pose_generation.candidate_generation_rules.FreeSpaceRule) | Restrict candidate centers to a world-space AABB. | | [MinDistanceToMeshRule](#aria_nbv.pose_generation.candidate_generation_rules.MinDistanceToMeshRule) | Reject candidates whose centers are too close to the GT mesh. | | [MotionRealismRule](#aria_nbv.pose_generation.candidate_generation_rules.MotionRealismRule) | Reject candidates that violate local egocentric motion bounds. | | [PathCollisionRule](#aria_nbv.pose_generation.candidate_generation_rules.PathCollisionRule) | Reject candidates whose straight-line path fails the selected mesh check. | | [Rule](#aria_nbv.pose_generation.candidate_generation_rules.Rule) | Protocol for one full-shell, mask-preserving candidate validity rule. | | [RuleBase](#aria_nbv.pose_generation.candidate_generation_rules.RuleBase) | Shared utilities for pruning rules (logging and mask helpers). | ### FreeSpaceRule { #aria_nbv.pose_generation.candidate_generation_rules.FreeSpaceRule } ```python pose_generation.candidate_generation_rules.FreeSpaceRule(config) ``` Restrict candidate centers to a world-space AABB. ### MinDistanceToMeshRule { #aria_nbv.pose_generation.candidate_generation_rules.MinDistanceToMeshRule } ```python pose_generation.candidate_generation_rules.MinDistanceToMeshRule(config) ``` Reject candidates whose centers are too close to the GT mesh. For each candidate center $c_i$ and mesh $\mathcal{M}$, this rule computes the distance $$ d_i = \min_{x \in \mathcal{M}} \lVert c_i - x \rVert_2 $$ and rejects candidates with $d_i \leq \text{min_distance_to_mesh}$. When `cfg.collect_debug_stats` is True, the per-candidate distances are stored as `ctx.debug['min_distance_to_mesh']` for later analysis. ### MotionRealismRule { #aria_nbv.pose_generation.candidate_generation_rules.MotionRealismRule } ```python pose_generation.candidate_generation_rules.MotionRealismRule(config) ``` Reject candidates that violate local egocentric motion bounds. ### PathCollisionRule { #aria_nbv.pose_generation.candidate_generation_rules.PathCollisionRule } ```python pose_generation.candidate_generation_rules.PathCollisionRule(config) ``` Reject candidates whose straight-line path fails the selected mesh check. The two backend families intentionally implement different checks. The PyTorch3D backend samples point-to-surface clearance at ``ray_subsample`` evenly spaced positions, including both segment endpoints. It can therefore reject a near miss, but a thin obstacle between samples can go undetected. Trimesh and PyEmbree cast a bounded ray and reject ray-surface intersections reported by the backend; they do not apply ``step_clearance`` as a swept-path radius. For every backend, a non-positive ``step_clearance`` disables the rule. The method: 1. Returns early if no mesh is available or the step clearance is non-positive. 2. Constructs a ray from the reference position to each candidate center. 3. Depending on `config.collision_backend`: * `CollisionBackend.P3D`: discretise each segment into ``ray_subsample`` points, compute distances via `point_mesh_distance`, and mark collisions where any sample falls below ``step_clearance``. * `CollisionBackend.TRIMESH` / `CollisionBackend.PYEMBREE`: cast rays with maximum distance equal to the segment length and use the ray engine's `intersects_any` result to identify bounded ray-surface intersections. 4. Records the boolean collision mask in ``ctx.debug['path_collision_mask']`` when debug stats are enabled. 5. Calls `CandidateContext.invalidate` to apply the collision mask as a rejection mask. ### Rule { #aria_nbv.pose_generation.candidate_generation_rules.Rule } ```python pose_generation.candidate_generation_rules.Rule() ``` Protocol for one full-shell, mask-preserving candidate validity rule. ### RuleBase { #aria_nbv.pose_generation.candidate_generation_rules.RuleBase } ```python pose_generation.candidate_generation_rules.RuleBase(config) ``` Shared utilities for pruning rules (logging and mask helpers). #### Methods | Name | Description | | --- | --- | | [warn_once](#aria_nbv.pose_generation.candidate_generation_rules.RuleBase.warn_once) | Emit at most one backend-fallback warning per rule instance. | ##### warn_once { #aria_nbv.pose_generation.candidate_generation_rules.RuleBase.warn_once } ```python pose_generation.candidate_generation_rules.RuleBase.warn_once(message) ``` Emit at most one backend-fallback warning per rule instance.