0
# Trimesh
1

2
A pure Python library for loading and using triangular meshes with emphasis on watertight surfaces. Trimesh provides comprehensive mesh processing capabilities including loading/saving various formats, geometric analysis, mesh repair, boolean operations, collision detection, and visualization.
3

4
## Package Information
5

6
- **Package Name**: trimesh
7
- **Language**: Python
8
- **Installation**: `pip install trimesh`
9

10
## Core Imports
11

12
```python
13
import trimesh
14
```
15

16
For specific functionality:
17

18
```python
19
from trimesh import Trimesh, Scene, PointCloud
20
from trimesh.exchange import load, export
21
from trimesh import primitives, path, voxel
22
```
23

24
## Basic Usage
25

26
```python
27
import trimesh
28
import numpy as np
29

30
# Load a mesh from file
31
mesh = trimesh.load('model.stl')
32

33
# Basic properties
34
print(f"Volume: {mesh.volume}")
35
print(f"Surface area: {mesh.area}")
36
print(f"Is watertight: {mesh.is_watertight}")
37
print(f"Bounds: {mesh.bounds}")
38

39
# Create a primitive mesh
40
sphere = trimesh.primitives.Sphere(radius=1.0)
41
box = trimesh.primitives.Box(extents=[2, 2, 2])
42

43
# Transform the mesh
44
translation = trimesh.transformations.translation_matrix([1, 0, 0])
45
mesh.apply_transform(translation)
46

47
# Boolean operations
48
result = mesh.union(sphere)
49

50
# Visualization
51
mesh.show()  # Interactive 3D viewer
52

53
# Export to different format
54
mesh.export('output.ply')
55
```
56

57
## Architecture
58

59
Trimesh follows a clean object-oriented design with several key components:
60

61
- **Geometry3D**: Base class for all 3D geometric objects providing common properties and methods
62
- **Trimesh**: Main triangular mesh class with comprehensive mesh processing capabilities
63
- **Scene**: Container for multiple geometries with hierarchical transformations and scene graph management
64
- **PointCloud**: Specialized class for point cloud data and operations
65
- **Path2D/Path3D**: Vector path handling for curves and 2D/3D sketches
66

67
The library emphasizes:
68
- **Watertight meshes**: Focus on manifold, closed surfaces for robust operations
69
- **NumPy integration**: Efficient array-based operations throughout
70
- **Modular design**: Clear separation between core geometry, I/O, processing, and visualization
71
- **Minimal dependencies**: Only numpy required, with optional dependencies for enhanced functionality
72

73
## Capabilities
74

75
### Core Mesh Operations
76

77
Essential mesh creation, loading, and basic geometric operations. These form the foundation for all mesh processing workflows in trimesh.
78

79
```python { .api }
80
def load(file_obj, file_type=None, resolver=None, **kwargs):
81
    """Load mesh from file"""
82

83
class Trimesh(Geometry3D):
84
    """Main triangular mesh class"""
85
    @property
86
    def vertices(self) -> np.ndarray: ...
87
    @property 
88
    def faces(self) -> np.ndarray: ...
89
    @property
90
    def volume(self) -> float: ...
91
    @property
92
    def area(self) -> float: ...
93
    def apply_transform(self, matrix: np.ndarray) -> 'Trimesh': ...
94
```
95

96
[Core Mesh Operations](./core-operations.md)
97

98
### File I/O and Data Exchange
99

100
Comprehensive support for loading and saving meshes in various formats including STL, PLY, OBJ, GLTF/GLB, 3MF, and many others.
101

102
```python { .api }
103
def load(file_obj, file_type=None, **kwargs):
104
    """Universal mesh loader with format auto-detection"""
105

106
def load_mesh(file_obj, **kwargs) -> Trimesh:
107
    """Load specifically as Trimesh object"""
108

109
def available_formats() -> dict:
110
    """List all supported file formats"""
111
```
112

113
[File I/O and Data Exchange](./file-io.md)
114

115
### Mesh Processing and Modification
116

117
Advanced mesh processing including repair operations, boolean operations, remeshing, and mesh quality improvement.
118

119
```python { .api }
120
def union(self, other, **kwargs) -> 'Trimesh':
121
    """Boolean union with another mesh"""
122

123
def intersection(self, other, **kwargs) -> 'Trimesh':
124
    """Boolean intersection with another mesh"""
125

126
def fix_normals(self) -> None:
127
    """Fix mesh face winding and normals"""
128

129
def fill_holes(self) -> 'Trimesh':
130
    """Fill holes in the mesh"""
131
```
132

133
[Mesh Processing and Modification](./mesh-processing.md)
134

135
### Analysis and Measurement
136

137
Comprehensive geometric analysis including mass properties, curvature analysis, mesh quality metrics, and geometric measurements.
138

