0
# Scene Loading and Export
1

2
Core functionality for loading 3D models from files or memory and exporting scenes to various formats. PyAssimp supports over 30 file formats and provides flexible loading options with comprehensive post-processing capabilities.
3

4
## Capabilities
5

6
### Scene Loading from Files
7

8
Load 3D models from files on disk with optional post-processing.
9

10
```python { .api }
11
def load(filename, file_type=None, processing=postprocess.aiProcess_Triangulate):
12
    """
13
    Load 3D model from file path.
14
    
15
    Parameters:
16
    - filename: str, path to 3D model file
17
    - file_type: str, optional file extension hint 
18
    - processing: int, post-processing flags (default: triangulate faces)
19
    
20
    Returns:
21
    Scene object containing loaded 3D data
22
    
23
    Raises:
24
    AssimpError: If file cannot be loaded or is invalid
25
    """
26
```
27

28
Usage examples:
29

30
```python
31
import pyassimp
32
from pyassimp.postprocess import aiProcess_Triangulate, aiProcess_GenNormals
33

34
# Basic loading with default triangulation
35
scene = pyassimp.load("model.obj")
36

37
# Loading with custom post-processing
38
scene = pyassimp.load("model.dae", processing=aiProcess_Triangulate | aiProcess_GenNormals)
39

40
# Loading with file type hint (optional)
41
scene = pyassimp.load("model.dat", file_type="obj")
42
```
43

44
### Scene Loading from Memory
45

46
Load 3D models from file objects or memory buffers.
47

48
```python { .api }
49
def load(filename, file_type=None, processing=postprocess.aiProcess_Triangulate):
50
    """
51
    Load 3D model from file object.
52
    
53
    Parameters:
54
    - filename: file object with read() method
55
    - file_type: str, required file extension when using file objects
56
    - processing: int, post-processing flags
57
    
58
    Returns:
59
    Scene object containing loaded 3D data
60
    
61
    Raises:
62
    AssimpError: If file_type is None or file cannot be loaded
63
    """
64
```
65

66
Usage examples:
67

68
```python
69
import pyassimp
70

71
# Loading from file object
72
with open("model.obj", "rb") as f:
73
    scene = pyassimp.load(f, file_type="obj")
74

75
# Loading from BytesIO
76
from io import BytesIO
77
data = BytesIO(model_bytes)
78
scene = pyassimp.load(data, file_type="stl")
79
```
80

81
### Scene Export to Files
82

83
Export loaded or modified scenes to files in various formats.
84

85
```python { .api }
86
def export(scene, filename, file_type=None, processing=postprocess.aiProcess_Triangulate):
87
    """
88
    Export scene to file.
89
    
90
    Parameters:
91
    - scene: Scene object to export
92
    - filename: str, output file path
93
    - file_type: str, export format identifier (e.g., "obj", "dae", "stl")
94
    - processing: int, post-processing flags applied during export
95
    
96
    Raises:
97
    AssimpError: If export fails or format is unsupported
98
    """
99
```
100

101
Usage examples:
102

103
```python
104
import pyassimp
105

106
# Load and export to different format
107
scene = pyassimp.load("input.dae")
108
pyassimp.export(scene, "output.obj", file_type="obj")
109

110
# Export with post-processing
111
pyassimp.export(scene, "output.stl", file_type="stl", 
112
                processing=pyassimp.postprocess.aiProcess_Triangulate)
113

114
# Clean up
115
pyassimp.release(scene)
116
```
117

118
### Scene Export to Memory
119

120
Export scenes to binary blobs in memory for further processing or network transmission.
121

122
```python { .api }
123
def export_blob(scene, file_type=None, processing=postprocess.aiProcess_Triangulate):
124
    """
125
    Export scene to binary blob.
126
    
127
    Parameters:
128
    - scene: Scene object to export
129
    - file_type: str, export format identifier
130
    - processing: int, post-processing flags
131
    
132
    Returns:
133
    Pointer to ExportDataBlob containing binary export data
134
    
135
    Raises:
136
    AssimpError: If export fails
137
    """
138
```
139

140
Usage examples:
141

142
```python
143
import pyassimp
144

145
# Export to memory blob
146
scene = pyassimp.load("model.obj")
147
blob_ptr = pyassimp.export_blob(scene, file_type="stl")
148

149
# The blob contains the binary data for the exported format
150
# Use with caution - this returns a ctypes pointer
151
```
152

153
### Memory Management
154

155
Explicit memory management for loaded scenes.
156

