---

name: geometry description: "Use GradSLAM's tensor geometry utilities for camera projection, homogeneous coordinates, pixel grids, rigid transforms, quaternions, SE(3) exponential maps, and point or normal frame changes." disable-model-invocation: true metadata: disco-role: operating license: MIT

Geometry

Use this skill when a GradSLAM operation needs camera-coordinate projection, depth unprojection, intrinsics handling, pixel-grid conversion, rigid-body transforms, quaternion rotation, or Lie-group SE(3) updates. The functions are PyTorch tensor operations: preserve the input dtype/device and keep tensors in the expected trailing-dimension layout.

Read the focused contracts in api-reference.md before selecting a function. Use workflows.md for projection/unprojection and transform pipelines, and troubleshooting.md when a shape, frame, dtype, or gradient check fails.

Module and export boundary

gradslam.geometry exports the projective functions from projutils:

• homogenize_points
• unhomogenize_points
• project_points
• unproject_points
• inverse_intrinsics

The package root also re-exports these projective names. Do not assume that other geometry helpers are attributes of gradslam.geometry; import them from their implementation modules explicitly:

from gradslam.geometry import project_points, unproject_points
from gradslam.geometry.geometryutils import (
    cam2pixel,
    compose_transforms_3d,
    create_meshgrid,
    relative_transformation,
    transform_normals,
    transform_pointcloud,
    transform_pts_3d,
)
from gradslam.geometry.se3utils import se3_exp, so3_exp

se3_exp is specifically a direct se3utils import. The same is true of so3_hat, se3_hat, and so3_exp. geometryutils also contains a second implementation of homogeneous conversion plus transform and pixel-grid helpers; importing from that module is intentional when using those helpers, not an alternate package-level export.

Operating rules

1. Name frames before multiplying. A transform t_ab in transform_pts_3d(pts_b, t_ab) maps coordinates expressed in frame b to frame a. Matrix composition compose_transforms_3d(t1, t2) computes t1 @ t2, so t2 is applied first.
2. Keep points in the last dimension. Projective points end in 3 or 4, pixels in 2 or homogeneous 3, and normals/Euclidean points in 3. Batched projective tensors retain all leading dimensions when the batching contract is satisfied.
3. Use true camera intrinsics for unprojection. unproject_points takes an inverse 3x3 matrix and a depth tensor with shape exactly equal to the pixel tensor without its last coordinate. inverse_intrinsics is a fast pinhole inverse for the supported 3x3/4x4 layout, not a general matrix inverse.
4. Treat zero denominators deliberately. Homogeneous weights within eps are left unscaled by unhomogenize_points; projected depth exactly equal to zero is divided by one. These guards avoid infinities but do not provide a physically meaningful point at infinity.
5. Do not detach geometry tensors. The routines are intended to remain in the autograd graph. Avoid .numpy(), .item() in the computational path, or in-place edits to leaf tensors requiring gradients.
6. Use rigid transforms for rigid helpers. The custom inverse in inverse_transfom_3d assumes an orthogonal rotation. Use relative_transformation(..., orthogonal_rotations=False) when the input may be a general invertible homogeneous matrix.
7. Respect implementation quirks. quaternion_to_rotation_matrix expects (x, y, z, w) and flattens leading batch dimensions beyond one batch axis; normalize_pixel_coords currently applies the first image-size factor to both coordinates. See the API and troubleshooting references rather than silently correcting these behaviors in a caller.

Minimal decision tree

• Euclidean or homogeneous point conversion: use the exported projutils functions for public camera code; use the geometryutils versions only when a transform helper in that module is also required.
• 3D camera points to pixels: use project_points with a 4x4 projection matrix; it accepts (..., 3) or (..., 4) points.
• Pixels and depth to camera points: use unproject_points with a 3x3 inverse intrinsics matrix and matching depth shape.
• Intrinsics inverse: use inverse_intrinsics for the library's pinhole K layout, including the 4x4 form used by RGB-D structures.
• Point/normal frame change: use transform_pts_3d or transform_pointcloud; rotate normals without translation using transform_normals.
• Relative poses: use relative_transformation for batched or general invertible poses; use relative_transform_3d for matching rigid tensors.
• Optimization update: use se3_exp on a six-vector ordered as (translation, rotation); it returns a 4x4 transform.

The bundled CPU smoke check is scripts/geometry_smoke.py. It uses only deterministic in-memory tensors and has no network, display, dataset, or GPU path.