OpenSceneGraph 0.1.1__cp312-cp312-win_amd64.whl

OpenSceneGraph/__init__.py

@@ -0,0 +1,52 @@
+"""Public Python package for the OpenSceneGraph native bindings.
+
+The compiled implementation remains private so this package can grow Python
+helpers, utilities, and examples without changing the public import surface.
+"""
+
+
+# start delvewheel patch
+def _delvewheel_patch_1_13_1():
+    import os
+    if os.path.isdir(libs_dir := os.path.abspath(os.path.join(os.path.dirname(__file__), os.pardir, 'openscenegraph.libs'))):
+        os.add_dll_directory(libs_dir)
+
+
+_delvewheel_patch_1_13_1()
+del _delvewheel_patch_1_13_1
+# end delvewheel patch
+
+import os as _os
+from pathlib import Path as _Path
+
+# The core extension's directory contains the project-built OSG DLLs and ktx.
+# osgDB loads format plugins from its child directory later; on Windows those
+# plugins need their parent DLL directory in the process search path too.
+_dll_directory = None
+_plugin_dll_directory = None
+_package_directory = _Path(__file__).parent
+_plugin_directory = _package_directory / "osgPlugins-3.6.5"
+if _os.name == "nt":
+	# osgDB loads plugins through legacy LoadLibrary(), which does not honor
+	# Python's add_dll_directory() entries.  Keep both directories on PATH for
+	# their transitive DLL dependencies as well.
+	_os.environ["PATH"] = _os.pathsep.join(
+		(str(_package_directory), str(_plugin_directory), _os.environ.get("PATH", ""))
+	)
+	if hasattr(_os, "add_dll_directory"):
+		_dll_directory = _os.add_dll_directory(str(_package_directory))
+		_plugin_dll_directory = _os.add_dll_directory(str(_plugin_directory))
+
+from ._OpenSceneGraph import * # noqa: F401,F403
+from . import _OpenSceneGraph as _native
+
+import sys as _sys
+
+# The native extension creates these submodules. Publish them under their
+# long-standing public paths, so both old and package-style imports work.
+for _name in ("osg", "osgAnimation", "osgUtil", "osgDB", "osgGA", "osgViewer", "GL"):
+	_sys.modules[f"{__name__}.{_name}"] = getattr(_native, _name)
+
+__all__ = [name for name in dir(_native) if not name.startswith("_")]
+
+del _name, _native, _sys, _os, _Path

OpenSceneGraph/aipython/00-index.md

