@volter/blender-engine 0.1.127 → 0.1.128

package/browser/three/blender-sky.ts

@@ -1,16 +1,13 @@
 /**
- * Blender's MULTIPLE SCATTERING sky, transcribed from the pinned source.
+ * Blender's scattering skies, transcribed from the pinned source.
  *
  * `intern/sky/source/sky_multiple_scattering.cpp` precomputes a 512x256 XYZ
  * texture and `gpu_shader_material_tex_sky.glsl`'s `node_tex_sky_nishita` reads
  * it back per direction; both halves are here because both are what a script
- * sees through `ShaderNodeTexSky`.
- *
- * This is the MULTIPLE scattering model, not Nishita's single scattering. The
- * courtyard's own recording is why: its seq 31 sets `sky_type = 'NISHITA'` and
- * native REFUSES -- `enum "NISHITA" not found in ('SINGLE_SCATTERING',
- * 'MULTIPLE_SCATTERING', 'PREETHAM', 'HOSEK_WILKIE')` -- so the sky it renders
- * is the untouched default, which is MULTIPLE_SCATTERING.
+ * sees through `ShaderNodeTexSky`. The single-scattering atmosphere is in
+ * `blender-single-scattering-sky.ts`; model selection, caching and the shared
+ * GPU lookup convention live here. Each model keeps its own native elevation
+ * and azimuth conventions.
  *
  * The constants and the arithmetic are the source's. The XYZ-to-scene-linear
  * matrix is not in the source -- it comes from the colour configuration -- and
@@ -18,6 +15,7 @@
  * `Linear CIE-XYZ D65`.
  */
 import * as THREE from 'three';
+import {precomputeSingleScatteringSky} from './blender-single-scattering-sky';
 
 const M_PI_2_F = 1.5707963267948966;
 const M_2PI_F = 6.2831853071795864;
