@driftengine/assets 4.6.1 → 4.7.1

package/dist/blendNormals.js

@@ -0,0 +1,458 @@
+/**
+ * The normal Blender shades each face corner with, computed from what a `.blend` stores.
+ *
+ * **A `.blend` stores no shading normals unless somebody customised them**, so a reader has to
+ * derive the ones Blender draws, and "a smooth normal" is not specific enough to agree with it.
+ * Blender's rule, which this follows step for step:
+ *
+ * - Every face flat, or every edge sharp: each corner takes its face's normal.
+ * - Every face smooth and no edge sharp: each corner takes its vertex's normal, the sum of the
+ *   normals of every face at the vertex weighted by the angle each face makes there.
+ * - Otherwise the corners around a vertex split into *fans* at every sharp edge — an edge tagged
+ *   sharp, an edge beside a flat face, an edge with more or fewer than two faces, and an edge whose
+ *   faces disagree about winding — and each fan takes the angle-weighted sum over its own faces.
+ *
+ * **Custom normals are stored relative to those fans**, two shorts per corner: an angle away from
+ * the fan's normal and an angle around it from the fan's first edge. Decoding them needs the fans
+ * walked in exactly Blender's order, which is why the walk below starts each fan where Blender
+ * starts it and visits faces in the direction Blender turns. A vector normal stored as an
+ * attribute — 4.5 on — needs none of this and is used as it stands.
+ *
+ * What it gives up: nothing it knows of. Its arithmetic is in doubles where Blender's is in
+ * floats, which is a difference of about 1e-4 in a normal and is what the fixtures allow.
+ */
+import { FACE, POINT } from './blendMesh.js';
+const EMPTY = -1;
+const UNSET = -2;
+const INVALID = -3;
+/** Blender's limit beyond which two directions are too close to define a frame between them. */
+const TRIGO_THRESHOLD = 1 - 1e-4;
+const TAU = Math.PI * 2;
+const acos = (x) => Math.acos(Math.max(-1, Math.min(1, x)));
+const f32 = Math.fround;
+/** Blender's approximate arc cosine for corner angles, in its single precision. */
+function cornerAngle(x) {
+    const f = f32(Math.abs(x));
+    const m = f < 1 ? f32(1 - f32(1 - f)) : 1;
+    const a = f32(Math.sqrt(f32(1 - m)) *
+        f32(1.5707963267 + m * f32(-0.213300989 + m * f32(0.077980478 + m * -0.02164095))));
+    return x < 0 ? f32(Math.PI - a) : a;
+}
+const dot = (a, b) => a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+function normalise(v) {
+    const length = Math.hypot(v[0], v[1], v[2]);
+    if (length > 1e-35) {
+        v[0] /= length;
+        v[1] /= length;
+        v[2] /= length;
+    }
+    else {
+        v[0] = v[1] = v[2] = 0;
+    }
+    return length;
+}
+/**
+ * Each face's normal, by the rule Blender uses for its size: two edges of a triangle, the two
+ * diagonals of a quad, and Newell's method beyond that.
+ *
+ * **Not Newell's method throughout**, which is what this was until a real file disagreed: a quad
+ * with two coincident corners has no area, so Newell gives it no normal, while its diagonals still
+ * cross. And where even they cancel — a quad whose corners coincide in pairs — Blender calls the
+ * face's normal straight up rather than zero, and averages that into its smooth neighbours. Both
+ * were found on a 2.79 wheel, where one such face moved a vertex normal 0.68 from Blender's.
+ */
+export function faceNormals(mesh) {
+    const { positions: p, faceOffsets, cornerVerts } = mesh;
+    const faces = faceOffsets.length - 1;
+    const out = new Float64Array(faces * 3);
+    const at = (corner, axis) => p[cornerVerts[corner] * 3 + axis];
+    for (let f = 0; f < faces; f++) {
+        const start = faceOffsets[f];
+        const end = faceOffsets[f + 1];
+        const n = [0, 0, 0];
+        if (end - start === 3 || end - start === 4) {
+            /* Triangle: (v0 - v1) x (v1 - v2). Quad: (v0 - v2) x (v1 - v3). */
+            const quad = end - start === 4;
+            const a = [0, 1, 2].map((k) => at(start, k) - at(start + (quad ? 2 : 1), k));
+            const b = [0, 1, 2].map((k) => at(start + 1, k) - at(start + (quad ? 3 : 2), k));
+            n[0] = a[1] * b[2] - a[2] * b[1];
+            n[1] = a[2] * b[0] - a[0] * b[2];
+            n[2] = a[0] * b[1] - a[1] * b[0];
+        }
+        else {
+            let prev = cornerVerts[end - 1] * 3;
+            for (let c = start; c < end; c++) {
+                const curr = cornerVerts[c] * 3;
+                const px = p[prev], py = p[prev + 1], pz = p[prev + 2];
+                const cx = p[curr], cy = p[curr + 1], cz = p[curr + 2];
+                n[0] += (py - cy) * (pz + cz);
+                n[1] += (pz - cz) * (px + cx);
+                n[2] += (px - cx) * (py + cy);
+                prev = curr;
+            }
+        }
+        /* Blender's convention for a face with no area: it faces up. Its neighbours average it in. */
+        if (normalise(n) === 0)
+            n[2] = 1;
+        out.set(n, f * 3);
+    }
+    return out;
+}
+function direction(mesh, from, to) {
+    const p = mesh.positions;
+    const v = [
+        p[to * 3] - p[from * 3],
+        p[to * 3 + 1] - p[from * 3 + 1],
+        p[to * 3 + 2] - p[from * 3 + 2],
+    ];
+    normalise(v);
+    return v;
+}
+/** The angle-weighted vertex normals, what an all-smooth mesh shades with. */
+export function vertexNormals(mesh, face) {
+    const { faceOffsets, cornerVerts, positions } = mesh;
+    const verts = positions.length / 3;
+    const out = new Float64Array(verts * 3);
+    for (let f = 0; f < faceOffsets.length - 1; f++) {
+        const start = faceOffsets[f];
+        const end = faceOffsets[f + 1];
+        for (let c = start; c < end; c++) {
+            const v = cornerVerts[c];
+            const prev = cornerVerts[c === start ? end - 1 : c - 1];
+            const next = cornerVerts[c + 1 === end ? start : c + 1];
+            const angle = cornerAngle(dot(direction(mesh, v, prev), direction(mesh, v, next)));
+            for (let k = 0; k < 3; k++)
+                out[v * 3 + k] = out[v * 3 + k] + face[f * 3 + k] * angle;
+        }
+    }
+    for (let v = 0; v < verts; v++) {
+        const n = [out[v * 3], out[v * 3 + 1], out[v * 3 + 2]];
+        /* Blender's convention for a vertex with no usable faces: point the normal along its position. */
+        if (normalise(n) === 0) {
+            n[0] = positions[v * 3];
+            n[1] = positions[v * 3 + 1];
+            n[2] = positions[v * 3 + 2];
+            normalise(n);
+        }
+        out.set(n, v * 3);
+    }
+    return out;
+}
+/** Every edge that splits a fan: tagged, beside a flat face, not two-faced, or flipped. */
+function edgeLoops(mesh, sharpEdge) {
+    const { faceOffsets, cornerVerts, cornerEdges, sharpFace } = mesh;
+    const edges = mesh.edgeVerts.length / 2;
+    const e2l = new Int32Array(edges * 2).fill(EMPTY);
+    for (let f = 0; f < faceOffsets.length - 1; f++) {
+        const flat = sharpFace !== null && sharpFace[f] === 1;
+        for (let c = faceOffsets[f]; c < faceOffsets[f + 1]; c++) {
+            const e = cornerEdges[c];
+            if (e2l[e * 2] === EMPTY) {
+                e2l[e * 2] = c;
+                e2l[e * 2 + 1] = flat ? INVALID : UNSET;
+            }
+            else if (e2l[e * 2 + 1] === UNSET) {
+                const first = e2l[e * 2];
+                if (flat ||
+                    (sharpEdge !== null && sharpEdge[e] === 1) ||
+                    cornerVerts[c] === cornerVerts[first]) {
+                    e2l[e * 2 + 1] = INVALID;
+                }
+                else
+                    e2l[e * 2 + 1] = c;
+            }
+            else if (e2l[e * 2 + 1] !== INVALID) {
+                e2l[e * 2 + 1] = INVALID;
+            }
+        }
+    }
+    return e2l;
+}
+const isSharp = (e2l, edge) => {
+    const second = e2l[edge * 2 + 1];
+    return second === UNSET || second === INVALID;
+};
+function defineSpace(lnor, ref, other, edges) {
+    const space = { lnor: [...lnor], ref: [0, 0, 0], ortho: [0, 0, 0], alpha: 0, beta: 0 };
+    const dRef = dot(ref, lnor);
+    const dOther = dot(other, lnor);
+    if (Math.abs(dRef) >= TRIGO_THRESHOLD || Math.abs(dOther) >= TRIGO_THRESHOLD)
+        return space;
+    if (edges.length > 0) {
+        let alpha = 0;
+        for (const e of edges)
+            alpha += acos(dot(e, lnor));
+        space.alpha = alpha / edges.length;
+    }
+    else {
+        space.alpha = (acos(dRef) + acos(dOther)) / 2;
+    }
+    const r = [ref[0] - lnor[0] * dRef, ref[1] - lnor[1] * dRef, ref[2] - lnor[2] * dRef];
+    normalise(r);
+    space.ref = r;
+    const o = [
+        lnor[1] * r[2] - lnor[2] * r[1],
+        lnor[2] * r[0] - lnor[0] * r[2],
+        lnor[0] * r[1] - lnor[1] * r[0],
+    ];
+    normalise(o);
+    space.ortho = o;
+    const t = [
+        other[0] - lnor[0] * dOther,
+        other[1] - lnor[1] * dOther,
+        other[2] - lnor[2] * dOther,
+    ];
+    normalise(t);
+    const d = dot(r, t);
+    if (d < TRIGO_THRESHOLD) {
+        const beta = acos(d);
+        space.beta = dot(o, t) < 0 ? TAU - beta : beta;
+    }
+    else
+        space.beta = TAU;
+    return space;
+}
+function decode(space, a, b) {
+    if (a === 0 || space.alpha === 0 || space.beta === 0)
+        return [...space.lnor];
+    const alphaFac = a / 32767;
+    const alpha = (alphaFac > 0 ? space.alpha : TAU - space.alpha) * alphaFac;
+    const out = [
+        space.lnor[0] * Math.cos(alpha),
+        space.lnor[1] * Math.cos(alpha),
+        space.lnor[2] * Math.cos(alpha),
+    ];
+    const sinAlpha = Math.sin(alpha);
+    if (b === 0) {
+        for (let k = 0; k < 3; k++)
+            out[k] = out[k] + space.ref[k] * sinAlpha;
+        return out;
+    }
+    const betaFac = b / 32767;
+    const beta = (betaFac > 0 ? space.beta : TAU - space.beta) * betaFac;
+    for (let k = 0; k < 3; k++) {
+        const i = k;
+        out[i] += space.ref[i] * sinAlpha * Math.cos(beta) + space.ortho[i] * sinAlpha * Math.sin(beta);
+    }
+    return out;
+}
+/**
+ * The normal every corner is shaded with, three floats per corner, in the mesh's own space.
+ *
+ * `splitAngle` also tags as sharp every edge whose faces meet at more than it: a pre-4.1 file's
+ * auto smooth by default, or the angle of a Smooth by Angle modifier, which does the same thing.
+ */
+export function cornerNormals(mesh, splitAngle = mesh.autoSmooth) {
+    const { faceOffsets, cornerVerts, cornerEdges, edgeVerts, sharpFace } = mesh;
+    const corners = cornerVerts.length;
+    const faces = faceOffsets.length - 1;
+    const out = new Float32Array(corners * 3);
+    const face = faceNormals(mesh);
+    const faceOf = new Int32Array(corners);
+    for (let f = 0; f < faces; f++)
+        faceOf.fill(f, faceOffsets[f], faceOffsets[f + 1]);
+    if (mesh.freeNormals !== null && mesh.packedNormals === null) {
+        const { domain, normals } = mesh.freeNormals;
+        for (let c = 0; c < corners; c++) {
+            const i = domain === POINT ? cornerVerts[c] : domain === FACE ? faceOf[c] : c;
+            const n = [
+                normals[i * 3],
+                normals[i * 3 + 1],
+                normals[i * 3 + 2],
+            ];
+            normalise(n);
+            out.set(n, c * 3);
+        }
+        return out;
+    }
+    let sharpEdge = mesh.sharpEdge;
+    if (splitAngle !== null)
+        sharpEdge = byAngle(mesh, face, splitAngle);
+    const allFlat = faces > 0 && sharpFace !== null && sharpFace.every((s) => s === 1);
+    const allSharp = sharpEdge !== null && sharpEdge.length > 0 && sharpEdge.every((s) => s === 1);
+    const anyFlat = sharpFace !== null && sharpFace.some((s) => s === 1);
+    const anySharp = sharpEdge !== null && sharpEdge.some((s) => s === 1);
+    if (mesh.packedNormals === null && (allFlat || allSharp)) {
+        for (let c = 0; c < corners; c++)
+            out.set(face.subarray(faceOf[c] * 3, faceOf[c] * 3 + 3), c * 3);
+        return out;
+    }
+    const vertex = vertexNormals(mesh, face);
+    if (mesh.packedNormals === null && !anyFlat && !anySharp) {
+        for (let c = 0; c < corners; c++) {
+            const v = cornerVerts[c];
+            out.set(vertex.subarray(v * 3, v * 3 + 3), c * 3);
+        }
+        return out;
+    }
+    const e2l = edgeLoops(mesh, sharpEdge);
+    const packed = mesh.packedNormals;
+    const other = (edge, pivot) => edgeVerts[edge * 2] === pivot
+        ? edgeVerts[edge * 2 + 1]
+        : edgeVerts[edge * 2];
+    const prevCorner = (c) => {
+        const f = faceOf[c];
+        return c === faceOffsets[f] ? faceOffsets[f + 1] - 1 : c - 1;
+    };
+    const nextCorner = (c) => {
+        const f = faceOf[c];
+        return c + 1 === faceOffsets[f + 1] ? faceOffsets[f] : c + 1;
+    };
+    /* Prefilled as Blender prefills: the vertex normal where smooth, the face normal where flat. */
+    for (let c = 0; c < corners; c++) {
+        const f = faceOf[c];
+        if (sharpFace !== null && sharpFace[f] === 1)
+            out.set(face.subarray(f * 3, f * 3 + 3), c * 3);
+        else {
+            const v = cornerVerts[c];
+            out.set(vertex.subarray(v * 3, v * 3 + 3), c * 3);
+        }
+    }
+    /** Cross the edge `curr` names into the next face around `pivot`: Blender's fan step. */
+    const step = (curr, pivot) => {
+        const edge = cornerEdges[curr];
+        const a = e2l[edge * 2];
+        const b = e2l[edge * 2 + 1];
+        const fromVert = cornerVerts[curr];
+        const next = a === curr ? b : a;
+        const nextVert = cornerVerts[next];
+        if ((fromVert === nextVert && fromVert === pivot) ||
+            (fromVert !== nextVert && fromVert !== pivot)) {
+            return { curr: prevCorner(next), vert: next };
+        }
+        const forward = nextCorner(next);
+        return { curr: forward, vert: forward };
+    };
+    const skip = new Uint8Array(corners);
+    const cyclic = (start, prev) => {
+        const pivot = cornerVerts[start];
+        if (isSharp(e2l, cornerEdges[prev]))
+            return false;
+        let curr = prev;
+        let vert = start;
+        skip[vert] = 1;
+        for (;;) {
+            ({ curr, vert } = step(curr, pivot));
+            if (isSharp(e2l, cornerEdges[curr]))
+                return false;
+            if (skip[vert] === 1)
+                return vert === start;
+            skip[vert] = 1;
+        }
+    };
+    const single = (c) => {
+        const f = faceOf[c];
+        const n = [face[f * 3], face[f * 3 + 1], face[f * 3 + 2]];
+        if (packed !== null) {
+            const v = cornerVerts[c];
+            const space = defineSpace(n, direction(mesh, v, cornerVerts[nextCorner(c)]), direction(mesh, v, cornerVerts[prevCorner(c)]), []);
+            out.set(decode(space, packed[c * 2], packed[c * 2 + 1]), c * 3);
+        }
+        else
+            out.set(n, c * 3);
+    };
+    const fan = (start, prev) => {
+        const pivot = cornerVerts[start];
+        const origin = cornerEdges[start];
+        const vecOrigin = direction(mesh, pivot, other(origin, pivot));
+        let vecPrev = vecOrigin;
+        let vecCurr = vecOrigin;
+        const edges = [vecOrigin];
+        const members = [];
+        const lnor = [0, 0, 0];
+        let curr = prev;
+        let vert = start;
+        for (let guard = 0; guard <= corners; guard++) {
+            const edge = cornerEdges[curr];
+            vecCurr = direction(mesh, pivot, other(edge, pivot));
+            const angle = cornerAngle(dot(vecCurr, vecPrev));
+            const f = faceOf[curr];
+            for (let k = 0; k < 3; k++)
+                lnor[k] += face[f * 3 + k] * angle;
+            members.push(vert);
+            if (edge !== origin)
+                edges.push(vecCurr);
+            if (isSharp(e2l, edge) || edge === origin)
+                break;
+            vecPrev = vecCurr;
+            ({ curr, vert } = step(curr, pivot));
+        }
+        let length = normalise(lnor);
+        if (packed !== null) {
+            if (length === 0) {
+                const v = cornerVerts[vert];
+                lnor[0] = vertex[v * 3];
+                lnor[1] = vertex[v * 3 + 1];
+                lnor[2] = vertex[v * 3 + 2];
+                length = 1;
+            }
+            const space = defineSpace(lnor, vecOrigin, vecCurr, edges);
+            const first = members[0];
+            let a = packed[first * 2];
+            let b = packed[first * 2 + 1];
+            if (members.some((m) => packed[m * 2] !== a || packed[m * 2 + 1] !== b)) {
+                let sa = 0;
+                let sb = 0;
+                for (const m of members) {
+                    sa += packed[m * 2];
+                    sb += packed[m * 2 + 1];
+                }
+                a = Math.trunc(sa / members.length);
+                b = Math.trunc(sb / members.length);
+            }
+            const custom = decode(space, a, b);
+            lnor[0] = custom[0];
+            lnor[1] = custom[1];
+            lnor[2] = custom[2];
+        }
+        if (length !== 0)
+            for (const m of members)
+                out.set(lnor, m * 3);
+    };
+    for (let f = 0; f < faces; f++) {
+        for (let c = faceOffsets[f]; c < faceOffsets[f + 1]; c++) {
+            const prev = prevCorner(c);
+            const currSharp = isSharp(e2l, cornerEdges[c]);
+            const prevSharp = isSharp(e2l, cornerEdges[prev]);
+            if (currSharp && prevSharp)
+                single(c);
+            else if (currSharp || (!prevSharp && skip[c] === 0 && cyclic(c, prev)))
+                fan(c, prev);
+        }
+    }
+    return out;
+}
+/** What Blender's smooth-by-angle does to a pre-4.1 file with auto smooth on: tag by angle too. */
+function byAngle(mesh, face, angle) {
+    const edges = mesh.edgeVerts.length / 2;
+    const out = new Uint8Array(edges);
+    if (mesh.sharpEdge !== null)
+        out.set(mesh.sharpEdge);
+    const first = new Int32Array(edges).fill(-1);
+    const count = new Int32Array(edges);
+    const second = new Int32Array(edges).fill(-1);
+    const { faceOffsets, cornerEdges } = mesh;
+    for (let f = 0; f < faceOffsets.length - 1; f++) {
+        for (let c = faceOffsets[f]; c < faceOffsets[f + 1]; c++) {
+            const e = cornerEdges[c];
+            if (count[e] === 0)
+                first[e] = f;
+            else if (count[e] === 1)
+                second[e] = f;
+            count[e] = count[e] + 1;
+        }
+    }
+    const cos = Math.cos(angle);
+    for (let e = 0; e < edges; e++) {
+        if (count[e] !== 2)
+            continue;
+        const a = first[e];
+        const b = second[e];
+        const d = face[a * 3] * face[b * 3] +
+            face[a * 3 + 1] * face[b * 3 + 1] +
+            face[a * 3 + 2] * face[b * 3 + 2];
+        if (d < cos)
+            out[e] = 1;
+    }
+    return out;
+}

