@volter/blender-engine 0.1.148 → 0.1.150

package/browser/volter_three.py

@@ -1,47 +1,4 @@
-"""OUR BLENDER RENDERS WITH THREE.JS -- the ask, shipped INSIDE the Blender.
-
-THE RENDER OVERRIDE IS NOT THE EDITOR'S. `session.py` is the editor tab's
-long-lived session and carries this same override for the session it owns;
-this file is the other delivery of it -- a Blender STARTUP module that ships in
-the pack's resource tree (`scripts/startup/volter_three.py`), so a bare
-`blender -b ... -a` on ANY surface renders with three.js too. Blender imports
-every module in `scripts/startup` and calls its `register()`.
-
-THE ASK SHIPS WITH THE BLENDER; THE ANSWER DOES NOT. What renders is a
-PRESENTER the host attached to this process (`browser/three/attach-presenter.ts`
-around `browser/three/presenter.ts`): a canvas, the frame translated to
-three.js, a camera, the display transform. This file only asks. The channel is
-the directory protocol `session.py`'s header states, with one writer per
-directory:
-
-    <root>/ask/     THIS PROGRAM writes and unlinks; the host only reads.
-    <root>/reply/   the HOST writes and unlinks; this program only reads.
-    <root>/arena.bin  THIS PROGRAM writes (the export door does); host reads.
-
-NO PRESENTER, NO OVERRIDE. `register()` asks `{"op": "hello"}` and waits two
-seconds. Answered, it takes the engine ids and every render is a photograph.
-Unanswered, it prints ONE line naming the root it waited at and registers
-nothing at all, so Blender renders with Cycles -- correct, slow, and never
-silent.
-
-THE ENGINE IS TAKEN ON `load_post`, NOT IN `register()`, and that is a
-measurement. Blender's `bpy.utils.load_scripts` registers every startup module
-BEFORE it enables the add-ons, so at `register()` time `cycles.CyclesRender`
-does not exist yet and taking the `CYCLES` id here would be overwritten by the
-add-on moments later. Measured on the native 5.2.0 LTS oracle
-(`blender -b --python-expr ...` with this module's probe in
-`BLENDER_USER_SCRIPTS`): at `register()` `CYCLES` is unregistered, and the
-FIRST `load_post` -- which Blender fires for the startup file itself, before
-any `--python-expr` runs -- sees `<class 'cycles.CyclesRender'>`. So the
-handler is where the ids are taken, and it runs again after every file load
-because a load re-enables the add-ons and hands `CYCLES` back.
-
-WHAT THIS FILE DOES NOT CARRY, deliberately: the editor session's incremental
-geometry record (every frame ships in full -- `known` is always empty, so no
-presenter can ever be asked about geometry it does not hold), its document,
-its overlays, and its world SHADER reducer. A world here is a CONSTANT
-background or nothing, named as a warning; see `_world`.
-"""
+"""Standalone Blender startup render override. Bare background Blender processes use the presenter’s ask/reply directory protocol, while session.py owns the editor session’s equivalent engine. The package carries protocol and data conversion without importing editor state."""
 
 import base64
 import json
@@ -65,19 +22,7 @@ REPLY = os.path.join(ROOT, "reply")
 EXPORT_BUFFER_PATH = os.environ.get(
     "VOLTER_EXPORT_BUFFER_PATH", os.path.join(ROOT, "arena.bin")
 )
-# THE FRAME'S IDENTITY IS A PAIR, `(session, revision)`, and the presenter
-# refuses a revision that went backwards under a name it already holds. One
-# process is one session; the revision only ever counts up within it.
-#
-# THE PID IS NOT THE NAME, and that is measured rather than cautious. A
-# presenter outlives the Blenders it serves, so two processes' names must
-# differ -- and in the browser the guest's pids START OVER: the second
-# `blender -b ... -a` on one page came up as the same pid, its revision
-# restarted at 1 under a name the view already held at 24, and every render in
-# it died on "The runtime frame is older than the displayed model" (measured
-# 2026-09-20 in the substrate tab; the first run on a freshly loaded page
-# always worked, which is what hid it). The start time is what makes the name
-# this process's own.
+# Identify frames by process session and monotonic revision. Include process start time because guest pids can repeat while a presenter remains alive.
 SESSION = "volter-three:%d-%d" % (os.getpid(), time.time_ns())
 HELLO_TIMEOUT_SECONDS = 2.0
 POLL_SECONDS = 0.002
@@ -87,25 +32,7 @@ _REVISION = [0]
 _WARNED = set()
 _WARNINGS = []
 def _say(line):
