0
# Mesh Data Access
1

2
Access and modify mesh data through convenient properties and array interfaces with support for both vertex-based and coordinate-based operations.
3

4
## Capabilities
5

6
### Triangle Data Properties
7

8
Access mesh triangle data through structured properties for efficient manipulation.
9

10
```python { .api }
11
@property
12
def data(self):
13
    """
14
    Raw mesh data as NumPy structured array.
15
    
16
    Returns:
17
    numpy.array: Structured array with dtype containing:
18
        - normals: (N, 3) float32 - Triangle normal vectors
19
        - vectors: (N, 3, 3) float32 - Triangle vertices
20
        - attr: (N, 1) uint16 - Triangle attributes
21
    
22
    Notes:
23
    - Primary data storage for the mesh
24
    - Direct modification affects all derived properties
25
    - Uses little-endian byte order for STL compatibility
26
    """
27

28
@property
29
def vectors(self):
30
    """
31
    Triangle vertices as a 3D array.
32
    
33
    Returns:
34
    numpy.array: Triangle vertices (N, 3, 3)
35
        - First dimension: triangle index
36
        - Second dimension: vertex index (0, 1, 2)
37
        - Third dimension: coordinate (x, y, z)
38
    """
39

40
@property
41
def normals(self):
42
    """
43
    Triangle normal vectors.
44
    
45
    Returns:
46
    numpy.array: Normal vectors (N, 3)
47
    
48
    Notes:
49
    - Automatically calculated by update_normals()
50
    - Can be manually set but should maintain consistency
51
    """
52

53
@property
54
def attr(self):
55
    """
56
    Triangle attributes from STL format.
57
    
58
    Returns:
59
    numpy.array: Triangle attributes (N, 1) uint16
60
    
61
    Notes:
62
    - Used by binary STL format for additional triangle data
63
    - Typically unused in most applications
64
    """
65
```
66

67
### Individual Vertex Access
68

69
Access individual vertices of triangles for detailed mesh manipulation.
70

71
```python { .api }
72
@property
73
def v0(self):
74
    """
75
    First vertex of each triangle.
76
    
77
    Returns:
78
    numpy.array: First vertices (N, 3)
79
    
80
    Notes:
81
    - Modifying this affects the underlying vectors array
82
    - Equivalent to vectors[:, 0]
83
    """
84

85
@property
86
def v1(self):
87
    """
88
    Second vertex of each triangle.
89
    
90
    Returns:
91
    numpy.array: Second vertices (N, 3)
92
    
93
    Notes:
94
    - Modifying this affects the underlying vectors array
95
    - Equivalent to vectors[:, 1]
96
    """
97

98
@property
99
def v2(self):
100
    """
101
    Third vertex of each triangle.
102
    
103
    Returns:
104
    numpy.array: Third vertices (N, 3)
105
    
106
    Notes:
107
    - Modifying this affects the underlying vectors array
108
    - Equivalent to vectors[:, 2]
109
    """
110
```
111

112
### Coordinate-Based Access
113

114
Access vertex data organized by coordinate axis for spatial operations.
115

116
```python { .api }
117
@property
118
def x(self):
119
    """
120
    X coordinates of all vertices.
121
    
122
    Returns:
123
    numpy.array: X coordinates (N, 3)
124
        - Each row contains x-coordinates of triangle's three vertices
125
    
126
    Notes:
127
    - Convenient for coordinate-based transformations
128
    - Modifying affects underlying vertex data
129
    """
130

131
@property
132
def y(self):
133
    """
134
    Y coordinates of all vertices.
135
    
136
    Returns:
137
    numpy.array: Y coordinates (N, 3)
138
        - Each row contains y-coordinates of triangle's three vertices
139
    """
140

141
@property
142
def z(self):
143
    """
144
    Z coordinates of all vertices.
145
    
146
    Returns:
147
    numpy.array: Z coordinates (N, 3)
148
        - Each row contains z-coordinates of triangle's three vertices
149
    """
150

151
@property
152
def points(self):
153
    """
154
    All vertices flattened into a 2D array.
155
    
156
    Returns:
157
    numpy.array: Flattened vertex coordinates (N, 9)
158
        - Each row: [v0_x, v0_y, v0_z, v1_x, v1_y, v1_z, v2_x, v2_y, v2_z]
159
    
160
    Notes:
161
    - Useful for operations that need all coordinates in linear format
162
    - Modifying affects underlying vector data
163
    """
164
```
165

