0
# File I/O and Data Exchange
1

2
Comprehensive support for loading and saving meshes in various formats including STL, PLY, OBJ, GLTF/GLB, 3MF, COLLADA, and many others. Trimesh provides unified interfaces for format handling with automatic format detection and extensive customization options.
3

4
## Capabilities
5

6
### Universal Loading Functions
7

8
Core loading functions that automatically detect file formats and handle different data types.
9

10
```python { .api }
11
def load(file_obj, file_type=None, resolver=None, **kwargs):
12
    """
13
    Universal loader with automatic format detection.
14
    
15
    Parameters:
16
    - file_obj: str file path, file-like object, or URL
17
    - file_type: str, force specific format ('stl', 'ply', 'obj', etc.)
18
    - resolver: function to resolve referenced files (materials, textures)
19
    - **kwargs: format-specific loading options
20
    
21
    Returns:
22
    Trimesh, Scene, Path2D, Path3D, or PointCloud depending on 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 (converts other types if necessary)
35
    """
36

37
def load_scene(file_obj, **kwargs) -> Scene:
38
    """
39
    Load file as Scene object.
40
    
41
    Parameters:
42
    - file_obj: file path or file-like object
43
    - **kwargs: loading options
44
    
45
    Returns:
46
    Scene object containing loaded geometries
47
    """
48

49
def load_path(file_obj, **kwargs):
50
    """
51
    Load file as Path2D or Path3D object.
52
    
53
    Parameters:
54
    - file_obj: file path or file-like object
55
    - **kwargs: loading options
56
    
57
    Returns:
58
    Path2D or Path3D object
59
    """
60

61
def load_remote(url, **kwargs):
62
    """
63
    Load mesh from remote URL.
64
    
65
    Parameters:
66
    - url: str, URL to mesh file
67
    - **kwargs: loading options
68
    
69
    Returns:
70
    Loaded geometry object
71
    """
72
```
73

74
### Format Support and Discovery
75

76
Query supported formats and capabilities.
77

78
```python { .api }
79
def available_formats() -> set:
80
    """
81
    Get set of supported file formats.
82
    
83
    Returns:
84
    set of format strings
85
    """
86

87
def export_formats() -> set:
88
    """
89
    Get set of supported export formats.
90
    
91
    Returns:
92
    set of format strings
93
    """
94

95
def load_formats() -> set:
96
    """
97
    Get set of supported load formats.
98
    
99
    Returns:
100
    set of format strings
101
    """
102
```
103

104
### Export Functions
105

106
Save meshes and scenes to various file formats.
107

108
```python { .api }
109
def export(self, file_obj=None, file_type=None, **kwargs):
110
    """
111
    Export mesh to file or return as bytes.
112
    
113
    Parameters:
114
    - file_obj: str file path or file-like object (None returns bytes)
115
    - file_type: str, force specific format
116
    - **kwargs: format-specific export options
117
    
118
    Returns:
119
    bytes if file_obj is None, otherwise None
120
    """
121

122
def export_scene(scene, file_obj=None, file_type=None, **kwargs):
123
    """
124
    Export Scene object to file.
125
    
126
    Parameters:
127
    - scene: Scene object to export
128
    - file_obj: file path or file-like object
129
    - file_type: str, force specific format
130
    - **kwargs: export options
131
    
132
    Returns:
133
    bytes if file_obj is None, otherwise None
134
    """
135
```
136

137
### Mesh Creation from Data
138

139
Create meshes from various data sources and formats.
140

141
```python { .api }
142
def from_dict(data: dict) -> Trimesh:
143
    """
144
    Create mesh from dictionary representation.
145
    
146
    Parameters:
147
    - data: dict with 'vertices' and 'faces' keys
148
    
149
    Returns:
150
    Trimesh object
151
    """
152

153
def from_glb(data: bytes) -> Scene:
154
    """
155
    Load mesh from GLB binary data.
156
    
157
    Parameters:
158
    - data: bytes, GLB file content
159
    
160
    Returns:
161
    Scene object
162
    """
163

164
def from_gltf(data: dict) -> Scene:
165
    """
166
    Load mesh from GLTF dictionary.
167
    
168
    Parameters:
169
    - data: dict, parsed GLTF content
170
    
171
    Returns:
172
    Scene object
173
    """
174
```
175

176
### Specific Format Loaders
177

178
Direct access to format-specific loading functions.
179

180
```python { .api }
181
# STL format
182
def load_stl(file_obj, **kwargs) -> Trimesh:
183
    """Load STL format (ASCII or binary)"""
184

185
def load_stl_ascii(file_obj) -> Trimesh:
186
    """Load ASCII STL format"""
187

188
def load_stl_binary(file_obj) -> Trimesh:
189
    """Load binary STL format"""
190

191
# PLY format  
192
def load_ply(file_obj, **kwargs) -> Trimesh:
193
    """Load PLY format (ASCII or binary)"""
194

195
# OBJ format
196
def load_obj(file_obj, **kwargs):
197
    """Load Wavefront OBJ format with materials"""
198

199
# GLTF/GLB format
200
def load_gltf(file_obj, resolver=None, **kwargs) -> Scene:
201
    """Load GLTF/GLB format"""
202

203
# OFF format
204
def load_off(file_obj, **kwargs) -> Trimesh:
205
    """Load Object File Format (OFF)"""
206

207
# 3MF format
208
def load_3mf(file_obj, **kwargs) -> Scene:
209
    """Load 3D Manufacturing Format (3MF)"""
210
```
211