package/dist/blendPacked.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Undoing the compression a `.blend` was saved with, through a decompressor the host supplies.
+ *
+ * **Blender has saved compressed files two ways.** Before 3.0 the whole file was one gzip stream.
+ * From 3.0 it is zstd in the *seekable* layout: the file cut into independent frames, and a table
+ * at the end in a skippable frame saying how long each one is. This module reads that table and
+ * hands each frame to the host's decoder, because a decoder asked for the whole file may stop at
+ * the end of the first frame and say nothing: Node 22's `zstdDecompressSync` returned 67 KB of a
+ * three-frame, 330 KB fixture, which then read as a file that ends before its `ENDB`.
+ *
+ * **The decoder is the host's, not this module's.** Node has both; a browser has gzip in
+ * `DecompressionStream` and, depending on the browser, no zstd at all. Shipping a zstd decoder
+ * here would be owning a correctness risk the platform already carries, which is the argument
+ * `fbxInflate.ts` makes for deflate. A host without one is told the name of what to pass.
+ *
+ * What it gives up: a zstd file with no seek table — one no Blender writes — is handed to the
+ * decoder whole, and a decoder that stops after one frame then truncates it. The truncation is
+ * caught downstream, by the missing `ENDB`, rather than here.
+ */
+/** Decompress one gzip stream or one zstd frame. Supplied by the host. */
+export type BlendDecompress = (compressed: Uint8Array, codec: 'gzip' | 'zstd') => Uint8Array | Promise<Uint8Array>;
+/** Each frame's compressed and decompressed length, from the seek table, or null where there is none. */
+export declare function zstdFrames(bytes: Uint8Array): {
+    packed: number;
+    plain: number;
+}[] | null;
+/**
+ * The plain bytes of a `.blend`, decompressing first where the file says it is compressed.
+ *
+ * **Allocated once, from the seek table.** The table states every frame's decompressed length, so
+ * the output is sized before the first frame is decoded and each frame is copied into place and
+ * dropped. Collecting the frames and joining them afterwards held the file twice at its peak, which
+ * is 14 GB for a 7 GB city and was the difference between reading it and not.
+ */
+export declare function unpackBlend(bytes: Uint8Array, decompress: BlendDecompress | undefined): Promise<Uint8Array>;