-    """One line on Blender's own stderr, resolved at CALL TIME.
-
-    WHERE THIS LINE COMES OUT, and it is not where a reader looks first.
-    MEASURED 2026-09-20 in the substrate tab with the whole command redirected
-    (`blender ... > log 2>&1`): Python's `sys.stderr` in this build is NOT the
-    process's fd 2. `print(..., file=sys.stderr)` and
-    `sys.stderr.buffer.write(...)` BOTH reached the terminal and NEITHER
-    reached the file, while `print()` to stdout reached the file and not the
-    terminal. So the one line this module ever prints -- the one that says
-    Cycles is about to render -- is read on the TERMINAL; a reader who greps
-    only a redirect will conclude the fallback is silent when it is not. That
-    reading cost an hour and a wrong diagnosis; it is written here so it costs
-    nobody else one.
-
-    The stream is taken at call time rather than captured at import because a
-    startup module is imported while Blender is still standing its streams up
-    and nothing here needs the captured one. Both spellings were measured to
-    work; this is the plainer.
-    """
+    """Write to Blender’s current stderr at call time, after the host has attached its streams."""
     print(line, file=sys.stderr or sys.stdout, flush=True)
 
 
@@ -250,8 +177,6 @@ def _export(depsgraph):
 
 
 def _present(depsgraph, capture):
-    if not hasattr(_blender_web, "begin_render_export"):
-        raise RuntimeError("This Blender artifact has no render-evaluated export")
     _blender_web.begin_render_export(depsgraph)
     try:
         answer = ask({"frame": _export(depsgraph), "capture": {**capture, "evaluation": "render"}})
@@ -317,6 +242,8 @@ def _photograph(depsgraph, width, height, linear=False):
         "AgX": "agx",
         "Filmic": "filmic",
         "Khronos PBR Neutral": "neutral",
+        "ACES 1.3": "aces13",
+        "ACES 2.0": "aces20",
     }.get(view.view_transform)
     if transform is None:
         raise RuntimeError(
@@ -349,20 +276,9 @@ def _photograph(depsgraph, width, height, linear=False):
 
 
 def _assert_photographed_from(reported, position, target, up):
-    """The photograph answers with the pose it ACTUALLY used, back in Blender's
-    frame, and it must be the pose that was sent -- exactly, with no tolerance.
-
-    This is an instrument, not a nicety. A render's image is allowed to differ
-    from Cycles (three.js is the renderer), so a camera placed in the wrong
-    frame produces a picture nobody can call wrong: the lane shipped for its
-    whole life photographing the model's underside from below the floor because
-    Blender's Z-up numbers were read as three.js world space.
-
-    The check is exact because the conversion is exact: the model root's world
-    matrix is a signed axis permutation, so a vector through it and its inverse
-    is bit-identical. A mismatch is the conversion being wrong, never the check
-    being too strict -- do not widen it.
-    """
+    """Require the photograph’s camera pose transformed back into Blender’s frame to equal the sent
+    pose exactly. The model root uses a signed axis permutation, so its transform and inverse
+    preserve values without a floating-point tolerance."""
     sent = {"position": position, "target": target, "up": up}
     if not isinstance(reported, dict):
         raise RuntimeError(
@@ -417,19 +333,7 @@ class VolterRenderEngine(bpy.types.RenderEngine):
 
 
 def _fill_result(engine, result, answer, png, width, height):
-    """THE RENDER RESULT HOLDS SCENE-LINEAR PIXELS, and Blender runs the scene's
-    view transform over them wherever it shows or saves one (`write_still`, the
-    Image Editor), as it does over Cycles'. The photograph's PNG is the display
-    image -- the transform already ran -- so loading it put every render
-    through AgX or Filmic twice. Measured 2026-09-28 by Cyclotron's
-    render view: a background 53 against the viewport's 59, a shadow's blue 2
-    against 7. The same capture's linear frame goes in instead: half floats,
-    RGBA, bottom row first, which is Blender's own row order. Linear 0.005,
-    0.05, 0.5 and 4.0 then save under AgX as 8, 58, 170 and 234 (the PNG
-    path saved 3, 53, 160 and 190), and under Standard as 15, 64, 188 and 255,
-    as the PNG path did.
-
-    A renderer that sends no linear frame gets the old path, and says so."""
+    """Load scene-linear capture pixels into RenderResult so Blender applies the view transform once. A presenter without linear pixels uses the declared PNG path."""
     linear = answer.get("linearBase64") if isinstance(answer, dict) else None
     if linear and answer.get("linearWidth") == width and answer.get("linearHeight") == height:
         import numpy