OpenSceneGraph 0.1.2__cp313-cp313-win_amd64.whl

OpenSceneGraph/aipython/25-async-osgpy.md

@@ -0,0 +1,228 @@
+# Async OSG.py: the pattern, the ceiling, and the glTF case study
+
+Two reusable pieces (`examples/pyosg_async.py`): running `viewer.frame()` as
+an ordinary `asyncio` task instead of a hand-rolled pump loop, and draining a
+`.poll()`-shaped progress object from the coroutine already awaiting the
+background work, instead of routing progress through a queue and a
+`call_soon_threadsafe` bridge. `osgx.gltf.readNodeFile()` +
+`osgx.gltf.AsyncProgress` is the concrete instance this grew out of and stays
+the worked example throughout.
+
+## The Node.js comparison
+
+The intuitive model is Node's "fire and forget": kick off slow work on a
+thread pool, keep the event loop responsive, `await` a result. Node's worker
+threads never touch the JS engine while they work; they post exactly one
+completion event back to the single JS thread.
+
+OSG.py can genuinely match this — where it's real, it's *stronger*, since a
+background thread doing off-GIL native work executes truly in parallel with
+rendering on a second core, not just an I/O-completion callback on one
+thread. But CPython's GIL is a sharper, stickier constraint than "the JS
+engine" is in Node's model: it applies to *any* thread running *any* Python
+bytecode, including a Python-written progress callback called from C++, not
+just to a language-level boundary a worker can choose to respect.
+
+## The mechanism: why a naive async loader can be slower than sync
+
+`Viewer.frame()`'s pybind11 binding (`pyosg/pyosgViewer.cpp`) deliberately
+does **not** release the GIL when `getThreadingModel() == SingleThreaded`
+(this project's standing default) — see [`01-core.md`](01-core.md) rule 8.
+A Python pump loop (`while not viewer.done: viewer.frame(); ...`) holds the
+GIL, uninterrupted, for `frame()`'s entire C++ execution. Any background
+thread that calls back into Python to report progress — including
+`pybind11x::put_nowait()` (`etc/pybind11x.hpp`), which does
+`py::gil_scoped_acquire` — cannot acquire the GIL until `frame()` returns. A
+loader reporting progress dozens of times per load this way spends most of
+its time waiting on the GIL, not working: measured as ~2x slower wall-clock
+than sync loading the same model, despite the loader itself doing less work.
+
+**Ruled out:** vsync/compositor pacing. Disabling vsync
+(`__GL_SYNC_TO_VBLANK=0`) made no measurable difference — vsync caps the pump
+loop's call rate, but each `frame()` call still costs real GIL-held C++ time
+regardless, and the aggregate GIL saturation stays similar whether
+distributed as few long holds (vsync-on) or many short ones (vsync-off).
+
+## Two valid ways to get data out of a background thread
+
+Both exist in this codebase for different situations. Neither is obsolete in
+favor of the other.
+
+**Push** (`pybind11x::StopEvent` + `pybind11x::put_nowait()`,
+`examples/pyosg-async.py`'s `task_cpp_example`): the background thread calls
+`put_nowait(loop, queue, ...)`, which acquires the GIL and schedules
+`queue.put_nowait(...)` via `call_soon_threadsafe`. Correct when the thread
+needs to hand back an irregular, genuinely Python-shaped value that doesn't
+reduce to a few numbers, or that only happens occasionally — the GIL
+acquisition cost is fine when infrequent.
+
+**Poll** (`pybind11x::PollableProgress<Stage>`, `osgx.gltf.AsyncProgress`,
+`examples/pyosg-async-gltf.py`): the background thread writes into
+independent `std::atomic` fields — no GIL, ever, from that side. A poller
+(which already owns the GIL) calls `.poll()` on its own schedule — a few
+relaxed atomic loads, effectively free. Use this for a hot native loop's
+simple, frequent, numeric tick (a progress bar) — pushing at that frequency
+is exactly what produces the mechanism above.
+
+Rule of thumb: if the background thread needs to call back into arbitrary
+Python, push, rarely. If it's just numbers a poller can pull, poll — but on
+a real cadence, not a busy-loop (next section).
+
+## Gotcha: a poll loop still needs a real, positive sleep
+
+`poll()` has no GIL cost, but `asyncio.sleep(0)` between checks isn't a real
+sleep — it's a bare cooperative yield, so a loop built purely to poll with it
+becomes an unthrottled busy-loop: near 100% of one CPU core spinning on
+polling overhead, real OS-level contention with the background thread's
+actual work. Measured **~75% slower** than the push-based version this
+pattern was meant to improve on, before being fixed with a real default
+poll interval. "Poll as often as convenient" only holds when the loop
+already exists for another reason (a render loop polling implicitly via its
+own 60fps cadence is free) — a loop whose only job is polling needs its own
+real `asyncio.sleep(dt)`. `run_with_progress()`'s default `poll_interval` is
+`1.0 / 60.0` — no reason to poll progress faster than it could be displayed.
+
+## Make the render loop an ordinary `asyncio` task
+
+Don't hand-roll the event loop pump:
+
+```python
+while not viewer.done:
+    viewer.frame()
+    loop.run_until_complete(asyncio.sleep(0))
+    # ...manually drain a queue...
+```
+
+An ordinary `async def` wrapping `viewer.frame()` already works — between
+calls, control genuinely returns to the Python bytecode eval loop, same as
+any other coroutine's await point. `examples/pyosg_async.py`'s `run()`:
+
+```python
+async def run(viewer, *coros, fps=60, max_frames=None):
+    async def render():
+        while not viewer.done:
+            viewer.frame()
+            await asyncio.sleep(1.0 / fps)
+
+    # NOT asyncio.gather(render(), *coros) — that waits for every task to finish,
+    # so a coros task outliving the window closing would hang the session open.
+    # The window closing (render_task finishing) must always end the session
+    # immediately, cancelling coros; a coros task finishing must never end the
+    # session by itself.
+    render_task = asyncio.ensure_future(render())
+    other_tasks = [asyncio.ensure_future(c) for c in coros]
+    pending = {render_task, *other_tasks}
+    try:
+        while True:
+            done, pending = await asyncio.wait(pending, return_when=asyncio.FIRST_COMPLETED)
+            for t in done:
+                if not t.cancelled() and t.exception() is not None:
+                    raise t.exception()
+            if render_task not in pending:
+                break  # the window closed — the only thing that ends the session
+    finally:
+        for t in (render_task, *other_tasks):
+            if not t.done():
+                t.cancel()
+        ...
+```
+
+Loading code then reads close to plain `await`:
+
+```python
+async def load(viewer, path, stop, progress):
+    node = await asyncio.to_thread(osgx.gltf.readNodeFile, path, stop, progress)
+    viewer.sceneData.children.append(node)
+
+asyncio.run(pyosg_async.run(viewer, load(viewer, path, stop, progress), bar.watch(progress)))
+```
+
+Two shapes for reacting to progress, both built on `run()`:
+
+- `pyosg_async.run_with_progress(blocking_fn, *args, progress=, on_progress=, stop=, poll_interval=1.0/60.0)`
+  — inline-callback shape: starts `blocking_fn` via `asyncio.to_thread`,
+  polls progress itself, forwards to `on_progress`, returns the result.
+  Right when the wait and the reaction naturally belong together (console
+  output).
+- `Progress.watch(progress, poll_interval=1.0/60.0)` — decoupled-task shape:
+  its own coroutine, added directly to `run()`'s task list alongside the
+  load, neither aware of the other. Right for a separate visual progress bar
+  (`Progress`/`ProgressBar` — a real `osg.Camera` subclass, POST_RENDER +
+  `clearMask=0` + identity view/projection, same shape as `pyosg-fire.py`'s
+  `build_flash_camera()`).
+
+**Only one poller per `AsyncProgress`.** Its "last seen generation" cursor
+lives inside the C++ object itself (`AsyncProgress::seen`,
+`~/dev/osgx/ext/python/osgx-gltf.cpp`), not per caller — two independent
+consumers calling `.poll()` on the same instance steal updates from each
+other; whichever polls first consumes that tick for both. Pick exactly one
+poller per progress object.
+
+## The glTF case study: `readNodeFile()` + `AsyncProgress`
+
+`osgx.gltf.readNodeFile(location, stop_event, progress)` is a plain blocking
+call, meant to run via `asyncio.to_thread(...)`, returning its result
+normally — there is no `readNodeFileAsync()`; that queue/loop-based function
+no longer exists. It never touches Python once it starts, not even to report
+progress — progress is written into an `osgx.gltf.AsyncProgress` purely
+through atomics, read back via `.poll()`.
+
+**Expected overhead: ~1.25x, not parity.** Isolating the loader entirely (no
+Viewer, no `frame()` calls at all) shows its wall-clock time is within noise
+of a sync `osgDB.readNodeFile()` call on the same model — the pure
+background load has no more headroom to give. The remaining ~1.25x gap in a
+real windowed async run is the genuine cost of rendering hundreds of
+concurrent `frame()` calls *while* the load runs — the actual point of async
+loading (a responsive, rendering viewer while data loads), not overhead left
+to eliminate. Don't chase this ratio to 1.0x. Validate any change to this
+path on a real model (dozens+ of nodes, load time comfortably over a
+second) — a tiny model's load is too fast/noisy to show a signal either way.
+
+**Unrelated:** a model with very large source textures (tens of MB PNGs) can
+show multi-second stalls inside `building_nodes` that are pure
+single-threaded CPU cost in `osgDB::readImageFile()`'s decode — identical in
+both sync and async loaders, nothing to do with GIL/threading. If
+`building_nodes` looks slow, check texture file sizes before assuming
+scene-graph construction is the cost.
+
+## What this actually buys you
+
+- A window that stays responsive immediately while a multi-second load
+  happens fully concurrently — real hardware parallelism, not a
+  cooperative-scheduling illusion.
+- Ordinary `asyncio` composition: `await`, `gather`, cancellation
+  propagation, once the render loop is just another task.
+- One idiom (`run_with_progress`, `Progress.watch()`) reusable across every
+  future "blocking native call + simple progress ticks" operation, instead
+  of re-deriving queue-draining boilerplate per feature.
+
+## Where the ceiling is
+
+- **The GIL is coarser than Node's model** — enforced on any thread running
+  any Python bytecode, including a Python-written progress callback passed
+  into C++. The poll design only avoids contention because the hot
+  reporting loop is pure C++ all the way down.
+- **`frame()` not releasing the GIL is a hard wall, not a tuning knob** — see
+  [`01-core.md`](01-core.md) rule 8. Async design works *around* this
+  window, not by changing it.
+- **Real CPU contention doesn't go away.** Two genuinely busy threads on
+  finite cores still cost real time together — the residual ~1.25x above is
+  concurrent rendering's actual cost, not a GIL artifact.
+- **Cancellation stays cooperative.** A stop flag can only be checked
+  between units of native work — it cannot interrupt one opaque blocking
+  call already in flight (one `tinygltf` parse, one texture decode). Same
+  limitation as Node's `AbortController` against synchronous native work.
+
+## Where the pieces live
+
+- `etc/pybind11x.hpp` — `StopEvent`, `put_nowait()` (push),
+  `PollableProgress<Stage>` (poll). Shared infra, used by both the core
+  pyosg bindings and osgx.
+- `~/dev/osgx/ext/python/osgx-gltf.cpp` — `AsyncProgress` (the glTF-specific
+  `PollableProgress` binding) and `readNodeFile()`.
+- `examples/pyosg_async.py` — `run()`, `run_with_progress()`, and
+  `Progress`/`ProgressBar`. Not yet part of the `OpenSceneGraph` package —
+  see `[[project_native_package_split]]`.
+- `examples/pyosg-async.py` — push-based demo.
+- `examples/pyosg-async-gltf.py` — poll-based demo, `load()` and
+  `bar.watch(progress)` as independent entries in `run()`'s task list.

OpenSceneGraph/aipython/29-material.md

@@ -0,0 +1,109 @@
+# osgx.Material — one PBR material as a real StateAttribute
+
+`osgx.Material` is a real `osg.StateAttribute` subclass: construct one,
+set its properties, attach it to a `StateSet` like any other attribute. This
+replaces hand-building a material UBO (`osg.FloatArray` +
+`osg.UniformBufferBinding`) yourself.
+
+```python
+import osgx
+
+material = osgx.Material()
+
+material.baseColor = osg.Vec4(0.95, 0.55, 0.12, 1.0)
+material.roughness = 0.12
+material.metallic = 1.0
+
+drawable.stateSet.attributes.append(material)
+```
+
+`StateSet.attributes[key] = value` (keyed by `osg.StateAttribute.Type`) also
+works, but `.attributes.append(material)` is simplest — it reads the key off
+the attribute's own `.type`.
+
+## Properties
+
+| Property | Meaning |
+|---|---|
+| `baseColor` | `osg.Vec4` RGBA factor, multiplied against `baseColorMap` when one is set. |
+| `roughness` | float factor. `0.0`–`0.1` reads as a sharp mirror-like reflection; `1.0` is fully matte. |
+| `metallic` | float factor. `1.0` tints specular by `baseColor` (real metal); `0.0` keeps a neutral white `F0=0.04` dielectric specular. |
+| `hasOcclusion` | bool. No dedicated texture slot — occlusion is read from `metallicRoughnessMap`'s R channel, so this flag opts in explicitly. |
+| `baseColorMap`, `normalMap`, `metallicRoughnessMap`, `emissiveMap` | `osg.Texture2D` or `None`. Bind at the loader's conventional units (`osgx.gltf.shader.{BASE_COLOR,NORMAL,ORM,EMISSIVE}_TEXTURE_UNIT`). |
+
+`hasBaseColorMap`/`hasMetallicRoughnessMap`/`hasNormalMap` are **not**
+separate properties — derived automatically from whether the corresponding
+`*Map` property is set. Setting `baseColorMap` and having the texture
+actually sample are the same operation.
+
+## Shader side: the same `osgx_gltf_Material` SSBO as before
+
+`Material` populates the exact same `osgx_gltf_Material` std430 buffer
+(`#pragma osgx::gltf MATERIAL_INPUTS`) the real glTF loader populates for a
+loaded asset, at the same binding (`osgx.MATERIAL_BINDING` /
+`osgx.gltf.shader.MATERIAL_BINDING`, both aliases of the same constant). A
+minimal factor-only fragment shader:
+
+```glsl
+#pragma osgx::gltf MATERIAL_INPUTS
+#pragma osgx::pbr MATERIAL_STRUCT, DIRECT_LIGHTING_DECL
+
+osgx_Material mat;
+
+mat.albedo = osgx_gltf_material.baseColorFactor.rgb;
+mat.ao = 1.0;
+mat.roughness = clamp(osgx_gltf_material.roughnessFactor, 0.04, 1.0);
+mat.metallic = osgx_gltf_material.metallicFactor;
+mat.F0 = mix(vec3(0.04), mat.albedo, mat.metallic);
+```
+
+Clamp roughness away from exactly `0.0` (`0.04` here) — a true zero
+denominator in the GGX distribution term is a real division-by-near-zero.
+
+## Works on a plain `osg.ShapeDrawable`, not just osgx shapes
+
+`Material` is a StateSet attribute like `osg.Program` or `osg.BlendFunc` — it
+doesn't care what built the geometry. Confirmed on both `osgx.Icosahedron`
+and a bare `osg.ShapeDrawable(osg.Sphere(...))`. One gotcha specific to
+`ShapeDrawable`, unrelated to `Material` itself: it builds its geometry with
+only classic `setVertexArray()`/`setNormalArray()` calls, not the extra
+`setVertexAttribArray(0/1, ...)` calls `osgx.Polyhedron`-derived shapes
+(`Cube`, `Icosahedron`) also make so a custom core-profile `Program` can rely
+on fixed `position`/`normal` attribute locations. A vertex shader for a
+`ShapeDrawable` should use OSG's own auto-aliased `osg_Vertex`/`osg_Normal`
+attribute names instead — the same convention `pyosg-dynamic.py`/
+`pyosg-hover.py`/`pyosg-picking.py` already use.
+
+## One material per mesh, not per face or per object instance
+
+Match how glTF (and every real exporter format) works: one `Material` per
+mesh/primitive. `StateAttribute`s only apply at Drawable granularity. For
+visibly different materials across the faces of one shape, either give each
+face its own small Drawable/Geode, or keep one Drawable and drive the
+variation through a per-vertex attribute feeding a shader-side branch/array
+yourself — `pyosg-material.py`'s "glitter" scene's `GLITTER_MATERIAL_COMBOS` is the working
+example of the second approach, and deliberately hand-rolls its own
+`osgx_Material` struct from vertex data rather than using
+`osgx.Material`.
+
+## `StateAttribute::Type` and dedup
+
+`Material.type` is `osg.StateAttribute.CAPABILITY` — its own claimed slot.
+Two `Material`s with equal factors and identical texture objects compare
+equal (`compare()` is real), so OSG's state-sorting can skip a redundant
+re-apply between drawables that share one material — e.g. several primitives
+loaded from the same glTF material, since the loader's `TextureLoader`
+already caches/shares `Texture2D` objects by source index.
+
+## Verify a live result
+
+If reflections look completely absent at low roughness/high metallic,
+suspect the geometry before the material: flat facets under a single
+directional light (no IBL environment) rarely catch a legible specular
+highlight or environment reflection, regardless of roughness. Add a smooth
+`osg.ShapeDrawable(osg.Sphere(...))` "chrome ball" control (max metallic,
+near-zero roughness, near-white base color) — if it shows a clear reflection
+and the original shape doesn't, that's a geometry limitation, not a material
+or shader bug. `examples/pyosg-material-lab.py` is exactly this setup, with
+`--hdr`/`--env` wiring a real environment through
+`osgx.gltf.pbribl.PBRIBLEnvironment` (see [`30-pbribl.md`](30-pbribl.md)).

OpenSceneGraph/aipython/30-pbribl.md

@@ -0,0 +1,162 @@
+# Reflective PBR/IBL for ordinary OSG geometry
+
+`osgx.gltf.pbribl.PBRIBLScene.create()` is not limited to glTF-loaded nodes —
+it works with an ordinary `osg.ShapeDrawable`, provided the drawable carries
+an `osgx.Material` (see [`29-material.md`](29-material.md)) — a real
+`StateAttribute` — so there's a real `osgx_gltf_Material` buffer for the
+renderer to read. This file covers the environment-loading and IBL-scene
+side. `PBRIBLEnvironment`/`PBRIBLScene` are classes with static factory
+methods (`.load()`/`.prepare()`/`.create()`), not free functions.
+
+## Minimal live REPL setup
+
+```python
+import osgx
+
+sphere = osg.Sphere(osg.Vec3(0.0, 0.0, 0.0), 2.0)
+drawable = osg.ShapeDrawable(sphere, osg.TessellationHints(detailRatio=2.0))
+geode = osg.Geode(drawables=(drawable,))
+
+material = osgx.Material()
+material.baseColor = osg.Vec4(0.95, 0.55, 0.12, 1.0)
+material.roughness = 0.12
+material.metallic = 1.0
+drawable.stateSet.attributes.append(material)
+
+environment = osgx.gltf.pbribl.PBRIBLEnvironment.load(
+	"/home/cubicool/dev/osgx/BUILD-g++-13.3.0-NOASAN/env/papermill.gltf",
+)
+pbr = osgx.gltf.pbribl.PBRIBLScene.create(
+	geode, environment, iblDiffuseIntensity=1.0, iblSpecularIntensity=1.0
+)
+
+if not environment.valid() or not pbr.valid():
+	raise RuntimeError("PBR/IBL setup failed")
+
+root = osg.Group()
+
+# The environment root is present when the manifest uses a built-in BRDF LUT.
+if environment.root is not None:
+	root.children.append(environment.root)
+
+root.children.append(pbr.node)
+viewer.sceneData = root
+viewer.camera.clearColor = osg.Vec4(48.0 / 255.0, 53.0 / 255.0, 66.0 / 255.0, 1.0)
+viewer.cameraManipulator = osgGA.TrackballManipulator()
+```
+
+## Use a pre-baked `osgx_pbribl` environment manifest
+
+The `.gltf` files in `osgx`'s build `env/` directory are not ordinary scene
+models: they carry the custom `osgx_pbribl` extension pointing at matching
+pre-baked specular and diffuse KTX2 cubemaps beside the manifest. Load one
+directly instead of preparing from HDR:
+
+```python
+environment = osgx.gltf.pbribl.PBRIBLEnvironment.load(
+	"/home/cubicool/dev/osgx/BUILD-g++-13.3.0-NOASAN/env/papermill.gltf",
+)
+
+if not environment.valid():
+	raise RuntimeError("failed to load PBR/IBL environment")
+```
+
+Use `PBRIBLEnvironment.prepare("environment.hdr", lutSize=1024)` only when
+the entire environment should be baked dynamically from one HDR source — it
+bakes diffuse irradiance, GGX-prefiltered specular, and the BRDF LUT live
+from that one source; add `environment.root` to the rendered graph so its
+`PRE_RENDER` passes can populate the generated textures. The helper is
+IBL-only and does not invent authored/direct lights; generic light rigs are
+`osgx` (see [`40-typed-lights-gizmos.md`](40-typed-lights-gizmos.md)),
+and glTF-authored camera/`KHR_lights_punctual` support is separate loader
+work.
+
+### Switch a running scene
+
+Given the `geode`/`viewer` variables from the setup above:
+
+```python
+environment = osgx.gltf.pbribl.PBRIBLEnvironment.load(
+	"/home/cubicool/dev/osgx/BUILD-g++-13.3.0-NOASAN/env/Cannon_Exterior.gltf",
+)
+
+if not environment.valid():
+	raise RuntimeError("failed to load PBR/IBL environment")
+
+pbr = osgx.gltf.pbribl.PBRIBLScene.create(
+	geode, environment, iblDiffuseIntensity=1.0, iblSpecularIntensity=1.0
+)
+
+if not pbr.valid():
+	raise RuntimeError("failed to apply PBR/IBL environment")
+
+root = osg.Group()
+
+if environment.root is not None:
+	root.children.append(environment.root)
+
+root.children.append(pbr.node)
+viewer.sceneData = root
+```
+
+Do not merely replace `environment.root`: `PBRIBLScene.create()` owns the
+program state and its environment texture bindings, so call it again for the
+new environment. The material attached to `drawable` does not need to be
+rebuilt.
+
+## Extra `PBRIBLScene.create()` options
+
+`create(node, environment, iblDiffuseIntensity=1.0, iblSpecularIntensity=1.0,
+diagnostics=False, shadowMap=None, hooks=[])`:
+
+- `diagnostics=True` builds `pbr.debugMode` for switching between
+  combined/diffuse/specular/normal/roughness/diffuse-IBL-only visualizations
+  (`examples/pyosg-khronos-viewer.py`'s `Diagnostics` event handler cycles
+  it with number keys).
+- `shadowMap` accepts an `osgx.ShadowMap` (see
+  [`10-rtt.md`](10-rtt.md)) to shadow the light at `LightSet` index
+  `shadowMap.casterIndex`; omit it for unshadowed direct light.
+- `hooks` is a plain list of `(osgx.Hook, osg.Shader)` pairs
+  substituting one of this Program's built-in shader slots (`osgx.Hook.Skinning`,
+  `osgx.Hook.Tonemap`). Each hook *replaces* the built-in definition (GLSL
+  allows one body per function; adding a second is a link error, not an
+  override) — `osgx.gltf.shader.SKINNING_HOOK_LINEAR_BLEND` (wrapped in
+  `osgx.gltf.pbribl.resolveShaderLibs()`) enables real joint-matrix skinning
+  in place of the identity-passthrough default.
+
+There is also a deferred, G-buffer-split path for scenes with many lights —
+`PBRIBLGBuffer.create(node, width, height)` (material-only geometry pass) →
+`PBRIBLLightingScene.create(gbuffer, environment, mainCamera, ...)`
+(lighting pass reading the G-buffer) — not covered in the minimal setup
+above; reach for it only once a scene's light count/overdraw makes the
+single-pass `PBRIBLScene` genuinely too expensive.
+
+## Hand-assembled shader (no `osgx.Material`)
+
+`osgx.Material` is the supported way to populate the material data (see
+[`29-material.md`](29-material.md)) — it's a real `StateAttribute`, not
+something worth hand-rolling. If assembling a shader by hand regardless, the
+buffer is `#pragma osgx::gltf MATERIAL_INPUTS`'s `osgx_gltf_Material`: a
+`std430` SSBO (`baseColorFactor` vec4, `roughnessFactor`, `metallicFactor`,
+then four map-presence float flags), plus a separate `GLTFTextures`
+sampler-struct uniform and `osgx_gltf_alphaMode`/`osgx_gltf_alphaCutoff`
+uniforms for texture-backed materials. Sampler units and UV arrays must
+follow `osgx.gltf.shader`'s glTF interface — at that point
+`osgx.Material` is almost always the clearer path.
+
+The Program and IBL textures attach to `geode`; the material attaches to
+`drawable`. That split lets one PBR scene contain several drawables with
+independent materials.
+
+## Verify a live result
+
+Do not use bare `Image.readPixels()` from the prompt. Queue the capture on
+the REPL controller instead:
+
+```python
+await _osg_repl_controller.capture_framebuffer("/tmp/pbr-sphere.png")
+```
+
+The sphere should show the environment reflected across its surface.
+Increase roughness toward `1.0` for a blurrier reflection; lower metallic
+toward `0.0` for a dielectric surface with a diffuse IBL term.