Struct Tetrahedron

#[repr(C)]
pub struct Tetrahedron {
    pub a: Point<f32>,
    pub b: Point<f32>,
    pub c: Point<f32>,
    pub d: Point<f32>,
}

A tetrahedron with 4 vertices.

What is a Tetrahedron?

A tetrahedron is the simplest 3D polyhedron, consisting of exactly 4 vertices, 6 edges, and 4 triangular faces. It’s the 3D equivalent of a triangle in 2D. Think of it as a pyramid with a triangular base.

Structure

A tetrahedron has:

• 4 vertices labeled a, b, c, and d
• 4 triangular faces: ABC, ABD, ACD, and BCD
• 6 edges: AB, AC, AD, BC, BD, and CD

Common Use Cases

Tetrahedra are fundamental building blocks in many applications:

• Mesh generation: Tetrahedral meshes are used for finite element analysis (FEA)
• Collision detection: Simple convex shape for physics simulations
• Volume computation: Computing volumes of complex 3D shapes
• Spatial partitioning: Subdividing 3D space for games and simulations
• Computer graphics: Rendering and ray tracing acceleration structures

Examples

Creating a Simple Tetrahedron

use parry3d::shape::Tetrahedron;
use parry3d::math::Point;

// Create a tetrahedron with vertices at unit positions
let tetra = Tetrahedron::new(
    Point::new(0.0, 0.0, 0.0),  // vertex a
    Point::new(1.0, 0.0, 0.0),  // vertex b
    Point::new(0.0, 1.0, 0.0),  // vertex c
    Point::new(0.0, 0.0, 1.0),  // vertex d
);

println!("First vertex: {:?}", tetra.a);

Computing Volume

use parry3d::shape::Tetrahedron;
use parry3d::math::Point;

// Create a regular tetrahedron
let tetra = Tetrahedron::new(
    Point::new(0.0, 0.0, 0.0),
    Point::new(1.0, 0.0, 0.0),
    Point::new(0.5, 0.866, 0.0),
    Point::new(0.5, 0.433, 0.816),
);

let volume = tetra.volume();
assert!(volume > 0.0);
println!("Volume: {}", volume);

Accessing Faces and Edges

use parry3d::shape::Tetrahedron;
use parry3d::math::Point;

let tetra = Tetrahedron::new(
    Point::new(0.0, 0.0, 0.0),
    Point::new(1.0, 0.0, 0.0),
    Point::new(0.0, 1.0, 0.0),
    Point::new(0.0, 0.0, 1.0),
);

// Get the first face (triangle ABC)
let face = tetra.face(0);
println!("First face: {:?}", face);

// Get the first edge (segment AB)
let edge = tetra.edge(0);
println!("First edge: {:?}", edge);

Fields

a: Point<f32>

The tetrahedron’s first vertex.

b: Point<f32>

The tetrahedron’s second vertex.

c: Point<f32>

The tetrahedron’s third vertex.

d: Point<f32>

The tetrahedron’s fourth vertex.

Implementations

impl Tetrahedron

pub fn new( a: Point<f32>, b: Point<f32>, c: Point<f32>, d: Point<f32>, ) -> Tetrahedron

Creates a tetrahedron from four points.

The vertices can be specified in any order, but the order affects the orientation and signed volume. For a tetrahedron with positive volume, vertex d should be on the positive side of the plane defined by the counter-clockwise triangle (a, b, c).

Examples

use parry3d::shape::Tetrahedron;
use parry3d::math::Point;

// Create a simple tetrahedron
let tetra = Tetrahedron::new(
    Point::new(0.0, 0.0, 0.0),
    Point::new(1.0, 0.0, 0.0),
    Point::new(0.0, 1.0, 0.0),
    Point::new(0.0, 0.0, 1.0),
);

assert!(tetra.volume() > 0.0);

pub fn from_array(arr: &[Point<f32>; 4]) -> &Tetrahedron

Creates the reference to a tetrahedron from the reference to an array of four points.

This is a zero-cost conversion that reinterprets the array as a tetrahedron. The array elements correspond to vertices [a, b, c, d].

