tessl/pypi-pyassimp

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

—

Pending

Overview

Eval results

Files

Post-Processing Options

Name: tessl/pypi-pyassimp
Author: tessl

Extensive mesh processing and optimization capabilities through bitwise-combinable flags. Post-processing steps transform and optimize 3D model data during loading and export operations, enabling mesh optimization, geometry fixes, format conversions, and rendering preparation.

Capabilities

Geometry Processing

Fundamental geometry processing operations for mesh optimization and standardization.

# Tangent and bitangent calculation
aiProcess_CalcTangentSpace = 0x1

# Vertex deduplication
aiProcess_JoinIdenticalVertices = 0x2

# Coordinate system conversion
aiProcess_MakeLeftHanded = 0x4

# Face triangulation
aiProcess_Triangulate = 0x8

# Normal generation
aiProcess_GenNormals = 0x20
aiProcess_GenSmoothNormals = 0x40

Usage examples:

import pyassimp
from pyassimp.postprocess import *

# Basic triangulation (default)
scene = pyassimp.load("model.obj", processing=aiProcess_Triangulate)

# Generate smooth normals and tangents
processing = aiProcess_Triangulate | aiProcess_GenSmoothNormals | aiProcess_CalcTangentSpace
scene = pyassimp.load("model.dae", processing=processing)

# Join identical vertices to reduce memory usage
processing = aiProcess_JoinIdenticalVertices | aiProcess_Triangulate
scene = pyassimp.load("model.stl", processing=processing)

Mesh Optimization

Performance optimization operations for real-time rendering and memory efficiency.

# Cache locality optimization
aiProcess_ImproveCacheLocality = 0x800

# Material deduplication
aiProcess_RemoveRedundantMaterials = 0x1000

# Mesh combination
aiProcess_OptimizeMeshes = 0x200000

# Scene graph optimization
aiProcess_OptimizeGraph = 0x400000

# Large mesh subdivision
aiProcess_SplitLargeMeshes = 0x80

# Bone weight limiting
aiProcess_LimitBoneWeights = 0x200

Usage examples:

from pyassimp.postprocess import *

# Real-time rendering optimization
processing = (aiProcess_Triangulate | 
              aiProcess_JoinIdenticalVertices |
              aiProcess_ImproveCacheLocality |
              aiProcess_OptimizeMeshes)

scene = pyassimp.load("complex_model.dae", processing=processing)

# Memory optimization
processing = (aiProcess_RemoveRedundantMaterials |
              aiProcess_OptimizeGraph |
              aiProcess_SplitLargeMeshes)

scene = pyassimp.load("large_model.obj", processing=processing)

Data Validation and Fixes

Data integrity validation and automatic fixes for common mesh issues.

# Structure validation
aiProcess_ValidateDataStructure = 0x400

# Normal direction fixes
aiProcess_FixInfacingNormals = 0x2000

# Degenerate primitive detection
aiProcess_FindDegenerates = 0x10000

# Invalid data detection and removal
aiProcess_FindInvalidData = 0x20000

# Primitive type sorting
aiProcess_SortByPType = 0x8000

Usage examples:

from pyassimp.postprocess import *

# Comprehensive validation and fixes
processing = (aiProcess_ValidateDataStructure |
              aiProcess_FixInfacingNormals |
              aiProcess_FindInvalidData |
              aiProcess_FindDegenerates)

scene = pyassimp.load("potentially_broken.obj", processing=processing)

# Sort primitives by type (separate triangles, lines, points)
processing = aiProcess_SortByPType | aiProcess_Triangulate
scene = pyassimp.load("mixed_primitives.ply", processing=processing)

Format Conversion

Coordinate system and data format conversions for different rendering pipelines.

# Coordinate system conversion
aiProcess_MakeLeftHanded = 0x4
aiProcess_FlipUVs = 0x800000
aiProcess_FlipWindingOrder = 0x1000000

# UV coordinate generation and transformation
aiProcess_GenUVCoords = 0x40000
aiProcess_TransformUVCoords = 0x80000

# Scene preprocessing
aiProcess_PreTransformVertices = 0x100
aiProcess_RemoveComponent = 0x10

Usage examples:

from pyassimp.postprocess import *

# DirectX/Direct3D conversion
processing = (aiProcess_MakeLeftHanded |
              aiProcess_FlipUVs |
              aiProcess_FlipWindingOrder)

scene = pyassimp.load("opengl_model.obj", processing=processing)

# Generate UV coordinates for non-UV mapped models
processing = aiProcess_GenUVCoords | aiProcess_Triangulate
scene = pyassimp.load("no_uvs.stl", processing=processing)

# Flatten scene hierarchy (remove transformations)
processing = aiProcess_PreTransformVertices | aiProcess_Triangulate
scene = pyassimp.load("hierarchical.dae", processing=processing)

Animation and Rigging

Processing options for animated models and skeletal data.

# Bone processing
aiProcess_LimitBoneWeights = 0x200
aiProcess_SplitByBoneCount = 0x2000000
aiProcess_Debone = 0x4000000

# Mesh instancing and duplicates
aiProcess_FindInstances = 0x100000

# Additional processing (note: these constants may have conflicts in source)
aiProcess_GenEntityMeshes = 0x100000
aiProcess_OptimizeAnimations = 0x200000  
aiProcess_FixTexturePaths = 0x200000

Usage examples:

from pyassimp.postprocess import *

# Optimize for hardware skinning (max 4 bones per vertex)
processing = (aiProcess_LimitBoneWeights |
              aiProcess_Triangulate)

