0
# PyAssimp
1
2
Python bindings for the Open Asset Import Library (ASSIMP) enabling 3D model loading, processing, and export. PyAssimp provides a Pythonic interface to ASSIMP's comprehensive 3D file format support, allowing developers to load, manipulate, and export 3D scenes, meshes, materials, textures, animations, and metadata from various 3D model formats.
3
4
## Package Information
5
6
- **Package Name**: pyassimp
7
- **Language**: Python
8
- **Installation**: `pip install pyassimp`
9
- **Python Support**: 2.6+ and 3.x
10
- **Optional Dependencies**: numpy (recommended for array optimizations)
11
12
## Core Imports
13
14
```python
15
import pyassimp
16
```
17
18
Common usage imports:
19
20
```python
21
from pyassimp import load, export, release
22
from pyassimp.postprocess import aiProcess_Triangulate, aiProcess_GenNormals
23
from pyassimp.errors import AssimpError
24
```
25
26
## Basic Usage
27
28
```python
29
import pyassimp
30
from pyassimp.postprocess import aiProcess_Triangulate
31
32
# Load a 3D model
33
try:
34
scene = pyassimp.load("model.obj", processing=aiProcess_Triangulate)
35
36
# Access scene data
37
print(f"Loaded {len(scene.meshes)} meshes")
38
print(f"Scene has {len(scene.materials)} materials")
39
40
# Access mesh data
41
for i, mesh in enumerate(scene.meshes):
42
print(f"Mesh {i}: {len(mesh.vertices)} vertices, {len(mesh.faces)} faces")
43
44
# Access vertex data (numpy arrays if available)
45
vertices = mesh.vertices
46
normals = mesh.normals
47
faces = mesh.faces
48
49
# Access materials
50
for i, material in enumerate(scene.materials):
51
print(f"Material {i}: {material.properties}")
52
53
# Clean up memory
54
pyassimp.release(scene)
55
56
except pyassimp.AssimpError as e:
57
print(f"Failed to load model: {e}")
58
```
59
60
## Architecture
61
62
PyAssimp wraps the native ASSIMP C++ library using ctypes, providing Python-friendly access to 3D model data:
63
64
- **Scene Graph**: Hierarchical scene structure with nodes, meshes, materials, and metadata
65
- **Mesh Data**: Vertex arrays, face indices, normals, UV coordinates, and vertex colors
66
- **Material System**: Material properties, textures, and shader parameters
67
- **Post-Processing Pipeline**: Configurable mesh optimization and processing steps
68
- **Memory Management**: Explicit memory control with automatic Python object wrapping
69
70
The library automatically converts C data structures to Python objects with list-like access patterns, and optionally uses NumPy arrays for efficient numerical operations.
71
72
## Capabilities
73
74
### Scene Loading and Export
75
76
Core functionality for loading 3D models from files or memory and exporting scenes to various formats. Supports 30+ file formats including OBJ, DAE, STL, PLY, and more.
77
78
```python { .api }
79
def load(filename, file_type=None, processing=postprocess.aiProcess_Triangulate):
80
"""
81
Load 3D model from file or file object.
82
83
Parameters:
84
- filename: str or file object, path to model file or file object
85
- file_type: str, file extension when using file objects
86
- processing: int, post-processing flags (bitwise combination)
87
88
Returns:
89
Scene object containing loaded 3D data
90
"""
91
92
def export(scene, filename, file_type=None, processing=postprocess.aiProcess_Triangulate):
93
"""
94
Export scene to file.
95
96
Parameters:
97
- scene: Scene object to export
98
- filename: str, output file path
99
- file_type: str, export format (e.g., "obj", "dae")
100
- processing: int, post-processing flags
101
"""
102
103
def export_blob(scene, file_type=None, processing=postprocess.aiProcess_Triangulate):
104
"""
105
Export scene to binary blob.
106
107
Parameters:
108
- scene: Scene object to export
109
- file_type: str, export format
110
- processing: int, post-processing flags
111
112
Returns:
113
Pointer to ExportDataBlob containing binary data
114
"""
115
116
def release(scene):
117
"""
118
Release scene memory.
119
120
Parameters:
121
- scene: Scene object to release
122
"""
123
```
124
125
[Scene Loading and Export](./scene-loading.md)
126
127
### Post-Processing Options
128
129
Extensive mesh processing and optimization capabilities through bitwise-combinable flags. Includes geometry processing, optimization, validation, and format conversion options.
130
131
```python { .api }
132
# Geometry Processing
133
aiProcess_CalcTangentSpace = 0x1
134
aiProcess_JoinIdenticalVertices = 0x2
135
aiProcess_Triangulate = 0x8
136
aiProcess_GenNormals = 0x20
137
aiProcess_GenSmoothNormals = 0x40
138
aiProcess_SplitLargeMeshes = 0x80
139
140
# Optimization
141
aiProcess_ImproveCacheLocality = 0x800
142
aiProcess_RemoveRedundantMaterials = 0x1000
143
aiProcess_OptimizeMeshes = 0x200000
144
aiProcess_OptimizeGraph = 0x400000
145
146
# Validation and Fixes
147
aiProcess_ValidateDataStructure = 0x400
148
aiProcess_FixInfacingNormals = 0x2000
149
aiProcess_FindInvalidData = 0x20000
150
151
# Format Conversion
152
aiProcess_MakeLeftHanded = 0x4
153
aiProcess_FlipUVs = 0x800000
154
aiProcess_FlipWindingOrder = 0x1000000
155
```
156
157
[Post-Processing](./post-processing.md)
158
159
### Scene Data Structures
160
161
Complete scene graph representation including nodes, meshes, materials, textures, animations, cameras, lights, and metadata. Provides hierarchical access to all 3D scene components.
162
163
```python { .api }
164
class Scene:
165
"""Root scene container"""
166
rootnode: Node # Scene graph root
167
meshes: list # List of Mesh objects
168
materials: list # List of Material objects
169
textures: list # List of Texture objects
170
animations: list # List of Animation objects
171
cameras: list # List of Camera objects
172
lights: list # List of Light objects
173
174
class Node:
175
"""Scene graph node"""
176
name: str # Node name
177
transformation: array # 4x4 transformation matrix
178
parent: Node # Parent node
179
children: list # Child nodes
180
meshes: list # Mesh indices/references
181
182
class Mesh:
183
"""3D mesh data"""
184
vertices: array # Vertex positions
185
normals: array # Vertex normals
186
faces: array # Face indices
187
texturecoords: array # UV coordinates
188
colors: array # Vertex colors
189
tangents: array # Tangent vectors
190
bitangents: array # Bitangent vectors
191
materialindex: int # Material index
192
```
193
194
[Scene Data Structures](./scene-data.md)
195
196
### Material and Texture System
197
198
Material properties, texture management, and shader parameter access. Supports various material types, texture mapping, and material property queries.
199
200
```python { .api }
201
class Material:
202
"""Material properties and textures"""
203
properties: PropertyGetter # Material property dictionary
204
205
class PropertyGetter(dict):
206
"""Material property access with semantic keys"""
207
def __getitem__(self, key): ...
208
def keys(self): ...
209
def items(self): ...
210
211
class Texture:
212
"""Texture data"""
213
achformathint: str # Format hint
214
data: array # Texture pixel data
215
width: int # Texture width
216
height: int # Texture height
217
```
218
219
[Materials and Textures](./materials.md)
220
221
### Matrix and Math Utilities
222
223
Mathematical operations for 3D transformations, matrix decomposition, and data type conversions between ASSIMP and Python formats.
224
225
```python { .api }
226
def make_tuple(ai_obj, type=None):
227
"""
228
Convert ASSIMP objects to Python tuples/numpy arrays.
229
230
Parameters:
231
- ai_obj: ASSIMP structure object
232
- type: Optional type hint
233
234
Returns:
235
Python tuple/list or numpy array
236
"""
237
238
def decompose_matrix(matrix):
239
"""
240
Decompose 4x4 transformation matrix.
241
242
Parameters:
243
- matrix: Matrix4x4 object
244
245
Returns:
246
Tuple of (scaling, rotation, position) as Vector3D objects
247
"""
248
```
249
250
[Matrix and Math Utilities](./math-utilities.md)
251
252
## Error Handling
253
254
```python { .api }
255
class AssimpError(BaseException):
256
"""Raised when ASSIMP operations fail"""
257
pass
258
```
259
260
Common error scenarios:
261
- Invalid file formats or corrupted files
262
- Missing file type specification for file objects
263
- Memory allocation failures
264
- Invalid scene data during export
265
266
## Memory Management
267
268
PyAssimp requires explicit memory management for loaded scenes:
269
270
```python
271
# Always release scenes when done
272
scene = pyassimp.load("model.obj")
273
try:
274
# Use scene data
275
pass
276
finally:
277
pyassimp.release(scene)
278
```
279
280
## Supported File Formats
281
282
Supports 30+ formats including: 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, and more.
283
284
## Types
285
286
```python { .api }
287
# Math Types
288
class Vector2D:
289
x: float
290
y: float
291
292
class Vector3D:
293
x: float
294
y: float
295
z: float
296
297
class Matrix3x3:
298
# 3x3 transformation matrix fields
299
a1: float; a2: float; a3: float
300
b1: float; b2: float; b3: float
301
c1: float; c2: float; c3: float
302
303
class Matrix4x4:
304
# 4x4 transformation matrix
305
pass
306
307
class Quaternion:
308
# Rotation quaternion
309
pass
310
311
class Color4D:
312
r: float # Red component
313
g: float # Green component
314
b: float # Blue component
315
a: float # Alpha component
316
317
# Scene Types
318
class Scene:
319
rootnode: Node
320
meshes: list
321
materials: list
322
textures: list
323
animations: list
324
cameras: list
325
lights: list
326
327
class Node:
328
name: str
329
transformation: array
330
parent: Node
331
children: list
332
meshes: list
333
334
class Mesh:
335
vertices: array
336
normals: array
337
faces: array
338
texturecoords: array
339
colors: array
340
tangents: array
341
bitangents: array
342
materialindex: int
343
344
class Face:
345
indices: list
346
347
class Material:
348
properties: PropertyGetter
349
350
class Texture:
351
achformathint: str
352
data: array
353
width: int
354
height: int
355
356
class Camera:
357
name: str
358
# Camera properties
359
360
class Light:
361
name: str
362
# Light properties
363
364
class Animation:
365
name: str
366
# Animation data
367
368
class Metadata:
369
keys: list
370
values: list
371
372
class MetadataEntry:
373
type: int
374
data: any
375
# Type constants
376
AI_BOOL = 0
377
AI_INT32 = 1
378
AI_UINT64 = 2
379
AI_FLOAT = 3
380
AI_DOUBLE = 4
381
AI_AISTRING = 5
382
AI_AIVECTOR3D = 6
383
```