Examples

use parry3d::shape::Tetrahedron;
use parry3d::math::Point;

let points = [
    Point::new(0.0, 0.0, 0.0),
    Point::new(1.0, 0.0, 0.0),
    Point::new(0.0, 1.0, 0.0),
    Point::new(0.0, 0.0, 1.0),
];

let tetra = Tetrahedron::from_array(&points);
assert_eq!(tetra.a, points[0]);
assert_eq!(tetra.b, points[1]);

pub fn face(&self, i: usize) -> Triangle

Returns the i-th face of this tetrahedron.

A tetrahedron has 4 triangular faces indexed from 0 to 3:

• Face 0: triangle ABC
• Face 1: triangle ABD
• Face 2: triangle ACD
• Face 3: triangle BCD

Panics

Panics if i >= 4.

Examples

use parry3d::shape::Tetrahedron;
use parry3d::math::Point;

let tetra = Tetrahedron::new(
    Point::new(0.0, 0.0, 0.0),
    Point::new(1.0, 0.0, 0.0),
    Point::new(0.0, 1.0, 0.0),
    Point::new(0.0, 0.0, 1.0),
);

// Get the first face (triangle ABC)
let face = tetra.face(0);
assert_eq!(face.a, tetra.a);
assert_eq!(face.b, tetra.b);
assert_eq!(face.c, tetra.c);

// Get the last face (triangle BCD)
let face = tetra.face(3);
assert_eq!(face.a, tetra.b);
assert_eq!(face.b, tetra.c);
assert_eq!(face.c, tetra.d);

pub fn face_ids(i: u32) -> (u32, u32, u32)

Returns the indices of the vertices of the i-th face of this tetrahedron.

Returns a tuple (v1, v2, v3) where each value is a vertex index (0=a, 1=b, 2=c, 3=d).

Face to vertex index mapping:

• Face 0: (0, 1, 2) = triangle ABC
• Face 1: (0, 1, 3) = triangle ABD
• Face 2: (0, 2, 3) = triangle ACD
• Face 3: (1, 2, 3) = triangle BCD

Panics

Panics if i >= 4.

Examples

use parry3d::shape::Tetrahedron;

// Get indices for face 0 (triangle ABC)
let (v1, v2, v3) = Tetrahedron::face_ids(0);
assert_eq!((v1, v2, v3), (0, 1, 2));  // vertices a, b, c

// Get indices for face 3 (triangle BCD)
let (v1, v2, v3) = Tetrahedron::face_ids(3);
assert_eq!((v1, v2, v3), (1, 2, 3));  // vertices b, c, d

pub fn edge(&self, i: u32) -> Segment

Returns the i-th edge of this tetrahedron.

A tetrahedron has 6 edges indexed from 0 to 5:

• Edge 0: segment AB
• Edge 1: segment AC
• Edge 2: segment AD
• Edge 3: segment BC
• Edge 4: segment BD
• Edge 5: segment CD

Panics

Panics if i >= 6.

Examples

use parry3d::shape::Tetrahedron;
use parry3d::math::Point;

let tetra = Tetrahedron::new(
    Point::new(0.0, 0.0, 0.0),
    Point::new(1.0, 0.0, 0.0),
    Point::new(0.0, 1.0, 0.0),
    Point::new(0.0, 0.0, 1.0),
);

// Get edge 0 (segment AB)
let edge = tetra.edge(0);
assert_eq!(edge.a, tetra.a);
assert_eq!(edge.b, tetra.b);

// Get edge 5 (segment CD)
let edge = tetra.edge(5);
assert_eq!(edge.a, tetra.c);
assert_eq!(edge.b, tetra.d);

pub fn edge_ids(i: u32) -> (u32, u32)

Returns the indices of the vertices of the i-th edge of this tetrahedron.

Returns a tuple (v1, v2) where each value is a vertex index (0=a, 1=b, 2=c, 3=d).

Edge to vertex index mapping:

• Edge 0: (0, 1) = segment AB
• Edge 1: (0, 2) = segment AC
• Edge 2: (0, 3) = segment AD
• Edge 3: (1, 2) = segment BC
• Edge 4: (1, 3) = segment BD
• Edge 5: (2, 3) = segment CD

Panics

Panics if i >= 6.

Examples

use parry3d::shape::Tetrahedron;

// Get indices for edge 0 (segment AB)
let (v1, v2) = Tetrahedron::edge_ids(0);
assert_eq!((v1, v2), (0, 1));  // vertices a, b

// Get indices for edge 5 (segment CD)
let (v1, v2) = Tetrahedron::edge_ids(5);
assert_eq!((v1, v2), (2, 3));  // vertices c, d

pub fn barycentric_coordinates(&self, p: &Point<f32>) -> Option<[f32; 4]>

Computes the barycentric coordinates of the given point in the coordinate system of this tetrahedron.

Barycentric coordinates express a point as a weighted combination of the tetrahedron’s vertices. For point p, the returned array [wa, wb, wc, wd] satisfies: p = wa*a + wb*b + wc*c + wd*d where wa + wb + wc + wd = 1.0.

These coordinates are useful for:

• Interpolating values defined at vertices
• Determining if a point is inside the tetrahedron (all weights are non-negative)
• Computing distances and projections

Returns

• Some([wa, wb, wc, wd]): The barycentric coordinates
• None: If the tetrahedron is degenerate (zero volume, coplanar vertices)

Examples

use parry3d::shape::Tetrahedron;
use parry3d::math::Point;

let tetra = Tetrahedron::new(
    Point::new(0.0, 0.0, 0.0),
    Point::new(1.0, 0.0, 0.0),
    Point::new(0.0, 1.0, 0.0),
    Point::new(0.0, 0.0, 1.0),
);

// Point at vertex a
let bcoords = tetra.barycentric_coordinates(&tetra.a).unwrap();
assert!((bcoords[0] - 1.0).abs() < 1e-6);
assert!(bcoords[1].abs() < 1e-6);

// Point at center
let center = tetra.center();
let bcoords = tetra.barycentric_coordinates(&center).unwrap();
// All coordinates should be approximately 0.25
for coord in &bcoords {
    assert!((coord - 0.25).abs() < 1e-6);
}

pub fn volume(&self) -> f32

Computes the volume of this tetrahedron.

The volume is always non-negative, regardless of vertex ordering. For the signed volume (which can be negative), use signed_volume.

Formula

Volume = |det(b-a, c-a, d-a)| / 6

Examples

use parry3d::shape::Tetrahedron;
use parry3d::math::Point;

let tetra = Tetrahedron::new(
    Point::new(0.0, 0.0, 0.0),
    Point::new(1.0, 0.0, 0.0),
    Point::new(0.0, 1.0, 0.0),
    Point::new(0.0, 0.0, 1.0),
);

let volume = tetra.volume();
assert!((volume - 1.0/6.0).abs() < 1e-6);

pub fn signed_volume(&self) -> f32

Computes the signed volume of this tetrahedron.

The sign of the volume depends on the vertex ordering:

• Positive: Vertex d is on the positive side of the plane defined by the counter-clockwise triangle (a, b, c)
• Negative: Vertex d is on the negative side (opposite orientation)
• Zero: The tetrahedron is degenerate (all vertices are coplanar)

Formula

Signed Volume = det(b-a, c-a, d-a) / 6

Examples

use parry3d::shape::Tetrahedron;
use parry3d::math::Point;

let tetra = Tetrahedron::new(
    Point::new(0.0, 0.0, 0.0),
    Point::new(1.0, 0.0, 0.0),
    Point::new(0.0, 1.0, 0.0),
    Point::new(0.0, 0.0, 1.0),
);

let signed_vol = tetra.signed_volume();
assert!(signed_vol > 0.0);  // Positive orientation

// Swap two vertices to flip orientation
let tetra_flipped = Tetrahedron::new(
    tetra.a, tetra.c, tetra.b, tetra.d
);
let signed_vol_flipped = tetra_flipped.signed_volume();
assert!(signed_vol_flipped < 0.0);  // Negative orientation
assert!((signed_vol + signed_vol_flipped).abs() < 1e-6);  // Same magnitude

