Struct ConvexPolyhedron

pub struct ConvexPolyhedron { /* private fields */ }

A 3D convex polyhedron without degenerate faces.

A convex polyhedron is a 3D solid shape where all faces are flat polygons, all interior angles are less than 180 degrees, and any line segment drawn between two points inside the polyhedron stays entirely within it. Common examples include cubes, tetrahedra (pyramids), and prisms.

What is a convex polyhedron?

In 3D space, a polyhedron is convex if:

• All faces are flat, convex polygons
• All dihedral angles (angles between adjacent faces) are less than or equal to 180 degrees
• The line segment between any two points inside the polyhedron lies entirely inside
• All vertices “bulge outward” - there are no indentations or concave regions

Examples of convex polyhedra: cube, tetrahedron, octahedron, rectangular prism, pyramid Examples of non-convex polyhedra: star shapes, torus, L-shapes, any shape with holes

Use cases

Convex polyhedra are widely used in:

• Game development: Collision hulls for characters, vehicles, and complex objects
• Physics simulations: Rigid body dynamics (more efficient than arbitrary meshes)
• Robotics: Simplified robot link shapes, workspace boundaries
• Computer graphics: Level of detail (LOD) representations, occlusion culling
• Computational geometry: Building blocks for complex mesh operations
• 3D printing: Simplified collision detection for print validation

Representation

This structure stores the complete topological information:

• Points: The 3D coordinates of all vertices
• Faces: Polygonal faces with their outward-pointing normals
• Edges: Connections between vertices, shared by exactly two faces
• Adjacency information: Which faces/edges connect to each vertex, and vice versa

This rich topology enables efficient collision detection algorithms like GJK, EPA, and SAT.

Important: No degenerate faces

This structure ensures that there are no degenerate (flat or zero-area) faces. Coplanar adjacent triangles are automatically merged into larger polygonal faces during construction.

Example: Creating a simple tetrahedron (pyramid)

use parry3d::shape::ConvexPolyhedron;
use nalgebra::Point3;

// Define the 4 vertices of a tetrahedron
let points = vec![
    Point3::origin(),      // base vertex 1
    Point3::new(1.0, 0.0, 0.0),      // base vertex 2
    Point3::new(0.5, 1.0, 0.0),      // base vertex 3
    Point3::new(0.5, 0.5, 1.0),      // apex
];

// Define the 4 triangular faces (indices into the points array)
let indices = vec![
    [0u32, 1, 2],  // base triangle
    [0, 1, 3],     // side 1
    [1, 2, 3],     // side 2
    [2, 0, 3],     // side 3
];

let tetrahedron = ConvexPolyhedron::from_convex_mesh(points, &indices)
    .expect("Failed to create tetrahedron");

// A tetrahedron has 4 vertices and 4 faces
assert_eq!(tetrahedron.points().len(), 4);
assert_eq!(tetrahedron.faces().len(), 4);

Implementations

impl ConvexPolyhedron

pub fn aabb(&self, pos: &Isometry<f32>) -> Aabb

Computes the world-space Aabb of this convex polyhedron, transformed by pos.

pub fn local_aabb(&self) -> Aabb

Computes the local-space Aabb of this convex polyhedron.

impl ConvexPolyhedron

pub fn bounding_sphere(&self, pos: &Isometry<f32>) -> BoundingSphere

Computes the world-space bounding sphere of this convex polyhedron, transformed by pos.

pub fn local_bounding_sphere(&self) -> BoundingSphere

Computes the local-space bounding sphere of this convex polyhedron.

impl ConvexPolyhedron

pub fn from_convex_hull(points: &[Point<f32>]) -> Option<ConvexPolyhedron>

Creates a new convex polyhedron from an arbitrary set of points by computing their convex hull.

This is the most flexible constructor - it automatically computes the convex hull of the given 3D points, which is the smallest convex polyhedron that contains all the input points. Think of it as shrink-wrapping the points with an elastic surface.

Use this when:

• You have an arbitrary collection of 3D points and want the convex boundary
• You’re not sure if your points form a convex shape
• You want to simplify a point cloud to its convex outer surface
• You need to create a collision hull from a detailed mesh

Returns

• Some(ConvexPolyhedron) if successful
• None if the convex hull computation failed (e.g., all points are coplanar, collinear, or coincident, or if the mesh is not manifold)

Example: Creating a convex hull from point cloud

use parry3d::shape::ConvexPolyhedron;
use nalgebra::Point3;

