geometry

# geometry Pure-math perception/planning geometry as in-process typed tools, from mask back-projection through OBB fitting to grasp-candidate generation, plus the two scalar helpers (`geometry.iou`, `geometry.pose_distance`). Fully CPU — no model weights, no GPU. ## When to use - Turning a segmentation mask + depth + camera calibration into world-frame points (`mask_to_world_points`) and an object OBB (`filter_and_compute_obb`). - Deriving grasp poses from an OBB: `top_down_grasp_candidates` for tabletop pick (feed the full list to `curobo.plan_to_grasp_poses` as a goalset), `front_grasp_from_obb` for horizontal interactions (drawer/door handles). - Building the collision world for the planner: `build_world_config` with the target's mask in `object_masks` so the planner can `ignore_obstacle_names` it. - Estimating feature geometry for constrained mating: use `fit_planar_feature` for loops/openings and `fit_linear_feature` for rods/pegs. Their axis signs are geometrically ambiguous, so pass a workcell- or camera-derived `normal_hint` / `axis_hint` when direction matters. ## Install ```bash uv sync --extra geometry # open3d + scikit-learn (cv2/scipy come with gap core) # (pip: pip install -e ".[geometry]") ``` The module imports lazily — the bundle loads (and the light tools work) without the extra; only OBB fitting, DBSCAN filtering and world reconstruction need open3d/sklearn/cv2. ## Gotchas (carried over from the service) - **OBB `extent` is HALF-extents** (gap.types convention, same as the proto). `compute_obb` is upright-only: rotation is around world Z (no 3D tilt), and extents use the 2nd/98th percentile of points, not strict min/max. - Single-camera clouds are 2.5D: only camera-facing surfaces are observed, so OBB centers carry a few cm of depth bias on opaque objects. (The service's rehearsal-sandbox ground-truth snap that compensated for this in-container was deliberately NOT ported — it depended on a `/app` sandbox file.) - A fitted plane normal has two valid signs and a fitted line has two valid directions. The feature-fit tools expose hints solely to resolve that sign; callers must derive the hint from observed support geometry, camera viewing direction, or a declared workcell frame rather than an evaluator target. - `top_down_grasp_candidates` default `z_offset=-0.04`: fingertip 4 cm below the OBB top. With `z_offset=0.0` the fingers close above the object (silent empty grip). Grasp Z is clamped to -0.05 m (table-clearance floor; LIBERO table top is at world z=0). - `mask_to_world_points` keeps only depths in [0.015, 20.0] m (HyRL bounds); invalid/zero-depth pixels are dropped. - `filter_noise` returns the ORIGINAL cloud unchanged when DBSCAN labels everything noise (defensive fallback, mirrors HyRL). - `build_world_config`: table removal only runs when `table_z_threshold != 0` (typical -0.01); robot-point exclusion is Franka-only (simplified DH FK) and skips non-7-DOF joint states; prefer explicit `object_masks` over the `target_obb` projection fallback — masks are pixel-accurate, the OBB projection is a corner-AABB approximation inflated by 2 cm. - `top_down_grasp_from_obb` yaw is NOT derived from the OBB — fingers may close across the wide axis; use the candidate fan when orientation matters.