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.

Install

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

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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: graph-robots
• Source: graph-robots/open-robot-skills
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.