Struct Cylinder

#[repr(C)]
pub struct Cylinder {
    pub half_height: f32,
    pub radius: f32,
}

A 3D cylinder shape with axis aligned along the Y axis.

A cylinder is a shape with circular cross-sections perpendicular to its axis. In Parry, cylinders are always aligned with the Y axis in their local coordinate system and centered at the origin.

Structure

• Axis: Always aligned with Y axis (up/down)
• half_height: Half the length along the Y axis
• radius: The radius of the circular cross-section
• Height: Total height = 2 * half_height

Properties

• 3D only: Only available with the dim3 feature
• Convex: Yes, cylinders are convex shapes
• Flat caps: The top and bottom are flat circles (not rounded)
• Sharp edges: The rim where cap meets side is a sharp edge

vs Capsule

If you need rounded ends instead of flat caps, use Capsule:

• Cylinder: Flat circular caps, sharp edges at rims
• Capsule: Hemispherical caps, completely smooth (no edges)
• Capsule: Better for characters and rolling objects
• Cylinder: Better for columns, cans, pipes

Use Cases

• Pillars and columns
• Cans and barrels
• Wheels and disks
• Pipes and tubes
• Any object with flat circular ends

Example

use parry3d::shape::Cylinder;

// Create a cylinder: radius 2.0, total height 10.0
let cylinder = Cylinder::new(5.0, 2.0);

assert_eq!(cylinder.half_height, 5.0);
assert_eq!(cylinder.radius, 2.0);

// Total height is 2 * half_height
let total_height = cylinder.half_height * 2.0;
assert_eq!(total_height, 10.0);

Fields

half_height: f32

Half the length of the cylinder along the Y axis.

The cylinder extends from -half_height to +half_height along Y. Total height = 2 * half_height. Must be positive.

radius: f32

The radius of the circular cross-section.

All points on the cylindrical surface are at this distance from the Y axis. Must be positive.

Implementations

impl Cylinder

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

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

pub fn local_aabb(&self) -> Aabb

Computes the local-space Aabb of this cylinder.

impl Cylinder

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

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

pub fn local_bounding_sphere(&self) -> BoundingSphere

Computes the local-space bounding sphere of this cylinder.

impl Cylinder

pub fn new(half_height: f32, radius: f32) -> Cylinder

Creates a new cylinder aligned with the Y axis.

Arguments

• half_height - Half the total height along the Y axis
• radius - The radius of the circular cross-section

Panics

Panics if half_height or radius is not positive.

Example

use parry3d::shape::Cylinder;

// Create a cylinder with radius 3.0 and height 8.0
let cylinder = Cylinder::new(4.0, 3.0);

assert_eq!(cylinder.half_height, 4.0);
assert_eq!(cylinder.radius, 3.0);

// The cylinder:
// - Extends from y = -4.0 to y = 4.0 (total height 8.0)
// - Has circular cross-section with radius 3.0 in the XZ plane

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

Computes a scaled version of this cylinder.

Scaling a cylinder can produce different results depending on the scale factors:

• Uniform scaling (all axes equal): Produces another cylinder
• Y different from X/Z: Produces another cylinder (if X == Z)
• Non-uniform X/Z: Produces an elliptical cylinder approximated as a convex mesh

Arguments

• scale - Scaling factors for X, Y, Z axes
• nsubdivs - Number of subdivisions for mesh approximation (if needed)

Returns

• Some(Either::Left(Cylinder)) - If X and Z scales are equal
• Some(Either::Right(ConvexPolyhedron)) - If X and Z scales differ (elliptical)
• None - If mesh approximation failed (e.g., zero scale on an axis)

Example

use parry3d::shape::Cylinder;
use nalgebra::Vector3;
use either::Either;

let cylinder = Cylinder::new(2.0, 1.0);

// Uniform scaling: produces a larger cylinder
let scale1 = Vector3::new(2.0, 2.0, 2.0);
if let Some(Either::Left(scaled)) = cylinder.scaled(&scale1, 20) {
    assert_eq!(scaled.radius, 2.0);      // 1.0 * 2.0
    assert_eq!(scaled.half_height, 4.0); // 2.0 * 2.0
}

// Different Y scale: still a cylinder
let scale2 = Vector3::new(1.5, 3.0, 1.5);
if let Some(Either::Left(scaled)) = cylinder.scaled(&scale2, 20) {
    assert_eq!(scaled.radius, 1.5);      // 1.0 * 1.5
    assert_eq!(scaled.half_height, 6.0); // 2.0 * 3.0
}

// Non-uniform X/Z: produces elliptical cylinder (mesh approximation)
let scale3 = Vector3::new(2.0, 1.0, 1.0);
if let Some(Either::Right(polyhedron)) = cylinder.scaled(&scale3, 20) {
    // Result is a convex mesh approximating an elliptical cylinder
    assert!(polyhedron.points().len() > 0);
}

impl Cylinder

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

Outlines this cylinder’s shape using polylines.

impl Cylinder

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

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

Trait Implementations

impl Clone for Cylinder

fn clone(&self) -> Cylinder

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Cylinder

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

Formats the value using the given formatter.

impl PartialEq for Cylinder

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

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 PolygonalFeatureMap for Cylinder

fn local_support_feature( &self, dir: &Unit<Vector<f32>>, out_features: &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 Cylinder

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 Cylinder

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 Cylinder

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 Cylinder

impl StructuralPartialEq for Cylinder