Enum FeatureId

pub enum FeatureId {
    Vertex(u32),
    Edge(u32),
    Face(u32),
    Unknown,
}

An identifier of a geometric feature (vertex, edge, or face) of a shape.

Feature IDs are used throughout Parry to identify specific geometric features on shapes during collision detection, contact generation, and other geometric queries. They allow algorithms to track which parts of shapes are interacting, which is essential for:

• Contact manifold generation: Tracking persistent contact points between frames
• Collision response: Determining which features are colliding
• Debug visualization: Highlighting specific geometric elements
• Feature-based queries: Retrieving geometric data for specific shape features

Feature Types

• Vertex: A corner point of the shape (0-dimensional feature)
• Edge: A line segment connecting two vertices (1-dimensional feature, 3D only)
• Face: A flat surface bounded by edges (2-dimensional feature)
• Unknown: Used when the feature type cannot be determined or is not applicable

Shape-Specific Identifiers

The numeric ID within each feature type is shape-dependent. For example:

• For a cuboid, vertex IDs might range from 0-7 (8 corners)
• For a triangle, face ID 0 typically refers to the triangle itself
• For composite shapes, IDs might encode both the sub-shape and the feature within it

The exact meaning of these IDs depends on the shape’s internal representation, but they are guaranteed to allow efficient retrieval of the feature’s geometric information.

Examples

Basic usage of feature IDs in 2D:

use parry2d::shape::FeatureId;

// Create a vertex feature identifier
let vertex_id = FeatureId::Vertex(5);
assert_eq!(vertex_id.unwrap_vertex(), 5);

// Create a face feature identifier (in 2D, faces are edges of the polygon)
let face_id = FeatureId::Face(2);
assert_eq!(face_id.unwrap_face(), 2);

// Unknown feature (used as default)
let unknown = FeatureId::Unknown;
assert_eq!(unknown, FeatureId::default());

Basic usage of feature IDs in 3D:

use parry3d::shape::FeatureId;

// Create a vertex feature identifier
let vertex_id = FeatureId::Vertex(5);
assert_eq!(vertex_id.unwrap_vertex(), 5);

// Create an edge feature identifier (only available in 3D)
let edge_id = FeatureId::Edge(3);
assert_eq!(edge_id.unwrap_edge(), 3);

// Create a face feature identifier
let face_id = FeatureId::Face(2);
assert_eq!(face_id.unwrap_face(), 2);

// Unknown feature (used as default)
let unknown = FeatureId::Unknown;
assert_eq!(unknown, FeatureId::default());

Pattern matching on feature types in 3D:

use parry3d::shape::FeatureId;

fn describe_feature(feature: FeatureId) -> String {
    match feature {
        FeatureId::Vertex(id) => format!("Vertex #{}", id),
        FeatureId::Edge(id) => format!("Edge #{}", id),
        FeatureId::Face(id) => format!("Face #{}", id),
        FeatureId::Unknown => "Unknown feature".to_string(),
    }
}

assert_eq!(describe_feature(FeatureId::Vertex(3)), "Vertex #3");
assert_eq!(describe_feature(FeatureId::Edge(5)), "Edge #5");
assert_eq!(describe_feature(FeatureId::Face(1)), "Face #1");

2D vs 3D

In 2D mode (dim2 feature), the Edge variant is not available since edges in 2D are effectively the same as faces (line segments). In 2D:

• Vertices represent corner points
• Faces represent edges of the polygon

In 3D mode (dim3 feature), all three types are available:

• Vertices are 0D points
• Edges are 1D line segments
• Faces are 2D polygons

Variants

Vertex(u32)

Shape-dependent identifier of a vertex (0-dimensional corner point).

The numeric ID is specific to each shape type and allows efficient lookup of the vertex’s position and other geometric properties.

Edge(u32)

Shape-dependent identifier of an edge (1-dimensional line segment).

Available only in 3D mode. The numeric ID is specific to each shape type and allows efficient lookup of the edge’s endpoints and direction.

