or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.mdmaterials.mdmath-utilities.mdpost-processing.mdscene-data.mdscene-loading.md
tile.json

tessl/pypi-pyassimp

Python bindings for the Open Asset Import Library (ASSIMP) enabling 3D model loading, processing, and export

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/pyassimp@4.1.x

To install, run

npx @tessl/cli install tessl/pypi-pyassimp@4.1.0

index.mddocs/

PyAssimp

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.

Package Information

  • Package Name: pyassimp
  • Language: Python
  • Installation: pip install pyassimp
  • Python Support: 2.6+ and 3.x
  • Optional Dependencies: numpy (recommended for array optimizations)

Core Imports

import pyassimp

Common usage imports:

from pyassimp import load, export, release
from pyassimp.postprocess import aiProcess_Triangulate, aiProcess_GenNormals
from pyassimp.errors import AssimpError

Basic Usage

import pyassimp
from pyassimp.postprocess import aiProcess_Triangulate

# Load a 3D model
try:
    scene = pyassimp.load("model.obj", processing=aiProcess_Triangulate)
    
    # Access scene data
    print(f"Loaded {len(scene.meshes)} meshes")
    print(f"Scene has {len(scene.materials)} materials")
    
    # Access mesh data
    for i, mesh in enumerate(scene.meshes):
        print(f"Mesh {i}: {len(mesh.vertices)} vertices, {len(mesh.faces)} faces")
        
        # Access vertex data (numpy arrays if available)
        vertices = mesh.vertices
        normals = mesh.normals
        faces = mesh.faces
    
    # Access materials
    for i, material in enumerate(scene.materials):
        print(f"Material {i}: {material.properties}")
    
    # Clean up memory
    pyassimp.release(scene)
    
except pyassimp.AssimpError as e:
    print(f"Failed to load model: {e}")

Architecture

PyAssimp wraps the native ASSIMP C++ library using ctypes, providing Python-friendly access to 3D model data:

  • Scene Graph: Hierarchical scene structure with nodes, meshes, materials, and metadata
  • Mesh Data: Vertex arrays, face indices, normals, UV coordinates, and vertex colors
  • Material System: Material properties, textures, and shader parameters
  • Post-Processing Pipeline: Configurable mesh optimization and processing steps
  • Memory Management: Explicit memory control with automatic Python object wrapping

The library automatically converts C data structures to Python objects with list-like access patterns, and optionally uses NumPy arrays for efficient numerical operations.

Capabilities

Scene Loading and Export

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.

def load(filename, file_type=None, processing=postprocess.aiProcess_Triangulate):
    """
    Load 3D model from file or file object.
    
    Parameters:
    - filename: str or file object, path to model file or file object
    - file_type: str, file extension when using file objects
    - processing: int, post-processing flags (bitwise combination)
    
    Returns:
    Scene object containing loaded 3D data
    """

def export(scene, filename, file_type=None, processing=postprocess.aiProcess_Triangulate):
    """
    Export scene to file.
    
    Parameters:
    - scene: Scene object to export
    - filename: str, output file path
    - file_type: str, export format (e.g., "obj", "dae")
    - processing: int, post-processing flags
    """

def export_blob(scene, file_type=None, processing=postprocess.aiProcess_Triangulate):
    """
    Export scene to binary blob.
    
    Parameters:
    - scene: Scene object to export
    - file_type: str, export format
    - processing: int, post-processing flags
    
    Returns:
    Pointer to ExportDataBlob containing binary data
    """

def release(scene):
    """
    Release scene memory.
    
    Parameters:
    - scene: Scene object to release
    """

Scene Loading and Export

Post-Processing Options

Extensive mesh processing and optimization capabilities through bitwise-combinable flags. Includes geometry processing, optimization, validation, and format conversion options.

# Geometry Processing
aiProcess_CalcTangentSpace = 0x1
aiProcess_JoinIdenticalVertices = 0x2
aiProcess_Triangulate = 0x8
aiProcess_GenNormals = 0x20
aiProcess_GenSmoothNormals = 0x40
aiProcess_SplitLargeMeshes = 0x80

# Optimization
aiProcess_ImproveCacheLocality = 0x800
aiProcess_RemoveRedundantMaterials = 0x1000
aiProcess_OptimizeMeshes = 0x200000
aiProcess_OptimizeGraph = 0x400000

# Validation and Fixes
aiProcess_ValidateDataStructure = 0x400
aiProcess_FixInfacingNormals = 0x2000
aiProcess_FindInvalidData = 0x20000

