Struct Capsule

#[repr(C)]
pub struct Capsule {
    pub segment: Segment,
    pub radius: f32,
}

A capsule shape, also known as a pill or capped cylinder.

A capsule is defined by a line segment (its central axis) and a radius. It can be visualized as a cylinder with hemispherical (2D: semicircular) caps on both ends. This makes it perfect for representing elongated round objects.

Structure

• Segment: The central axis from point a to point b
• Radius: The thickness around the segment
• In 2D: Looks like a rounded rectangle or “stadium” shape
• In 3D: Looks like a cylinder with spherical caps (a pill)

Properties

• Convex: Yes, capsules are always convex
• Smooth: Completely smooth surface (no edges or corners)
• Support mapping: Efficient (constant time)
• Rolling: Excellent for objects that need to roll smoothly

Use Cases

Capsules are ideal for:

• Characters and humanoid figures (torso, limbs)
• Pills, medicine capsules
• Elongated projectiles (missiles, torpedoes)
• Smooth rolling objects
• Any object that’s “cylinder-like” but needs smooth collision at ends

Advantages Over Cylinders

• No sharp edges: Smoother collision response
• Better for characters: More natural movement and rotation
• Simpler collision detection: Easier to compute contacts than cylinders

Example

use parry3d::shape::Capsule;
use nalgebra::Point3;

// Create a vertical capsule (aligned with Y axis)
// Half-height of 2.0 means the segment is 4.0 units long
let capsule = Capsule::new_y(2.0, 0.5);
assert_eq!(capsule.radius, 0.5);
assert_eq!(capsule.height(), 4.0);

// Create a custom capsule between two points
let a = Point3::origin();
let b = Point3::new(3.0, 4.0, 0.0);
let custom = Capsule::new(a, b, 1.0);
assert_eq!(custom.height(), 5.0); // Distance from a to b

Fields

segment: Segment

The line segment forming the capsule’s central axis.

The capsule extends from segment.a to segment.b, with hemispherical caps centered at each endpoint.

radius: f32

The radius of the capsule.

This is the distance from the central axis to the surface. Must be positive. The total “thickness” of the capsule is 2 * radius.

Implementations

impl Capsule

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

The axis-aligned bounding box of this capsule.

pub fn local_aabb(&self) -> Aabb

The axis-aligned bounding box of this capsule.

impl Capsule

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

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

pub fn local_bounding_sphere(&self) -> BoundingSphere

Computes the world-space bounding sphere of this capsule.

impl Capsule

pub fn new_x(half_height: f32, radius: f32) -> Self

Creates a new capsule aligned with the X axis.

The capsule is centered at the origin and extends along the X axis.

Arguments

• half_height - Half the length of the central segment (total length = 2 * half_height)
• radius - The radius of the capsule

Example

use parry3d::shape::Capsule;

// Create a capsule extending 6 units along X axis (3 units in each direction)
// with radius 0.5
let capsule = Capsule::new_x(3.0, 0.5);
assert_eq!(capsule.height(), 6.0);
assert_eq!(capsule.radius, 0.5);

// The center is at the origin
let center = capsule.center();
assert!(center.coords.norm() < 1e-6);

pub fn new_y(half_height: f32, radius: f32) -> Self

Creates a new capsule aligned with the Y axis.

The capsule is centered at the origin and extends along the Y axis. This is the most common orientation for character capsules (standing upright).

Arguments

• half_height - Half the length of the central segment
• radius - The radius of the capsule

Example

use parry3d::shape::Capsule;

// Create a typical character capsule: 2 units tall with 0.3 radius
let character = Capsule::new_y(1.0, 0.3);
assert_eq!(character.height(), 2.0);
assert_eq!(character.radius, 0.3);

// Total height including the spherical caps: 2.0 + 2 * 0.3 = 2.6

pub fn new_z(half_height: f32, radius: f32) -> Self

Creates a new capsule aligned with the Z axis.

The capsule is centered at the origin and extends along the Z axis.

Arguments

• half_height - Half the length of the central segment
• radius - The radius of the capsule

Example

use parry3d::shape::Capsule;