package/dist/blendPacked.js

@@ -0,0 +1,82 @@
+/**
+ * Undoing the compression a `.blend` was saved with, through a decompressor the host supplies.
+ *
+ * **Blender has saved compressed files two ways.** Before 3.0 the whole file was one gzip stream.
+ * From 3.0 it is zstd in the *seekable* layout: the file cut into independent frames, and a table
+ * at the end in a skippable frame saying how long each one is. This module reads that table and
+ * hands each frame to the host's decoder, because a decoder asked for the whole file may stop at
+ * the end of the first frame and say nothing: Node 22's `zstdDecompressSync` returned 67 KB of a
+ * three-frame, 330 KB fixture, which then read as a file that ends before its `ENDB`.
+ *
+ * **The decoder is the host's, not this module's.** Node has both; a browser has gzip in
+ * `DecompressionStream` and, depending on the browser, no zstd at all. Shipping a zstd decoder
+ * here would be owning a correctness risk the platform already carries, which is the argument
+ * `fbxInflate.ts` makes for deflate. A host without one is told the name of what to pass.
+ *
+ * What it gives up: a zstd file with no seek table — one no Blender writes — is handed to the
+ * decoder whole, and a decoder that stops after one frame then truncates it. The truncation is
+ * caught downstream, by the missing `ENDB`, rather than here.
+ */
+import { DrftError } from '@driftengine/drft';
+import { blendCompression } from './blendFile.js';
+const SEEKABLE_MAGIC = 0x8f92eab1;
+const SKIPPABLE_MAGIC = 0x184d2a5e;
+/** Each frame's compressed and decompressed length, from the seek table, or null where there is none. */
+export function zstdFrames(bytes) {
+    if (bytes.length < 17)
+        return null;
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    const footer = bytes.length - 9;
+    if (view.getUint32(footer + 5, true) !== SEEKABLE_MAGIC)
+        return null;
+    const frames = view.getUint32(footer, true);
+    const descriptor = bytes[footer + 4] ?? 0;
+    const entry = descriptor & 0x80 ? 12 : 8;
+    const table = footer - frames * entry;
+    const header = table - 8;
+    if (header < 0 || view.getUint32(header, true) !== SKIPPABLE_MAGIC)
+        return null;
+    const sizes = [];
+    let total = 0;
+    for (let i = 0; i < frames; i++) {
+        const packed = view.getUint32(table + i * entry, true);
+        sizes.push({ packed, plain: view.getUint32(table + i * entry + 4, true) });
+        total += packed;
+    }
+    return total === header ? sizes : null;
+}
+/**
+ * The plain bytes of a `.blend`, decompressing first where the file says it is compressed.
+ *
+ * **Allocated once, from the seek table.** The table states every frame's decompressed length, so
+ * the output is sized before the first frame is decoded and each frame is copied into place and
+ * dropped. Collecting the frames and joining them afterwards held the file twice at its peak, which
+ * is 14 GB for a 7 GB city and was the difference between reading it and not.
+ */
+export async function unpackBlend(bytes, decompress) {
+    const codec = blendCompression(bytes);
+    if (codec === null)
+        return bytes;
+    if (decompress === undefined) {
+        throw new DrftError(`.blend saved with ${codec} compression needs a "decompress" to be read. Bake it with ` +
+            '`npm run bake`, which supplies one, or pass decompress to readModel.');
+    }
+    if (codec === 'gzip')
+        return decompress(bytes, 'gzip');
+    const frames = zstdFrames(bytes);
+    if (frames === null)
+        return decompress(bytes, 'zstd');
+    const out = new Uint8Array(frames.reduce((n, frame) => n + frame.plain, 0));
+    let from = 0;
+    let to = 0;
+    for (const frame of frames) {
+        const part = await decompress(bytes.subarray(from, from + frame.packed), 'zstd');
+        if (part.length !== frame.plain) {
+            throw new DrftError(`blend: a zstd frame decoded to ${part.length} bytes where the seek table says ${frame.plain}`);
+        }
+        out.set(part, to);
+        from += frame.packed;
+        to += part.length;
+    }
+    return out;
+}

