{"id":6143,"library":"pyobjc-framework-modelio","title":"PyObjC ModelIO Framework","description":"pyobjc-framework-modelio provides Python bindings for Apple's ModelIO framework, enabling macOS applications to work with 3D assets, meshes, materials, and other related data. As part of the larger PyObjC project, it typically releases new versions to align with new macOS SDKs, with version 12.1 being the current stable release.","status":"active","version":"12.1","language":"en","source_language":"en","source_url":"https://github.com/ronaldoussoren/pyobjc","tags":["macos","objective-c","framework","graphics","3d","modelio"],"install":[{"cmd":"pip install pyobjc-framework-modelio","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Provides the core bridge between Python and Objective-C, essential for all PyObjC framework bindings.","package":"pyobjc-core","optional":false},{"reason":"ModelIO often relies on fundamental Cocoa types and functionalities, making it a common indirect or direct dependency.","package":"pyobjc-framework-Cocoa","optional":false}],"imports":[{"symbol":"MDLAsset","correct":"from ModelIO import MDLAsset"},{"symbol":"MDLMesh","correct":"from ModelIO import MDLMesh"}],"quickstart":{"code":"import os\nfrom ModelIO import MDLAsset, MDLMesh, MDLMaterial\nfrom Foundation import NSURL\n\n# Note: ModelIO is a macOS-only framework for 3D asset manipulation.\n# This code will only run on macOS.\n\ndef create_simple_asset():\n    # Create a simple mesh (e.g., a cube)\n    # newBoxWithDimensions_segments_geometryType_inwardNormals_allocator_ is a class method\n    cube_mesh = MDLMesh.newBoxWithDimensions_segments_geometryType_inwardNormals_allocator_(\n        (1.0, 1.0, 1.0),    # Dimensions (width, height, depth)\n        (1, 1, 1),          # Number of segments along each dimension\n        1,                  # MDLGeometryTypeTriangles = 1\n        False,              # Inward normals\n        None                # Allocator (None for default)\n    )\n\n    # Create a basic material\n    material = MDLMaterial.alloc().initWithName_scatteringFunction_(\"MyMaterial\", None)\n\n    # Add the material to the mesh\n    cube_mesh.addMaterial_(material)\n\n    # Create an asset and add the mesh to it\n    asset = MDLAsset.alloc().init()\n    asset.addObjects_([cube_mesh])\n\n    # Define a temporary path to save the asset\n    temp_dir = '/tmp'\n    if not os.path.exists(temp_dir):\n        os.makedirs(temp_dir)\n    output_path = os.path.join(temp_dir, \"simple_cube.obj\")\n    output_url = NSURL.fileURLWithPath_(output_path)\n\n    # Export the asset to a file (e.g., OBJ format)\n    # ModelIO supports various formats, but OBJ is simple.\n    # exportAssetToURL_ is an instance method\n    asset.exportAssetToURL_(output_url)\n\n    print(f\"Successfully created and saved a simple 3D asset to: {output_path}\")\n\nif __name__ == \"__main__\":\n    create_simple_asset()\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=11.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=11.1"},{"fix":"Develop and run PyObjC applications exclusively on macOS. For cross-platform development, consider alternative libraries.","message":"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.","severity":"gotcha","affected_versions":"all"},{"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.","message":"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__`.","severity":"gotcha","affected_versions":"10.3 - 10.3.1"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=10.3"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z"}