Struct Compound

pub struct Compound { /* private fields */ }

A compound shape with an aabb bounding volume.

A compound shape is a shape composed of the union of several simpler shape. This is the main way of creating a concave shape from convex parts. Each parts can have its own delta transformation to shift or rotate it with regard to the other shapes.

Implementations

impl Compound

pub fn new(shapes: Vec<(Isometry<f32>, SharedShape)>) -> Compound

Builds a new compound shape from a collection of sub-shapes.

A compound shape combines multiple primitive shapes into a single composite shape, each with its own relative position and orientation. This is the primary way to create concave shapes from convex primitives. The compound internally builds a Bounding Volume Hierarchy (BVH) for efficient collision detection.

Arguments

• shapes - A vector of (position, shape) pairs. Each pair defines:
  • An Isometry representing the sub-shape’s position and orientation relative to the compound’s origin
  • A SharedShape containing the actual geometry

Panics

• If the input vector is empty (a compound must contain at least one shape)
• If any of the provided shapes are themselves composite shapes (nested composites are not allowed)

Performance

The BVH is built using a binned construction strategy optimized for static scenes. For large compounds (100+ shapes), construction may take noticeable time but provides excellent query performance.

Example

use parry3d::math::Isometry;
use nalgebra::Vector3;

// Create a compound shape resembling a dumbbell
let shapes = vec![
    // Left sphere
    (
        Isometry::translation(-2.0, 0.0, 0.0),
        SharedShape::new(Ball::new(0.5))
    ),
    // Center bar
    (
        Isometry::identity(),
        SharedShape::new(Cuboid::new(Vector3::new(2.0, 0.2, 0.2)))
    ),
    // Right sphere
    (
        Isometry::translation(2.0, 0.0, 0.0),
        SharedShape::new(Ball::new(0.5))
    ),
];

let compound = Compound::new(shapes);

// The compound now contains all three shapes
assert_eq!(compound.shapes().len(), 3);

// Create an L-shaped compound
let shapes = vec![
    // Vertical rectangle
    (
        Isometry::translation(0.0, 1.0),
        SharedShape::new(Cuboid::new(Vector2::new(0.5, 1.0)))
    ),
    // Horizontal rectangle
    (
        Isometry::translation(1.0, 0.0),
        SharedShape::new(Cuboid::new(Vector2::new(1.0, 0.5)))
    ),
];

let l_shape = Compound::new(shapes);
assert_eq!(l_shape.shapes().len(), 2);

impl Compound

pub fn shapes(&self) -> &[(Isometry<f32>, SharedShape)]

Returns a slice containing all sub-shapes and their positions in this compound.

Each element in the returned slice is a tuple containing:

• The sub-shape’s position and orientation (Isometry) relative to the compound’s origin
• The sub-shape itself (SharedShape)

The order of shapes matches the order they were provided to Compound::new. The index of each shape in this slice corresponds to its ID used in other operations like BVH traversal.

Returns

A slice of (isometry, shape) pairs representing all sub-shapes in this compound.

Example

use parry3d::math::Isometry;
use nalgebra::Vector3;

let shapes = vec![
    (Isometry::translation(1.0, 0.0, 0.0), SharedShape::new(Ball::new(0.5))),
    (Isometry::translation(-1.0, 0.0, 0.0), SharedShape::new(Ball::new(0.3))),
    (Isometry::identity(), SharedShape::new(Cuboid::new(Vector3::new(0.5, 0.5, 0.5)))),
];

let compound = Compound::new(shapes);

// Access all shapes
assert_eq!(compound.shapes().len(), 3);

// Inspect individual shapes
for (i, (position, shape)) in compound.shapes().iter().enumerate() {
    println!("Shape {} at position: {:?}", i, position.translation);

    // Check if it's a ball
    if let Some(ball) = shape.as_ball() {
        println!("  Ball with radius: {}", ball.radius);
    }
}

Example: Modifying Sub-Shape Positions

use parry3d::math::Isometry;

