@volter/blender-engine 0.1.45 → 0.1.47

package/browser/runtime.ts

@@ -225,6 +225,12 @@ export class BlenderRuntime {
     return this.#document;
   }
 
+  /** Blender's last lines of output (the worker's log, newest last): what a status read shows,
+   *  including each document save's size and phase timings (`@@VOLTER-DOCUMENT`). */
+  get lastOutput(): readonly string[] {
+    return [...this.#lastLines];
+  }
+
   /** Idempotent: the first call boots Blender at `project`'s
    *  absolute path; later calls await it (a different path is refused).
    *

package/browser/session.py

@@ -1587,6 +1587,8 @@ class Session:
         for kind, keys, door in (("mesh", meshes, _blender_web.export_mesh),
                                  ("image", images, _blender_web.export_image)):
             for key in keys:
+                if kind == "image" and self._send_encoded_image(key, frame["images"][key]):
+                    continue
                 options["key"] = key
                 piece = json.loads(door(json.dumps(options)))
                 if piece.get("error"):
@@ -1598,6 +1600,53 @@ class Session:
                 ask({kind: key, "piece": piece[kind]})
         return True
 
+    def _send_encoded_image(self, key, deferred):
+        """A PICTURE AS ITS FILE'S OWN BYTES, when that is exactly what the frame would carry.
+
+        A modelling program keeps a picture compressed as its file and lets the GPU hold the
+        decoded texture; only this side's raster door decoded every picture into RGBA and shipped
+        that. MEASURED 2026-09-29 on the Stoneguard bridge: its 84 material pictures are 171 MB as
+        their packed files and 1,343 MB as RGBA, and the hosted tab's renderer passed 10 GB while
+        it opened. So a picture whose texels ARE its file -- a plain file or packed PNG or JPEG,
+        not edited in this session -- is written to the engine's filesystem as those bytes and
+        crosses as they are (`worker.ts`), decoded by the browser. The rest keep the raster door:
+        a key with `@` (a roughness remap bakes new texels), a picture painted here (`is_dirty`),
+        a UDIM or generated one, or bytes neither decoder reads.
+
+        Answers whether it was sent."""
+        if "@" in key:
+            return False
+        image = bpy.data.images.get(key)
+        if image is None or image.source != "FILE" or image.is_dirty:
+            return False
+        try:
+            if image.packed_file is not None:
+                data = bytes(image.packed_file.data)
+            else:
+                with open(bpy.path.abspath(image.filepath), "rb") as fh:
+                    data = fh.read()
+        except (OSError, TypeError, ValueError):
+            return False
+        if data[:8] == b"\x89PNG\r\n\x1a\n":
+            mime = "image/png"
+        elif data[:3] == b"\xff\xd8\xff":
+            mime = "image/jpeg"
+        else:
+            return False
+        path = os.path.join(ROOT, "encoded-image.bin")
+        with open(path, "wb") as fh:
+            fh.write(data)
+        try:
+            ask({"image": key, "piece": {
+                "revision": deferred["revision"],
+                "mime": mime,
+                "colorspace": "sRGB" if image.colorspace_settings.name == "sRGB" else "data",
+                "encodedPath": path,
+            }})
+        finally:
+            os.remove(path)
+        return True
+
     def _drop_unreachable_textures(self, frame):
         """A picture the export could not read is a WARNING, not a refusal.
 

package/browser/three/blender-runtime-view.ts

@@ -249,9 +249,13 @@ export async function texturesReady(): Promise<void> {
   while (pendingTextures.size > 0) await Promise.all([...pendingTextures]);
 }
 
-/** A PNG's bytes as a three texture, decoded by the browser's own decoder. */
-function loadPngTexture(png: Uint8Array): { texture: THREE.Texture; ready: Promise<void> } {
-  const blob = new Blob([png as BlobPart], { type: 'image/png' });
+/** An image file's own bytes (PNG or JPEG) as a three texture, decoded by the browser's own
+ *  decoder. */
+function loadEncodedTexture(
+  encoded: Uint8Array,
+  mime: 'image/png' | 'image/jpeg',
+): { texture: THREE.Texture; ready: Promise<void> } {
+  const blob = new Blob([encoded as BlobPart], { type: mime });
   const texture = new THREE.Texture();
   let disposed = false;
   texture.addEventListener('dispose', () => {
@@ -275,8 +279,14 @@ function loadPngTexture(png: Uint8Array): { texture: THREE.Texture; ready: Promi
   //
   // Its alpha is asked for here too: the browser's `default` premultiplies (Chrome's does), and
   // every reader of this texture takes the file's own texels, straight unless the image says it
-  // stores them premultiplied, which the reader then undoes.
-  const decoding = createImageBitmap(blob, { imageOrientation: 'flipY', premultiplyAlpha: 'none' })
+  // stores them premultiplied, which the reader then undoes. And its colour is the file's own: no
+  // embedded profile or gamma is applied, because Blender reads the texels as stored and applies
+  // the image's colour space setting itself, as the sampler does here.
+  const decoding = createImageBitmap(blob, {
+    imageOrientation: 'flipY',
+    premultiplyAlpha: 'none',
+    colorSpaceConversion: 'none',
+  })
     .then((bitmap) => {
       if (disposed) {
         bitmap.close();
@@ -392,14 +402,20 @@ const rasterImageSchema = z
     }).strict()).optional(),
   })
   .strict();
-const pngImageSchema = z
+/** An image as its FILE'S OWN BYTES, PNG or JPEG (`session.py::_encoded_image`): what the file
+ *  already carries compressed, decoded by the browser into the texture, so neither side holds
+ *  the picture as raw RGBA. MEASURED 2026-09-29 on the Stoneguard bridge: its 84 material images
+ *  are 171 MB as their packed files and 1,343 MB as RGBA. */
+const encodedImageSchema = z
   .object({
     revision: z.number().int().nonnegative(),
-    png: z.instanceof(Uint8Array).optional(),
-    pngBase64: z.string().optional(),
+    encoded: z.instanceof(Uint8Array).optional(),
+    encodedBase64: z.string().optional(),
+    mime: z.enum(['image/png', 'image/jpeg']),
+    colorspace: z.enum(['sRGB', 'data']).optional(),
   })
   .strict();
-const frameImageSchema = z.union([rasterImageSchema, pngImageSchema]);
+const frameImageSchema = z.union([rasterImageSchema, encodedImageSchema]);
 
 const textureReferenceSchema = z
   .object({
@@ -694,7 +710,7 @@ export class BlenderRuntimeView {
       width: number;
       height: number;
       revision: number;
-      png?: Uint8Array;
+      encoded?: { bytes: Uint8Array; mime: 'image/png' | 'image/jpeg'; colorspace: 'sRGB' | 'data' };
       ready?: Promise<void>;
       /** A UDIM image's tiles as a graph samples them (`udimTextures`). */
       udim?: {tiles: THREE.DataArrayTexture; map: THREE.DataTexture; frame: NonNullable<z.infer<typeof rasterImageSchema>['tiles']>};
@@ -1609,24 +1625,25 @@ export class BlenderRuntimeView {
         });
         continue;
       }
-      // A FILE'S OWN PNG, decoded once here. Its size is the bitmap's, so the
+      // A FILE'S OWN BYTES, decoded once here. Its size is the bitmap's, so the
       // cache records none: the next raster for this name, whatever its size,
       // is a rebuild rather than an upload into a texture whose dimensions
       // this side never learned.
-      const png = data.png ?? (data.pngBase64 ? bytesFromBase64(data.pngBase64) : undefined);
-      if (!png) throw new Error(`Runtime image ${name} carries no bytes`);
+      const encoded = data.encoded ?? (data.encodedBase64 ? bytesFromBase64(data.encodedBase64) : undefined);
+      if (!encoded) throw new Error(`Runtime image ${name} carries no bytes`);
       held?.texture.dispose();
       held?.udim?.tiles.dispose();
       held?.udim?.map.dispose();
-      const { texture, ready } = loadPngTexture(png);
-      texture.colorSpace = THREE.SRGBColorSpace;
+      const colorspace = data.colorspace ?? 'sRGB';
+      const { texture, ready } = loadEncodedTexture(encoded, data.mime);
+      texture.colorSpace = colorspace === 'data' ? THREE.NoColorSpace : THREE.SRGBColorSpace;
       this.textures.set(name, {
         texture,
         ready,
         width: 0,
         height: 0,
         revision: data.revision,
-        png: png.slice(),
+        encoded: { bytes: encoded.slice(), mime: data.mime, colorspace },
       });
     }
     for (const [id, data] of Object.entries(next.materials)) {
@@ -2034,8 +2051,13 @@ export class BlenderRuntimeView {
     for (const name of images) {
       const held = this.textures.get(name);
       if (!held) throw new Error(`Blender capture image ${name} is not resident`);
-      if (held.png) {
-        frame.images[name] = { revision: held.revision, png: held.png.slice() };
+      if (held.encoded) {
+        frame.images[name] = {
+          revision: held.revision,
+          encoded: held.encoded.bytes.slice(),
+          mime: held.encoded.mime,
+          colorspace: held.encoded.colorspace,
+        };
       } else {
         const data = held.texture.image?.data;
         if (!(data instanceof Uint8Array))

package/browser/worker.ts

@@ -198,9 +198,19 @@ function setDocumentDirty(dirty: boolean): void {
 async function saveDocument(): Promise<void> {
   if (!engine || documentPath === null) return;
   const relative = documentPath;
+  // Each phase's milliseconds, reported with the save: on a large document the save is the
+  // edit's cost, and where it goes differs by host (a tab-served project runs the server here).
+  const ms: Record<string, number> = {};
+  let mark = performance.now();
+  const lap = (phase: string) => {
+    const now = performance.now();
+    ms[phase] = Math.round(now - mark);
+    mark = now;
+  };
   let answer: { saved?: boolean; path?: string; size?: number };
   try {
     answer = (await engine.request({ op: 'save-document' })) as typeof answer;
+    lap('save');
   } catch (error) {
     // A document that cannot be written is the session's work at risk, so it
     // is a named condition in the editor's console, not a debug line.
@@ -211,6 +221,7 @@ async function saveDocument(): Promise<void> {
   let bytes: Uint8Array;
   try {
     bytes = await engine.files.readFile(answer.path);
+    lap('read');
   } catch (error) {
     throw new Error(`The Blender document ${relative} could not be read back out of the engine: ${describeThrown(error)}`);
   }
@@ -222,6 +233,7 @@ async function saveDocument(): Promise<void> {
   let sent = 0;
   try {
     const chunks = await documentChunks(bytes);
+    lap('chunk');
     const query = `path=${encodeURIComponent(relative)}`;
     const manifest = JSON.stringify({ chunks: chunks.map(({ hash, start, end }) => [hash, end - start]) });
     // The manifest asks for what the server lacks; after those are sent it commits. A second
@@ -232,9 +244,15 @@ async function saveDocument(): Promise<void> {
         headers: { 'content-type': 'application/json' },
         body: manifest,
       });
-      const said = (await posted.json().catch(() => null)) as { ok?: boolean; missing?: string[]; error?: string } | null;
+      const said = (await posted.json().catch(() => null)) as
+        | { ok?: boolean; missing?: string[]; error?: string; ms?: Record<string, number> }
+        | null;
+      lap(`manifest${round}`);
       if (!posted.ok) throw new Error(`HTTP ${posted.status} ${said?.error ?? ''}`);
-      if (said?.ok) break;
+      if (said?.ok) {
+        for (const [phase, value] of Object.entries(said.ms ?? {})) ms[`server.${phase}`] = value;
+        break;
+      }
       if (round === 2 || !Array.isArray(said?.missing)) throw new Error(`the server still lacks ${said?.missing?.length ?? '?'} chunks`);
       const wanted = new Set(said.missing);
       for (const chunk of chunks) {
@@ -247,12 +265,13 @@ async function saveDocument(): Promise<void> {
         if (!part.ok) throw new Error(`HTTP ${part.status} ${await part.text().catch(() => '')}`);
         sent += chunk.end - chunk.start;
       }
+      lap(`send${round}`);
     }
   } catch (error) {
     throw new Error(`The Blender document ${relative} was not written to the project: ${describeThrown(error)}`);
   }
   setDocumentDirty(false);
-  log('log', `@@VOLTER-DOCUMENT ${JSON.stringify({ path: relative, bytes: bytes.length, sent })}`);
+  log('log', `@@VOLTER-DOCUMENT ${JSON.stringify({ path: relative, bytes: bytes.length, sent, ms })}`);
 }
 
 async function startBlender(project: string, document?: string): Promise<unknown> {
@@ -281,10 +300,26 @@ async function startBlender(project: string, document?: string): Promise<unknown
       }
       if (mesh !== undefined || image !== undefined) {
         if (!pending) throw new Error(`The Blender session sent ${mesh ?? image} before its frame`);
-        const copied = {
-          typed: columnsToTypedArrays(arena, piece),
-          description: await describeFrame(arena, piece),
-        };
+        // A PICTURE AS ITS FILE'S OWN BYTES (`session.py::_encoded_image`): the session wrote
+        // them to `encodedPath` rather than decoding them into the arena, and they cross as they
+        // are; the record keeps their digest, as it does a column's.
+        const encodedPath = (piece as { encodedPath?: unknown } | undefined)?.encodedPath;
+        let copied: Copied;
+        if (image !== undefined && typeof encodedPath === 'string') {
+          const { encodedPath: _path, ...rest } = piece as Record<string, unknown>;
+          const bytes = (await holder.engine.files.readFile(encodedPath)).slice();
+          const digest = new Uint8Array(await crypto.subtle.digest('SHA-256', bytes));
+          const sha256 = Array.from(digest, (byte) => byte.toString(16).padStart(2, '0')).join('');
+          copied = {
+            typed: { ...rest, encoded: bytes },
+            description: { ...rest, encoded: { dtype: 'u8', length: bytes.length, sha256 } },
+          };
+        } else {
+          copied = {
+            typed: columnsToTypedArrays(arena, piece),
+            description: await describeFrame(arena, piece),
+          };
+        }
         if (mesh !== undefined) pending.meshes.set(mesh, copied);
         else pending.images.set(image as string, copied);
         return {};

package/package.json

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