scene = pyassimp.load("rigged_character.dae", processing=processing)

# Remove unnecessary bones
processing = aiProcess_Debone | aiProcess_Triangulate
scene = pyassimp.load("over_rigged.fbx", processing=processing)

Preset Combinations

Predefined processing combinations for common use cases.

# DirectX/Direct3D preset
aiProcess_ConvertToLeftHanded = (aiProcess_MakeLeftHanded | 
                                aiProcess_FlipUVs | 
                                aiProcess_FlipWindingOrder)

# Fast real-time rendering preset
aiProcessPreset_TargetRealtime_Fast = (aiProcess_CalcTangentSpace |
                                      aiProcess_GenNormals |
                                      aiProcess_JoinIdenticalVertices |
                                      aiProcess_Triangulate |
                                      aiProcess_GenUVCoords |
                                      aiProcess_SortByPType)

# Quality real-time rendering preset  
aiProcessPreset_TargetRealtime_Quality = (aiProcess_CalcTangentSpace |
                                         aiProcess_GenSmoothNormals |
                                         aiProcess_JoinIdenticalVertices |
                                         aiProcess_ImproveCacheLocality |
                                         aiProcess_LimitBoneWeights |
                                         aiProcess_RemoveRedundantMaterials |
                                         aiProcess_SplitLargeMeshes |
                                         aiProcess_Triangulate |
                                         aiProcess_GenUVCoords |
                                         aiProcess_SortByPType |
                                         aiProcess_FindDegenerates |
                                         aiProcess_FindInvalidData)

# Maximum quality preset
aiProcessPreset_TargetRealtime_MaxQuality = (aiProcessPreset_TargetRealtime_Quality |
                                            aiProcess_FindInstances |
                                            aiProcess_ValidateDataStructure |
                                            aiProcess_OptimizeMeshes)

Usage examples:

from pyassimp.postprocess import *

# Use preset for DirectX applications
scene = pyassimp.load("model.obj", processing=aiProcess_ConvertToLeftHanded)

# Use preset for fast loading
scene = pyassimp.load("model.dae", processing=aiProcessPreset_TargetRealtime_Fast)

# Use preset for maximum quality
scene = pyassimp.load("model.blend", processing=aiProcessPreset_TargetRealtime_MaxQuality)

# Combine preset with custom flags
custom_processing = aiProcessPreset_TargetRealtime_Quality | aiProcess_FixTexturePaths
scene = pyassimp.load("model.x", processing=custom_processing)

Advanced Usage Patterns

Conditional Processing

Apply different processing based on model characteristics:

import pyassimp
from pyassimp.postprocess import *

def load_with_smart_processing(filename):
    # Basic load to inspect model
    scene = pyassimp.load(filename, processing=0)  # No processing
    
    processing = aiProcess_Triangulate  # Always triangulate
    
    # Add processing based on model characteristics
    if len(scene.meshes) > 100:
        processing |= aiProcess_OptimizeMeshes
    
    if any(len(mesh.faces) > 10000 for mesh in scene.meshes):
        processing |= aiProcess_SplitLargeMeshes
    
    if any(not hasattr(mesh, 'normals') or not mesh.normals for mesh in scene.meshes):
        processing |= aiProcess_GenSmoothNormals
    
    # Release initial scene and reload with proper processing
    pyassimp.release(scene)
    return pyassimp.load(filename, processing=processing)

Processing Pipeline

Chain multiple processing steps:

from pyassimp.postprocess import *

def create_processing_pipeline(target="realtime"):
    """Create processing pipeline for different targets."""
    
    base = aiProcess_Triangulate | aiProcess_JoinIdenticalVertices
    
    if target == "realtime":
        return base | aiProcess_GenSmoothNormals | aiProcess_ImproveCacheLocality
    elif target == "quality":
        return base | aiProcess_CalcTangentSpace | aiProcess_OptimizeMeshes
    elif target == "directx":
        return base | aiProcess_ConvertToLeftHanded
    elif target == "validation":
        return base | aiProcess_ValidateDataStructure | aiProcess_FindInvalidData
    else:
        return base

# Usage
scene = pyassimp.load("model.obj", processing=create_processing_pipeline("quality"))

Performance Considerations

Processing Time: More flags = longer processing time
Memory Usage: Some flags increase memory usage (e.g., tangent calculation)
Quality vs Speed: Balance processing quality with loading performance
Format-Specific: Some formats benefit more from certain processing steps
Order Independence: Processing flags are applied in optimal order automatically

Common Processing Combinations

from pyassimp.postprocess import *

# Game development (fast rendering)
GAME_PROCESSING = (aiProcess_Triangulate | 
                  aiProcess_JoinIdenticalVertices |
                  aiProcess_GenSmoothNormals |
                  aiProcess_ImproveCacheLocality)

# Visualization (quality focus)
VIZ_PROCESSING = (aiProcess_Triangulate |
                 aiProcess_CalcTangentSpace |
                 aiProcess_GenSmoothNormals |
                 aiProcess_OptimizeMeshes)

# CAD import (data integrity)
CAD_PROCESSING = (aiProcess_Triangulate |
                 aiProcess_ValidateDataStructure |
                 aiProcess_FixInfacingNormals |
                 aiProcess_FindInvalidData)

# Mobile/WebGL (size optimization)
MOBILE_PROCESSING = (aiProcess_Triangulate |
                    aiProcess_JoinIdenticalVertices |
                    aiProcess_RemoveRedundantMaterials |
                    aiProcess_SplitLargeMeshes |
                    aiProcess_OptimizeGraph)

Install with Tessl CLI