// Points defining a cube, plus some interior points
let points = vec![
    Point3::origin(),
    Point3::new(1.0, 0.0, 0.0),
    Point3::new(1.0, 1.0, 0.0),
    Point3::new(0.0, 1.0, 0.0),
    Point3::new(0.0, 0.0, 1.0),
    Point3::new(1.0, 0.0, 1.0),
    Point3::new(1.0, 1.0, 1.0),
    Point3::new(0.0, 1.0, 1.0),
    Point3::new(0.5, 0.5, 0.5),  // Interior point - will be excluded
];

let polyhedron = ConvexPolyhedron::from_convex_hull(&points)
    .expect("Failed to create convex hull");

// The cube has 8 vertices (interior point excluded)
assert_eq!(polyhedron.points().len(), 8);
// And 6 faces (one per side of the cube)
assert_eq!(polyhedron.faces().len(), 6);

Example: Simplifying a complex mesh

use parry3d::shape::ConvexPolyhedron;
use nalgebra::Point3;

// Imagine these are vertices from a detailed character mesh
let detailed_mesh_vertices = vec![
    Point3::new(-1.0, -1.0, -1.0),
    Point3::new(1.0, -1.0, -1.0),
    Point3::new(1.0, 1.0, -1.0),
    Point3::new(-1.0, 1.0, -1.0),
    Point3::new(-1.0, -1.0, 1.0),
    Point3::new(1.0, -1.0, 1.0),
    Point3::new(1.0, 1.0, 1.0),
    Point3::new(-1.0, 1.0, 1.0),
    // ... many more vertices in the original mesh
];

// Create a simplified collision hull
let collision_hull = ConvexPolyhedron::from_convex_hull(&detailed_mesh_vertices)
    .expect("Failed to create collision hull");

// The hull is much simpler than the original mesh
println!("Simplified to {} vertices", collision_hull.points().len());

pub fn from_convex_mesh( points: Vec<Point<f32>>, indices: &[[u32; 3]], ) -> Option<ConvexPolyhedron>

Creates a new convex polyhedron from vertices and face indices, assuming the mesh is already convex.

This constructor is more efficient than from_convex_hull because it assumes the input mesh is already convex and manifold. The convexity is not verified - if you pass a non-convex mesh, the resulting shape may behave incorrectly in collision detection.

The method automatically:

• Merges coplanar adjacent triangular faces into larger polygonal faces
• Removes degenerate (zero-area) faces
• Builds complete topological connectivity information (vertices, edges, faces)

Important requirements

The input mesh must be:

• Manifold: Each edge is shared by exactly 2 faces, no T-junctions, no holes
• Closed: The mesh completely encloses a volume with no gaps
• Convex (not enforced, but assumed): All faces bulge outward
• Valid: Faces use counter-clockwise winding when viewed from outside

When to use this

Use this constructor when:

• You already have a triangulated convex mesh
• The mesh comes from a trusted source (e.g., generated procedurally)
• You want better performance by skipping convex hull computation
• You’re converting from another 3D format (OBJ, STL, etc.)

Arguments

• points - The vertex positions (3D coordinates)
• indices - The face triangles, each containing 3 indices into the points array

Returns

• Some(ConvexPolyhedron) if successful
• None if the mesh is not manifold, has T-junctions, is not closed, or has invalid topology

Example: Creating a cube from vertices and faces

use parry3d::shape::ConvexPolyhedron;
use nalgebra::Point3;

// Define the 8 vertices of a unit cube
let vertices = vec![
    Point3::origin(),  // 0: bottom-left-front
    Point3::new(1.0, 0.0, 0.0),  // 1: bottom-right-front
    Point3::new(1.0, 1.0, 0.0),  // 2: bottom-right-back
    Point3::new(0.0, 1.0, 0.0),  // 3: bottom-left-back
    Point3::new(0.0, 0.0, 1.0),  // 4: top-left-front
    Point3::new(1.0, 0.0, 1.0),  // 5: top-right-front
    Point3::new(1.0, 1.0, 1.0),  // 6: top-right-back
    Point3::new(0.0, 1.0, 1.0),  // 7: top-left-back
];

// Define the faces as triangles (2 triangles per cube face)
let indices = vec![
    // Bottom face (z = 0)
    [0, 2, 1], [0, 3, 2],
    // Top face (z = 1)
    [4, 5, 6], [4, 6, 7],
    // Front face (y = 0)
    [0, 1, 5], [0, 5, 4],
    // Back face (y = 1)
    [2, 3, 7], [2, 7, 6],
    // Left face (x = 0)
    [0, 4, 7], [0, 7, 3],
    // Right face (x = 1)
    [1, 2, 6], [1, 6, 5],
];

