avian3d/collision/collider/
trimesh_builder.rs

1//! Types used for creating triangle meshes from [`Collider`]s.
2
3use core::num::NonZeroU32;
4
5use bevy::prelude::*;
6use parry::shape::{SharedShape, TypedShape};
7use thiserror::Error;
8
9use crate::prelude::*;
10
11/// An ergonomic builder for triangle meshes from [`Collider`]s.
12///
13/// The builder can configure different subdivision levels for different shapes.
14/// If a shape was not explicitly configured, the builder will use [`Self::fallback_subdivisions`].
15///
16/// Shapes with rounded corners such as [`Collider::round_cuboid`] will be subdivided as if they were not rounded.
17///
18/// # Example
19///
20/// ```
21/// # use avian3d::{prelude::*, math::Vector};
22///
23/// let collider = Collider::sphere(1.0);
24///
25/// // Using default settings
26/// let trimesh = collider.trimesh_builder().build().unwrap();
27///
28/// // Using extra subdivisions
29/// let trimesh = collider
30///     .trimesh_builder()
31///     .sphere_subdivisions(20, 20)
32///     .build()
33///     .unwrap();
34///
35/// // Setting different subdivisions for different shapes
36/// let trimesh = collider
37///     .trimesh_builder()
38///     .sphere_subdivisions(20, 20)
39///     .capsule_subdivisions(10, 5)
40///     .fallback_subdivisions(15)
41///     .build()
42///     .unwrap();
43///
44/// // Generating the trimesh with a transformation
45/// let trimesh = collider
46///     .trimesh_builder()
47///     .translated(Vector::new(1.0, 0.0, 0.0))
48///     .build()
49///     .unwrap();
50/// ```
51#[derive(Debug, Clone)]
52pub struct TrimeshBuilder {
53    /// The shape to be converted into a triangle mesh.
54    pub shape: SharedShape,
55    /// The position of the shape. The default is [0, 0, 0].
56    pub position: Position,
57    /// The rotation of the shape. The default is the identity rotation.
58    pub rotation: Rotation,
59    /// Whether a failure to trimesh a subshape in a compound shape should fail the entire build process.
60    /// Default is true.
61    pub fail_on_compound_error: bool,
62    /// The number of subdivisions to use for shapes that do not have a specific subdivision count.
63    /// Default is 16.
64    pub fallback_subdivisions: NonZeroU32,
65    /// The number of subdivisions for shapes that derive from a sphere.
66    /// Default is None.
67    pub sphere_subdivisions: Option<(NonZeroU32, NonZeroU32)>,
68    /// The number of subdivisions for shapes that derive from a capsule.
69    /// Default is None.
70    pub capsule_subdivision: Option<(NonZeroU32, NonZeroU32)>,
71    /// The number of subdivisions for shapes that derive from a cylinder.
72    /// Default is None.
73    pub cylinder_subdivisions: Option<NonZeroU32>,
74    /// The number of subdivisions for shapes that derive from a cone.
75    /// Default is None.
76    pub cone_subdivisions: Option<NonZeroU32>,
77}
78
79/// A generic triangle mesh representation.
80#[derive(Debug, Clone, PartialEq, Reflect, Default)]
81pub struct Trimesh {
82    /// The vertices in
83    pub vertices: Vec<Vector>,
84    /// The indices in counter-clockwise winding
85    pub indices: Vec<[u32; 3]>,
86}
87
88impl Trimesh {
89    /// Extends the trimesh with the vertices and indices of another trimesh.
90    /// The indices of `other` will be offset by the number of vertices in `self`.
91    pub fn extend(&mut self, other: Trimesh) {
92        let next_vertex_index = self.vertices.len() as u32;
93        self.vertices.extend(other.vertices);
94        self.indices.extend(
95            other
96                .indices
97                .iter()
98                .map(|is| is.map(|i| i + next_vertex_index)),
99        );
100    }
101}
102
103/// An error that can occur when building a triangle mesh with [`TrimeshBuilder::build`].
104#[derive(Debug, Error)]
105pub enum TrimeshBuilderError {
106    /// The shape is not supported by the builder.
107    #[error("Unsupported shape type: {0}")]
108    UnsupportedShape(String),
109}
110
111impl TrimeshBuilder {
112    /// Creates a new [`TrimeshBuilder`] for the given shape. Usually you'll want to call [`Collider::trimesh_builder`] instead.
113    pub fn new(shape: SharedShape) -> Self {
114        TrimeshBuilder {
115            shape,
116            position: default(),
117            rotation: default(),
118            fail_on_compound_error: true,
119            // arbitrary number
120            fallback_subdivisions: 16_u32.try_into().unwrap(),
121            sphere_subdivisions: None,
122            capsule_subdivision: None,
123            cylinder_subdivisions: None,
124            cone_subdivisions: None,
125        }
126    }
127
128    /// Translates the mesh. Subsequent calls to this method will add to the previous translation.
129    pub fn translated(&mut self, position: impl Into<Position>) -> &mut Self {
130        self.position.0 += position.into().0;
131        self
132    }
133
134    /// Rotates the mesh. Subsequent calls to this method will add to the previous rotation.
135    pub fn rotated(&mut self, rotation: impl Into<Rotation>) -> &mut Self {
136        self.rotation = rotation.into() * self.rotation;
137        self
138    }
139
140    /// Sets the fallback subdivision count for shapes that don't have a specific subdivision count.
141    /// Default is 16.
142    pub fn fallback_subdivisions(&mut self, subdivisions: impl TryInto<NonZeroU32>) -> &mut Self {
143        self.fallback_subdivisions = subdivisions
144            .try_into()
145            .unwrap_or_else(|_| panic!("Fallback subdivision count must be non-zero"));
146        self
147    }
148
149    /// Sets the subdivision count for sphere shapes. `theta` is the number of subdivisions along the
150    /// latitude, and `phi` is the number of subdivisions along the longitude.
151    pub fn sphere_subdivisions(
152        &mut self,
153        theta: impl TryInto<NonZeroU32>,
154        phi: impl TryInto<NonZeroU32>,
155    ) -> &mut Self {
156        self.sphere_subdivisions = Some((
157            theta
158                .try_into()
159                .unwrap_or_else(|_| panic!("Sphere theta subdivisions must be non-zero")),
160            phi.try_into()
161                .inspect(|phi| {
162                    assert!(phi.get() >= 2, "Sphere phi subdivisions must be at least 2")
163                })
164                .unwrap_or_else(|_| panic!("Sphere phi subdivisions must be non-zero")),
165        ));
166        self
167    }
168
169    /// Sets the subdivision count for capsule shapes. `theta` is the number of subdivisions along the
170    /// latitude, and `phi` is the number of subdivisions along the longitude.
171    pub fn capsule_subdivisions(
172        &mut self,
173        theta: impl TryInto<NonZeroU32>,
174        phi: impl TryInto<NonZeroU32>,
175    ) -> &mut Self {
176        self.capsule_subdivision = Some((
177            theta
178                .try_into()
179                .unwrap_or_else(|_| panic!("Capsule theta subdivisions must be non-zero")),
180            phi.try_into()
181                .inspect(|phi| {
182                    assert!(
183                        phi.get() >= 2,
184                        "Capsule phi subdivisions must be at least 2"
185                    )
186                })
187                .unwrap_or_else(|_| panic!("Capsule phi subdivisions must be non-zero")),
188        ));
189        self
190    }
191
192    /// Sets the subdivision count for cylinder shapes.
193    pub fn cylinder_subdivisions(&mut self, subdivisions: impl TryInto<NonZeroU32>) -> &mut Self {
194        self.cylinder_subdivisions = Some(
195            subdivisions
196                .try_into()
197                .unwrap_or_else(|_| panic!("Cylinder subdivisions must be non-zero")),
198        );
199        self
200    }
201
202    /// Sets the subdivision count for cone shapes.
203    pub fn cone_subdivisions(&mut self, subdivisions: impl TryInto<NonZeroU32>) -> &mut Self {
204        self.cone_subdivisions = Some(
205            subdivisions
206                .try_into()
207                .unwrap_or_else(|_| panic!("Cone subdivisions must be non-zero")),
208        );
209        self
210    }
211
212    /// Whether a failure to trimesh a subshape in a compound shape should fail the entire build process.
213    /// Default is true.
214    pub fn fail_on_compound_error(&mut self, fail_on_compound_error: bool) -> &mut Self {
215        self.fail_on_compound_error = fail_on_compound_error;
216        self
217    }
218
219    fn subdivisions(&self, get: impl Fn(&Self) -> Option<NonZeroU32>) -> u32 {
220        get(self).unwrap_or(self.fallback_subdivisions).into()
221    }
222
223    /// Builds the trimesh from the configured settings.
224    ///
225    /// Returns an error if the shape is not supported.
226    /// If the shape is a compound, errors in a subshape will either be ignored or fail the entire build process
227    /// depending on the value of [`Self::fail_on_compound_error`].
228    pub fn build(&self) -> Result<Trimesh, TrimeshBuilderError> {
229        let (vertices, indices) = match self.shape.as_typed_shape() {
230            // Simple cases
231            TypedShape::Cuboid(cuboid) => cuboid.to_trimesh(),
232            TypedShape::Voxels(voxels) => voxels.to_trimesh(),
233            TypedShape::ConvexPolyhedron(convex_polyhedron) => convex_polyhedron.to_trimesh(),
234            TypedShape::HeightField(height_field) => height_field.to_trimesh(),
235            // Triangles
236            TypedShape::Triangle(triangle) => {
237                (vec![triangle.a, triangle.b, triangle.c], vec![[0, 1, 2]])
238            }
239            TypedShape::TriMesh(tri_mesh) => {
240                (tri_mesh.vertices().to_vec(), tri_mesh.indices().to_vec())
241            }
242            // Need subdivisions
243            TypedShape::Ball(ball) => ball.to_trimesh(
244                self.subdivisions(|t| t.sphere_subdivisions?.0.into()),
245                self.subdivisions(|t| t.sphere_subdivisions?.1.into()),
246            ),
247            TypedShape::Capsule(capsule) => capsule.to_trimesh(
248                self.subdivisions(|t| t.capsule_subdivision?.0.into()),
249                self.subdivisions(|t| t.capsule_subdivision?.1.into()),
250            ),
251            TypedShape::Cylinder(cylinder) => {
252                cylinder.to_trimesh(self.subdivisions(|t| t.cylinder_subdivisions))
253            }
254            TypedShape::Cone(cone) => cone.to_trimesh(self.subdivisions(|t| t.cone_subdivisions)),
255            // Compounds need to be unpacked
256            TypedShape::Compound(compound) => {
257                let mut sub_builder = self.clone();
258                return compound.shapes().iter().try_fold(
259                    Trimesh::default(),
260                    move |mut compound_trimesh, (sub_pos, shape)| {
261                        sub_builder.shape = shape.clone();
262                        sub_builder.position =
263                            Position(self.position.0 + self.rotation * sub_pos.translation);
264                        sub_builder.rotation =
265                            self.rotation.mul_quat(sub_pos.rotation).normalize().into();
266                        let trimesh = match sub_builder.build() {
267                            Ok(trimesh) => trimesh,
268                            Err(error) => {
269                                return if self.fail_on_compound_error {
270                                    Err(error)
271                                } else {
272                                    Ok(compound_trimesh)
273                                };
274                            }
275                        };
276
277                        compound_trimesh.extend(trimesh);
278
279                        // No need to track recursive compounds because parry panics on nested compounds anyways lol
280                        Ok(compound_trimesh)
281                    },
282                );
283            }
284            // Rounded shapes ignore the rounding and use the inner shape
285            TypedShape::RoundCuboid(round_shape) => round_shape.inner_shape.to_trimesh(),
286            TypedShape::RoundTriangle(round_shape) => (
287                vec![
288                    round_shape.inner_shape.a,
289                    round_shape.inner_shape.b,
290                    round_shape.inner_shape.c,
291                ],
292                vec![[0, 1, 2]],
293            ),
294            TypedShape::RoundConvexPolyhedron(round_shape) => round_shape.inner_shape.to_trimesh(),
295            TypedShape::RoundCylinder(round_shape) => round_shape
296                .inner_shape
297                .to_trimesh(self.subdivisions(|t| t.cylinder_subdivisions)),
298            TypedShape::RoundCone(round_shape) => round_shape
299                .inner_shape
300                .to_trimesh(self.subdivisions(|t| t.cone_subdivisions)),
301            // Not supported
302            TypedShape::Segment(segment) => {
303                return Err(TrimeshBuilderError::UnsupportedShape(format!(
304                    "{segment:?}",
305                )));
306            }
307            TypedShape::Polyline(polyline) => {
308                return Err(TrimeshBuilderError::UnsupportedShape(format!(
309                    "{polyline:?}",
310                )));
311            }
312            TypedShape::HalfSpace(half_space) => {
313                return Err(TrimeshBuilderError::UnsupportedShape(format!(
314                    "{half_space:?}",
315                )));
316            }
317            TypedShape::Custom(_shape) => {
318                return Err(TrimeshBuilderError::UnsupportedShape("Custom".to_string()));
319            }
320        };
321        let pos = self.position;
322        Ok(Trimesh {
323            vertices: vertices
324                .into_iter()
325                .map(|v| pos.0 + self.rotation * v)
326                .collect(),
327            indices,
328        })
329    }
330}
331
332impl Collider {
333    /// Create a [`TrimeshBuilder`] for building a [`Trimesh`].
334    pub fn trimesh_builder(&self) -> TrimeshBuilder {
335        TrimeshBuilder::new(self.shape_scaled().clone())
336    }
337}
338
339#[cfg(feature = "collider-from-mesh")]
340impl From<Trimesh> for Mesh {
341    fn from(trimesh: Trimesh) -> Self {
342        use bevy::asset::RenderAssetUsages;
343        use bevy::mesh::{Indices, PrimitiveTopology, VertexAttributeValues, prelude::*};
344
345        let mut mesh = Mesh::new(
346            PrimitiveTopology::TriangleList,
347            RenderAssetUsages::default(),
348        );
349        mesh.insert_attribute(
350            Mesh::ATTRIBUTE_POSITION,
351            VertexAttributeValues::Float32x3(
352                trimesh
353                    .vertices
354                    .into_iter()
355                    .map(|v| v.f32().to_array())
356                    .collect(),
357            ),
358        );
359        mesh.insert_indices(Indices::U32(
360            trimesh.indices.into_iter().flatten().collect(),
361        ));
362        mesh.compute_normals();
363        if let Err(err) = mesh.generate_tangents() {
364            warn!("Failed to generate tangents for mesh: {err}");
365        }
366
367        mesh
368    }
369}
370
371#[cfg(test)]
372mod tests {
373    use bevy_math::DVec3;
374
375    use super::*;
376
377    #[test]
378    fn rasterizes_cuboid() {
379        let collider = Collider::cuboid(1.0, 2.0, 3.0);
380        let trimesh = collider.trimesh_builder().build().unwrap();
381        assert_eq!(trimesh.vertices.len(), 8);
382        assert_eq!(trimesh.indices.len(), 12);
383    }
384
385    #[test]
386    fn rasterizes_compound() {
387        let a = Collider::cuboid(1.0, 2.0, 3.0);
388        let b = Collider::sphere(0.4);
389        let collider = Collider::compound(vec![
390            (Vector::new(1.0, 2.0, 3.0), Quat::from_rotation_z(0.2), a),
391            (
392                Vector::new(-12.0, 4.0, -0.01),
393                Quat::from_rotation_x(0.1),
394                b,
395            ),
396        ]);
397        let trimesh = collider
398            .trimesh_builder()
399            .fallback_subdivisions(2)
400            .translated(Vector::new(3.0, -2.0, 0.0))
401            .rotated(Quat::from_rotation_y(-3.0))
402            .build()
403            .unwrap();
404        assert_eq!(
405            trimesh.vertices,
406            vec![
407                DVec3::new(1.663415604680207, -1.0794012104819937, -4.354963570435039)
408                    .adjust_precision(),
409                DVec3::new(2.0867756033225007, -1.0794012104819934, -1.3849860769934488)
410                    .adjust_precision(),
411                DVec3::new(1.116517045301514, -0.8807318727109547, -1.246679082171598)
412                    .adjust_precision(),
413                DVec3::new(0.6931570466592203, -0.8807318727109547, -4.216656575613189)
414                    .adjust_precision(),
415                DVec3::new(2.056777912558161, 0.8807319423722882, -4.411036004147714)
416                    .adjust_precision(),
417                DVec3::new(2.4801379112004547, 0.8807319423722882, -1.4410585107061238)
418                    .adjust_precision(),
419                DVec3::new(1.5098793531794679, 1.0794012801433273, -1.302751515884273)
420                    .adjust_precision(),
421                DVec3::new(1.086519354537174, 1.079401280143327, -4.272729009325864)
422                    .adjust_precision(),
423                DVec3::new(14.886956777274035, 1.6019984034862897, -1.6440063661356903)
424                    .adjust_precision(),
425                DVec3::new(14.485324381553463, 2.0000000696613336, -1.6270920990914757)
426                    .adjust_precision(),
427                DVec3::new(15.277318379804553, 2.0000000696613336, -1.739988098729421)
428                    .adjust_precision(),
429                DVec3::new(14.875685984083981, 2.3980017358363774, -1.7230738316852063)
430                    .adjust_precision(),
431            ]
432        );
433        assert_eq!(
434            trimesh.indices,
435            vec![
436                [4, 5, 0],
437                [5, 1, 0],
438                [5, 6, 1],
439                [6, 2, 1],
440                [6, 7, 3],
441                [2, 6, 3],
442                [7, 4, 0],
443                [3, 7, 0],
444                [0, 1, 2],
445                [3, 0, 2],
446                [7, 6, 5],
447                [4, 7, 5],
448                [8, 9, 10],
449                [8, 10, 9],
450                [9, 11, 10],
451                [10, 11, 9],
452            ]
453        );
454    }
455}
avian3d/collision/collider/trimesh_builder.rs

avian3d/collision/collider/
trimesh_builder.rs
