Struct Segment

#[repr(C)]
pub struct Segment {
    pub a: Point<f32>,
    pub b: Point<f32>,
}

A line segment shape.

A segment is the simplest 1D shape, defined by two endpoints. It represents a straight line between two points with no thickness or volume.

Structure

• a: The first endpoint
• b: The second endpoint
• Direction: Points from a toward b

Properties

• 1-dimensional: Has length but no width or volume
• Convex: Always convex
• No volume: Mass properties are zero
• Simple: Very fast collision detection

Use Cases

Segments are commonly used for:

• Thin objects: Ropes, wires, laser beams
• Skeletal animation: Bone connections
• Path representation: Straight-line paths
• Geometry building block: Part of polylines and meshes
• Testing: Simple shape for debugging

Note

For shapes with thickness, consider using Capsule instead, which is a segment with a radius (rounded cylinder).

Example

use parry3d::shape::Segment;
use nalgebra::Point3;

// Create a horizontal segment of length 5
let a = Point3::origin();
let b = Point3::new(5.0, 0.0, 0.0);
let segment = Segment::new(a, b);

assert_eq!(segment.length(), 5.0);
assert_eq!(segment.a, a);
assert_eq!(segment.b, b);

Fields

a: Point<f32>

The first endpoint of the segment.

b: Point<f32>

The second endpoint of the segment.

Implementations

impl Segment

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

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

pub fn local_aabb(&self) -> Aabb

Computes the local-space Aabb of this segment.

impl Segment

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

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

pub fn local_bounding_sphere(&self) -> BoundingSphere

Computes the local-space bounding sphere of this segment.

impl Segment

pub fn canonical_split( &self, axis: usize, bias: f32, epsilon: f32, ) -> SplitResult<Self>

Splits this segment along the given canonical axis.

This will split the segment by a plane with a normal with it’s axis-th component set to 1. The splitting plane is shifted wrt. the origin by the bias (i.e. it passes through the point equal to normal * bias).

Result

Returns the result of the split. The first shape returned is the piece lying on the negative half-space delimited by the splitting plane. The second shape returned is the piece lying on the positive half-space delimited by the splitting plane.

pub fn local_split( &self, local_axis: &UnitVector<f32>, bias: f32, epsilon: f32, ) -> SplitResult<Self>

Splits this segment by a plane identified by its normal local_axis and the bias (i.e. the plane passes through the point equal to normal * bias).

pub fn local_split_and_get_intersection( &self, local_axis: &UnitVector<f32>, bias: f32, epsilon: f32, ) -> (SplitResult<Self>, Option<(Point<f32>, f32)>)

Split a segment with a plane.

This returns the result of the splitting operation, as well as the intersection point (and barycentric coordinate of this point) with the plane. The intersection point is None if the plane is parallel or near-parallel to the segment.

impl Segment

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

Creates a new segment from two endpoints.

Arguments

• a - The first endpoint
• b - The second endpoint

Example

use parry3d::shape::Segment;
use nalgebra::Point3;

let segment = Segment::new(
    Point3::origin(),
    Point3::new(5.0, 0.0, 0.0)
);
assert_eq!(segment.length(), 5.0);

pub fn from_array(arr: &[Point<f32>; 2]) -> &Segment

Creates a segment reference from an array of two points.

This is a zero-cost conversion using memory transmutation.

Example

use parry3d::shape::Segment;
use nalgebra::Point3;

let points = [Point3::origin(), Point3::new(1.0, 0.0, 0.0)];
let segment = Segment::from_array(&points);
assert_eq!(segment.a, points[0]);
assert_eq!(segment.b, points[1]);

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

Computes a scaled version of this segment.

Each endpoint is scaled component-wise by the scale vector.

Arguments

• scale - The scaling factors for each axis

Example

use parry3d::shape::Segment;
use nalgebra::{Point3, Vector3};

let segment = Segment::new(
    Point3::new(1.0, 2.0, 3.0),
    Point3::new(4.0, 5.0, 6.0)
);

let scaled = segment.scaled(&Vector3::new(2.0, 2.0, 2.0));
assert_eq!(scaled.a, Point3::new(2.0, 4.0, 6.0));
assert_eq!(scaled.b, Point3::new(8.0, 10.0, 12.0));

pub fn scaled_direction(&self) -> Vector<f32>

Returns the direction vector of this segment scaled by its length.

