Struct Cuboid

#[repr(C)]
pub struct Cuboid {
    pub half_extents: Vector<f32>,
}

A cuboid shape, also known as a box or rectangle.

A cuboid is defined by its half-extents, which are half the width, height (and depth in 3D) along each axis. The cuboid is always axis-aligned in its local coordinate system and centered at the origin.

Properties

• In 2D: Represents a rectangle with dimensions 2 * half_extents.x by 2 * half_extents.y
• In 3D: Represents a box with dimensions 2 * half_extents.x/y/z
• Convex: Yes, cuboids are always convex shapes
• Axis-aligned: In local space, yes (but can be rotated via transformation)

Why Half-Extents?

Using half-extents instead of full dimensions makes many calculations simpler and more efficient. For example, checking if a point is inside a cuboid becomes: abs(point.x) <= half_extents.x && abs(point.y) <= half_extents.y

Use Cases

Cuboids are ideal for:

• Boxes, crates, and containers
• Walls, floors, and platforms
• Simple collision bounds for complex objects
• AABB (Axis-Aligned Bounding Box) representations

Example

use parry3d::shape::Cuboid;
use nalgebra::Vector3;

// Create a box that is 4 units wide, 2 units tall, and 6 units deep
// (half-extents are half of each dimension)
let cuboid = Cuboid::new(Vector3::new(2.0, 1.0, 3.0));

assert_eq!(cuboid.half_extents.x, 2.0);
assert_eq!(cuboid.half_extents.y, 1.0);
assert_eq!(cuboid.half_extents.z, 3.0);

// Full dimensions would be:
// width = 4.0, height = 2.0, depth = 6.0

Fields

half_extents: Vector<f32>

The half-extents of the cuboid along each axis.

Each component represents half the dimension along that axis:

• half_extents.x: Half the width
• half_extents.y: Half the height
• half_extents.z: Half the depth (3D only)

All components should be positive.

Implementations

impl Cuboid

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

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

pub fn local_aabb(&self) -> Aabb

Computes the local-space Aabb of this cuboid.

impl Cuboid

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

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

pub fn local_bounding_sphere(&self) -> BoundingSphere

Computes the local-space bounding sphere of this cuboid.

impl Cuboid

pub fn new(half_extents: Vector<f32>) -> Cuboid

Creates a new cuboid from its half-extents.

Half-extents represent half the width along each axis. To create a cuboid with full dimensions (width, height, depth), divide each by 2.

Arguments

• half_extents - Half the dimensions along each axis. All components should be positive.

Example

use parry3d::shape::Cuboid;
use nalgebra::Vector3;

// Create a 10x6x4 box (full dimensions)
let cuboid = Cuboid::new(Vector3::new(5.0, 3.0, 2.0));

// Verify the half-extents
assert_eq!(cuboid.half_extents.x, 5.0);
assert_eq!(cuboid.half_extents.y, 3.0);
assert_eq!(cuboid.half_extents.z, 2.0);

// In 2D:
use parry2d::shape::Cuboid;
use nalgebra::Vector2;

// Create a 20x10 rectangle
let rect = Cuboid::new(Vector2::new(10.0, 5.0));
assert_eq!(rect.half_extents.x, 10.0);
assert_eq!(rect.half_extents.y, 5.0);

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

Computes a scaled version of this cuboid.

Each dimension is multiplied by the corresponding component of the scale vector. Unlike balls, cuboids can be scaled non-uniformly (different scale factors per axis) and still remain valid cuboids.

Arguments

• scale - The scaling factors for each axis

Returns

A new cuboid with scaled dimensions

Example

use parry3d::shape::Cuboid;
use nalgebra::Vector3;

let cuboid = Cuboid::new(Vector3::new(1.0, 2.0, 3.0));

// Uniform scaling: double all dimensions
let scaled_uniform = cuboid.scaled(&Vector3::new(2.0, 2.0, 2.0));
assert_eq!(scaled_uniform.half_extents, Vector3::new(2.0, 4.0, 6.0));

// Non-uniform scaling: different scale per axis
let scaled_non_uniform = cuboid.scaled(&Vector3::new(2.0, 1.0, 0.5));
assert_eq!(scaled_non_uniform.half_extents, Vector3::new(2.0, 2.0, 1.5));

pub fn support_feature(&self, local_dir: Vector<f32>) -> PolygonalFeature

Return the face of this cuboid with a normal that maximizes the dot product with local_dir.

pub fn local_support_edge_segment(&self, local_dir: Vector<f32>) -> Segment

Return the edge segment of this cuboid with a normal cone containing a direction that that maximizes the dot product with local_dir.

pub fn support_face(&self, local_dir: Vector<f32>) -> PolygonalFeature

Computes the face with a normal that maximizes the dot-product with local_dir.

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

The normal of the given feature of this shape.

impl Cuboid

pub fn to_outline(&self) -> (Vec<Point<f32>>, Vec<[u32; 2]>)

Outlines this cuboid’s shape using polylines.

impl Cuboid

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

Discretize the boundary of this cuboid as a triangle-mesh.

Trait Implementations

impl Clone for Cuboid

fn clone(&self) -> Cuboid

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Cuboid

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

Formats the value using the given formatter.

impl From<Cuboid> for TriMesh

fn from(cuboid: Cuboid) -> Self

Converts to this type from the input type.

impl PartialEq for Cuboid

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

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 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_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 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 Cuboid

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 Cuboid

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 Cuboid

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 Cuboid

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 Copy for Cuboid

impl StructuralPartialEq for Cuboid