let cube = ConvexPolyhedron::from_convex_mesh(vertices, &indices)
    .expect("Failed to create cube");

// The cube has 8 vertices
assert_eq!(cube.points().len(), 8);
// The 12 triangles are merged into 6 square faces
assert_eq!(cube.faces().len(), 6);

Example: Creating a triangular prism

use parry3d::shape::ConvexPolyhedron;
use nalgebra::Point3;

// 6 vertices: 3 on bottom, 3 on top
let vertices = vec![
    Point3::origin(),
    Point3::new(1.0, 0.0, 0.0),
    Point3::new(0.5, 1.0, 0.0),
    Point3::new(0.0, 0.0, 2.0),
    Point3::new(1.0, 0.0, 2.0),
    Point3::new(0.5, 1.0, 2.0),
];

let indices = vec![
    // Bottom triangle
    [0, 2, 1],
    // Top triangle
    [3, 4, 5],
    // Side faces (2 triangles each)
    [0, 1, 4], [0, 4, 3],
    [1, 2, 5], [1, 5, 4],
    [2, 0, 3], [2, 3, 5],
];

let prism = ConvexPolyhedron::from_convex_mesh(vertices, &indices)
    .expect("Failed to create prism");

assert_eq!(prism.points().len(), 6);
// 2 triangular faces + 3 rectangular faces = 5 faces
assert_eq!(prism.faces().len(), 5);

pub fn check_geometry(&self)

Verify if this convex polyhedron is actually convex.

pub fn points(&self) -> &[Point<f32>]

Returns the 3D coordinates of all vertices in this convex polyhedron.

Each point represents a corner of the polyhedron where three or more edges meet.

Example

use parry3d::shape::ConvexPolyhedron;
use nalgebra::Point3;

let points = vec![
    Point3::origin(),
    Point3::new(1.0, 0.0, 0.0),
    Point3::new(0.5, 1.0, 0.0),
    Point3::new(0.5, 0.5, 1.0),
];
let indices = vec![[0u32, 1, 2], [0, 1, 3], [1, 2, 3], [2, 0, 3]];

let tetrahedron = ConvexPolyhedron::from_convex_mesh(points, &indices).unwrap();

assert_eq!(tetrahedron.points().len(), 4);
assert_eq!(tetrahedron.points()[0], Point3::origin());

pub fn vertices(&self) -> &[Vertex]

Returns the topology information for all vertices.

Each Vertex contains indices into the adjacency arrays, telling you which faces and edges are connected to that vertex. This is useful for advanced topological queries and mesh processing algorithms.

Most users will want points() instead to get the 3D coordinates.

pub fn edges(&self) -> &[Edge]

Returns the topology information for all edges.

Each Edge contains:

• The two vertex indices it connects
• The two face indices it borders
• The edge direction as a unit vector

This is useful for advanced geometric queries and rendering wireframes.

Example

use parry3d::shape::ConvexPolyhedron;
use nalgebra::Point3;

let points = vec![
    Point3::origin(),
    Point3::new(1.0, 0.0, 0.0),
    Point3::new(0.5, 1.0, 0.0),
    Point3::new(0.5, 0.5, 1.0),
];
let indices = vec![[0u32, 1, 2], [0, 1, 3], [1, 2, 3], [2, 0, 3]];

let tetrahedron = ConvexPolyhedron::from_convex_mesh(points, &indices).unwrap();

// A tetrahedron has 6 edges (4 vertices choose 2)
assert_eq!(tetrahedron.edges().len(), 6);

// Each edge connects two vertices
let edge = &tetrahedron.edges()[0];
println!("Edge connects vertices {} and {}", edge.vertices[0], edge.vertices[1]);

pub fn faces(&self) -> &[Face]

Returns the topology information for all faces.

Each Face contains:

• Indices into the vertex and edge adjacency arrays
• The number of vertices/edges in the face (faces can be triangles, quads, or larger polygons)
• The outward-pointing unit normal vector

Faces are polygonal and can have 3 or more vertices. Adjacent coplanar triangles are automatically merged into larger polygonal faces.

Example

use parry3d::shape::ConvexPolyhedron;
use nalgebra::Point3;

// Create a cube (8 vertices, 12 triangular input faces)
let vertices = vec![
    Point3::origin(), Point3::new(1.0, 0.0, 0.0),
    Point3::new(1.0, 1.0, 0.0), Point3::new(0.0, 1.0, 0.0),
    Point3::new(0.0, 0.0, 1.0), Point3::new(1.0, 0.0, 1.0),
    Point3::new(1.0, 1.0, 1.0), Point3::new(0.0, 1.0, 1.0),
];
let indices = vec![
    [0, 2, 1], [0, 3, 2], [4, 5, 6], [4, 6, 7],
    [0, 1, 5], [0, 5, 4], [2, 3, 7], [2, 7, 6],
    [0, 4, 7], [0, 7, 3], [1, 2, 6], [1, 6, 5],
];

