Geometry tensor kernels

embodichain.compute.geometry provides reusable Torch operations on dense float32/float64 tensors. Inputs share dtype and device; outputs stay on that CPU or CUDA device. The kernels do not accept entity UIDs, asset paths, mesh library objects or simulator handles, and do not import scene services.

Shape, dtype, device and scalar-argument checks use host metadata. Numeric validity is computed on the tensor device and returned through masks or NaN outputs; no tensor value is copied to the host to decide validity.

Independent batches and object axes

Leading dimensions broadcast according to Torch rules. B denotes independent layouts and N denotes objects within one layout. A collection of N objects is not N independent layouts. Pairwise comparisons require explicit singleton axes; there is no implicit all-pairs expansion:

# boxes: (B, N, 2, 3), with min/max corners in the penultimate axis.
from embodichain.compute.geometry import aabb_overlap_depth

depths = aabb_overlap_depth(boxes[:, :, None], boxes[:, None, :])
# depths: (B, N, N, 3), with comparisons confined to each batch.

group_height_offset reduces only the N object axis of (..., N, 2, 3) boxes. Its boolean valid_mask has shape (..., N) and ignores padded objects, including their invalid numeric values. Support heights and mask leading axes may broadcast with the independent batch dimensions. Empty or all-padding groups return zero offsets and false validity. This object mask is independent of simulator environment selection.

Operations and invalid values

Tensor contracts

Operation	Output	Numeric invalidity
aabb_overlap_depth	Per-axis intersection lengths, (..., D)	Nonfinite/reversed boxes or nonfinite results produce all-NaN rows.
aabb_containment_violation	Per-axis boundary violations, (..., D)	Invalid boxes or regions produce all-NaN rows; boundary contact is valid.
group_height_offset	(offset, valid) in the broadcast batch shape	An unmasked invalid box or invalid support/result invalidates that group.
transform_aabbs	Affine-transformed bounds, (..., 2, 3)	Invalid boxes, transforms, non-affine last rows or overflow produce NaN boxes.
triangle_geometry	Normals (..., 3), areas (...), validity (...)	Degenerate, nonfinite or unrepresentable triangles return zero measurements and false validity.

AABB overlap is positive volume only when all axis depths are positive; touching faces produce zero on the touching axis. Affine transforms support rotation, nonuniform scale, shear and reflection, with an exact final row of [0, 0, 0, 1]. They bound transformed input boxes, not the original mesh. Triangle winding controls normal sign; callers own slope and area thresholds.

CPU strategies and benchmark scope

Scene support selection, polygon placement, greedy packing and constrained SLSQP solving remain CPU strategies under sim.scene. They may invoke these kernels using CPU tensors. Kernel CUDA support does not move those strategies to GPU or enable B>1 scene-state operations and physical hosts.

The geometry kernel benchmark measures kernels separately from scene solver and simulator work. Compare recorded shapes, dtype, device, warmup and synchronization policy when interpreting results.

Public kernel namespace

aabb_overlap_depth	Return nonnegative intersection lengths along every coordinate axis.
aabb_containment_violation	Return the largest boundary violation on each coordinate axis.
group_height_offset	Compute a common Z translation aligning a group's lowest box to a height.
transform_aabbs	Compute exact axis-aligned bounds of affine-transformed input boxes.
triangle_geometry	Measure triangle unit normals and areas across arbitrary leading batches.

AABB arithmetic and group reductions

aabb_overlap_depth	Return nonnegative intersection lengths along every coordinate axis.
aabb_containment_violation	Return the largest boundary violation on each coordinate axis.
group_height_offset	Compute a common Z translation aligning a group's lowest box to a height.

Broadcastable Torch box arithmetic without host reads of tensor values.

Functions:

aabb_containment_violation(bounds, region)	Return the largest boundary violation on each coordinate axis.
aabb_overlap_depth(bounds_a, bounds_b)	Return nonnegative intersection lengths along every coordinate axis.
group_height_offset(bounds, support_z, *[, ...])	Compute a common Z translation aligning a group's lowest box to a height.

embodichain.compute.geometry.aabb.aabb_containment_violation(bounds, region)

Return the largest boundary violation on each coordinate axis.

Parameters:

• bounds (Tensor) – Object minimum and maximum corners, shaped (..., 2, D).

