Struct Ball

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

A ball shape, also known as a sphere in 3D or a circle in 2D.

A ball is one of the simplest shapes in collision detection, defined by a single parameter: its radius. The center of the ball is always at the origin of its local coordinate system.

Properties

• In 2D: Represents a circle (all points at distance radius from the center)
• In 3D: Represents a sphere (all points at distance radius from the center)
• Convex: Yes, balls are always convex shapes
• Support mapping: Extremely efficient (constant time)

Use Cases

Balls are ideal for:

• Projectiles (bullets, cannonballs)
• Spherical objects (planets, marbles, balls)
• Bounding volumes for fast collision detection
• Dynamic objects that need to roll

Example

use parry3d::shape::Ball;
use nalgebra::Vector3;

// Create a ball with radius 2.0
let ball = Ball::new(2.0);
assert_eq!(ball.radius, 2.0);

Fields

radius: f32

The radius of the ball.

This must be a positive value. A radius of 0.0 is valid but represents a degenerate ball (a single point).

Implementations

impl Ball

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

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

pub fn local_aabb(&self) -> Aabb

Computes the local-space Aabb of this ball.

impl Ball

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

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

pub fn local_bounding_sphere(&self) -> BoundingSphere

Computes the local-space Aabb of this ball.

impl Ball

pub fn new(radius: f32) -> Ball

Creates a new ball with the given radius.

Arguments

• radius - The radius of the ball. Should be positive.

Example

use parry3d::shape::Ball;

// Create a ball with radius 5.0
let ball = Ball::new(5.0);
assert_eq!(ball.radius, 5.0);

// You can also create very small balls
let tiny_ball = Ball::new(0.001);
assert_eq!(tiny_ball.radius, 0.001);

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

Computes a scaled version of this ball.

Uniform scaling (same scale factor on all axes) produces another ball. Non-uniform scaling (different scale factors) produces an ellipsoid, which is approximated as a convex polyhedron.

Arguments

• scale - The scaling factors for each axis (x, y, z in 3D)
• nsubdivs - Number of subdivisions for polyhedron approximation when scaling is non-uniform

Returns

• Some(Either::Left(Ball)) - If scaling is uniform, returns a scaled ball
• Some(Either::Right(ConvexPolyhedron)) - If scaling is non-uniform, returns a polyhedron approximation
• None - If the approximation failed (e.g., zero scaling on an axis)

Example

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

let ball = Ball::new(5.0);

// Uniform scaling: produces another ball
let uniform_scale = Vector3::new(2.0, 2.0, 2.0);
if let Some(Either::Left(scaled_ball)) = ball.scaled(&uniform_scale, 10) {
    assert_eq!(scaled_ball.radius, 10.0); // 5.0 * 2.0
}

// Non-uniform scaling: produces a polyhedron (ellipsoid approximation)
let non_uniform_scale = Vector3::new(2.0, 1.0, 1.5);
if let Some(Either::Right(polyhedron)) = ball.scaled(&non_uniform_scale, 10) {
    // The polyhedron approximates an ellipsoid
    assert!(polyhedron.points().len() > 0);
}

impl Ball

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

Outlines this ball’s shape using polylines.

impl Ball

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

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

Trait Implementations

impl Clone for Ball

fn clone(&self) -> Ball

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Ball

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

Formats the value using the given formatter.

impl PartialEq for Ball

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

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

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 Ball

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

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

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 ccd_thickness(&self) -> f32

fn ccd_angular_thickness(&self) -> f32

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 as_support_map(&self) -> Option<&dyn SupportMap>

Converts this shape into its support mapping, if it has 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 as_polygonal_feature_map(&self) -> Option<(&dyn PolygonalFeatureMap, f32)>

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

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 Ball

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

Evaluates the support function of this shape transformed by transform.

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

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

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).

impl Copy for Ball

impl StructuralPartialEq for Ball