cmeel-assimp

Common errors

• ImportError: No module named pyassimp

  cause The user is trying to import 'assimp' directly, or 'pyassimp' was not correctly installed as the interface for cmeel-assimp.
  fix Ensure you are importing 'load' or other symbols from `pyassimp`, not `assimp`. For example: `from pyassimp import load`. If the module is not found, verify `pip install cmeel-assimp` ran successfully.

• AssimpError: Could not import file 'your_model.obj'

  cause This error typically indicates that the specified 3D model file either does not exist, is corrupted, or is in an unsupported format, or the underlying Assimp C++ library failed to parse it.
  fix Double-check the file path and name. Ensure the model file is valid and readable. Assimp supports a wide range of formats, but extremely malformed or very new/uncommon formats might not be supported. Try with a known-good model file.

Warnings

• gotcha Direct modification of scene data loaded via pyassimp (and thus cmeel-assimp) and subsequent export may not be reflected. The library is primarily designed for importing and reading, not for in-place modification and export.
  Fix: For complex scene manipulations or exports after modification, consider using other 3D libraries or a different approach for editing the model data outside of pyassimp's scene structure before re-exporting.
• breaking Assimp C++ library versions, particularly around 6.0.0, introduced API changes (e.g., in enums). While cmeel-assimp aims to provide compatible Python bindings, direct usage of underlying C++ Assimp concepts or older Python binding patterns might break.
  Fix: Refer to the official pyassimp and Assimp documentation for updated API usage. Ensure your code aligns with the Python interface provided by cmeel-assimp's wrapped Assimp version.
• gotcha Although cmeel-assimp aims to bundle the Assimp C++ shared library, some exotic environments or custom builds might still encounter issues where the shared library (DLL on Windows, .so on Linux, .dylib on macOS) is not found.
  Fix: If 'library not found' errors occur after installation, verify system PATHs or LD_LIBRARY_PATH (Linux) / DYLD_LIBRARY_PATH (macOS) to ensure the Assimp shared library is discoverable. Re-installing in a clean environment or consulting `cmeel` documentation for debugging bundled libraries might be necessary.

Install

• pip install cmeel-assimp Install latest version

Imports

• load
  wrong:

  import assimp

  correct:

  from pyassimp import load

  cmeel-assimp provides the pyassimp API, so 'pyassimp' is the top-level import. Directly importing 'assimp' will fail.
• postprocess
  wrong:

  import assimp.postprocess

  correct:

  from pyassimp import postprocess

  Post-processing flags are part of the 'pyassimp.postprocess' module.

Quickstart

Loads a basic Wavefront OBJ file, demonstrates accessing mesh data (vertices and faces), and ensures proper scene release. It includes common post-processing flags for triangulation and normal generation.

import os
from pyassimp import load, postprocess

# Create a dummy model file for demonstration
dummy_model_content = """
# Wavefront .obj file
# A simple triangle

v 0.0 0.0 0.0
v 1.0 0.0 0.0
v 0.0 1.0 0.0

f 1 2 3
"""

model_path = 'dummy_triangle.obj'
with open(model_path, 'w') as f:
    f.write(dummy_model_content)

try:
    # Load a 3D model with basic post-processing
    # Use aiProcess_Triangulate to ensure all faces are triangles
    # Use postprocess.aiProcess_GenNormals to generate smooth normals if not present
    scene = load(model_path, processing=postprocess.aiProcess_Triangulate | postprocess.aiProcess_GenNormals)

    print(f"Successfully loaded model: {model_path}")
    print(f"Number of meshes in scene: {len(scene.meshes)}")
    
    if scene.meshes:
        mesh = scene.meshes[0]
        print(f"First mesh has {len(mesh.vertices)} vertices and {len(mesh.faces)} faces.")
        if mesh.vertices:
            print(f"First vertex: {mesh.vertices[0]}")
        if mesh.faces:
            print(f"First face (indices): {mesh.faces[0]}")
    
    # It's good practice to release the scene explicitly when done
    scene.release()

except Exception as e:
    print(f"Error loading model: {e}")
finally:
    # Clean up the dummy model file
    if os.path.exists(model_path):
        os.remove(model_path)