PyObjC SceneKit Framework

Warnings

• breaking Python 3.9 support was dropped in PyObjC 12.0. Ensure your Python environment is 3.10 or later.
  Fix: Upgrade your Python installation to 3.10 or a newer supported version.
• breaking Python 3.8 support was dropped in PyObjC 11.0. Ensure your Python environment is 3.9 or later.
  Fix: Upgrade your Python installation to 3.9 or a newer supported version.
• gotcha PyObjC 11.1 changed how it models initializer methods ('init' family) to align with Clang's Automatic Reference Counting (ARC) documentation. Methods in the 'init' family now correctly steal a reference to `self` and return a new one.
  Fix: Review code that relies on precise reference counting for 'init' methods. In most cases, this change aligns with expected Objective-C behavior and should not require manual adjustments unless managing references explicitly.
• gotcha In PyObjC 10.3, support for calling `__init__` on Python classes that implement `__new__` was temporarily broken, then partially reintroduced in 10.3.1. If a class or its superclass has a user-implemented `__new__`, `__init__` can be used. Otherwise, if relying on PyObjC's `__new__`, `__init__` cannot be used.
  Fix: Ensure `__init__` is used correctly with `__new__` implementations, or avoid using `__init__` for classes relying on PyObjC's default `__new__`.
• gotcha PyObjC 12.1 automatically disables Key-Value Observing (KVO) usage for subclasses of `NSProxy` defined in Python to fix `SystemError` issues.
  Fix: If you are subclassing `NSProxy` in Python and relying on KVO, be aware that it will be automatically disabled. Consider alternative observation patterns or verify behavior.
• gotcha SceneKit methods that expect or return `vector_float3` or `vector_float4` arguments are not fully available from Python due to limitations in PyObjC's core bridge. This includes `SCNVector3ToFloat3` and `SCNVector3FromFloat3`.
  Fix: Use alternative methods for vector manipulation or handle vector data manually where these specific types are involved. The `objc.simd` package may offer some related functionality but direct SceneKit binding limitations remain.
• gotcha PyObjC framework wrappers, including SceneKit, do not include their own documentation. Refer to Apple's official SceneKit documentation for API details and usage.
  Fix: Consult Apple's developer documentation (e.g., via Xcode or online) for `SceneKit` classes and methods when working with `pyobjc-framework-scenekit`.

Install

• pip install pyobjc-framework-scenekit Install only SceneKit bindings
• pip install 'pyobjc[allbindings]' Install core PyObjC and all framework bindings

Imports

• SceneKit

  import SceneKit

  Provides access to all SceneKit classes, functions, and constants, e.g., SceneKit.SCNView, SceneKit.SCNScene.
• Cocoa

  from Cocoa import NSApplication, NSWindow, NSView

  Required for basic macOS application structure like windows and application loops.
• AppHelper

  from PyObjCTools import AppHelper

  Utility for managing the Cocoa application event loop.

Quickstart

This quickstart code initializes a basic macOS application window and embeds an SCNView. It then sets up a SceneKit scene with a camera, lights, and a simple rotating cube, allowing user camera control. The `AppHelper.runEventLoop()` ensures the Cocoa application event loop is started and managed.

import SceneKit
from Cocoa import NSApplication, NSWindow, NSView, NSRect, NSMakeRect
from PyObjCTools import AppHelper
import objc

class AppDelegate(objc.NSObject):
    def applicationDidFinishLaunching_(self, aNotification):
        print("SceneKit app launched!")

        # Create a window
        rect = NSMakeRect(100, 100, 640, 480)
        self.window = NSWindow.alloc().initWithContentRect_styleMask_backing_defer_(
            rect, 
            (1 << 0) | (1 << 1) | (1 << 2), # NSWindowStyleMaskTitled | NSWindowStyleMaskClosable | NSWindowStyleMaskMiniaturizable
            2, # NSBackingStoreBuffered
            False
        )
        self.window.setTitle_("PyObjC SceneKit Cube")
        
        # Create an SCNView (SceneKit view)
        self.scnView = SceneKit.SCNView.alloc().initWithFrame_(rect)
        self.window.setContentView_(self.scnView)

        # Create a scene
        scene = SceneKit.SCNScene.scene()
        self.scnView.setScene_(scene)

        # Create a camera and add it to a node
        camera = SceneKit.SCNCamera.camera()
        cameraNode = SceneKit.SCNNode.node()
        cameraNode.setCamera_(camera)
        cameraNode.setPosition_(SceneKit.SCNVector3(0, 0, 15))
        scene.rootNode().addChildNode_(cameraNode)
        self.scnView.setPointOfView_(cameraNode)

        # Create a light and add it to a node
        light = SceneKit.SCNLight.light()
        light.setType_(SceneKit.SCNLightTypeOmni)
        lightNode = SceneKit.SCNNode.node()
        lightNode.setLight_(light)
        lightNode.setPosition_(SceneKit.SCNVector3(0, 10, 10))
        scene.rootNode().addChildNode_(lightNode)

        # Create an ambient light
        ambientLight = SceneKit.SCNLight.light()
        ambientLight.setType_(SceneKit.SCNLightTypeAmbient)
        ambientLight.setColor_(SceneKit.SCNColor.colorWithRed_green_blue_alpha_(0.1, 0.1, 0.1, 1.0))
        ambientLightNode = SceneKit.SCNNode.node()
        ambientLightNode.setLight_(ambientLight)
        scene.rootNode().addChildNode_(ambientLightNode)

        # Create a cube geometry
        box = SceneKit.SCNBox.boxWithWidth_height_length_chamferRadius_(5.0, 5.0, 5.0, 0.5)
        boxNode = SceneKit.SCNNode.nodeWithGeometry_(box)
        scene.rootNode().addChildNode_(boxNode)
        
        # Allow the user to manipulate the camera
        self.scnView.setAllowsCameraControl_(True)

        self.window.makeKeyAndOrderFront_(None)

def main():
    app = NSApplication.sharedApplication()
    delegate = AppDelegate.alloc().init()
    app.setDelegate_(delegate)
    AppHelper.runEventLoop()

if __name__ == '__main__':
    main()