@volter/blender-engine 0.1.46 → 0.1.48

package/browser/session.py

@@ -143,6 +143,25 @@ REPLY = os.path.join(ROOT, "reply")
 # (`blender-wali-engine.mts`), where the file is not a fallback but the
 # native door onto the same bytes.
 EXPORT_BUFFER_PATH = os.environ.get("VOLTER_EXPORT_BUFFER_PATH", "")
+
+# WHERE THE ENGINE'S HEAP WENT, stage by stage: the heap only grows, so its size after a stage says
+# nothing about the stage before it; this records `_blender_web.memory()` at each, in MB
+# ([label, heap, mallocInUse, mallocFree, guarded, guardedPeak]), and a script reads `MEMORY_MARKS`
+# (the last 64) to say which stage raised the high-water mark. MEASURED 2026-09-29 on the
+# Stoneguard file: the first export's door call took the heap from 1,442 to 3,644 MB while in-use
+# rose 28 MB and the guarded peak did not move -- OpenSubdiv's limit-surface evaluator for one
+# head (quality 3), which native Blender pays too (+1.2 GB peak RSS there).
+MEMORY_MARKS = []
+
+
+def _mark(label):
+    try:
+        reading = _blender_web.memory()
+    except Exception:  # noqa: BLE001 -- an engine without the door records nothing
+        return
+    MEMORY_MARKS.append([label] + [round(reading.get(key, 0) / 1048576)
+                                   for key in ("heap", "mallocInUse", "mallocFree", "guarded", "guardedPeak")])
+    del MEMORY_MARKS[:-64]
 _real_stderr = sys.stderr
 
 
@@ -1358,6 +1377,7 @@ class Session:
         """
         scene = bpy.context.scene
         graphs = material_graphs(scene)
+        _mark("export:graphs")
         # An IMAGE EMPTY's picture travels with the graphs' images: the overlay draws it
         # (`overlay_empty.hh` `image_sync`).
         empty_images = {obj.data.name for obj in scene.objects
@@ -1378,7 +1398,13 @@ class Session:
         # An engine without the pull door ships them all in this call, as before.
         if hasattr(_blender_web, "export_mesh"):
             options["defer"] = True
-        frame = json.loads(_blender_web.export_frame(json.dumps(options)))
+        if hasattr(_blender_web, "memory_reset_peak"):
+            _blender_web.memory_reset_peak()
+        exported = _blender_web.export_frame(json.dumps(options))
+        _mark("export:door")
+        frame = json.loads(exported)
+        del exported
+        _mark("export:parsed")
         error = frame.get("error")
         if error:
             raise RuntimeError("Blender export door: %s" % error)
@@ -1507,8 +1533,11 @@ class Session:
 
     def _present(self, capture=None):
         known = dict(self._known)
+        _mark("present:before")
         frame = self._export()
+        _mark("present:exported")
         pulled = self._pull(frame)
+        _mark("present:pulled")
         self._drop_unreachable_textures(frame)
         # WHAT THIS FRAME SHIPPED, for the session's own accounting: the ids
         # whose columns crossed, and the ids that went as a reference. The
@@ -1587,6 +1616,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 +1629,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.
 
@@ -1767,7 +1845,9 @@ class Session:
         self.document = os.path.join(self.project, relative_path)
         if not os.path.exists(self.document):
             return {"document": relative_path, "opened": False}
+        _mark("open:before")
         bpy.ops.wm.open_mainfile(filepath=self.document)
+        _mark("open:after")
         size = os.path.getsize(self.document)
         # THE STAGED COPY GOES ONCE BLENDER HAS READ IT. It sits in the engine's heap (WasmFS keeps
         # file data in linear memory) and nothing reads it again: the load took everything into

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

@@ -300,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.46",
+  "version": "0.1.48",
   "publishConfig": {
     "access": "public"
   },