Crate fast_mesh_query 

Queries on meshes stored in fast_mesh_store, accelerated by fast_mesh_bvh.

Every query takes a mesh and a BVH built for it, works in the mesh’s local f32 coordinates, and fails with QueryError::StaleBvh when the mesh was edited after the BVH was last updated. Point, ray, region and pair queries allocate only into the output vector they are given. slice(), fill(), contour_gap, triangulate and intersection_polylines also build per-call temporaries, all reserved fallibly, so that running out of memory is QueryError::OutOfMemory.

• Closest point: closest_point and closest_point_many, with the Feature of the triangle the nearest point lies on.
• Raycasts: raycast (nearest hit), raycast_any (occlusion), raycast_all (every hit, sorted) and raycast_many (a batch). The ray-triangle test is watertight: a ray through a shared edge or vertex never slips between the triangles meeting there. Ties go to the smallest triangle id.
• Region queries: triangles_in and vertices_in find the triangles that touch, or the vertices inside, a Region (a box or a sphere). The box is an Aabb, re-exported from fast_mesh_bvh so that callers need not depend on that crate to build a Region::Box.
• Relative placement: a Rigid transform (rotation and translation, no scale) maps one mesh’s local coordinates into another’s, for queries between two meshes. Whether two triangles intersect or touch is decided exactly, by exact orientation predicates on the transformed f64 coordinates.
• Mesh-vs-mesh queries, with mesh B placed in mesh A’s space by a Rigid: intersects, mesh_distance (a MeshDistance with both points in A’s space), triangles_near (the triangles of each mesh within a margin of the other), intersecting_pairs and intersection_polylines (the intersecting pairs clipped and chained into Polylines). Results are in A’s space; passing the same mesh twice means two coincident copies.
• Self-intersection: self_intersecting_pairs finds the triangle pairs of one mesh that intersect and share no vertex id, by the same exact test.
• Cutting planes: a Plane (origin and unit normal, in f64 mesh-local coordinates) with an orthonormal 2D frame (u, v). A point is on its + side when its signed distance is zero or more.
• Sections: slice() cuts a mesh with a Plane into a Slice of Contours, chained by crossed edge, with flags for open, unoriented and non-manifold pieces.
• Polygon fill: triangulate::triangulate splits a 2D polygon with holes into counter-clockwise triangles by ear clipping.
• Section measurements on (u, v) polylines: contour_length, signed_area, fill (nesting into outers and holes, then a Fill of triangles) and contour_gap (the exact in-plane Gap2 between two sets of polylines, found through a grid).

Modules

triangulate

Triangulation of 2D polygons with holes.

Structs

Aabb

The axis-aligned box type of Region::Box, re-exported from fast_mesh_bvh. Axis-aligned bounding box in mesh-local coordinates.

ClosestHit

The point of a mesh nearest to a query point.

ClosestOptions

Options for closest_point.

Contour

One chain of the cut: a closed loop or an open polyline.

Fill

The filled cross-section made by fill: triangles over (u, v) points.

Gap2

The closest pair between two sets of polylines, found by contour_gap.

MeshDistance

The closest pair of points between two meshes, found by mesh_distance.

PairSegment

One intersection segment between a triangle of A and one of B, in A’s space (B placed by the query’s Rigid).

Plane

A plane in mesh-local coordinates, with an orthonormal 2D frame (u, v) in it. The frame is right-handed: normal = u × v.

Polyline

One chain of the intersection: a closed loop or an open polyline, in A’s space (B placed by the query’s Rigid).

Ray

A ray origin + t * dir, in mesh-local coordinates.

RayHit

Where a ray hit a triangle.

RayOptions

Options shared by the raycasts.

Rigid

Maps mesh B’s local coordinates into mesh A’s local coordinates: p_a = rotation * p_b + translation.

Slice

The cut of a mesh by a plane, as contours.

Enums

Cull