# Format Conversion
aiProcess_MakeLeftHanded = 0x4
aiProcess_FlipUVs = 0x800000
aiProcess_FlipWindingOrder = 0x1000000

Post-Processing

Scene Data Structures

Complete scene graph representation including nodes, meshes, materials, textures, animations, cameras, lights, and metadata. Provides hierarchical access to all 3D scene components.

class Scene:
    """Root scene container"""
    rootnode: Node  # Scene graph root
    meshes: list    # List of Mesh objects
    materials: list # List of Material objects
    textures: list  # List of Texture objects
    animations: list # List of Animation objects
    cameras: list   # List of Camera objects
    lights: list    # List of Light objects

class Node:
    """Scene graph node"""
    name: str           # Node name
    transformation: array  # 4x4 transformation matrix
    parent: Node        # Parent node
    children: list      # Child nodes
    meshes: list        # Mesh indices/references

class Mesh:
    """3D mesh data"""
    vertices: array     # Vertex positions
    normals: array      # Vertex normals
    faces: array        # Face indices
    texturecoords: array # UV coordinates
    colors: array       # Vertex colors
    tangents: array     # Tangent vectors
    bitangents: array   # Bitangent vectors
    materialindex: int  # Material index

Scene Data Structures

Material and Texture System

Material properties, texture management, and shader parameter access. Supports various material types, texture mapping, and material property queries.

class Material:
    """Material properties and textures"""
    properties: PropertyGetter  # Material property dictionary

class PropertyGetter(dict):
    """Material property access with semantic keys"""
    def __getitem__(self, key): ...
    def keys(self): ...
    def items(self): ...

class Texture:
    """Texture data"""
    achformathint: str  # Format hint
    data: array         # Texture pixel data
    width: int          # Texture width
    height: int         # Texture height

Materials and Textures

Matrix and Math Utilities

Mathematical operations for 3D transformations, matrix decomposition, and data type conversions between ASSIMP and Python formats.

def make_tuple(ai_obj, type=None):
    """
    Convert ASSIMP objects to Python tuples/numpy arrays.
    
    Parameters:
    - ai_obj: ASSIMP structure object
    - type: Optional type hint
    
    Returns:
    Python tuple/list or numpy array
    """

def decompose_matrix(matrix):
    """
    Decompose 4x4 transformation matrix.
    
    Parameters:
    - matrix: Matrix4x4 object
    
    Returns:
    Tuple of (scaling, rotation, position) as Vector3D objects
    """

Matrix and Math Utilities

Error Handling

class AssimpError(BaseException):
    """Raised when ASSIMP operations fail"""
    pass

Common error scenarios:

  • Invalid file formats or corrupted files
  • Missing file type specification for file objects
  • Memory allocation failures
  • Invalid scene data during export

Memory Management

PyAssimp requires explicit memory management for loaded scenes:

# Always release scenes when done
scene = pyassimp.load("model.obj")
try:
    # Use scene data
    pass
finally:
    pyassimp.release(scene)

Supported File Formats

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.

Types

# Math Types
class Vector2D:
    x: float
    y: float

class Vector3D:
    x: float
    y: float
    z: float

class Matrix3x3:
    # 3x3 transformation matrix fields
    a1: float; a2: float; a3: float
    b1: float; b2: float; b3: float  
    c1: float; c2: float; c3: float

class Matrix4x4:
    # 4x4 transformation matrix
    pass

class Quaternion:
    # Rotation quaternion
    pass

class Color4D:
    r: float  # Red component
    g: float  # Green component
    b: float  # Blue component
    a: float  # Alpha component

# Scene Types
class Scene:
    rootnode: Node
    meshes: list
    materials: list
    textures: list
    animations: list
    cameras: list
    lights: list

class Node:
    name: str
    transformation: array
    parent: Node
    children: list
    meshes: list

class Mesh:
    vertices: array
    normals: array
    faces: array
    texturecoords: array
    colors: array
    tangents: array
    bitangents: array
    materialindex: int

class Face:
    indices: list

class Material:
    properties: PropertyGetter

class Texture:
    achformathint: str
    data: array
    width: int
    height: int

class Camera:
    name: str
    # Camera properties

class Light:
    name: str
    # Light properties

class Animation:
    name: str
    # Animation data

class Metadata:
    keys: list
    values: list

class MetadataEntry:
    type: int
    data: any
    # Type constants
    AI_BOOL = 0
    AI_INT32 = 1
    AI_UINT64 = 2
    AI_FLOAT = 3
    AI_DOUBLE = 4
    AI_AISTRING = 5
    AI_AIVECTOR3D = 6