212
### Scene and Multi-Mesh Handling
213

214
Handle complex scenes with multiple meshes and transformations.
215

216
```python { .api }
217
class Scene:
218
    """Container for multiple geometries with transforms"""
219
    
220
    def export(self, file_obj=None, file_type=None, **kwargs):
221
        """Export entire scene to file"""
222
    
223
    def save_image(self, resolution=None, **kwargs) -> bytes:
224
        """Render scene to image"""
225
    
226
    def dump(self) -> list:
227
        """Export scene as list of transformed meshes"""
228
    
229
    @property
230
    def geometry(self) -> dict:
231
        """Dictionary of geometry objects in scene"""
232
    
233
    @property
234
    def graph(self) -> dict:
235
        """Scene graph with transformations"""
236
```
237

238
### Advanced I/O Options
239

240
Specialized loading and export options for advanced use cases.
241

242
```python { .api }
243
def load_compressed(file_obj, **kwargs):
244
    """Load from compressed archive formats"""
245

246
def load_step(file_obj, **kwargs):
247
    """Load STEP CAD format (requires opencascade)"""
248

249
def load_collada(file_obj, **kwargs) -> Scene:
250
    """Load COLLADA (.dae) format"""
251

252
def load_x3d(file_obj, **kwargs) -> Scene:
253
    """Load X3D format"""
254

255
def export_gltf(mesh, **kwargs) -> dict:
256
    """Export mesh as GLTF dictionary"""
257

258
def export_obj(mesh, include_materials=True, **kwargs) -> str:
259
    """Export mesh as OBJ format with materials"""
260
```
261

262
## Usage Examples
263

264
### Basic Loading and Saving
265

266
```python
267
import trimesh
268

269
# Load various formats - automatic detection
270
mesh_stl = trimesh.load('model.stl')
271
mesh_ply = trimesh.load('scan.ply') 
272
scene_gltf = trimesh.load('scene.gltf')
273
path_svg = trimesh.load('drawing.svg')
274

275
# Force specific format
276
mesh = trimesh.load('model.dat', file_type='stl')
277

278
# Load from URL
279
mesh = trimesh.load_remote('https://example.com/model.stl')
280

281
# Export to different formats
282
mesh.export('output.ply')
283
mesh.export('output.obj')
284
mesh.export('compressed.stl.gz')
285

286
# Export as bytes
287
stl_data = mesh.export(file_type='stl')
288
```
289

290
### Working with Scenes
291

292
```python
293
# Load complex scene
294
scene = trimesh.load('assembly.gltf')
295

296
print(f"Scene contains {len(scene.geometry)} objects")
297
print(f"Scene bounds: {scene.bounds}")
298

299
# Export entire scene
300
scene.export('output.gltf')
301

302
# Get individual meshes with transforms applied  
303
meshes = scene.dump()
304
for i, mesh in enumerate(meshes):
305
    mesh.export(f'part_{i}.stl')
306

307
# Access individual objects
308
for name, geometry in scene.geometry.items():
309
    print(f"Object {name}: {type(geometry)}")
310
```
311

312
### Format-Specific Options
313

314
```python
315
# STL with custom precision
316
mesh.export('high_precision.stl', digits=8)
317

318
# PLY with vertex colors
319
mesh.visual.vertex_colors = colors  # Set colors first
320
mesh.export('colored.ply')
321

322
# OBJ with materials and textures
323
mesh.export('textured.obj', include_materials=True)
324

325
# GLTF with compression
326
scene.export('compressed.glb', compress=True)
327

328
# Check supported formats
329
formats = trimesh.available_formats()
330
print("Supported formats:")
331
for fmt, info in formats.items():
332
    print(f"  {fmt}: {info}")
333
```
334

335
### Custom Resolution and Loading
336

337
```python
338
# Custom file resolver for relative paths
339
def my_resolver(name):
340
    return open(f'/assets/{name}', 'rb')
341

342
# Load with custom resolver
343
scene = trimesh.load('model.gltf', resolver=my_resolver)
344

345
# Load with specific options
346
mesh = trimesh.load('scan.ply', 
347
                   skip_materials=True,
348
                   process_args={'validate': True})
349

350
# Create mesh from dictionary
351
data = {
352
    'vertices': [[0, 0, 0], [1, 0, 0], [0, 1, 0]],
353
    'faces': [[0, 1, 2]]
354
}
355
mesh = trimesh.Trimesh.from_dict(data)
356
```