1 geometry.point_mesh

geometry.point_mesh

Prepared mesh state shared by candidate pruning and RRI kernels.

1.1 Classes

Name Description
PreparedMeshQuery Prepare immutable mesh state once for repeated geometric queries.

1.1.1 PreparedMeshQuery

geometry.point_mesh.PreparedMeshQuery(verts, faces, *, device, dtype, mesh=None)

Prepare immutable mesh state once for repeated geometric queries.

The module lazily materializes normalized PyTorch3D tensors and Trimesh adapters behind one interface. A query is valid only while its source tensors and optional CPU mesh remain immutable. Inference-mode tensors are valid for one query but deliberately uncacheable because Torch does not expose their mutation counters.

1.1.1.1 Parameters

Name Type Description Default
verts Tensor["V 3", float] World-frame vertices in metres. required
faces Tensor["F 3", int] Triangle indices into verts. required
device torch.device | str Device used by point-distance kernels. required
dtype torch.dtype Floating-point dtype used by point-distance kernels. required
mesh 'trimesh.Trimesh | None' Optional CPU Trimesh adapter for signed-distance and ray queries. None

1.1.1.2 Attributes

Name Description
is_persistently_reusable Return whether sources are safe to retain across requests.
source_faces_dtype Return the original face dtype without changing historical materialization.

1.1.1.3 Methods

Name Description
acquire Reuse a matching query or prepare one for the supplied mesh contract.
matches Return whether this query can safely serve the supplied mesh inputs.
validate_source_face_indices Check original triangle indices before an evaluator materializes the mesh.
matches_request Validate immediate use against exact sources, including inference tensors.
pytorch3d_mesh Return normalized mesh tensors while caching only autograd-safe state.
point_distance Return point-to-mesh distances for matching device/dtype points.
signed_distance Return absolute Trimesh signed distances on the points’ device.
intersects_any Return whether each bounded ray intersects the prepared mesh.
1.1.1.3.1 acquire
geometry.point_mesh.PreparedMeshQuery.acquire(
    current,
    verts,
    faces,
    *,
    device,
    dtype,
    mesh=None,
)

Reuse a matching query or prepare one for the supplied mesh contract.

1.1.1.3.2 matches
geometry.point_mesh.PreparedMeshQuery.matches(
    verts,
    faces,
    *,
    device,
    dtype,
    mesh,
)

Return whether this query can safely serve the supplied mesh inputs.

1.1.1.3.3 validate_source_face_indices
geometry.point_mesh.PreparedMeshQuery.validate_source_face_indices()

Check original triangle indices before an evaluator materializes the mesh.

The historical prepared-mesh path retains its existing coercion behavior; stricter evaluators call this explicitly before PyTorch indexing can reinterpret a negative index or an out-of-range value.

1.1.1.3.4 matches_request
geometry.point_mesh.PreparedMeshQuery.matches_request(
    verts,
    faces,
    *,
    device,
    dtype,
    mesh,
)

Validate immediate use against exact sources, including inference tensors.

Matching unavailable mutation counters are safe only at this explicit request boundary. :meth:matches remains fail-closed for cross-request cache reuse.

1.1.1.3.5 pytorch3d_mesh
geometry.point_mesh.PreparedMeshQuery.pytorch3d_mesh()

Return normalized mesh tensors while caching only autograd-safe state.

1.1.1.3.6 point_distance
geometry.point_mesh.PreparedMeshQuery.point_distance(points, *, squared=False)

Return point-to-mesh distances for matching device/dtype points.

1.1.1.3.6.1 Parameters
Name Type Description Default
points Tensor["N 3", float] World-frame points in metres. required
squared bool Return squared distances when true. False
1.1.1.3.6.2 Returns
Name Type Description
torch.Tensor Tensor["N", float] distances in metres or square metres.
1.1.1.3.6.3 Raises
Name Type Description
ValueError If points do not match the prepared device and dtype.
1.1.1.3.7 signed_distance
geometry.point_mesh.PreparedMeshQuery.signed_distance(points)

Return absolute Trimesh signed distances on the points’ device.

1.1.1.3.8 intersects_any
geometry.point_mesh.PreparedMeshQuery.intersects_any(
    origins,
    directions,
    *,
    max_distance,
    use_pyembree,
)

Return whether each bounded ray intersects the prepared mesh.

1.2 Functions

Name Description
bounded_ray_intersects_any Return first-hit intersections bounded by each ray segment length.
tensor_identity_token Return a mutation-sensitive token for tensors safe in derived caches.

1.2.1 bounded_ray_intersects_any

geometry.point_mesh.bounded_ray_intersects_any(
    engine,
    origins,
    directions,
    *,
    max_distance,
)

Return first-hit intersections bounded by each ray segment length.

1.2.2 tensor_identity_token

geometry.point_mesh.tensor_identity_token(tensor)

Return a mutation-sensitive token for tensors safe in derived caches.

Back to top