1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
//! Triangle mesh generation from geometric shapes.
//!
//! This module provides functionality to convert various geometric shapes into triangle meshes
//! (also called "trimesh" in Parry's nomenclature). A triangle mesh is represented as a pair
//! of vectors: `(Vec<Vector>, Vec<[u32; 3]>)` containing vertices and triangle indices.
//!
//! # Overview
//!
//! Each shape in Parry implements a `to_trimesh()` method that discretizes its boundary into
//! a triangle mesh. This is useful for:
//! - **Visualization**: Rendering shapes in graphics applications
//! - **Export**: Converting shapes to standard mesh formats (OBJ, STL, etc.)
//! - **Physics simulation**: Converting analytical shapes to mesh-based collision detection
//! - **Mesh processing**: Using shape primitives as building blocks for complex geometry
//!
//! # Supported Shapes
//!
//! ## 2D and 3D Shapes
//! - **Cuboid**: Axis-aligned box with rectangular faces
//! - **Aabb**: Axis-aligned bounding box (uses `Cuboid` internally)
//!
//! ## 3D-Only Shapes
//! - **Ball**: Sphere discretized into triangular patches
//! - **Capsule**: Cylinder with hemispherical caps
//! - **Cylinder**: Circular cylinder with flat caps
//! - **Cone**: Circular cone with flat base
//! - **ConvexPolyhedron**: Already a mesh, returns its triangles
//! - **HeightField**: Terrain height map converted to mesh
//! - **Voxels**: Voxel grid converted to boundary mesh
//!
//! # Mesh Quality Control
//!
//! Most curved shapes (Ball, Capsule, Cylinder, Cone) accept subdivision parameters that
//! control the mesh resolution. Higher subdivision values produce smoother but heavier meshes:
//! - **Low subdivision** (4-8): Fast, angular approximation
//! - **Medium subdivision** (16-32): Good balance for most uses
//! - **High subdivision** (64+): Smooth curves, high polygon count
//!
//! # Examples
//!
//! ## Basic Mesh Generation
//!
//! ```
//! # #[cfg(all(feature = "dim3", feature = "f32"))]
//! # {
//! use parry3d::shape::{Ball, Cuboid};
//! use parry3d::math::Vector;
//!
//! // Convert a cuboid to a triangle mesh
//! let cuboid = Cuboid::new(Vector::new(1.0, 2.0, 3.0));
//! let (vertices, indices) = cuboid.to_trimesh();
//!
//! // A cuboid has 8 vertices and 12 triangles (2 per face × 6 faces)
//! assert_eq!(vertices.len(), 8);
//! assert_eq!(indices.len(), 12);
//!
//! // Convert a sphere with medium resolution
//! let ball = Ball::new(5.0);
//! let (vertices, indices) = ball.to_trimesh(16, 32);
//! // 16 theta subdivisions × 32 phi subdivisions
//! println!("Ball mesh: {} vertices, {} triangles",
//! vertices.len(), indices.len());
//! # }
//! ```
//!
//! ## Controlling Subdivision Quality
//!
//! ```
//! # #[cfg(all(feature = "dim3", feature = "f32"))]
//! # {
//! use parry3d::shape::Cylinder;
//!
//! let cylinder = Cylinder::new(2.0, 1.0); // half-height=2.0, radius=1.0
//!
//! // Low quality - faster, fewer triangles
//! let (vertices_low, indices_low) = cylinder.to_trimesh(8);
//! println!("Low quality: {} triangles", indices_low.len());
//!
//! // High quality - slower, more triangles, smoother appearance
//! let (vertices_high, indices_high) = cylinder.to_trimesh(64);
//! println!("High quality: {} triangles", indices_high.len());
//! # }
//! ```
//!
//! ## Converting Height Fields
//!
//! ```
//! # #[cfg(all(feature = "dim3", feature = "f32"))]
//! # {
//! use parry3d::shape::HeightField;
//! use parry3d::math::Vector;
//! use parry3d::utils::Array2;
//!
//! // Create a simple 3×3 height field
//! // Column-major order: column 0 first, then column 1, then column 2
//! let heights = Array2::new(3, 3, vec![
//! 0.0, 1.0, 0.0, // column 0
//! 1.0, 2.0, 1.0, // column 1
//! 0.0, 1.0, 0.0, // column 2
//! ]);
//!
//! let heightfield = HeightField::new(heights, Vector::new(10.0, 10.0, 1.0));
//! let (vertices, indices) = heightfield.to_trimesh();
//!
//! // Height fields generate 2 triangles per grid cell
//! // (3-1) × (3-1) cells × 2 triangles = 8 triangles
//! assert_eq!(indices.len(), 8);
//! # }
//! ```
//!
//! # Return Format
//!
//! All `to_trimesh()` methods return a tuple `(Vec<Vector>, Vec<[u32; 3]>)`:
//!
//! - **Vertices** (`Vec<Vector>`): Array of 3D points (or 2D for `dim2` feature)
//! - **Indices** (`Vec<[u32; 3]>`): Array of triangle indices, where each `[u32; 3]` contains
//! three indices into the vertices array
//!
//! The triangles follow a **counter-clockwise winding order** when viewed from outside the shape,
//! which is the standard convention for outward-facing normals.
//!
//! # Performance Considerations
//!
//! - Triangle mesh generation allocates new memory each time
//! - For dynamic scenes, consider caching generated meshes
//! - Subdivision parameters have quadratic or cubic impact on triangle count
//! - Simple shapes (Cuboid, ConvexPolyhedron) have negligible generation cost
//! - Complex shapes (Ball, Capsule with high subdivision) can be expensive
//!
//! # See Also
//!
//! - \`to_polyline\` - 2D shape to polyline conversion (internal, not public API)
//! - [`TriMesh`](crate::shape::TriMesh) - Triangle mesh shape type