let shapes = vec![
    (Isometry::translation(0.0, 0.0, 0.0), SharedShape::new(Ball::new(1.0))),
    (Isometry::translation(2.0, 0.0, 0.0), SharedShape::new(Ball::new(1.0))),
];

let compound = Compound::new(shapes);

// Note: To modify positions, you need to create a new compound
let mut new_shapes: Vec<_> = compound.shapes()
    .iter()
    .map(|(pos, shape)| {
        // Shift all shapes up by 1 unit
        let new_pos = pos * Isometry::translation(0.0, 1.0, 0.0);
        (new_pos, shape.clone())
    })
    .collect();

let shifted_compound = Compound::new(new_shapes);
assert_eq!(shifted_compound.shapes().len(), 2);

pub fn local_aabb(&self) -> &Aabb

Returns the Axis-Aligned Bounding Box (AABB) of this compound in local space.

The local AABB is the smallest axis-aligned box that contains all sub-shapes in the compound, computed in the compound’s local coordinate system. This AABB is automatically computed when the compound is created and encompasses all sub-shapes at their specified positions.

Returns

A reference to the Aabb representing the compound’s bounding box in local space.

Use Cases

• Broad-phase collision detection: Quick rejection tests before detailed queries
• Spatial partitioning: Organizing compounds in larger spatial structures
• Culling: Determining if the compound is visible or relevant to a query
• Size estimation: Getting approximate dimensions of the compound

Example

use parry3d::math::Isometry;
use nalgebra::Point3;

let shapes = vec![
    (Isometry::translation(-2.0, 0.0, 0.0), SharedShape::new(Ball::new(0.5))),
    (Isometry::translation(2.0, 0.0, 0.0), SharedShape::new(Ball::new(0.5))),
];

let compound = Compound::new(shapes);
let aabb = compound.local_aabb();

// The AABB should contain both balls
// Left ball extends from -2.5 to -1.5 on X axis
// Right ball extends from 1.5 to 2.5 on X axis
assert!(aabb.mins.x <= -2.5);
assert!(aabb.maxs.x >= 2.5);

// Check if a point is inside the AABB
assert!(aabb.contains_local_point(&Point3::origin()));
assert!(!aabb.contains_local_point(&Point3::new(10.0, 0.0, 0.0)));

Example: Computing Compound Dimensions

use parry3d::math::Isometry;
use nalgebra::Vector3;

let shapes = vec![
    (Isometry::identity(), SharedShape::new(Cuboid::new(Vector3::new(1.0, 1.0, 1.0)))),
    (Isometry::translation(3.0, 0.0, 0.0), SharedShape::new(Cuboid::new(Vector3::new(0.5, 0.5, 0.5)))),
];

let compound = Compound::new(shapes);
let aabb = compound.local_aabb();

// Calculate the total dimensions
let dimensions = aabb.maxs - aabb.mins;
println!("Compound dimensions: {:?}", dimensions);

// The compound extends from -1.0 to 3.5 on the X axis (4.5 units total)
assert!((dimensions.x - 4.5).abs() < 1e-5);

pub fn local_bounding_sphere(&self) -> BoundingSphere

Returns the bounding sphere of this compound in local space.

The bounding sphere is the smallest sphere that contains all sub-shapes in the compound. It is computed from the compound’s AABB by finding the sphere that tightly encloses that box. This provides a simple, rotation-invariant bounding volume useful for certain collision detection algorithms.

Returns

A BoundingSphere centered in local space that contains the entire compound.

Performance

This method is very fast as it simply computes the bounding sphere from the pre-computed AABB. The bounding sphere is not cached - it’s computed on each call.

Comparison with AABB

• Bounding Sphere: Rotation-invariant, simpler intersection tests, but often looser fit
• AABB: Tighter fit for axis-aligned objects, but must be recomputed when rotated

Example

use parry3d::math::Isometry;

let shapes = vec![
    (Isometry::translation(-1.0, 0.0, 0.0), SharedShape::new(Ball::new(0.5))),
    (Isometry::translation(1.0, 0.0, 0.0), SharedShape::new(Ball::new(0.5))),
];