let cube = ConvexPolyhedron::from_convex_mesh(vertices, &indices).unwrap();

// The 12 triangles are merged into 6 square faces
assert_eq!(cube.faces().len(), 6);

// Each face has 4 vertices (it's a square)
assert_eq!(cube.faces()[0].num_vertices_or_edges, 4);

pub fn vertices_adj_to_face(&self) -> &[u32]

The array containing the indices of the vertices adjacent to each face.

pub fn edges_adj_to_face(&self) -> &[u32]

The array containing the indices of the edges adjacent to each face.

pub fn faces_adj_to_vertex(&self) -> &[u32]

The array containing the indices of the faces adjacent to each vertex.

pub fn scaled(self, scale: &Vector<f32>) -> Option<Self>

Computes a scaled version of this convex polyhedron.

This method scales the polyhedron by multiplying each vertex coordinate by the corresponding component of the scale vector. This allows for non-uniform scaling (different scale factors for x, y, and z axes).

The face normals and edge directions are also updated to reflect the scaling transformation.

Returns

• Some(ConvexPolyhedron) with the scaled shape
• None if the scaling results in degenerate normals (e.g., if the scale factor along one axis is zero or nearly zero)

Example: Uniform scaling

use parry3d::shape::ConvexPolyhedron;
use nalgebra::{Point3, Vector3};

let points = vec![
    Point3::origin(),
    Point3::new(1.0, 0.0, 0.0),
    Point3::new(0.5, 1.0, 0.0),
    Point3::new(0.5, 0.5, 1.0),
];
let indices = vec![[0u32, 1, 2], [0, 1, 3], [1, 2, 3], [2, 0, 3]];

let tetrahedron = ConvexPolyhedron::from_convex_mesh(points, &indices).unwrap();

// Scale uniformly by 2x
let scaled = tetrahedron.scaled(&Vector3::new(2.0, 2.0, 2.0))
    .expect("Failed to scale");

// All coordinates are doubled
assert_eq!(scaled.points()[1], Point3::new(2.0, 0.0, 0.0));
assert_eq!(scaled.points()[3], Point3::new(1.0, 1.0, 2.0));

Example: Non-uniform scaling to create a rectangular prism

use parry3d::shape::ConvexPolyhedron;
use nalgebra::{Point3, Vector3};

// Start with a unit cube
let vertices = vec![
    Point3::origin(), Point3::new(1.0, 0.0, 0.0),
    Point3::new(1.0, 1.0, 0.0), Point3::new(0.0, 1.0, 0.0),
    Point3::new(0.0, 0.0, 1.0), Point3::new(1.0, 0.0, 1.0),
    Point3::new(1.0, 1.0, 1.0), Point3::new(0.0, 1.0, 1.0),
];
let indices = vec![
    [0, 2, 1], [0, 3, 2], [4, 5, 6], [4, 6, 7],
    [0, 1, 5], [0, 5, 4], [2, 3, 7], [2, 7, 6],
    [0, 4, 7], [0, 7, 3], [1, 2, 6], [1, 6, 5],
];

let cube = ConvexPolyhedron::from_convex_mesh(vertices, &indices).unwrap();

// Scale to make it wider (3x), deeper (2x), and taller (4x)
let box_shape = cube.scaled(&Vector3::new(3.0, 2.0, 4.0))
    .expect("Failed to scale");

assert_eq!(box_shape.points()[6], Point3::new(3.0, 2.0, 4.0));

pub fn support_feature_id_toward( &self, local_dir: &Unit<Vector<f32>>, ) -> FeatureId

Computes the ID of the features with a normal that maximize the dot-product with local_dir.

pub fn feature_normal(&self, feature: FeatureId) -> Option<Unit<Vector<f32>>>

The normal of the given feature.

impl ConvexPolyhedron

pub fn to_trimesh(&self) -> (Vec<Point3<f32>>, Vec<[u32; 3]>)

Discretize the boundary of this convex polyhedron as a triangle-mesh.

Trait Implementations

impl Clone for ConvexPolyhedron

fn clone(&self) -> ConvexPolyhedron

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for ConvexPolyhedron

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

Formats the value using the given formatter.

impl PartialEq for ConvexPolyhedron

fn eq(&self, other: &ConvexPolyhedron) -> 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 PointQuery for ConvexPolyhedron

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