Which triangle faces a ray ignores. A triangle’s front is the side its counter-clockwise winding is seen from.

Feature

The part of a triangle that is closest to a query point.

QueryError

Why a query could not run.

Region

A region of space, in mesh-local coordinates. Both shapes are closed: points on the boundary are inside.

Functions

closest_point

The point of the mesh nearest to p within opts.max_distance, or None when the mesh has no triangle that close. Equal distances go to the smallest triangle id. Triangles with zero area take part, as their edges.

closest_point_many

closest_point for many points: out[i] gets the result for points[i].

contour_gap

The minimum distance between the segments of the polylines a and those of b, each with whether it is closed, with the closest pair of points.

contour_length

The length of a polyline: the sum of its segment lengths. A closed one also counts the segment from its last point back to its first.

distance_to_triangle

The distance from p to a triangle, in f64: for measuring a result exactly when f32 is not enough, as on long thin triangles, whose f32 distances are dominated by rounding.

fill

Fills the closed contours contours (each with whether it is oriented) and writes the triangles to out, replacing what it held.

intersecting_pairs

Appends to out every pair (a, b) of an alive triangle a of A and an alive triangle b of B that intersect or touch, with B placed in A’s space by xf, and returns how many were appended. The appended pairs are sorted by (a, b); elements already in out are kept and stay in front.

intersecting_segments

Appends the intersection segment of every intersecting triangle pair of mesh_a and mesh_b (B placed in A’s space by xf), and returns how many were appended. Elements already in out are kept and stay in front.

intersection_polylines

Appends to out the polylines where mesh_a and mesh_b (placed in A’s space by xf) intersect, and returns how many were appended. Elements already in out are kept and stay in front.

intersects

Whether any alive triangle of A intersects or touches any alive triangle of B, with B placed in A’s space by xf.

mesh_distance

The minimum distance between the surfaces of A and B, with B placed in A’s space by xf, and a closest pair of points. None when the distance is greater than max_distance, or when either mesh has no alive triangle.

raycast

The nearest hit with opts.min_t <= t <= opts.max_t, or None. Equal t goes to the smallest triangle id, so the result is deterministic.

raycast_all

Appends every hit with opts.min_t <= t <= opts.max_t to out, sorted by (t, triangle), and returns how many were appended. Elements already in out are kept.

raycast_any

Some hit with opts.min_t <= t <= opts.max_t, or None. It stops at the first hit found, so it suits occlusion tests; which hit it returns is unspecified.

raycast_many

raycast for many rays: out[i] gets the nearest hit of the ray origins[i] + t * dirs[i].

self_intersecting_pairs

Appends to out every pair (a, b) with a < b of alive triangles of mesh that intersect or touch and share no vertex id. The appended pairs are sorted; elements already in out are kept and stay in front.

self_intersects

Whether any two alive triangles of mesh intersect or touch while sharing no vertex id: the early-exit form of self_intersecting_pairs, for callers that only need the bool.

signed_area

The signed area of the closed polygon points, by the shoelace formula: positive when it runs counter-clockwise. Fewer than three points have no area.

slice

Cuts mesh with plane and writes the contours to out, replacing what it held and reusing its allocations. The plane and the points are in the mesh’s stored local coordinates (the f32 positions widened to f64, without the mesh origin).

triangles_in

Appends to out every alive triangle that touches region (shares a point with it), and returns how many were appended. The order is unspecified. Elements already in out are kept.

triangles_near

Appends to out_a every alive triangle of A within margin of B, and to out_b every alive triangle of B within margin of A, with B placed in A’s space by xf. Elements already in the vectors are kept and stay in front; each appended part is in ascending order without duplicates.

vertices_in

Appends to out, in ascending order and without duplicates, every vertex inside region that belongs to an alive triangle, and returns how many were appended. Elements already in out are kept and stay in front; only the appended part is sorted.

Type Aliases

Result

Result with QueryError as the error type.