let compound = Compound::new(shapes);
let bounding_sphere = compound.local_bounding_sphere();

// The bounding sphere should contain both balls
println!("Center: {:?}", bounding_sphere.center());
println!("Radius: {}", bounding_sphere.radius());

// The center should be near the origin
assert!(bounding_sphere.center().coords.norm() < 0.1);

// The radius should be at least 1.5 (distance to ball edge: 1.0 + 0.5)
assert!(bounding_sphere.radius() >= 1.5);

Example: Using Bounding Sphere for Quick Rejection

use parry3d::math::Isometry;
use nalgebra::{Vector3, Point3};

let shapes = vec![
    (Isometry::identity(), SharedShape::new(Cuboid::new(Vector3::new(1.0, 1.0, 1.0)))),
    (Isometry::translation(2.0, 0.0, 0.0), SharedShape::new(Cuboid::new(Vector3::new(0.5, 0.5, 0.5)))),
];

let compound = Compound::new(shapes);
let sphere = compound.local_bounding_sphere();

// Quick test: is a point potentially inside the compound?
let test_point = Point3::new(5.0, 5.0, 5.0);
let distance_to_center = (test_point - sphere.center()).norm();

if distance_to_center > sphere.radius() {
    println!("Point is definitely outside the compound");
    assert!(distance_to_center > sphere.radius());
} else {
    println!("Point might be inside - need detailed check");
}

pub fn aabbs(&self) -> &[Aabb]

Returns a slice of AABBs, one for each sub-shape in this compound.

Each AABB in the returned slice corresponds to the bounding box of a sub-shape, transformed to the compound’s local coordinate system. The AABBs are stored in the same order as the shapes returned by Compound::shapes, so index i in this slice corresponds to shape i.

These AABBs are used internally by the BVH for efficient spatial queries and collision detection. They are pre-computed during compound construction.

Returns

A slice of Aabb representing the local-space bounding boxes of each sub-shape.

Use Cases

• Inspecting individual sub-shape bounds without accessing the shapes themselves
• Custom spatial queries or culling operations
• Debugging and visualization of the compound’s structure
• Understanding the BVH’s leaf nodes

Example

use parry3d::math::Isometry;
use nalgebra::Vector3;

let shapes = vec![
    (Isometry::translation(-2.0, 0.0, 0.0), SharedShape::new(Ball::new(0.5))),
    (Isometry::identity(), SharedShape::new(Cuboid::new(Vector3::new(1.0, 1.0, 1.0)))),
    (Isometry::translation(3.0, 0.0, 0.0), SharedShape::new(Ball::new(0.3))),
];

let compound = Compound::new(shapes);

// Get AABBs for all sub-shapes
let aabbs = compound.aabbs();
assert_eq!(aabbs.len(), 3);

// Inspect each AABB
for (i, aabb) in aabbs.iter().enumerate() {
    println!("Shape {} AABB:", i);
    println!("  Min: {:?}", aabb.mins);
    println!("  Max: {:?}", aabb.maxs);

    let center = aabb.center();
    let extents = aabb.half_extents();
    println!("  Center: {:?}", center);
    println!("  Half-extents: {:?}", extents);
}

Example: Finding Sub-Shapes in a Region

use parry3d::math::Isometry;
use parry3d::bounding_volume::Aabb;
use nalgebra::Point3;

let shapes = vec![
    (Isometry::translation(-5.0, 0.0, 0.0), SharedShape::new(Ball::new(0.5))),
    (Isometry::translation(0.0, 0.0, 0.0), SharedShape::new(Ball::new(0.5))),
    (Isometry::translation(5.0, 0.0, 0.0), SharedShape::new(Ball::new(0.5))),
];

let compound = Compound::new(shapes);

// Define a query point
let query_point = Point3::origin();

// Find which sub-shapes might contain this point
let potentially_containing: Vec<usize> = compound.aabbs()
    .iter()
    .enumerate()
    .filter(|(_, aabb)| aabb.contains_local_point(&query_point))
    .map(|(i, _)| i)
    .collect();