@@ -104,6 +102,8 @@ const aerosolDensity = (h: number): number =>
   (Math.exp(-h / AEROSOL_HEIGHT_SCALE) + AEROSOL_BACKGROUND_DENSITY / AEROSOL_BASE_DENSITY);
 
 export interface SkyParameters {
+  /** Omitted in older frames, whose only supported model was multiple scattering. */
+  model?: 'SINGLE_SCATTERING' | 'MULTIPLE_SCATTERING';
   sunElevation: number;
   sunRotation: number;
   altitude: number;
@@ -363,16 +363,17 @@ function precomputeTexture(p: SkyParameters, sunElevation: number): Float32Array
  * post the Float32Array back. See `contributions/sky-precompute-worker.ts`.
  */
 export function precomputeSkyTexture(p: SkyParameters): Float32Array {
+  if (p.model === 'SINGLE_SCATTERING') return precomputeSingleScatteringSky(p);
   const [elevation] = simplify(p.sunElevation, p.sunRotation);
   return precomputeTexture(p, elevation);
 }
 
-/** The identity of a precomputed sky: every parameter the texture depends on.
- *  Rotation is NOT one of them -- `simplify` can fold half a turn of elevation
- *  into it, so it is folded here too and the texture keyed on what is left. */
+/** Texture identity: model, native elevation, altitude and three densities.
+ * Rotation only changes the lookup. Multiple scattering folds elevation;
+ * single scattering keeps it as supplied to Blender's precompute. */
 export function skyTextureKey(p: SkyParameters): string {
-  const [elevation] = simplify(p.sunElevation, p.sunRotation);
-  return JSON.stringify([elevation, p.altitude, p.airDensity, p.aerosolDensity, p.ozoneDensity]);
+  const elevation = p.model === 'SINGLE_SCATTERING' ? p.sunElevation : simplify(p.sunElevation, p.sunRotation)[0];
+  return JSON.stringify([p.model ?? 'MULTIPLE_SCATTERING', elevation, p.altitude, p.airDensity, p.aerosolDensity, p.ozoneDensity]);
 }
 
 /** Precomputed sky textures, however they were derived. `skyField` is
@@ -410,11 +411,14 @@ export function primeSkyTexture(p: SkyParameters, pixels: Float32Array): void {
  * who cares about the main thread primes the cache first.
  */
 export function skyField(p: SkyParameters): (direction: THREE.Vector3) => THREE.Vector3 {
-  const [elevation, rotation] = simplify(p.sunElevation, p.sunRotation);
+  // Single scattering only wraps azimuth; it does not fold sun elevation.
+  const rotation = p.model === 'SINGLE_SCATTERING'
+    ? M_2PI_F - ((p.sunRotation % M_2PI_F + M_2PI_F) % M_2PI_F)
+    : simplify(p.sunElevation, p.sunRotation)[1];
   const key = skyTextureKey(p);
   let pixels = skyTextures.get(key);
   if (pixels === undefined) {
-    pixels = precomputeTexture(p, elevation);
+    pixels = precomputeSkyTexture(p);
     primeSkyTexture(p, pixels);
   }
   const colour = new THREE.Vector3();

package/browser/three/presenter.ts

@@ -1,3 +1,4 @@
+import { createBlenderDisplayTransform, blenderDisplaySettingsForRender } from './blender-display-transform';
 /**
  * THE PRESENTER FOR A HOST WITHOUT A STAGE (WS-AC, cut 1b).
  *
@@ -15,16 +16,12 @@
  * What it does NOT do, on purpose: overlays (modeling chrome, hidden for a
  * render anyway), selection outlines, the editor's supersampled `captureImage`
  * for the Standard transform. Every transform here goes through the linear
- * capture and the same encoders the editor uses for AgX and Filmic.
+ * capture and the same OCIO GPU display processors the editor uses.
  */
 import * as THREE from 'three';
-import type { CaptureRequest, RenderRequest } from '../protocol';
+import type { CaptureRequest } from '../protocol';
 import type { PresentAnswer } from '../runtime';
-import { AGX_LOOK_TABLES, agxEncodeFrame } from './blender-agx';
-import { displayTableUrl } from './blender-display-lut';
-import { filmicEncodeFrame } from './blender-filmic';
 import { BlenderRuntimeView } from './blender-runtime-view';
-import { standardEncodeFrame } from './blender-standard';
 
 export interface PresenterOptions {
   /** The canvas to render into; an OffscreenCanvas of 1x1 when absent. */
@@ -45,35 +42,6 @@ export interface Presenter {
 
 const MAXIMUM_EDGE = 2048;
 
-const displayTables = new Map<string, Promise<Uint16Array>>();
-function displayTable(file: string): Promise<Uint16Array> {
-  let pending = displayTables.get(file);
-  if (!pending) {
-    pending = fetch(displayTableUrl(file)).then(async (response) => {
-      if (!response.ok)
-        throw new Error(`Blender display table ${file}: ${response.status} ${response.statusText}`);
-      return new Uint16Array(await response.arrayBuffer());
-    });
-    displayTables.set(file, pending);
-  }
-  return pending;
-}
-
-function displayTableFor(render: RenderRequest): string | null {
-  const look = render.look ?? 'None';
-  if (render.toneMapping === 'none') return null;
-  if (render.toneMapping === 'filmic') return 'filmic-srgb.lut';
-  if (render.toneMapping !== 'agx')
-    throw new Error(
-      `Blender's Khronos PBR Neutral view transform has no scene-linear implementation in the ` +
-        `browser (implemented: Standard, AgX, Filmic)`,
-    );
-  if (look === 'None') return 'agx-base-srgb.lut';
-  const file = AGX_LOOK_TABLES[look as keyof typeof AGX_LOOK_TABLES];
-  if (file === undefined) throw new Error(`Blender display transform has no table for look ${look}`);
-  return file;
-}
-
 async function pngBase64(bytes: Uint8Array | Uint8ClampedArray, width: number, height: number): Promise<string> {
   // The linear capture is bottom-up (GL); the image is top-down.
   const stride = width * 4;
@@ -178,18 +146,11 @@ export function createPresenter(options: PresenterOptions = {}): Presenter {
       render: { width, height, fov: render.fov, orthographic: render.orthographic },
     });
 
-    const tableFile = displayTableFor(render);
-    const table = tableFile ? await displayTable(tableFile) : null;
-    const mappings: Record<string, THREE.ToneMapping> = {
-      none: THREE.NoToneMapping,
-      agx: THREE.AgXToneMapping,
-      neutral: THREE.NeutralToneMapping,
-      filmic: THREE.NoToneMapping,
-    };
+    const displayTransform = await createBlenderDisplayTransform(blenderDisplaySettingsForRender(render));
     const previousMapping = renderer.toneMapping;
     const previousExposure = renderer.toneMappingExposure;
-    renderer.toneMapping = mappings[render.toneMapping] ?? THREE.AgXToneMapping;
-    renderer.toneMappingExposure = render.exposure;
+    renderer.toneMapping = THREE.NoToneMapping;
+    renderer.toneMappingExposure = 1;
     const sceneTarget = new THREE.WebGLRenderTarget(width, height, { type: THREE.HalfFloatType });
     let effect: ReturnType<BlenderRuntimeView['createWorldVolumePass']>;
     try {
@@ -217,16 +178,7 @@ export function createPresenter(options: PresenterOptions = {}): Presenter {
         renderer.readRenderTargetPixels(resolved, 0, 0, width, height, pixels);
         renderer.setRenderTarget(null);
       }
-      const count = width * height;
-      const bytes =
-        render.toneMapping === 'none'
-          ? standardEncodeFrame(pixels, count, render.exposure)
-          : render.toneMapping === 'filmic'
-            ? filmicEncodeFrame(table!, pixels, count, render.exposure)
-            : agxEncodeFrame(table!, pixels, count, {
-                exposure: render.exposure,
-                composedLook: (render.look ?? 'None') !== 'None',
-              });
+      const bytes = displayTransform.encodeFrame(renderer, pixels, width, height);
       const photograph: Record<string, unknown> = {
         base64: await pngBase64(bytes, width, height),
         mimeType: 'image/png',
@@ -245,6 +197,7 @@ export function createPresenter(options: PresenterOptions = {}): Presenter {
     } finally {
       effect?.dispose();
       sceneTarget.dispose();
+      displayTransform.dispose();
       renderer.toneMapping = previousMapping;
       renderer.toneMappingExposure = previousExposure;
       await view.setRendered(false);

package/browser/three/world-field-sampler.ts

@@ -100,6 +100,7 @@ export function worldField(
     // Built ONCE per node: the model precomputes a 512x256 texture, and
     // rebuilding it per direction would be a 65,536-pixel job per texel.
     const field = skyField({
+      ...(expression.sky_model === undefined ? {} : {model: expression.sky_model}),
       sunElevation: expression.sun_elevation,
       sunRotation: expression.sun_rotation,
       altitude: expression.altitude,
@@ -253,6 +254,7 @@ export function collectSkyParameters(expression: WorldExpression): SkyParameters
     switch (node.kind) {
       case 'sky':
         found.push({
+          ...(node.sky_model === undefined ? {} : {model: node.sky_model}),
           sunElevation: node.sun_elevation,
           sunRotation: node.sun_rotation,
           altitude: node.altitude,

package/browser/volter_three.py

@@ -318,13 +318,12 @@ def _photograph(depsgraph, width, height, linear=False):
         "fov": _vertical_extent(camera.data, int(width), int(height)),
         "toneMapping": transform,
         "exposure": float(2.0 ** view.exposure),
+        "gamma": float(view.gamma),
         "orthographic": camera.data.type == "ORTHO",
         "transparent": bool(scene.render.film_transparent),
     }
-    # The renderer keys its baked look tables by the config's FULL name
-    # (`AgX - Medium High Contrast`), and `AgX - Base Contrast` is the AgX base
-    # view itself -- the same table as no look at all.
-    if look not in ("None", "AgX - Base Contrast"):
+    # Preserve the full look name for the native OCIO display processor.
+    if look != "None":
         render["look"] = look
     # The capture's scene-referred frame rides along when asked for: a render
     # result is what a render leaves, and it holds scene-linear pixels.
@@ -412,7 +411,7 @@ def _fill_result(engine, result, answer, png, width, height):
     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 the model editor's
+    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,

package/browser/worker.ts

@@ -351,7 +351,13 @@ async function startBlender(project: string, document?: string): Promise<unknown
   // be `open_mainfile` on the document — which lives on the host's disk and is
   // not in the engine's filesystem until it is staged. Every other call stages
   // on its way in (`execute`); start had nothing to open before it did.
-  if (document) await stageProjectFiles(started.files, project);
+  if (document) {
+    // The document itself not reaching the engine is a refusal, not a footnote: the open below
+    // would fail on a missing file (or open a stale copy) without saying why.
+    const failed = await stageProjectFiles(started.files, project);
+    const mine = failed.find((line) => line.startsWith("The project's files are not readable") || line.startsWith(`${document} `));
+    if (mine) throw new Error(`${document} could not be copied into Blender, so it cannot be opened: ${mine}`);
+  }
   await loadCheckpoint?.("project-imported");
   const banner = (await started.request({
     op: 'start',
@@ -459,10 +465,11 @@ function say(line: string): void {
   log('error', line);
 }
 
-async function projectIndex(project: string): Promise<ProjectFile[] | null> {
-  const unreadable = (reason: string): null => {
-    say(`The project's files are not readable from Python: ${reason}`);
-    return null;
+async function projectIndex(project: string): Promise<ProjectFile[] | string> {
+  const unreadable = (reason: string): string => {
+    const line = `The project's files are not readable from Python: ${reason}`;
+    say(line);
+    return line;
   };
   let answer: Response;
   try {
@@ -515,9 +522,20 @@ async function stampOf(files_: BlenderFiles, path: string): Promise<string> {
   return info ? `${info.size}:${info.mtimeMs}` : '';
 }
 
-async function stageProjectFiles(files_: BlenderFiles, project: string): Promise<void> {
+/**
+ * Copy the project's changed files into the engine, and answer what could NOT be copied.
+ *
+ * THE ANSWER IS THE POINT (2026-10-06 audit: files that failed to copy were "reported to the
+ * console only"). `say` writes the page console once per line, which nobody running a script
+ * reads; a script that then opens or loads the missing file fails, or worse succeeds on a
+ * stale copy, with no word of why. So every call returns its failures, and the callers put
+ * them where the caller of THAT is looking: `execute` appends them to the script's answer, and
+ * `start` refuses when the document itself is among them.
+ */
+async function stageProjectFiles(files_: BlenderFiles, project: string): Promise<string[]> {
   const files = await projectIndex(project);
-  if (!files) return;
+  if (typeof files === 'string') return [files];
+  const failed: string[] = [];
   const present = new Set(files.map((file) => `${project}/${file.path}`));
   for (const path of [...staged.keys()]) {
     if (present.has(path)) continue;
@@ -539,6 +557,7 @@ async function stageProjectFiles(files_: BlenderFiles, project: string): Promise
     );
     if (!answer.ok) {
       say(`${file.path}: HTTP ${answer.status}`);
+      failed.push(`${file.path} (the session answered HTTP ${answer.status})`);
       continue;
     }
     // The index can precede an append or rewrite. Stream the response's own size,
@@ -555,20 +574,34 @@ async function stageProjectFiles(files_: BlenderFiles, project: string): Promise
     }
     staged.set(path, { host: stamp, engine: await stampOf(files_, path) });
   }
+  return failed;
+}
+
+/** The failures `stageProjectFiles` answered, as one paragraph a script's caller can read. */
+function stagingNote(failed: readonly string[]): string {
+  return failed.length === 0 ? '' :
+    `\n\nThese project files could not be copied into Blender, so this code did not see their current contents: ${failed.join('; ')}`;
 }
 
 /** Everything under `root` this SESSION owns -- what the transport mirrors out.
  *  A host file staged in and NEVER WRITTEN is the host's and is not output;
  *  one Python has written over since it was staged is this session's output,
  *  the same as a path it created (see {@link staged}). */
-async function listSessionFiles(files: BlenderFiles, root: string): Promise<FileEntry[]> {
+async function listSessionFiles(files: BlenderFiles, hostRoot: string): Promise<FileEntry[]> {
+  // A host root reaches the engine in the engine's spelling, as the project itself does.
+  const root = projectMount(hostRoot);
   const out: FileEntry[] = [];
+  // A root the engine has no directory at holds no output yet, and that is an honest empty
+  // listing. A directory that exists and cannot be read is NOT: until 2026-10-06 every readdir
+  // failure was answered as "no files", which is how a Windows root the engine never had (the
+  // host's `C:\…` instead of `/C:/…`) reported success while nothing reached disk.
+  if ((await files.stat(root)) === null) return out;
   const walk = async (dir: string): Promise<void> => {
     let names: string[];
     try {
       names = await files.readdir(dir);
-    } catch {
-      return;
+    } catch (error) {
+      throw new Error(`Blender's files under ${dir} could not be listed, so its outputs there cannot be written back: ${String(error)}`);
     }
     for (const name of names) {
       if (name === '.' || name === '..') continue;
@@ -641,13 +674,13 @@ async function handle(request: WorkerRequest): Promise<unknown> {
       return ask({ op: 'history-step', token: request.token, direction: request.direction });
     case 'execute':
       // Code about to run may open a file the host wrote since the last call.
-      await stageProjectFiles(files, projectRoot);
       {
+        const note = stagingNote(await stageProjectFiles(files, projectRoot));
         const answer = await ask({ op: 'execute', code: request.code, history: request.history ?? true,
           label: request.label ?? 'Blender Python' }) as {
           error?: string; result: string;
         };
-        return answer.error ? `Error executing code: ${answer.error}` : `Code executed successfully: ${answer.result}`;
+        return (answer.error ? `Error executing code: ${answer.error}` : `Code executed successfully: ${answer.result}`) + note;
       }
     case 'present':
       // Straight through to `session.py`'s own `present` op — the worker adds

package/package.json

@@ -2,7 +2,7 @@
   "name": "@volter/blender-engine",
   "author": "Volter AI, Inc.",
   "license": "GPL-3.0-or-later",
-  "version": "0.1.127",
+  "version": "0.1.128",
   "publishConfig": {
     "access": "public"
   },