PyObjC ModelIO Framework

Warnings

• breaking PyObjC releases frequently drop support for older Python versions. For example, v12.0 dropped Python 3.9, and v11.0 dropped Python 3.8. Ensure your Python version meets the `requires_python` specification for the PyObjC version you are installing.
  Fix: Upgrade to a compatible Python version (e.g., Python 3.10+ for PyObjC 12.x) or use an older PyObjC version that supports your Python environment.
• breaking The automatic reference counting (ARC) behavior for Objective-C initializer methods (`init` family) was changed in PyObjC 11.1 to align with `clang`'s documentation. PyObjC now correctly models that these methods steal a reference to `self` and return a new reference, which can affect memory management if not accounted for.
  Fix: Review any custom `__new__` or `__init__` methods in Python subclasses of Objective-C classes, especially those mimicking initializer patterns, to ensure correct reference handling.
• gotcha PyObjC and all its framework bindings are macOS-specific. They cannot be installed or run on other operating systems (Windows, Linux, etc.), as they directly interface with macOS system frameworks.
  Fix: Develop and run PyObjC applications exclusively on macOS. For cross-platform development, consider alternative libraries.
• gotcha The interaction between Python's `__init__` and Objective-C's `__new__` was subtly changed in PyObjC 10.3 and then partially reverted in 10.3.1. Initially, `__init__` was disabled when `__new__` was provided by PyObjC, breaking some projects. Reintroduced `__init__` support if a user implements `__new__`.
  Fix: If experiencing issues with `__init__` not being called correctly on subclasses, especially when `__new__` is involved, ensure you are on PyObjC 10.3.1 or later. Review your `__new__` and `__init__` implementations for compatibility with PyObjC's object lifecycle.
• gotcha PyObjC has varying levels of support for Python's experimental free-threading (PEP 703). PyObjC 10.3 explicitly did *not* support it, while PyObjC 11 introduced experimental support for Python 3.13. Relying on free-threading with PyObjC can lead to instability or undefined behavior in certain versions.
  Fix: Avoid using PyObjC in a free-threading enabled Python environment unless explicitly stated as fully supported for your PyObjC version. Consult the PyObjC release notes for specific guidance on free-threading compatibility.

Install

• pip install pyobjc-framework-modelio Install latest version

Imports

• MDLAsset

  from ModelIO import MDLAsset

• MDLMesh

  from ModelIO import MDLMesh

Quickstart

This quickstart demonstrates how to create a simple 3D cube mesh using ModelIO, add it to an MDLAsset, and then export it to an OBJ file. This code is macOS-specific due to its reliance on Apple's ModelIO framework.

import os
from ModelIO import MDLAsset, MDLMesh, MDLMaterial
from Foundation import NSURL

# Note: ModelIO is a macOS-only framework for 3D asset manipulation.
# This code will only run on macOS.

def create_simple_asset():
    # Create a simple mesh (e.g., a cube)
    # newBoxWithDimensions_segments_geometryType_inwardNormals_allocator_ is a class method
    cube_mesh = MDLMesh.newBoxWithDimensions_segments_geometryType_inwardNormals_allocator_(
        (1.0, 1.0, 1.0),    # Dimensions (width, height, depth)
        (1, 1, 1),          # Number of segments along each dimension
        1,                  # MDLGeometryTypeTriangles = 1
        False,              # Inward normals
        None                # Allocator (None for default)
    )

    # Create a basic material
    material = MDLMaterial.alloc().initWithName_scatteringFunction_("MyMaterial", None)

    # Add the material to the mesh
    cube_mesh.addMaterial_(material)

    # Create an asset and add the mesh to it
    asset = MDLAsset.alloc().init()
    asset.addObjects_([cube_mesh])

    # Define a temporary path to save the asset
    temp_dir = '/tmp'
    if not os.path.exists(temp_dir):
        os.makedirs(temp_dir)
    output_path = os.path.join(temp_dir, "simple_cube.obj")
    output_url = NSURL.fileURLWithPath_(output_path)

    # Export the asset to a file (e.g., OBJ format)
    # ModelIO supports various formats, but OBJ is simple.
    # exportAssetToURL_ is an instance method
    asset.exportAssetToURL_(output_url)

    print(f"Successfully created and saved a simple 3D asset to: {output_path}")

if __name__ == "__main__":
    create_simple_asset()