Projects a point on self.

fn project_local_point_and_get_feature( &self, point: &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 PolygonalFeatureMap for ConvexPolyhedron

fn local_support_feature( &self, dir: &Unit<Vector<f32>>, out_feature: &mut PolygonalFeature, )

Compute the support polygonal face of self towards the dir.

fn is_convex_polyhedron(&self) -> bool

Is this shape a ConvexPolyhedron?

impl RayCast for ConvexPolyhedron

fn cast_local_ray_and_get_normal( &self, ray: &Ray, max_time_of_impact: f32, solid: bool, ) -> Option<RayIntersection>

Computes the time of impact, and normal between this transformed shape and a ray.

fn cast_local_ray( &self, ray: &Ray, max_time_of_impact: f32, solid: bool, ) -> Option<f32>

Computes the time of impact between this transform shape and a ray.

fn intersects_local_ray(&self, ray: &Ray, max_time_of_impact: f32) -> bool

Tests whether a ray intersects this transformed shape.

fn cast_ray( &self, m: &Isometry<f32>, ray: &Ray, max_time_of_impact: f32, solid: bool, ) -> Option<f32>

Computes the time of impact between this transform shape and a ray.

fn cast_ray_and_get_normal( &self, m: &Isometry<f32>, ray: &Ray, max_time_of_impact: f32, solid: bool, ) -> Option<RayIntersection>

Computes the time of impact, and normal between this transformed shape and a ray.

fn intersects_ray( &self, m: &Isometry<f32>, ray: &Ray, max_time_of_impact: f32, ) -> bool

Tests whether a ray intersects this transformed shape.

impl Shape for ConvexPolyhedron

fn clone_dyn(&self) -> Box<dyn Shape>

Clones this shape into a boxed trait-object.

fn scale_dyn( &self, scale: &Vector<f32>, _num_subdivisions: u32, ) -> Option<Box<dyn Shape>>

Scales this shape by scale into a boxed trait-object.

fn compute_local_aabb(&self) -> Aabb

Computes the Aabb of this shape.

fn compute_local_bounding_sphere(&self) -> BoundingSphere

Computes the bounding-sphere of this shape.

fn compute_aabb(&self, position: &Isometry<f32>) -> Aabb

Computes the Aabb of this shape with the given position.

fn mass_properties(&self, density: f32) -> MassProperties

Compute the mass-properties of this shape given its uniform density.

fn is_convex(&self) -> bool

Is this shape known to be convex?

fn shape_type(&self) -> ShapeType

Gets the type tag of this shape.

fn as_typed_shape(&self) -> TypedShape<'_>

Gets the underlying shape as an enum.

fn ccd_thickness(&self) -> f32

fn ccd_angular_thickness(&self) -> f32

fn as_support_map(&self) -> Option<&dyn SupportMap>

Converts this shape into its support mapping, if it has one.

fn as_polygonal_feature_map(&self) -> Option<(&dyn PolygonalFeatureMap, f32)>

Converts this shape to a polygonal feature-map, if it is one.

fn feature_normal_at_point( &self, feature: FeatureId, _point: &Point<f32>, ) -> Option<Unit<Vector<f32>>>

The shape’s normal at the given point located on a specific feature.

fn clone_box(&self) -> Box<dyn Shape>

👎Deprecated: renamed to clone_dyn

Clones this shape into a boxed trait-object.

fn compute_bounding_sphere(&self, position: &Isometry<f32>) -> BoundingSphere

Computes the bounding-sphere of this shape with the given position.

fn as_composite_shape(&self) -> Option<&dyn CompositeShape>

fn compute_swept_aabb( &self, start_pos: &Isometry<f32>, end_pos: &Isometry<f32>, ) -> Aabb

Computes the swept Aabb of this shape, i.e., the space it would occupy by moving from the given start position to the given end position.

impl SupportMap for ConvexPolyhedron

fn local_support_point(&self, dir: &Vector<f32>) -> Point<f32>

Evaluates the support function of this shape in local space.

fn local_support_point_toward(&self, dir: &Unit<Vector<f32>>) -> Point<f32>

Same as local_support_point except that dir is guaranteed to be normalized (unit length).

fn support_point( &self, transform: &Isometry<f32>, dir: &Vector<f32>, ) -> Point<f32>

Evaluates the support function of this shape transformed by transform.

fn support_point_toward( &self, transform: &Isometry<f32>, dir: &Unit<Vector<f32>>, ) -> Point<f32>

Same as support_point except that dir is guaranteed to be normalized (unit length).

impl StructuralPartialEq for ConvexPolyhedron