• region (Tensor) – Allowed minimum and maximum corners, shaped (..., 2, D).

Return type:

Tensor

Returns:

Nonnegative violation distances, shaped broadcast(...), D. A fully contained box has a zero row, including boundary contact. Invalid boxes produce all-NaN rows. Tensor values remain on their original device; only shape/dtype/device metadata is validated on the host.

embodichain.compute.geometry.aabb.aabb_overlap_depth(bounds_a, bounds_b)

Return nonnegative intersection lengths along every coordinate axis.

Parameters:

• bounds_a (Tensor) – Minimum and maximum corners, shaped (..., 2, D).

• bounds_b (Tensor) – Corresponding or broadcastable boxes, shaped (..., 2, D).

Return type:

Tensor

Returns:

Intersection lengths, shaped broadcast(...), D. A pair intersects with positive volume only when every component is positive. Touching faces and disjoint axes have zero depth. Invalid (nonfinite or reversed) input boxes produce an all-NaN row without synchronizing the device.

Inputs must share float32/float64 dtype and device. Add singleton leading axes explicitly for pairwise comparisons; this function does not infer an object axis or materialize an implicit N-by-N matrix.

embodichain.compute.geometry.aabb.group_height_offset(bounds, support_z, *, valid_mask=None, clearance=0.0)

Compute a common Z translation aligning a group’s lowest box to a height.

Parameters:

• bounds (Tensor) – Group boxes, shaped (..., N, 2, 3). Leading dimensions are independent batches; N is the number of objects within one group.

• support_z (Tensor) – Target support height, broadcastable to the leading batch dimensions. Must share the bounds’ float32/float64 dtype and device.

• valid_mask (Tensor | None) – Optional bool tensor, shaped (..., N), on the same device. False entries are padding; their numeric values are ignored.

• clearance (float) – Finite Python scalar added to the target height, in metres.

Return type:

tuple[Tensor, Tensor]

Returns:

(offset, valid) with the broadcast batch shape. Empty/all-padding groups, nonfinite support heights, or any unmasked invalid box return zero offset and false validity. The validity tensor is never read by the host. A valid offset translates every group member by the same amount.

Affine box transforms

transform_aabbs

Compute exact axis-aligned bounds of affine-transformed input boxes.

Batched affine bounding-box transforms implemented with Torch tensors.

Functions:

transform_aabbs(bounds, transforms)

Compute exact axis-aligned bounds of affine-transformed input boxes.

embodichain.compute.geometry.transforms.transform_aabbs(bounds, transforms)

Compute exact axis-aligned bounds of affine-transformed input boxes.

Parameters:

• bounds (Tensor) – Minimum/maximum corners, shaped (..., 2, 3).

• transforms (Tensor) – Broadcastable affine transforms, shaped (..., 4, 4). Rotation, nonuniform scale, shear and reflection are supported.

Return type:

Tensor

Returns:

Transformed minimum/maximum corners in the broadcast batch shape, preserving input dtype and device. Nonfinite/reversed boxes, nonfinite transforms, non-affine last rows and unrepresentable results produce all-NaN boxes using device-side masks. No rigid-transform policy is applied, and no tensor value is copied to the host.

Triangle measurements

triangle_geometry

Measure triangle unit normals and areas across arbitrary leading batches.

Batched triangle measurements without mesh-library or scene dependencies.

Functions:

triangle_geometry(triangles)

Measure triangle unit normals and areas across arbitrary leading batches.

embodichain.compute.geometry.mesh.triangle_geometry(triangles)

Measure triangle unit normals and areas across arbitrary leading batches.

Parameters:

triangles (Tensor) – Three 3D vertices per triangle, shaped (..., 3, 3), with float32/float64 coordinates on their original CPU or CUDA device.

Return type:

tuple[Tensor, Tensor, Tensor]

Returns:

(normals, areas, valid) with shapes (..., 3), (...) and (...). Winding determines normal sign. Degenerate, nonfinite or numerically unrepresentable triangles return zero normals and areas with false validity. Numerical degeneracy includes cross products whose components cannot exceed their cancellation error bound, twice dtype epsilon times the sum of the two determinant-product magnitudes. This scale-relative arithmetic check is not a scene area or slope threshold. No tensor values are read on the host.