This is equivalent to b - a and points from a toward b. The magnitude equals the segment length.

Example

use parry3d::shape::Segment;
use nalgebra::{Point3, Vector3};

let segment = Segment::new(
    Point3::origin(),
    Point3::new(3.0, 4.0, 0.0)
);

let dir = segment.scaled_direction();
assert_eq!(dir, Vector3::new(3.0, 4.0, 0.0));
assert_eq!(dir.norm(), 5.0); // Length of the segment

pub fn length(&self) -> f32

Returns the length of this segment.

Example

use parry3d::shape::Segment;
use nalgebra::Point3;

// 3-4-5 right triangle
let segment = Segment::new(
    Point3::origin(),
    Point3::new(3.0, 4.0, 0.0)
);
assert_eq!(segment.length(), 5.0);

pub fn swap(&mut self)

Swaps the two endpoints of this segment.

After swapping, a becomes b and b becomes a.

Example

use parry3d::shape::Segment;
use nalgebra::Point3;

let mut segment = Segment::new(
    Point3::new(1.0, 0.0, 0.0),
    Point3::new(5.0, 0.0, 0.0)
);

segment.swap();
assert_eq!(segment.a, Point3::new(5.0, 0.0, 0.0));
assert_eq!(segment.b, Point3::new(1.0, 0.0, 0.0));

pub fn direction(&self) -> Option<Unit<Vector<f32>>>

Returns the unit direction vector of this segment.

Points from a toward b with length 1.0.

Returns

• Some(direction) - The normalized direction if the segment has non-zero length
• None - If both endpoints are equal (degenerate segment)

Example

use parry3d::shape::Segment;
use nalgebra::{Point3, Vector3};

let segment = Segment::new(
    Point3::origin(),
    Point3::new(3.0, 4.0, 0.0)
);

if let Some(dir) = segment.direction() {
    // Direction is normalized
    assert!((dir.norm() - 1.0).abs() < 1e-6);
    // Points from a to b
    assert_eq!(*dir, Vector3::new(0.6, 0.8, 0.0));
}

// Degenerate segment (zero length)
let degenerate = Segment::new(Point3::origin(), Point3::origin());
assert!(degenerate.direction().is_none());

pub fn scaled_normal(&self) -> Vector<f32>

In 2D, the not-normalized counterclockwise normal of this segment.

pub fn normal(&self) -> Option<Unit<Vector<f32>>>

In 2D, the normalized counterclockwise normal of this segment.

pub fn transformed(&self, m: &Isometry<f32>) -> Self

Applies the isometry m to the vertices of this segment and returns the resulting segment.

pub fn point_at(&self, location: &SegmentPointLocation) -> Point<f32>

Computes the point at the given location.

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

The normal of the given feature of this shape.

Trait Implementations

impl Clone for Segment

fn clone(&self) -> Segment

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Segment

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

Formats the value using the given formatter.

impl From<[OPoint<f32, Const<2>>; 2]> for Segment

fn from(arr: [Point<f32>; 2]) -> Self

Converts to this type from the input type.

impl From<Segment> for PolygonalFeature

fn from(seg: Segment) -> Self

Converts to this type from the input type.

impl PartialEq for Segment

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

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 PointQueryWithLocation for Segment

type Location = SegmentPointLocation

Additional shape-specific projection information

fn project_local_point_and_get_location( &self, pt: &Point<f32>, _: bool, ) -> (PointProjection, Self::Location)

Projects a point on self.

fn project_point_and_get_location( &self, m: &Isometry<f32>, pt: &Point<f32>, solid: bool, ) -> (PointProjection, Self::Location)

Projects a point on self transformed by m.

fn project_local_point_and_get_location_with_max_dist( &self, pt: &Point<f32>, solid: bool, max_dist: f32, ) -> Option<(PointProjection, Self::Location)>

Projects a point on self, with a maximum projection distance.

fn project_point_and_get_location_with_max_dist( &self, m: &Isometry<f32>, pt: &Point<f32>, solid: bool, max_dist: f32, ) -> Option<(PointProjection, Self::Location)>

Projects a point on self transformed by m, with a maximum projection distance.

impl PolygonalFeatureMap for Segment

fn local_support_feature( &self, _: &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 Segment

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 Segment

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

fn ccd_angular_thickness(&self) -> f32

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

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 Segment

impl StructuralPartialEq for Segment