// Create a capsule for a torpedo extending along Z axis
let torpedo = Capsule::new_z(5.0, 0.4);
assert_eq!(torpedo.height(), 10.0);
assert_eq!(torpedo.radius, 0.4);

pub fn new(a: Point<f32>, b: Point<f32>, radius: f32) -> Self

Creates a new capsule with custom endpoints and radius.

This is the most flexible constructor, allowing you to create a capsule with any orientation and position.

Arguments

• a - The first endpoint of the central segment
• b - The second endpoint of the central segment
• radius - The radius of the capsule

Example

use parry3d::shape::Capsule;
use nalgebra::Point3;

// Create a diagonal capsule
let a = Point3::origin();
let b = Point3::new(3.0, 4.0, 0.0);
let capsule = Capsule::new(a, b, 0.5);

// Height is the distance between a and b
assert_eq!(capsule.height(), 5.0); // 3-4-5 triangle

// Center is the midpoint
let center = capsule.center();
assert_eq!(center, Point3::new(1.5, 2.0, 0.0));

pub fn height(&self) -> f32

Returns the length of the capsule’s central segment.

This is the distance between the two endpoints, not including the hemispherical caps. The total length of the capsule including caps is height() + 2 * radius.

Example

use parry3d::shape::Capsule;

let capsule = Capsule::new_y(3.0, 0.5);

// Height of the central segment
assert_eq!(capsule.height(), 6.0);

// Total length including spherical caps
let total_length = capsule.height() + 2.0 * capsule.radius;
assert_eq!(total_length, 7.0);

pub fn half_height(&self) -> f32

Returns half the length of the capsule’s central segment.

This is equivalent to height() / 2.0.

Example

use parry3d::shape::Capsule;

let capsule = Capsule::new_y(3.0, 0.5);
assert_eq!(capsule.half_height(), 3.0);
assert_eq!(capsule.half_height(), capsule.height() / 2.0);

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

Returns the center point of the capsule.

This is the midpoint between the two endpoints of the central segment.

Example

use parry3d::shape::Capsule;
use nalgebra::Point3;

let a = Point3::new(-2.0, 0.0, 0.0);
let b = Point3::new(4.0, 0.0, 0.0);
let capsule = Capsule::new(a, b, 1.0);

let center = capsule.center();
assert_eq!(center, Point3::new(1.0, 0.0, 0.0));

pub fn transform_by(&self, pos: &Isometry<f32>) -> Self

Creates a new capsule equal to self with all its endpoints transformed by pos.

This applies a rigid transformation (translation and rotation) to the capsule.

Arguments

• pos - The isometry (rigid transformation) to apply

Example

use parry3d::shape::Capsule;
use nalgebra::{Isometry3, Vector3};

let capsule = Capsule::new_y(1.0, 0.5);

// Translate the capsule 5 units along X axis
let transform = Isometry3::translation(5.0, 0.0, 0.0);
let transformed = capsule.transform_by(&transform);

// Center moved by 5 units
assert_eq!(transformed.center().x, 5.0);
// Radius unchanged
assert_eq!(transformed.radius, 0.5);

pub fn canonical_transform(&self) -> Isometry<f32>

The transformation such that t * Y is collinear with b - a and t * origin equals the capsule’s center.

pub fn rotation_wrt_y(&self) -> Rotation<f32>

The rotation r such that r * Y is collinear with b - a.

pub fn transform_wrt_y(&self) -> Isometry<f32>

The transform t such that t * Y is collinear with b - a and such that t * origin = (b + a) / 2.0.

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

Computes a scaled version of this capsule.

If the scaling factor is non-uniform, then it can’t be represented as capsule. Instead, a convex polygon approximation (with nsubdivs subdivisions) is returned. Returns None if that approximation had degenerate normals (for example if the scaling factor along one axis is zero).

impl Capsule

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

Outlines this capsule’s shape using polylines.

impl Capsule

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

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

Trait Implementations

impl Clone for Capsule

fn clone(&self) -> Capsule

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Capsule

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

Formats the value using the given formatter.

impl PointQuery for Capsule

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

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 Capsule

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 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 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 SupportMap for Capsule

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 Capsule