166
### Array Interface Methods
167

168
Standard Python array interface for mesh manipulation.
169

170
```python { .api }
171
def __len__(self):
172
    """
173
    Number of triangles in the mesh.
174
    
175
    Returns:
176
    int: Triangle count
177
    """
178

179
def __getitem__(self, key):
180
    """
181
    Get triangle data by index.
182
    
183
    Parameters:
184
    - key: Index or slice for triangle selection
185
    
186
    Returns:
187
    numpy.array: Points data for selected triangles
188
    
189
    Notes:
190
    - Returns flattened coordinate data (9 values per triangle)
191
    - Supports standard indexing and slicing
192
    """
193

194
def __setitem__(self, key, value):
195
    """
196
    Set triangle data by index.
197
    
198
    Parameters:
199
    - key: Index or slice for triangle selection
200
    - value: New coordinate data for triangles
201
    
202
    Notes:
203
    - Accepts flattened coordinate data (9 values per triangle)
204
    - Updates underlying vector storage
205
    """
206

207
def __iter__(self):
208
    """
209
    Iterate over triangle point data.
210
    
211
    Yields:
212
    numpy.array: Flattened coordinates for each triangle (9 values)
213
    """
214
```
215

216
### Mesh Metadata
217

218
Access mesh identification and configuration properties.
219

220
```python { .api }
221
@property
222
def name(self):
223
    """
224
    Mesh name from STL file or user assignment.
225
    
226
    Returns:
227
    str: Mesh name
228
    
229
    Notes:
230
    - ASCII STL files can contain named solids
231
    - Binary STL names come from file headers
232
    - Can be manually assigned for identification
233
    """
234

235
@property
236
def speedups(self):
237
    """
238
    Whether Cython optimizations are enabled.
239
    
240
    Returns:
241
    bool: True if using Cython extensions, False for pure Python
242
    """
243
```
244

245
## Usage Examples
246

247
### Basic Data Access
248

249
```python
250
import numpy as np
251
from stl import mesh
252

253
# Load a mesh
254
my_mesh = mesh.Mesh.from_file('model.stl')
255

256
# Basic information
257
print(f"Mesh name: {my_mesh.name}")
258
print(f"Triangle count: {len(my_mesh)}")
259
print(f"Using speedups: {my_mesh.speedups}")
260

261
# Access triangle data
262
first_triangle = my_mesh.vectors[0]
263
print(f"First triangle vertices:\n{first_triangle}")
264

265
# Access normal vectors
266
normals = my_mesh.normals
267
print(f"Normal vector shape: {normals.shape}")
268
```
269

270
### Vertex Manipulation
271

272
```python
273
import numpy as np
274
from stl import mesh
275

276
my_mesh = mesh.Mesh.from_file('model.stl')
277

278
# Access individual vertices
279
v0_vertices = my_mesh.v0  # First vertex of each triangle
280
v1_vertices = my_mesh.v1  # Second vertex of each triangle
281
v2_vertices = my_mesh.v2  # Third vertex of each triangle
282

283
# Modify specific vertices
284
my_mesh.v0[0] = [1.0, 2.0, 3.0]  # Change first vertex of first triangle
285

286
# Bulk vertex operations
287
my_mesh.v0 += [0.1, 0.0, 0.0]  # Move all first vertices in X direction
288
my_mesh.v1[:, 2] += 1.0        # Move all second vertices up in Z
289
```
290

291
### Coordinate-Based Operations
292

293
```python
294
import numpy as np
295
from stl import mesh
296

297
my_mesh = mesh.Mesh.from_file('model.stl')
298

299
# Access by coordinate
300
x_coords = my_mesh.x  # All X coordinates (N, 3)
301
y_coords = my_mesh.y  # All Y coordinates (N, 3)
302
z_coords = my_mesh.z  # All Z coordinates (N, 3)
303

304
# Find bounding box
305
min_x, max_x = np.min(my_mesh.x), np.max(my_mesh.x)
306
min_y, max_y = np.min(my_mesh.y), np.max(my_mesh.y)
307
min_z, max_z = np.min(my_mesh.z), np.max(my_mesh.z)
308

309
print(f"Bounding box: X[{min_x:.2f}, {max_x:.2f}] "
310
      f"Y[{min_y:.2f}, {max_y:.2f}] Z[{min_z:.2f}, {max_z:.2f}]")
311

312
# Coordinate transformations
313
my_mesh.z += 10.0  # Move entire mesh up by 10 units
314
my_mesh.x *= 2.0   # Scale X coordinates by factor of 2
315
```
316