Face(u32)

Shape-dependent identifier of a face (2-dimensional flat surface).

In 2D, faces represent the edges of polygons (line segments). In 3D, faces represent polygonal surfaces. The numeric ID is specific to each shape type and allows efficient lookup of the face’s vertices, normal vector, and other properties.

Unknown

Unknown or unidentified feature.

Used as a default value or when the specific feature cannot be determined. This variant should generally be avoided in production code.

Implementations

impl FeatureId

pub fn unwrap_vertex(self) -> u32

Retrieves the numeric ID if this is a vertex feature.

Panics

Panics if the feature is not a vertex (i.e., if it’s an edge, face, or unknown).

Examples

use parry2d::shape::FeatureId;

let vertex = FeatureId::Vertex(42);
assert_eq!(vertex.unwrap_vertex(), 42);

This will panic:

use parry2d::shape::FeatureId;

let face = FeatureId::Face(5);
face.unwrap_vertex(); // Panics!
use parry2d_f64::shape::FeatureId;

let face = FeatureId::Face(5);
face.unwrap_vertex(); // Panics!
use parry3d::shape::FeatureId;

let face = FeatureId::Face(5);
face.unwrap_vertex(); // Panics!
use parry3d_f64::shape::FeatureId;

let face = FeatureId::Face(5);
face.unwrap_vertex(); // Panics!

pub fn unwrap_edge(self) -> u32

Retrieves the numeric ID if this is an edge feature.

Available only in 3D mode (dim3 feature).

Panics

Panics if the feature is not an edge (i.e., if it’s a vertex, face, or unknown).

Examples

use parry3d::shape::FeatureId;

let edge = FeatureId::Edge(7);
assert_eq!(edge.unwrap_edge(), 7);

This will panic:

use parry3d::shape::FeatureId;

let vertex = FeatureId::Vertex(3);
vertex.unwrap_edge(); // Panics!

pub fn unwrap_face(self) -> u32

Retrieves the numeric ID if this is a face feature.

Panics

Panics if the feature is not a face (i.e., if it’s a vertex, edge, or unknown).

Examples

use parry2d::shape::FeatureId;

let face = FeatureId::Face(12);
assert_eq!(face.unwrap_face(), 12);

This will panic:

use parry2d::shape::FeatureId;

let vertex = FeatureId::Vertex(0);
vertex.unwrap_face(); // Panics!
use parry2d_f64::shape::FeatureId;

let vertex = FeatureId::Vertex(0);
vertex.unwrap_face(); // Panics!
use parry3d::shape::FeatureId;

let vertex = FeatureId::Vertex(0);
vertex.unwrap_face(); // Panics!
use parry3d_f64::shape::FeatureId;

let vertex = FeatureId::Vertex(0);
vertex.unwrap_face(); // Panics!

Trait Implementations

impl Clone for FeatureId

fn clone(&self) -> FeatureId

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for FeatureId

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

Formats the value using the given formatter.

impl Default for FeatureId

fn default() -> FeatureId

Returns the “default value” for a type.

impl From<FeatureId> for PackedFeatureId

fn from(value: FeatureId) -> Self

Converts a FeatureId into its packed representation.

This is a lossless conversion that encodes the feature type and index into a single u32 value.

Examples

use parry2d::shape::{FeatureId, PackedFeatureId};

// Explicit conversion
let feature = FeatureId::Vertex(123);
let packed = PackedFeatureId::from(feature);
assert!(packed.is_vertex());

// Using Into trait
let feature = FeatureId::Face(456);
let packed: PackedFeatureId = feature.into();
assert!(packed.is_face());

// Round-trip conversion preserves the value
let original = FeatureId::Vertex(789);
let packed: PackedFeatureId = original.into();
assert_eq!(packed.unpack(), original);

impl Hash for FeatureId

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for FeatureId

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

impl Eq for FeatureId

impl StructuralPartialEq for FeatureId