0
# Core Mesh Operations
1

2
Essential mesh creation, loading, and basic geometric operations that form the foundation for all mesh processing workflows in trimesh.
3

4
## Capabilities
5

6
### Mesh Loading and Creation
7

8
Load meshes from files or create them from vertex and face arrays.
9

10
```python { .api }
11
def load(file_obj, file_type=None, resolver=None, **kwargs):
12
    """
13
    Load mesh from file with automatic format detection.
14
    
15
    Parameters:
16
    - file_obj: file path, file-like object, or URL
17
    - file_type: str, force specific file type 
18
    - resolver: function to resolve referenced assets
19
    - **kwargs: format-specific loading options
20
    
21
    Returns:
22
    Trimesh, Scene, or Path object depending on file content
23
    """
24

25
def load_mesh(file_obj, **kwargs) -> Trimesh:
26
    """
27
    Load file specifically as Trimesh object.
28
    
29
    Parameters:
30
    - file_obj: file path or file-like object
31
    - **kwargs: loading options
32
    
33
    Returns:
34
    Trimesh object
35
    """
36
```
37

38
### Trimesh Class Properties
39

40
Core properties providing essential geometric information about the mesh.
41

42
```python { .api }
43
class Trimesh(Geometry3D):
44
    """Main triangular mesh class"""
45
    
46
    @property
47
    def vertices(self) -> np.ndarray:
48
        """Vertex coordinates as (n, 3) float array"""
49
    
50
    @property
51
    def faces(self) -> np.ndarray:
52
        """Face indices as (m, 3) int array"""
53
    
54
    @property
55
    def face_normals(self) -> np.ndarray:
56
        """Face normal vectors as (m, 3) array"""
57
    
58
    @property
59
    def vertex_normals(self) -> np.ndarray:
60
        """Vertex normal vectors as (n, 3) array"""
61
    
62
    @property
63
    def bounds(self) -> np.ndarray:
64
        """Axis-aligned bounding box as (2, 3) array"""
65
    
66
    @property
67
    def extents(self) -> np.ndarray:
68
        """Size in each dimension as (3,) array"""
69
    
70
    @property
71
    def centroid(self) -> np.ndarray:
72
        """Geometric center as (3,) array"""
73
    
74
    @property
75
    def center_mass(self) -> np.ndarray:
76
        """Center of mass as (3,) array"""
77
    
78
    @property
79
    def volume(self) -> float:
80
        """Mesh volume (positive for watertight meshes)"""
81
    
82
    @property
83
    def area(self) -> float:
84
        """Surface area"""
85
    
86
    @property
87
    def mass(self) -> float:
88
        """Mass (volume * density)"""
89
    
90
    @property
91
    def density(self) -> float:
92
        """Material density"""
93
    
94
    @density.setter
95
    def density(self, value: float) -> None:
96
        """Set material density"""
97
```
98

99
### Mesh Quality and Validation
100

101
Check mesh properties and quality metrics.
102

103
```python { .api }
104
@property
105
def is_watertight(self) -> bool:
106
    """True if mesh is watertight (manifold and closed)"""
107

108
@property
109
def is_winding_consistent(self) -> bool:
110
    """True if face winding is consistent"""
111

112
@property
113
def is_volume(self) -> bool:
114
    """True if mesh bounds a volume"""
115

116
@property
117
def euler_number(self) -> int:
118
    """Euler characteristic (V - E + F)"""
119
120
```
121

122
### Basic Transformations
123

124
Apply transformations to modify mesh position, orientation, and scale.
125

126
```python { .api }
127
def apply_transform(self, matrix: np.ndarray) -> 'Trimesh':
128
    """
129
    Apply 4x4 transformation matrix to mesh.
130
    
131
    Parameters:
132
    - matrix: (4, 4) transformation matrix
133
    
134
    Returns:
135
    Self for method chaining
136
    """
137
138
```
139

140
### Mesh Copying and Modification
141

142
Create copies and modify mesh structure.
143

144
```python { .api }
145
def copy(self, include_cache=False, include_visual=True) -> 'Trimesh':
146
    """
147
    Create a copy of the mesh.
148
    
149
    Parameters:
150
    - include_cache: bool, copy cached properties  
151
    - include_visual: bool, copy visual properties
152
    
153
    Returns:
154
    New Trimesh object
155
    """
156

157
def update_vertices(self, vertices: np.ndarray) -> None:
158
    """
159
    Update vertex positions.
160
    
161
    Parameters:
162
    - vertices: (n, 3) new vertex coordinates
163
    """
164

165
def update_faces(self, faces: np.ndarray) -> None:
166
    """
167
    Update face connectivity.
168
    
169
    Parameters:
170
    - faces: (m, 3) new face indices
171
    """
172

173
def rezero(self) -> 'Trimesh':
174
    """Center mesh at origin and reset cached properties"""
175
```
176

177
### Mesh Splitting and Combining
178

179
Split meshes into components or combine multiple meshes.
180

181
```python { .api }
182
def split(self, only_watertight=True, adjacency=None) -> list:
183
    """
184
    Split mesh into separate components.
185
    
186
    Parameters:
187
    - only_watertight: bool, only return watertight components
188
    - adjacency: face adjacency matrix (computed if not provided)
189
    
190
    Returns:
191
    List of Trimesh objects for each component
192
    """
193
194
```
195

196
## Usage Examples
197

198
### Basic Mesh Operations
199

200
```python
201
import trimesh
202
import numpy as np
203

204
# Load and examine a mesh
205
mesh = trimesh.load('model.stl')
206
print(f"Vertices: {len(mesh.vertices)}")
207
print(f"Faces: {len(mesh.faces)}")
208
print(f"Volume: {mesh.volume}")
209
print(f"Surface area: {mesh.area}")
210
print(f"Is watertight: {mesh.is_watertight}")
211

212
# Apply transformations using transformation matrices
213
translation_matrix = trimesh.transformations.translation_matrix([1.0, 0.0, 0.5])
214
mesh.apply_transform(translation_matrix)
215

216
# Scale mesh to unit volume using transformation matrix
217
target_volume = 1.0
218
scale_factor = (target_volume / mesh.volume) ** (1/3)
219
scale_matrix = trimesh.transformations.scale_matrix(scale_factor)
220
mesh.apply_transform(scale_matrix)
221

222
# Split into components
223
components = mesh.split()
224
print(f"Found {len(components)} components")
225

226
# Create mesh from arrays
227
vertices = np.array([[0, 0, 0], [1, 0, 0], [0, 1, 0], [0, 0, 1]])
228
faces = np.array([[0, 1, 2], [0, 1, 3], [0, 2, 3], [1, 2, 3]])
229
tetrahedron = trimesh.Trimesh(vertices=vertices, faces=faces)
230
```
231

232
### Mesh Validation and Quality Checks
233

234
```python
235
# Check mesh quality
236
if mesh.is_watertight:
237
    print("Mesh is watertight")
238
    print(f"Volume: {mesh.volume}")
239
else:
240
    print("Mesh has holes or non-manifold edges")
241

242
# Check winding consistency
243
if not mesh.is_winding_consistent:
244
    print("Face winding is inconsistent")
245
    
246
# Get mesh statistics
247
print(f"Euler number: {mesh.euler_number}")
248
print(f"Bounds: {mesh.bounds}")
249
print(f"Extents: {mesh.extents}")
250
print(f"Centroid: {mesh.centroid}")
251
```