@@ -0,0 +1,44 @@
+# aipython + OpenSceneGraph.py — Index
+
+This directory is OpenSceneGraph.py's accumulated knowledge for driving a
+live OSG viewer through the `aipython` MCP bridge (tmux or Jupyter-kernel
+backed IPython). It exists because this project's REPL setup has sharp,
+non-obvious edges that get rediscovered by trial and error unless written
+down.
+
+**Always read [`01-core.md`](01-core.md) first**, in any session that's
+about to drive `viewer.frame()` live via `aipython`, before writing any
+callback or running any multi-line block through a tmux-backed session.
+
+Read the others situationally:
+
+| File | Read when... |
+|---|---|
+| [`01-core.md`](01-core.md) | Always, first. Session bootstrap, callback safety, tmux/IPython mechanics, and the Pythonic-vs-raw-OSG binding surface. |
+| [`02-inspect.md`](02-inspect.md) | Handed a live viewer or loaded scene you didn't build — get a real read on its structure/shaders/uniforms instead of guessing. |
+| [`03-headless-frames.md`](03-headless-frames.md) | Testing callbacks, events, visitors, or Python/C++ trampolines without behavior that genuinely needs a Viewer, graphics context, cull, or draw traversal. |
+| [`05-camera-manipulator.md`](05-camera-manipulator.md) | Building/customizing an `osgGA.CameraManipulator` subclass, or doing camera-relative work (e.g. "light the subject from the camera's upper-right"). |
+| [`06-camera-effects.md`](06-camera-effects.md) | Layering a TEMPORARY camera effect (shake, kick, scripted move) on top of the user's live manipulator without taking control away. |
+| [`07-camera-manual.md`](07-camera-manual.md) | Driving `viewer.camera` directly with NO manipulator (a fixed/orthographic camera) — `realize()`-before-matrices ordering, near/far, and viewport-confinement gotchas. |
+| [`08-lighting.md`](08-lighting.md) | Getting PBR/IBL lighting going via `osgx`'s `#pragma osgx::*` shader-library system — fastest path to a lit glTF model, plus the full IBL pipeline. |
+| [`09-picking.md`](09-picking.md) | Wiring `osgx` (hover/click) into a scene that ALSO has an `osgx.imgui.Widget` panel — three independent guards needed to block picking near/under ImGui. |
+| [`10-rtt.md`](10-rtt.md) | Building a render-to-texture / multi-camera scene graph live. **Read before debugging any fullscreen pass that outputs one flat color** — fullscreen quads must disable `GL_DEPTH_TEST` or they break silently once re-targeted to an FBO. |
+| [`11-mrt.md`](11-mrt.md) | Reading/writing multiple render targets, linearizing RTT depth with the actual effective camera projection, or combining pass callbacks with `osgx.imgui.Widget`. |
+| [`12-gbuffer.md`](12-gbuffer.md) | Designing a generic G-buffer or composing deferred/NPR post-process passes from canonical color, normal, and depth data. |
+| [`15-shader-hotswap.md`](15-shader-hotswap.md) | Debugging shader-side logic live by patching GLSL and hot-swapping a `Program`, or when a live variable reassignment "has no effect." |
+| [`17-particles.md`](17-particles.md) | Building a one-shot, GPU-only instanced particle/burst effect (fire, explosions, debris) driven by `osg_SimulationTime` + a `triggerTime` uniform, or wiring an `osgx.imgui` live-tuning panel on top of one. |
+| [`18-deterministic-captures.md`](18-deterministic-captures.md) | Capturing a precise, repeatable animation state by freezing an effect-local elapsed-time uniform instead of racing the realtime frame loop. |
+| [`20-object-lifetime.md`](20-object-lifetime.md) | Investigating a leak, a "removed but still alive" object, or verifying true C++ destruction vs. just scene-graph detachment. |
+| [`25-async-osgpy.md`](25-async-osgpy.md) | Any background OSG.py operation (not just glTF loading): push vs. poll, why a naive async loader can be *slower* than sync (GIL contention between the render pump and a push-based progress mechanism), making `viewer.frame()` an ordinary `asyncio` task, and where the ceiling is (GIL, non-preemptible `frame()`, cooperative cancellation). Read before assuming async is "free" overlap with rendering. |
+| [`29-material.md`](29-material.md) | Setting a PBR material (base color/roughness/metallic/maps) on any Drawable via `osgx.Material` — a real `osg.StateAttribute`. Read before `30-pbribl.md` if you just need factors on a shape, no full IBL renderer. |
+| [`30-pbribl.md`](30-pbribl.md) | Applying `osgx.gltf.pbribl`'s full reflective PBR/IBL renderer to ordinary OSG geometry such as `ShapeDrawable`. |
+| [`40-typed-lights-gizmos.md`](40-typed-lights-gizmos.md) | Adding typed direct/punctual lights (`osgx.LightSet` — Point/Directional/Spot/Sphere) and their debug gizmos (`osgx.LightGizmos`/`osgx.LightMarkers`) to a live scene; also documents the `osgx_DirectLighting()` hook contract every direct-lit shader should call into. |
+
+## Why this exists as `aipython/*.md` and not a Claude Code skill
+
+Deliberately a plain, agent-agnostic directory of markdown files at the repo
+root, not `.claude/skills/`. Multiple agentic tools (Claude Code, Codex,
+others) use this project via the `aipython` MCP server; a Claude-Code-specific
+location would hide this from the rest. An agent working in this repo should
+proactively `ls`/`Read` this directory before starting REPL work here, the
+same way it would check `CLAUDE.md`.

OpenSceneGraph/aipython/01-core.md