pub fn center(&self) -> Point<f32>

Computes the center of this tetrahedron.

The center (also called centroid or barycenter) is the average of all four vertices. It’s the point where all barycentric coordinates are equal to 0.25.

Formula

Center = (a + b + c + d) / 4

Examples

use parry3d::shape::Tetrahedron;
use parry3d::math::Point;

let tetra = Tetrahedron::new(
    Point::new(0.0, 0.0, 0.0),
    Point::new(1.0, 0.0, 0.0),
    Point::new(0.0, 1.0, 0.0),
    Point::new(0.0, 0.0, 1.0),
);

let center = tetra.center();
assert!((center.x - 0.25).abs() < 1e-6);
assert!((center.y - 0.25).abs() < 1e-6);
assert!((center.z - 0.25).abs() < 1e-6);

// The center has equal barycentric coordinates
let bcoords = tetra.barycentric_coordinates(&center).unwrap();
for coord in &bcoords {
    assert!((coord - 0.25).abs() < 1e-6);
}

Trait Implementations

impl Clone for Tetrahedron

fn clone(&self) -> Tetrahedron

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Tetrahedron

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

Formats the value using the given formatter.

impl PointQuery for Tetrahedron

fn project_local_point(&self, pt: &Point<f32>, solid: bool) -> PointProjection

Projects a point on self.

fn project_local_point_and_get_feature( &self, pt: &Point<f32>, ) -> (PointProjection, FeatureId)

Projects a point on the boundary of self and returns the id of the feature the point was projected on.

fn project_local_point_with_max_dist( &self, pt: &Point<f32>, solid: bool, max_dist: f32, ) -> Option<PointProjection>

Projects a point onto the shape, with a maximum distance limit.

fn project_point_with_max_dist( &self, m: &Isometry<f32>, pt: &Point<f32>, solid: bool, max_dist: f32, ) -> Option<PointProjection>

Projects a point on self transformed by m, unless the projection lies further than the given max distance.

fn distance_to_local_point(&self, pt: &Point<f32>, solid: bool) -> f32

Computes the minimal distance between a point and self.

fn contains_local_point(&self, pt: &Point<f32>) -> bool

Tests if the given point is inside of self.

fn project_point( &self, m: &Isometry<f32>, pt: &Point<f32>, solid: bool, ) -> PointProjection

Projects a point on self transformed by m.

fn distance_to_point( &self, m: &Isometry<f32>, pt: &Point<f32>, solid: bool, ) -> f32

Computes the minimal distance between a point and self transformed by m.

fn project_point_and_get_feature( &self, m: &Isometry<f32>, pt: &Point<f32>, ) -> (PointProjection, FeatureId)

Projects a point on the boundary of self transformed by m and returns the id of the feature the point was projected on.

fn contains_point(&self, m: &Isometry<f32>, pt: &Point<f32>) -> bool

Tests if the given point is inside of self transformed by m.

impl PointQueryWithLocation for Tetrahedron

type Location = TetrahedronPointLocation

Additional shape-specific projection information

fn project_local_point_and_get_location( &self, pt: &Point<f32>, solid: bool, ) -> (PointProjection, Self::Location)

Projects a point on self.

fn project_point_and_get_location( &self, m: &Isometry<f32>, pt: &Point<f32>, solid: bool, ) -> (PointProjection, Self::Location)

Projects a point on self transformed by m.

fn project_local_point_and_get_location_with_max_dist( &self, pt: &Point<f32>, solid: bool, max_dist: f32, ) -> Option<(PointProjection, Self::Location)>

Projects a point on self, with a maximum projection distance.

fn project_point_and_get_location_with_max_dist( &self, m: &Isometry<f32>, pt: &Point<f32>, solid: bool, max_dist: f32, ) -> Option<(PointProjection, Self::Location)>

Projects a point on self transformed by m, with a maximum projection distance.

impl Copy for Tetrahedron