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

bashCopy code
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.