Enum MeshIntersectionError

pub enum MeshIntersectionError {
    MissingTopology,
    MissingPseudoNormals,
    TriTriError,
    DuplicateVertices,
    TriangulationError,
    TriMeshBuilderError(TriMeshBuilderError),
}

Errors that can occur when computing the boolean intersection of two triangle meshes.

The intersect_meshes function computes the geometric intersection of two triangle meshes, producing a new mesh that represents their overlapping volume. This operation requires both input meshes to have certain properties and can fail for various reasons.

Prerequisites for Mesh Intersection

Both input meshes must have:

1. Topology information: Half-edge data structure for adjacency information
2. Pseudo-normals: For robust inside/outside testing

These are enabled by setting the TriMeshFlags::ORIENTED flag when creating the mesh.

Variants

MissingTopology

One or both meshes are missing topology information.

Mesh intersection requires half-edge topology data to determine adjacency relationships between triangles. This information is automatically computed when you create a mesh with the TriMeshFlags::ORIENTED flag.

How to Fix

// Instead of:
// let mesh = TriMesh::new(vertices, indices)?;

// Use ORIENTED flag:
let mesh = TriMesh::with_flags(
    vertices,
    indices,
    TriMeshFlags::ORIENTED
).unwrap();

Alternative

You can also add topology to an existing mesh:

let mut mesh = TriMesh::new(vertices, indices).unwrap();
mesh.set_flags(TriMeshFlags::ORIENTED).unwrap();

MissingPseudoNormals

One or both meshes are missing pseudo-normal information.

Pseudo-normals are weighted normals used for robust point-in-mesh testing, which is essential for determining which parts of the meshes are inside or outside each other during intersection. They are computed when using the TriMeshFlags::ORIENTED flag.

Background

Mesh intersection needs to determine which triangles from each mesh are inside, outside, or intersecting the other mesh. This requires reliable point containment tests, which use pseudo-normals as described in:

“Signed distance computation using the angle weighted pseudonormal” by Baerentzen et al., DOI: 10.1109/TVCG.2005.49

How to Fix

Use the same solution as MissingTopology - create your meshes with TriMeshFlags::ORIENTED.

TriTriError

Internal failure while computing the intersection between two triangles.

This error occurs when the triangle-triangle intersection algorithm encounters a case it cannot handle, typically due to:

• Degenerate triangles (zero area, collinear vertices)
• Numerical precision issues with nearly-parallel triangles
• Edge cases in the intersection geometry

What to Try

• Check your input meshes for degenerate triangles
• Try using TriMeshFlags::DELETE_DEGENERATE_TRIANGLES when creating meshes
• Ensure your mesh has reasonable numeric precision (not too small or too large coordinates)
• Consider using intersect_meshes_with_tolerances with custom tolerances

DuplicateVertices

Internal failure while merging vertices from triangle intersections.

After computing triangle-triangle intersections, the algorithm merges nearby vertices to create a clean mesh. This error occurs when the merging process detects inconsistencies, usually caused by:

• Numerical precision issues causing vertices to appear in wrong positions
• Complex intersection patterns that create ambiguous vertex relationships

What to Try

• Use intersect_meshes_with_tolerances with larger tolerances
• Simplify your input meshes if they have very high triangle counts
• Check for and remove nearly-degenerate triangles

TriangulationError

Internal failure while triangulating an intersection face.

The intersection of two meshes can create non-triangular polygonal faces that must be triangulated. This error occurs when the triangulation algorithm fails, typically due to:

• Self-intersecting intersection polygons
• Numerical issues creating invalid polygon geometry
• Very complex intersection patterns

This often happens with grazing intersections or when meshes have very different triangle sizes at the intersection boundary.

TriMeshBuilderError(TriMeshBuilderError)

The resulting intersection mesh could not be constructed.

After computing all triangle intersections and creating the intersection geometry, the final mesh construction failed. This wraps errors from TriMeshBuilderError and typically indicates:

• The intersection resulted in invalid mesh topology
• No triangles in the intersection (meshes don’t overlap)
• Topology violations in the computed intersection

See TriMeshBuilderError for details on the specific failure.

Trait Implementations

impl Clone for MeshIntersectionError

fn clone(&self) -> MeshIntersectionError

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for MeshIntersectionError

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for MeshIntersectionError

fn fmt(&self, __formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Error for MeshIntersectionError

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0: use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0: replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl From<TriMeshBuilderError> for MeshIntersectionError

fn from(value: TriMeshBuilderError) -> Self

Converts to this type from the input type.

impl PartialEq for MeshIntersectionError

fn eq(&self, other: &MeshIntersectionError) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Copy for MeshIntersectionError

impl Eq for MeshIntersectionError

impl StructuralPartialEq for MeshIntersectionError