139
```python { .api }
140
@property
141
def mass_properties(self) -> dict:
142
    """Calculate mass, center of mass, and inertia tensor"""
143

144
@property
145
def principal_inertia_components(self) -> np.ndarray:
146
    """Principal moments of inertia"""
147

148
def discrete_gaussian_curvature_measure(self) -> np.ndarray:
149
    """Gaussian curvature at vertices"""
150

151
def discrete_mean_curvature_measure(self) -> np.ndarray:
152
    """Mean curvature at vertices"""
153
```
154

155
[Analysis and Measurement](./analysis.md)
156

157
### Spatial Queries and Collision
158

159
Ray casting, nearest point queries, collision detection, and spatial acceleration structures for efficient geometric queries.
160

161
```python { .api }
162
def ray_triangle(self, ray_origins, ray_directions, **kwargs):
163
    """Intersect rays with mesh triangles"""
164

165
@property
166
def nearest(self):
167
    """Nearest point query object"""
168

169
def collision(self, other_mesh) -> dict:
170
    """Check collision with another mesh"""
171

172
def contains(self, points) -> np.ndarray:
173
    """Test if points are inside the mesh"""
174
```
175

176
[Spatial Queries and Collision](./spatial-queries.md)
177

178
### Visualization and Rendering
179

180
Interactive 3D visualization, material and texture support, scene management, and integration with various rendering systems.
181

182
```python { .api }
183
def show(self, **kwargs) -> None:
184
    """Display mesh in interactive 3D viewer"""
185

186
def scene(self) -> Scene:
187
    """Create scene containing this mesh"""
188

189
@property
190
def visual(self):
191
    """Visual properties (materials, colors, textures)"""
192

193
class Scene:
194
    """Scene graph for multiple geometries"""
195
    def show(self, **kwargs) -> None: ...
196
    def export(self, file_obj, **kwargs) -> None: ...
197
```
198

199
[Visualization and Rendering](./visualization.md)
200

201
### Advanced Features
202

203
Specialized functionality including voxelization, vector path handling, primitive shape generation, and advanced algorithms.
204

205
```python { .api }
206
def voxelized(self, pitch) -> VoxelGrid:
207
    """Convert mesh to voxel representation"""
208

209
class VoxelGrid:
210
    """Voxel grid representation"""
211
    def as_boxes(self) -> Trimesh: ...
212
    def marching_cubes(self) -> Trimesh: ...
213

214
# Primitive shapes
215
def Sphere(radius=1.0, **kwargs) -> Trimesh: ...
216
def Box(extents=None, **kwargs) -> Trimesh: ...
217
def Cylinder(radius=1.0, height=1.0, **kwargs) -> Trimesh: ...
218
```
219

220
[Advanced Features](./advanced-features.md)
221

222
### Point Clouds and Alternative Representations
223

224
Point cloud processing, conversion between different geometric representations, and point-based analysis operations.
225

226
```python { .api }
227
class PointCloud(Geometry3D):
228
    """Point cloud representation"""
229
    @property
230
    def vertices(self) -> np.ndarray: ...
231
    def convex_hull(self) -> Trimesh: ...
232
    def k_means(self, k) -> tuple: ...
233

234
def sample_surface(self, count) -> np.ndarray:
235
    """Sample points on mesh surface"""
236

237
def sample_surface_even(self, count) -> np.ndarray:
238
    """Even distribution surface sampling"""
239
```
240

241
[Point Clouds and Alternative Representations](./point-clouds.md)
242

243
## Types
244

245
```python { .api }
246
class Geometry3D:
247
    """Base class for 3D geometric objects"""
248
    @property
249
    def bounds(self) -> np.ndarray: ...
250
    @property
251
    def extents(self) -> np.ndarray: ...
252
    @property
253
    def centroid(self) -> np.ndarray: ...
254
    def apply_transform(self, matrix: np.ndarray): ...
255

256
class Trimesh(Geometry3D):
257
    """Triangular mesh representation"""
258
    vertices: np.ndarray  # (n, 3) vertex positions
259
    faces: np.ndarray     # (m, 3) face indices
260

261
class Scene:
262
    """Scene graph container"""
263
    geometry: dict        # Geometry objects in scene
264
    graph: dict          # Transform hierarchy
265

266
class PointCloud(Geometry3D):
267
    """Point cloud representation"""
268
    vertices: np.ndarray  # (n, 3) point positions
269

270
class VoxelGrid:
271
    """Voxel grid representation"""
272
    encoding: np.ndarray  # Voxel data
273
    transform: np.ndarray # Coordinate transform
274
    
275
class Path2D:
276
    """2D vector path"""
277
    vertices: np.ndarray  # Path vertices
278
    entities: list       # Path entities (lines, arcs, etc.)
279

280
class Path3D:
281
    """3D vector path"""
282
    vertices: np.ndarray  # 3D path vertices
283
    entities: list       # 3D path entities
284
```