// Only the middle shape (index 1) should contain the origin
assert_eq!(potentially_containing.len(), 1);
assert_eq!(potentially_containing[0], 1);

pub fn bvh(&self) -> &Bvh

Returns the Bounding Volume Hierarchy (BVH) used for efficient spatial queries.

The BVH is an acceleration structure that organizes the sub-shapes hierarchically for fast collision detection and spatial queries. It enables logarithmic-time queries instead of linear searches through all sub-shapes. The BVH is automatically built when the compound is created using a binned construction strategy.

Returns

A reference to the Bvh acceleration structure for this compound.

Use Cases

• Custom spatial queries: Traverse the BVH for specialized collision detection
• Ray casting: Efficiently find which sub-shapes intersect a ray
• AABB queries: Find all sub-shapes intersecting a region
• Debugging: Inspect the BVH structure and quality
• Performance analysis: Understand query performance characteristics

Performance

The BVH provides O(log n) query performance for most spatial operations, where n is the number of sub-shapes. For compounds with many shapes (100+), the BVH provides dramatic speedups compared to naive linear searches.

Example

use parry3d::math::Isometry;
use parry3d::bounding_volume::Aabb;
use nalgebra::Point3;

let shapes = vec![
    (Isometry::translation(-3.0, 0.0, 0.0), SharedShape::new(Ball::new(0.5))),
    (Isometry::translation(0.0, 0.0, 0.0), SharedShape::new(Ball::new(0.5))),
    (Isometry::translation(3.0, 0.0, 0.0), SharedShape::new(Ball::new(0.5))),
];

let compound = Compound::new(shapes);
let bvh = compound.bvh();

// The BVH provides efficient hierarchical organization
assert_eq!(bvh.leaf_count(), 3);
println!("BVH root AABB: {:?}", bvh.root_aabb());

Example: Accessing BVH for Custom Queries

use parry3d::math::Isometry;

let mut shapes = vec![];
for i in 0..10 {
    let x = i as f32 * 2.0;
    shapes.push((
        Isometry::translation(x, 0.0, 0.0),
        SharedShape::new(Ball::new(0.5))
    ));
}

let compound = Compound::new(shapes);
let bvh = compound.bvh();

// The BVH organizes 10 shapes hierarchically
assert_eq!(bvh.leaf_count(), 10);
assert_eq!(compound.shapes().len(), 10);

// Access the root AABB which bounds all shapes
let root_aabb = bvh.root_aabb();
println!("Root AABB spans from {:?} to {:?}", root_aabb.mins, root_aabb.maxs);

Trait Implementations

impl Clone for Compound

fn clone(&self) -> Compound

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl CompositeShape for Compound

fn map_part_at( &self, shape_id: u32, f: &mut dyn FnMut(Option<&Isometry<f32>>, &dyn Shape, Option<&dyn NormalConstraints>), )

Applies a function to one sub-shape of this composite shape.

fn bvh(&self) -> &Bvh

Gets the acceleration structure of the composite shape.

impl Debug for Compound

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

Formats the value using the given formatter.

impl PointQuery for Compound

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 contains_local_point(&self, point: &Point<f32>) -> bool

Tests if the given point is inside of self.

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 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 RayCast for Compound

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 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 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 Compound

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 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_composite_shape(&self) -> Option<&dyn CompositeShape>

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 is_convex(&self) -> bool

Is this shape known to be convex?

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 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 TypedCompositeShape for Compound

type PartShape = dyn Shape

type PartNormalConstraints = ()

fn map_typed_part_at<T>( &self, i: u32, f: impl FnMut(Option<&Isometry<f32>>, &Self::PartShape, Option<&Self::PartNormalConstraints>) -> T, ) -> Option<T>

fn map_untyped_part_at<T>( &self, i: u32, f: impl FnMut(Option<&Isometry<f32>>, &Self::PartShape, Option<&dyn NormalConstraints>) -> T, ) -> Option<T>