@@ -0,0 +1,255 @@
+# Core rules for any OSG.py + aipython REPL session
+
+Read this before driving `viewer.frame()` live, writing any callback, or sending
+multi-line code through a tmux-backed session.
+
+## 1. Launch `pyosg_repl.py` directly — never from inside an already-running `ipython3`
+
+`repl(viewer, namespace)` embeds its own IPython shell (`InteractiveShellEmbed`).
+Launching a bare `ipython3` first and calling `repl()` from inside it raises:
+
+```
+MultipleInstanceError: An incompatible sibling of 'InteractiveShellEmbed' is
+already instanciated as singleton: TerminalInteractiveShell
+```
+
+Run the script directly (`python3 pyosg_repl.py`) so `repl()` is the first shell
+created. Edit the `if __name__ == "__main__":` block for a custom scene instead
+of driving a pre-existing prompt.
+
+## 2. Bind free variables into callbacks as default args
+
+C++-invoked callbacks (draw callbacks, `osgx.imgui` sections, `debug=` deletion
+callbacks, `NodeCallback`/`updateCallback`, event handlers) can fail to resolve
+names defined at the prompt after the shell embedded — `user_ns` and
+`user_module.__dict__` can be separate dicts. The terminal backend merges them
+at embed time, but defend anyway:
+
+```python
+spin_xform.updateCallback = lambda node, nv, osg=osg: setattr(
+	node, "matrix", osg.Matrix.rotate(nv.frameStamp.simulationTime * 0.4, osg.Vec3(0, 0, 1))
+)
+```
+
+Consequences differ by callback type:
+- A `DrawCallback` exception crashes the render thread/process.
+- An `osgx.imgui` section exception corrupts ImGui's frame state; the *next*
+  frame hard-aborts the process — no `try/except` catches this after the fact.
+- A `NodeCallback`/`updateCallback` exception doesn't crash but silently
+  breaks the update traversal every frame — queued captures stop resolving,
+  input stops responding. Check `_osg_repl_state` and try a plain
+  `viewer.frame()` to surface the real traceback.
+- A `debug=<callable>` deletion callback (see [`20-object-lifetime.md`](20-object-lifetime.md))
+  hits the same error from an ordinary GC destructor call, main thread, no
+  render loop involved.
+
+If wrapping defensively: set a one-shot "done" flag before risky code, wrap
+the body in `try/except Exception:`, write results to a file rather than a
+shared Python object — `except: pass` makes failures silent, not absent.
+
+## 3. `os.environ.setdefault()`, never `.update()`, in shared helper modules
+
+An unconditional `os.environ.update(...)` in a helper (e.g. `pyosg_repl.py`)
+clobbers a caller's already-set `OSG_WINDOW`/`OSG_THREADING`/etc. back to the
+helper's defaults. `Viewer::realize()` doesn't read `OSG_WINDOW` until the
+first `frame()` call, so this can look like an unrelated timing/display bug
+well after import. Use `setdefault()`.
+
+## 4. Multi-line code sent through tmux is fragile
+
+IPython's terminal autoindent stacks on top of pasted indentation and can
+cascade into `IndentationError`, or silently corrupt a triple-quoted string.
+
+- Send `%autoindent off` as the first command in any tmux session, once.
+- Prefer single-line forms (lambdas, `exec("...")`) for anything defined live.
+- After a large block, call `capture()` again explicitly rather than trusting
+  `execute()`'s returned text, which can be a stale snapshot.
+
+Most reliable way to run a nontrivial script live — two single-line
+statements, neither has an indented continuation:
+
+```python
+p = "/absolute/path/to/script.py"
+exec(compile(open(p).read(), p, "exec"), locals())
+```
+
+Two requirements:
+- Use the real absolute path as the `compile()` filename — a fake name makes
+  `stack_data`/`executing` throw and replaces the real traceback with a wrong
+  one pointing at unrelated code.
+- Pass `locals()` explicitly. `globals() is locals()` is `False` at this
+  shell's top-level prompt (top-level-await wraps each cell in an async
+  function), so a bare `exec(code)` binds any `def`'s `__globals__` to a dict
+  missing `osg`/`viewer`/etc., raising `NameError` only when that function is
+  later called from elsewhere.
+
+## 5. `help(x)` hangs the session
+
+Opens a pager; the tmux pane blocks waiting for input (`idle: false` forever).
+Send `"q"` to unstick it, confirm recovery with a throwaway `execute()`.
+Prefer `x.__doc__` instead.
+
+## 6. Screenshots: use the controller's queued capture, never bare `readPixels()`
+
+```python
+# BROKEN — the GL context isn't necessarily current here; silently returns
+# all-zero (black) data, no exception:
+img = osg.Image()
+img.readPixels(0, 0, w, h, GL_RGB, GL_UNSIGNED_BYTE)
+
+# WORKS — queued into the render loop's own finalDrawCallback, context
+# guaranteed current:
+result = await _osg_repl_controller.capture_framebuffer("/tmp/shot.png")
+```
+
+If a screenshot comes back black, rule out the capture path first (check the
+window directly, check `_osg_repl_state["frames"]` is incrementing) before
+assuming the scene is broken. Confirmed reliable on the terminal/tmux backend;
+the ipykernel backend has crashed outright on this call — treat as unproven
+there.
+
+### Model controls facade
+
+```python
+controls = _osg_repl_controls
+
+controls.input.locked = True       # swallow human mouse/keyboard input
+controls.frames.target_fps = None  # uncapped — never "lock the user out"
+controls.frames.target_fps = 30
+controls.frames.paused = True
+print(controls.status)
+```
+
+FRAME/resize/close events still pass through while input is locked.
+`controls.window.always_on_top` uses `osgx.platform.alwaysOnTop()`. For a
+short MP4 with no intermediate image files:
+
+```python
+controls.capture.video("/tmp/take.mp4", fps=24, duration=5)
+print(controls.capture.video_status)
+```
+
+Samples in the final-draw callback on a monotonic wall-clock schedule and
+streams RGB directly to FFmpeg; the call returns immediately. Pass
+`lock_input=True` only when the capture must be deterministic. Readback is
+still synchronous `readPixels()` in the draw callback, not yet PBO/fence-backed.
+A resize during a take fails that capture.
+
+## 7. Backend choice: tmux vs. kernel
+
+- **tmux**: visible, attachable (`tmux attach -t <name>`), the only backend
+  screenshot capture is confirmed on. `execute()`'s returned text can be a
+  stale snapshot for slow calls — always `capture()` again before assuming
+  something is stuck.
+- **kernel**: structured JSON, better for programmatic inspection — but slow
+  calls have hung 120s+ on things that finish quickly via tmux, and async
+  screenshot capture has crashed the session outright. Less proven for this
+  project's live-viewer workflow.
+
+If a session looks frozen on either backend, check rule 2 first — it's the
+most common actual cause, not a backend bug.
+
+## 8. `viewer.frame()` doesn't release the GIL under `SingleThreaded`
+
+Deliberate: OSG can drop the last `ref_ptr` on a GL-tracked object during
+`frame()`'s own flush pass, and that pybind11 wrapper's destructor needs the
+GIL to deregister. Releasing the GIL during `frame()` under `SingleThreaded`
+(this project's standing default) aborts the process
+(`PyGILState_Check()` failure, no Python traceback) the moment a live scene
+graph is replaced while already running. `pyosg/pyosgViewer.cpp`'s `frame()`
+binding only releases the GIL when `threadingModel != SingleThreaded` — don't
+"fix" this by releasing it unconditionally.
+
+## 9. OSG's matrix and quaternion multiplication order is reversed vs. GLSL
+
+OSG is row-vector (`v' = v * M`), GLSL is column-vector (`v' = M * v`). A
+chain that reads left-to-right in GLSL (`A * B * C_vec`, apply `C` first)
+must be written reversed in Python/OSG (`C_vec_source * B * A`). Translation
+lives in **row 3**, not column 3. See [`ai/context-core.md`](../ai/context-core.md)
+for the full derivation.
+
+`osg.Quat` has the same reversed convention: `q1 * q2` applied to a vector
+applies `q1` first, then `q2` — opposite of the standard Hamilton product.
+Don't extend this rule to a new case by analogy; verify empirically:
+
+```python
+combined = a * b
+print(combined * known_vector)  # does this match "apply a, then b", or the reverse?
+```
+
+## 10. `MatrixTransform.matrix` is a live C++ alias, not a snapshot
+
+`getMatrix()` returns `const osg::Matrix&`; reading `.matrix` aliases the
+transform's native matrix. Rebuilding a pose from "rest" each frame using a
+bare read compounds every update:
+
+```python
+rest = transform.matrix
+transform.matrix = osg.Matrix.rotate(angle, axis) * rest  # WRONG — rest aliases the live matrix
+```
+
+Take an explicit copy once:
+
+```python
+rest = osg.Matrix(transform.matrix)
+
+def update(node, nv):
+	transform.matrix = osg.Matrix.rotate(angle, axis) * rest
+	return True
+```
+
+`test/osg_Transform.py::test_matrixtransform_matrix_is_a_live_reference` locks
+this down.
+
+## 11. Title any extra debug `osgViewer.Viewer()` window
+
+Any REPL-created `osgViewer.Viewer()` beyond the user's primary session
+viewer should be titled immediately after `realize()`, before pumping visible
+frames — otherwise identical-looking windows become impossible to tell apart:
+
+```python
+osgx.platform.setWindowTitle(viewer, "SOME-DESCRIPTIVE-LABEL")
+```
+
+Pick a label describing what's different about this one. Close throwaway
+windows explicitly (`viewer.close()`) once done.
+
+## 12. This binding reshapes OSG's C++ API into Python idiom — check for that surface before reaching for a raw `get`/`set`/`add` method
+
+`pyosg`/`osgx` deliberately do not mirror OSG's C++ API 1:1. A method or
+shape that isn't in OSG's C++ headers at all is often the *intended* way to
+do something — don't fall back to a `get*`/`set*`/`add*`/`remove*` call just
+because that's what the C++ docs show. Check `dir(obj)` or a live REPL probe
+before assuming the raw method is the only path.
+
+Recognizable patterns:
+
+- Child/array-of-object members are Python sequences, not `add*`/`remove*`/
+  `insert*`/`get*At` method quartets: `node.children.append(x)`,
+  `geode.drawables[i]`, `program.shaders`, `geometry.primitiveSets`,
+  `view.eventHandlers` (`pyx::bind_proxy_property`, `etc/pybind11x.hpp`).
+- `StateSet.uniforms`/`.attributes`/`.textureAttributes` are dict-like
+  (`MappingProxy`): `ss.uniforms["name"] = value` adds-or-replaces. Never
+  guard with `if "name" in ss.uniforms:` first — the assignment already
+  handles both cases.
+- `Uniform` values read/write through `.value`, not `.getFloat()`/`[0]`. A
+  `vecN` assignment needs an explicit `osg.Vec3/Vec4(*t)` — a bare tuple
+  raises `GL_INVALID_OPERATION` at draw time, not at assignment time.
+- `node.stateSet` is `getOrCreateStateSet()` (forces a new `StateSet` if
+  none exists). Use the module-level `osg.getStateSet(node)` instead when a
+  `None` result matters (read-only inspection, see `02-inspect.md`).
+- A class-scoped `py::enum_<>` calls `.export_values()`: its members are
+  reachable both fully qualified (`GUIEventAdapter.EventType.KEYDOWN`) and
+  flattened onto the owning class (`GUIEventAdapter.KEYDOWN` — the form
+  every example in this repo actually uses), mirroring OSG's own unscoped
+  C++ enum. A MODULE-scoped enum does NOT do this (`osg.NotifySeverity` is
+  the one example) — `osg.INFO`/`osg.WARN` sitting bare at module scope
+  next to every class would be a real collision risk, so only the qualified
+  form (`osg.NotifySeverity.INFO`) exists for those.
+
+`OVERVIEW.md` (repo root, regenerated by
+`etc/scripts/generate-bindings-overview.py`) is the current census of every
+bound symbol, but it reports raw pybind11 shape (`method`/`property`/`enum
+value`/...) — it doesn't say which of those is the intended Pythonic entry
+point for a task. Cross-check against this rule, not just against a symbol
+merely existing in that file.

OpenSceneGraph/aipython/02-inspect.md

@@ -0,0 +1,81 @@
+# Inspecting a scene graph you didn't build
+
+When handed a live viewer or a loaded scene with no prior context, don't
+reconstruct its structure by re-reading source or guessing at `StateSet`
+contents. Fire `GatherVisitor` at it: every node's type/name, every attached
+`Program` (plus each `Shader`'s type and a source preview), every `Uniform`
+(name + type), all via `osg.notice()`.
+
+```python
+from pyosg_visitor import GatherVisitor
+
+osg.setNotifyLevel(osg.NotifySeverity.NOTICE)  # GatherVisitor reports via osg.notice()
+
+viewer.sceneData.accept(GatherVisitor())
+```
+
+`pyosg_visitor.py` lives in `examples/`, alongside `pyosg_repl.py` — a plain
+`from pyosg_visitor import GatherVisitor` resolves when your script also
+lives there. From a subdirectory, fix `sys.path` first:
+
+```python
+import pathlib, sys
+
+examples_dir = pathlib.Path(__file__).resolve().parent.parent
+
+if str(examples_dir) not in sys.path:
+	sys.path.insert(0, str(examples_dir))
+
+from pyosg_visitor import GatherVisitor
+```
+
+## "Which Python variable is this?" — the `namespace=` hint
+
+Pass `locals()`/`globals()` in and any gathered object whose `.addr` matches
+a bare name in that dict gets an extra hint appended:
+
+```python
+viewer.sceneData.accept(GatherVisitor(namespace=globals()))
+```
+
+```
+[gather] Camera 'Composite HUD' (bound to local: 'hud_cam')
+  [gather] Uniforms: ['colorTex', 'depthTex', 'invProjectionMatrix', ...]
+    invProjectionMatrix: type=Type.FLOAT_MAT4 (bound to local: 'inv_proj_u')
+    colorTex: type=Type.INT
+```
+
+This is a reverse lookup (`.addr` → matching names, computed once at
+construction), not a live namespace walk — it only finds bare top-level
+names. An object only reachable via a chain (e.g.
+`hud_cam.stateSet.attributes[PROGRAM]`, never assigned its own name) gets no
+hint; that's expected.
+
+## Reading a `StateSet`'s attached attributes
+
+`osg.getStateSet(node)` is a **module-level function**, deliberately not a
+`Node` method — `node.stateSet` (`getOrCreateStateSet()`) forces a new empty
+`StateSet` onto every node it touches, which a read-only visitor must avoid.
+
+`StateSet.attributes[]` is a `MappingProxy` keyed by `StateAttribute::Type`,
+same shape as `.uniforms`/`.textureAttributes`, and does real polymorphic
+downcasting (`ss.attributes[PROGRAM]` returns a real `osg.Program`):
+
+```python
+ss.attributes.append(program)                           # key inferred from program.type
+ss.attributes[osg.StateAttribute.PROGRAM] = program      # explicit key, must match program.type
+ss.attributes[osg.StateAttribute.PROGRAM] = (program, osg.StateAttribute.OVERRIDE)
+```
+
+**Known limitation:** `.attributes[]` only ever addresses `member=0`
+(`StateAttribute::getMember()`, overridden by `ClipPlane`/`Light` for
+OpenGL's numbered fixed-function slots). Neither is bound in Python yet, so a
+`StateSet` holding multiple attributes of the same `Type` at different
+members currently only shows one via `.attributes[]`/`keys()`.
+
+## See also
+
+- [`15-shader-hotswap.md`](15-shader-hotswap.md) — once you know which
+  `Program`/`Shader` you're looking at, patch its GLSL and hot-swap it live.
+- [`20-object-lifetime.md`](20-object-lifetime.md) — scene *structure* (this
+  file) vs. object *lifetime* (is it really destroyed, not just detached).

OpenSceneGraph/aipython/03-headless-frames.md

@@ -0,0 +1,149 @@
+# Headless event and update frames
+
+Do not create an `osgViewer.Viewer` merely to make OSG callbacks run in a
+unit test. A Viewer brings windows, graphics contexts, event polling, camera
+setup, cull traversal, and draw traversal — only pay that tax when the
+behavior under test actually depends on one of those things. For update
+callbacks, event callbacks, deterministic animation, or Python/C++
+trampoline dispatch, use OSG's existing visitors directly.
+
+## Pytest: use the fixture
+
+`test/conftest.py` provides a fresh `simulate_frame` fixture per test. It
+owns a `FrameStamp`, `EventQueue`, `EventVisitor`, `UpdateVisitor`, and a
+recording Python `GUIActionAdapter`.
+
+```python
+def test_update_callback(simulate_frame):
+	root = osg.Group()
+	seen = []
+
+	root.updateCallback = lambda node, visitor: seen.append(
+		visitor.frameStamp.simulationTime
+	)
+
+	simulate_frame.advance(simulationTime=1.25)
+	simulate_frame.traverseUpdate(root)
+
+	assert seen == [1.25]
+```
+
+For event callbacks, queue events and traverse them:
+
+```python
+root.eventCallback = lambda node, visitor: ...
+
+simulate_frame.advance(simulationTime=0.0)
+simulate_frame.events.keyPress(ord("A"))
+simulate_frame.events.frame(0.0)
+simulate_frame.traverseEvents(root)
+```
+
+`simulate_frame.actions` records `requestRedraw()`,
+`requestContinuousUpdate()`, and `requestWarpPointer()` calls. Assert against
+`redraws`, `continuousUpdates`, or `pointerWarps`.
+
+## Forcing a real C++ virtual call
+
+A direct call such as `manip.handle(event, actions)` is not trampoline-proof
+— ordinary Python attribute lookup can find a Python subclass method without
+entering the C++ virtual-dispatch path. Call through the bound OSG base class
+instead, so C++ uses the object's vtable and reaches the pybind trampoline
+exactly as real OSG dispatch would:
+
+```python
+simulate_frame.dispatchEvent(manipulator, event)
+CameraManipulator.updateCamera(manipulator, osg.Camera())
+CameraManipulator.home(
+	manipulator,
+	simulate_frame.events.currentEventState,
+	simulate_frame.actions
+)
+```
+
+`test/osgGA_CameraManipulator.py` has the reference examples.
+
+## Wall-clock-driven callbacks
+
+Some animation callbacks track their own elapsed time via `time.time()`
+directly instead of reading `nv.frameStamp.simulationTime`
+(`LiveUpdateCallback`, `ShrinkCallback`/`FallCallback`).
+`simulate_frame.advance(simulationTime=...)` has no effect on these;
+monkeypatch `time.time` to a controllable fake clock instead:
+
+```python
+import time as time_module
+
+class FakeClock:
+	def __init__(self, t=0.0):
+		self.t = t
+
+	def __call__(self):
+		return self.t
+
+clock = FakeClock()
+orig = time_module.time
+time_module.time = clock
+
+# ... build scene, attach callbacks ...
+
+clock.t += 10.0  # jump well past any animation's duration
+simulate_frame.traverseUpdate(root)
+
+time_module.time = orig  # restore — other tests need the real clock
+```
+
+Still drive the tick through `simulate_frame.traverseUpdate(root)`, not by
+calling each node's `updateCallback` directly — that exercises the real
+`accept()`/traversal path instead of just the leaf callable in isolation.
+
+## Testing an example script's OSG-dependent helpers
+
+`examples/*.py` mix pure-Python logic, OSG-dependent helpers, and an
+`if __name__ == "__main__":` block that opens a real window — only that last
+part needs a display. To unit-test the helpers without constructing a
+`Viewer`, `exec()` the file's source up to (not including) that guard:
+
+```python
+src = open("examples/pyosg-match4.py").read()
+end = src.index('if __name__ == "__main__":')
+
+ns = {"osg": osg, "osgGA": osgGA, "osgViewer": osgViewer, "__name__": "match4_headless"}
+
+exec(src[:end], ns)
+
+make_piece = ns["make_piece"]
+ShrinkCallback = ns["ShrinkCallback"]
+```
+
+This works because constructing scene-graph objects (`osg.Sphere`,
+`osg.Geode`, `osg.MatrixTransform`, `osg.Uniform`, ...) needs no GL context —
+only `viewer.frame()` does. Combined with the fake-clock trick above, this is
+enough to headlessly drive a whole multi-frame animation sequence end to end
+against real OSG objects.
+
+## Raw building blocks
+
+- `osg.FrameStamp`
+- `osgUtil.UpdateVisitor`
+- `osgGA.EventQueue`
+- `osgGA.EventVisitor`
+- Python-subclassable `osgGA.GUIActionAdapter`
+- `Node.updateCallback` and `Node.eventCallback`, each accepting either an
+  OSG `NodeCallback` or a plain Python callable
+
+For a manual update traversal, increment the frame number, set reference and
+simulation time, set the visitor's `frameStamp` and `traversalNumber`, then
+call `root.accept(visitor)`. Reset and feed each event to `EventVisitor`
+before accepting it on the root.
+
+## When a Viewer is still required
+
+- a `View`'s own handler/manipulator ownership or scene/camera wiring;
+- window/device polling, pointer-data reprojection, or close-window handling;
+- cull traversal, camera ordering, render-to-texture execution, draw
+  callbacks, OpenGL object compilation, readback, swap buffers, or any real
+  GL state.
+
+Headless simulation covers event and update traversal only — it is not fake
+rendering.

OpenSceneGraph/aipython/05-camera-manipulator.md

@@ -0,0 +1,68 @@
+# Camera manipulators in a live REPL session
+
+## Custom `osgGA.CameraManipulator` subclasses: overrides that actually dispatch
+
+- **`setNode()`/`getNode()` dispatch to a Python override.** `View.setCameraManipulator(manip, resetPosition=True)` calls `manip->setNode(scene)` internally.
+- **`.node` doesn't leak on reassignment** — a replaced, not accumulated, property slot.
+- **`home(ea, aa)` doesn't crash** on a Python subclass override.
+
+A subclass that doesn't override `setNode`/`getNode` at all still needs
+explicit overrides storing into e.g. `self._node` if you want `self.node` to
+reflect the real bound scene (radius/center), not a `1.0`/origin fallback.
+
+## Live camera-relative technique: aiming a light relative to the CURRENT view
+
+Useful for interactively tuning a directional light "from the camera's
+perspective" rather than in raw world-space azimuth, which looks different
+every time the user orbits:
+
+```python
+eye, center, up_v = v.camera.viewMatrix.getLookAt(1.0)  # NOT the inverse — see gotcha below
+fwd = center - eye; fwd.normalize()
+right = fwd.cross(up_v); right.normalize()
+up_v.normalize()
+
+# Decompose an existing direction against this basis:
+offset = osg.Vec3d(light_dir_u.value.x, light_dir_u.value.y, light_dir_u.value.z)
+screen_right = offset.dot(right)      # + = camera's right
+screen_up    = offset.dot(up_v)       # + = above
+toward_camera = -offset.dot(fwd)      # + = pointing back at the viewer
+
+# Build a new direction directly in this basis, e.g. 45deg upper-right, 45deg off-axis:
+L_world = right * 0.5 + up_v * 0.5 - fwd * 0.70710678
+L_world.normalize()
+new_offset = L_world * offset.length()  # preserve the original magnitude
+```
+
+Always recompute the camera basis fresh, immediately before use — a basis
+read even one call ago is stale if the user is actively orbiting between REPL
+calls.
+
+**Directional-light caveat:** there is no "point at X" for a sun-type light
+(no position, no falloff) — the only lever is elevation, which changes *what
+surfaces catch light*, not *where* it's aimed. Translate "point down at the
+subject" into "increase the up-component, decrease the frontal component,"
+not literal aiming.
+
+### Gotchas specific to this technique
+
+- **`Matrixd.getLookAt(distance)` operates on the view matrix directly, NOT
+  its inverse.** Calling it on `osg.Matrix.inverse(v.camera.viewMatrix)`
+  silently returns plausible-looking-but-wrong eye/center/up, no error.
+- **`Vec3.dot()`/arithmetic require matching types** — a uniform's `.value`
+  is often `Vec3f` while matrix math returns `Vec3d`; mixing raises
+  `TypeError: incompatible function arguments`. Cast explicitly:
+  `osg.Vec3d(v.x, v.y, v.z)`.
+- **No `^` cross-product operator** — use `.cross()`.
+- **`osg.setNotifyLevel` set too high floods the tmux pane** with X11 event
+  spam. Fix: `osg.setNotifyLevel(osg.NotifySeverity.WARN)`.
+
+## There is no `viewer.home()`
+
+`osgViewer::ViewerBase`/`Viewer` has no `home()` in these bindings —
+`viewer.cameraManipulator.home` exists but wants `(ea, aa)` event-handler args
+not trivially available outside actual event dispatch. In practice this
+doesn't matter: assigning `viewer.cameraManipulator = ...` *after*
+`viewer.sceneData` is already set triggers the manipulator's own
+`autoComputeHomePosition` framing automatically — no explicit home call
+needed for the common "just frame the scene" case.