157
```python { .api }
158
def release(scene):
159
    """
160
    Release scene memory allocated by ASSIMP.
161
    
162
    Parameters:
163
    - scene: Scene object to release
164
    
165
    Note:
166
    Always call this when done with a scene to prevent memory leaks.
167
    The scene object becomes invalid after calling release().
168
    """
169

170
def pythonize_assimp(type, obj, scene):
171
    """
172
    Make ASSIMP data structures more Python-friendly.
173
    
174
    Applies post-processing to convert ASSIMP structures to Python objects
175
    with enhanced accessibility and cross-references.
176
    
177
    Parameters:
178
    - type: str, operation type ("MESH", "ADDTRANSFORMATION")  
179
    - obj: object to process
180
    - scene: Scene object for context
181
    
182
    Returns:
183
    Processed object with Python-friendly structure
184
    """
185

186
def recur_pythonize(node, scene):
187
    """
188
    Recursively apply pythonization to scene node hierarchy.
189
    
190
    Traverses the scene graph and applies pythonize_assimp to all nodes
191
    and their associated data structures.
192
    
193
    Parameters:
194
    - node: Node to process recursively
195
    - scene: Scene object for context
196
    """
197
```
198

199
Usage patterns:
200

201
```python
202
import pyassimp
203

204
# Pattern 1: Try/finally
205
scene = pyassimp.load("model.obj")
206
try:
207
    # Use scene data
208
    process_scene(scene)
209
finally:
210
    pyassimp.release(scene)
211

212
# Pattern 2: Context manager (custom)
213
class SceneManager:
214
    def __init__(self, filename, **kwargs):
215
        self.scene = pyassimp.load(filename, **kwargs)
216
    
217
    def __enter__(self):
218
        return self.scene
219
    
220
    def __exit__(self, exc_type, exc_val, exc_tb):
221
        pyassimp.release(self.scene)
222

223
# Usage
224
with SceneManager("model.obj") as scene:
225
    process_scene(scene)
226
```
227

228
## Supported File Formats
229

230
PyAssimp supports loading and exporting numerous 3D file formats:
231

232
**Common Formats:**
233
- OBJ (Wavefront OBJ)
234
- DAE (COLLADA)
235
- STL (Stereolithography)
236
- PLY (Stanford Polygon Library)
237
- 3DS (3D Studio Max)
238
- X (DirectX)
239
- BLEND (Blender)
240

241
**CAD and Engineering:**
242
- IFC (Industry Foundation Classes)
243
- OFF (Object File Format)
244

245
**Game Formats:**
246
- MD2, MD3 (Quake formats)
247
- MS3D (MilkShape 3D)
248
- Q3O, Q3D (Quick3D formats)
249

250
**Others:**
251
- B3D, COB, SMD, IRRMESH, HMP, TER, WRL, XML, NFF, AC, IRR, Q3S, ZGL, CSM, LWS, MDL, XGL, MD5MESH, MAX, LXO, DXF, BVH, LWO, NDO
252

253
### Format Detection
254

255
Query supported formats programmatically:
256

257
```python { .api }
258
def available_formats():
259
    """
260
    Get list of supported file formats.
261
    
262
    Returns:
263
    list: List of supported file format extensions (uppercase strings)
264
    """
265
```
266

267
Usage example:
268

269
```python
270
from pyassimp.formats import available_formats
271

272
# Get list of all supported formats
273
formats = available_formats()
274
print("Supported formats:", formats)
275

276
# Check if specific format is supported
277
if "OBJ" in formats:
278
    print("OBJ format is supported")
279

280
# Print all formats
281
for format_name in formats:
282
    print(f"- {format_name}")
283
```
284

285
The complete list includes: CSM, LWS, B3D, COB, PLY, IFC, OFF, SMD, IRRMESH, 3D, DAE, MDL, HMP, TER, WRL, XML, NFF, AC, OBJ, 3DS, STL, IRR, Q3O, Q3D, MS3D, Q3S, ZGL, MD2, X, BLEND, XGL, MD5MESH, MAX, LXO, DXF, BVH, LWO, NDO
286

287
## Error Handling
288

289
Common loading and export errors:
290

291
```python
292
import pyassimp
293

294
try:
295
    scene = pyassimp.load("nonexistent.obj")
296
except pyassimp.AssimpError as e:
297
    print(f"Loading failed: {e}")
298

299
try:
300
    # File object without file_type
301
    with open("model.obj", "rb") as f:
302
        scene = pyassimp.load(f)  # Missing file_type parameter
303
except pyassimp.AssimpError as e:
304
    print(f"File type required: {e}")
305

306
try:
307
    scene = pyassimp.load("model.obj")
308
    pyassimp.export(scene, "output.xyz", file_type="xyz")  # Unsupported format
309
except pyassimp.AssimpError as e:
310
    print(f"Export failed: {e}")
311
finally:
312
    pyassimp.release(scene)
313
```
314

315
## Performance Considerations
316

317
1. **Post-processing Impact**: More post-processing flags increase loading time but improve data quality
318
2. **Memory Usage**: Large models with many meshes/textures consume significant memory
319
3. **File Format Efficiency**: Binary formats (like DAE) typically load faster than text formats (like OBJ)
320
4. **NumPy Integration**: Install numpy for better performance with large vertex arrays
321
5. **Memory Management**: Always call `release()` to prevent memory leaks, especially in long-running applications