package/dist/blendScene.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Which objects of a `.blend` are drawn, and where: the scene walk, in Blender's coordinates.
+ *
+ * **"Drawn" means what a render of the open scene shows**, the same rule `scripts/blender/
+ * export_gltf.py` applies before it hands the scene to Blender's exporter, so both routes into
+ * the engine agree on what an asset contains. An object is drawn when it is linked into the scene
+ * through at least one collection that is neither excluded from the view layer nor disabled for
+ * rendering, and is not itself hidden from renders. Parenting does not hide: a child of a hidden
+ * object is drawn where its parent would have put it, which is what Blender does.
+ *
+ * **A collection instance is expanded** into its objects, placed by the instancer and shifted by
+ * the collection's instance offset. Before 2.8 there were no collections, and the scene's bases and
+ * layer bits say the same thing.
+ *
+ * **What has to be evaluated is refused rather than guessed.** A constraint, a vertex parent or a
+ * particle instancer changes where things are by running Blender, so the walk names it in
+ * `refusals` and the caller declines the whole file. Animation does not refuse: Blender writes the
+ * evaluated value of every animated property back to the datablock, so a saved file holds the
+ * pose of the frame it was saved on.
+ */
+import type { BlendData, BlendStruct } from './blendData.ts';
+import type { Mat4 } from './blendMatrix.ts';
+/** One drawn object, or an empty that carries others, at its place in the world. */
+export interface BlendPlaced {
+    readonly object: BlendStruct;
+    readonly name: string;
+    /** Blender's object type: 0 empty, 1 mesh, 10 light, 25 armature, and the rest. */
+    readonly kind: number;
+    /** World matrix, Blender space (Z up), column-major. */
+    readonly world: Mat4;
+    /** Index of the nearest placed ancestor, or -1. */
+    readonly parent: number;
+}
+export declare const OB_EMPTY = 0;
+export declare const OB_MESH = 1;
+export declare const OB_LAMP = 10;
+export declare const OB_CAMERA = 11;
+export declare const OB_ARMATURE = 25;
+/** The scene the file was saved looking at. */
+export declare function activeScene(blend: BlendData): BlendStruct | null;
+/**
+ * The object's transform relative to its parent: location, rotation and scale, deltas folded in.
+ *
+ * `values`, where given, overrides what the file stores with what an animation says at a frame,
+ * keyed by Blender's data path and index — `location[0]`, `rotation_quaternion[3]` — which is what
+ * `Animation.values` fills (`blendAnimation.ts`).
+ */
+export declare function localMatrix(object: BlendStruct, values?: ReadonlyMap<string, number>): Mat4;
+/** Walk the scene into placed objects, naming in `refusals` anything that needs Blender to run. */
+export declare function placeObjects(blend: BlendData, refusals: string[], bonePose: (armature: BlendStruct, bone: string) => Mat4 | null): BlendPlaced[];