Enum SplitResult

pub enum SplitResult<T> {
    Pair(T, T),
    Negative,
    Positive,
}

The result of a plane-splitting operation.

This enum represents the three possible outcomes when splitting a geometric shape with a plane. It efficiently handles all cases without unnecessary allocations when the shape doesn’t need to be split.

Type Parameter

The generic type T represents the shape being split. Common types include:

• Aabb - Axis-aligned bounding box
• Segment - Line segment
• TriMesh - Triangle mesh

Half-Space Definition

Given a plane defined by a normal vector n and bias b, a point p lies in:

• Negative half-space if n · p < b (behind the plane)
• Positive half-space if n · p > b (in front of the plane)
• On the plane if n · p ≈ b (within epsilon tolerance)

Examples

Splitting an AABB

use parry3d::bounding_volume::Aabb;
use parry3d::math::Point;
use parry3d::query::SplitResult;

let aabb = Aabb::new(Point::new(0.0, 0.0, 0.0), Point::new(10.0, 10.0, 10.0));

// Split along X-axis at x = 5.0
match aabb.canonical_split(0, 5.0, 1e-6) {
    SplitResult::Pair(left, right) => {
        println!("AABB split into two pieces");
        println!("Left AABB: {:?}", left);
        println!("Right AABB: {:?}", right);
    }
    SplitResult::Negative => {
        println!("AABB is entirely on the negative side (x < 5.0)");
    }
    SplitResult::Positive => {
        println!("AABB is entirely on the positive side (x > 5.0)");
    }
}

Splitting a Segment

use parry3d::shape::Segment;
use parry3d::math::Point;
use parry3d::query::SplitResult;

let segment = Segment::new(Point::new(0.0, 0.0, 0.0), Point::new(10.0, 0.0, 0.0));

// Split along X-axis at x = 3.0
match segment.canonical_split(0, 3.0, 1e-6) {
    SplitResult::Pair(seg1, seg2) => {
        println!("Segment split at x = 3.0");
        println!("First segment: {:?} to {:?}", seg1.a, seg1.b);
        println!("Second segment: {:?} to {:?}", seg2.a, seg2.b);
    }
    SplitResult::Negative => {
        println!("Entire segment is on the negative side");
    }
    SplitResult::Positive => {
        println!("Entire segment is on the positive side");
    }
}

Variants

Pair(T, T)

The split operation yielded two results: one lying on the negative half-space of the plane and the second lying on the positive half-space of the plane.

The first element is the shape piece on the negative side of the plane (where n · p < b). The second element is the shape piece on the positive side of the plane (where n · p > b).

For closed meshes, both pieces are typically “capped” with new geometry on the cutting plane to ensure the result consists of valid closed shapes.

Negative

The shape being split is fully contained in the negative half-space of the plane.

This means all points of the shape satisfy n · p < b (or are within epsilon of the plane). No splitting occurred because the shape doesn’t cross the plane.

Positive

The shape being split is fully contained in the positive half-space of the plane.

This means all points of the shape satisfy n · p > b (or are within epsilon of the plane). No splitting occurred because the shape doesn’t cross the plane.