317
### Array Interface Usage
318

319
```python
320
import numpy as np
321
from stl import mesh
322

323
my_mesh = mesh.Mesh.from_file('model.stl')
324

325
# Iterate over triangles
326
for i, triangle_points in enumerate(my_mesh):
327
    if i < 3:  # Print first 3 triangles
328
        print(f"Triangle {i}: {triangle_points}")
329

330
# Index-based access
331
first_triangle = my_mesh[0]  # Get first triangle points (9 values)
332
last_triangle = my_mesh[-1]  # Get last triangle points
333

334
# Slice access
335
first_ten = my_mesh[:10]     # First 10 triangles
336
middle_range = my_mesh[5:15] # Triangles 5-14
337

338
# Modify triangles
339
my_mesh[0] = np.array([0, 0, 0, 1, 0, 0, 0, 1, 0])  # Set first triangle
340
```
341

342
### Working with Points Array
343

344
```python
345
import numpy as np
346
from stl import mesh
347

348
my_mesh = mesh.Mesh.from_file('model.stl')
349

350
# Get flattened points (N, 9)
351
points = my_mesh.points
352
print(f"Points shape: {points.shape}")
353

354
# Reshape to work with individual coordinates
355
reshaped = points.reshape(-1, 3)  # All vertices as (N*3, 3)
356
print(f"Individual vertex coordinates: {reshaped.shape}")
357

358
# Statistical analysis on all vertices
359
mean_vertex = np.mean(reshaped, axis=0)
360
std_vertex = np.std(reshaped, axis=0)
361
print(f"Mean vertex position: {mean_vertex}")
362
print(f"Standard deviation: {std_vertex}")
363
```
364

365
### Direct Data Array Manipulation
366

367
```python
368
import numpy as np
369
from stl import mesh
370

371
my_mesh = mesh.Mesh.from_file('model.stl')
372

373
# Access raw structured array
374
raw_data = my_mesh.data
375
print(f"Data dtype: {raw_data.dtype}")
376

377
# Direct field access
378
triangles = raw_data['vectors']
379
normals = raw_data['normals']
380
attributes = raw_data['attr']
381

382
# Modify raw data (advanced usage)
383
raw_data['vectors'][0, 0, :] = [1, 2, 3]  # Set first vertex of first triangle
384
raw_data['attr'][:] = 42                   # Set all attributes to 42
385
```
386

387
## Performance Considerations
388

389
### Memory Layout
390

391
- NumPy structured arrays provide efficient memory usage
392
- Contiguous memory layout enables fast vectorized operations
393
- Direct property access avoids unnecessary copying
394

395
### Efficient Operations
396

397
```python
398
# Efficient: Vectorized operations
399
my_mesh.vectors += offset  # Fast batch translation
400

401
# Less efficient: Loop-based operations  
402
for i in range(len(my_mesh)):
403
    my_mesh.vectors[i] += offset  # Slower individual updates
404
```
405

406
### Property Caching
407

408
- Computed properties (areas, centroids) are cached
409
- Modifying vertex data invalidates cached properties
410
- Call update methods to refresh computed values
411

412
## Data Type Information
413

414
### Structured Array Format
415

416
```python
417
# NumPy dtype for mesh data
418
dtype = np.dtype([
419
    ('normals', np.float32, (3,)),    # Triangle normals (N, 3)
420
    ('vectors', np.float32, (3, 3)),  # Triangle vertices (N, 3, 3)
421
    ('attr', np.uint16, (1,)),        # Triangle attributes (N, 1)
422
])
423
```
424

425
### Coordinate System
426

427
- Right-handed coordinate system
428
- Units depend on source STL file (typically millimeters)
429
- Z-axis often represents vertical direction in 3D printing