@driftengine/assets 3.61.0

package/src/weld.ts

@@ -0,0 +1,264 @@
+/**
+ * Collapse a triangle soup into shared vertices.
+ *
+ * Importers produce one vertex per triangle *corner*, because that is how the source
+ * formats index their attributes: FBX and OBJ address positions, normals and UVs through
+ * separate index lists, and the only way to flatten that into one array per attribute is
+ * to give every corner its own vertex. A real model comes out five to eight times larger
+ * than it is — a BMW measured 4.57M corners for perhaps 600k distinct vertices.
+ *
+ * **Corners are only merged when everything about them matches**, not just the position.
+ * Two corners at the same point with different normals are a hard edge, and welding them
+ * would round it off — the seam down a car's bonnet would soften into a dent. That is a
+ * change to the model, made silently, which is exactly what a reader must not do.
+ *
+ * Offline work, so it may allocate. Nothing here runs per frame.
+ */
+
+import type { MeshData } from '@driftengine/drft';
+
+/**
+ * How finely positions are compared, in units of the model.
+ *
+ * Exact bit equality is the wrong test: two corners meant to be the same point routinely
+ * differ in the last place after a transform, so exact matching welds almost nothing on
+ * exactly the files that need it most. Quantising to a millionth is far below anything a
+ * model expresses and far above float noise.
+ */
+const QUANTUM = 1e-6;
+
+function quantise(value: number): number {
+  return Math.round(value / QUANTUM);
+}
+
+/**
+ * Every optional attribute, and how many floats each spends on a vertex.
+ *
+ * **One table, read by both halves of the weld** — the key that decides whether two corners are
+ * the same vertex, and the copy that writes the survivors. They were two lists written out by
+ * hand, and what that cost is the reason this exists: `MeshData` gained a tangent frame, relief,
+ * a rig and morph deltas over four days in August and neither list was told about any of them,
+ * so for five releases a merged mesh came back **without** its rig, its tangents and its morph
+ * targets, and with corners merged across the bones they were weighted to. Nothing raised: an
+ * unskinned mesh is a valid mesh, and it draws at its bind pose.
+ *
+ * **The `satisfies` is the load-bearing part and not decoration.** It names every optional
+ * per-vertex attribute the format has, so the day a new one is added to `MeshData` this file
+ * stops compiling until it is listed here. A table that can be forgotten is exactly the thing
+ * that was already forgotten twice.
+ */
+const ATTRIBUTES = {
+  uvs: 2,
+  specular: 1,
+  roughness: 1,
+  grain: 1,
+  relief: 1,
+  emissiveColor: 3,
+  tangents: 4,
+  joints: 4,
+  weights: 4,
+  /*
+   * The four-lane per-vertex channel. It joins the key above as well as the copy below, which is
+   * the behaviour that matters: two vertices at one position whose sway or sky exposure differ
+   * are not the same vertex, and welding them would silently keep whichever came first. A leaf
+   * tip merged into the trunk it grows from would stop moving.
+   */
+  channel: 4,
+} as const satisfies Record<PerVertexAttribute, number>;
+
+/**
+ * Every optional `Float32Array` on `MeshData`, except the morph deltas.
+ *
+ * Morph targets are excluded because they are the one attribute whose stride is not fixed by the
+ * format — it is three floats times the mesh's own `morphTargetCount` — so they are keyed and
+ * copied a few lines below instead of through the table. `morphTargetCount` itself is a number
+ * and drops out of this type on its own.
+ */
+type PerVertexAttribute = Exclude<
+  {
+    [K in keyof MeshData]-?: undefined extends MeshData[K]
+      ? MeshData[K] extends Float32Array | undefined
+        ? K
+        : never
+      : never;
+  }[keyof MeshData],
+  'morphTargets'
+>;
+
+const NAMES = Object.keys(ATTRIBUTES) as readonly PerVertexAttribute[];
+
+/**
+ * Weld one mesh. Returns the same mesh when nothing can be merged.
+ *
+ * **Every attribute decides identity, and that is a cost as well as a correctness rule.** Two
+ * corners alike in position, normal and UV but weighted to different bones are two vertices, and
+ * merging them moves geometry with the wrong limb; two alike in everything including their UV but
+ * opposite in the bitangent's sign are a mirrored UV shell, and merging them lights one side of
+ * the model inside out. Neither is visible in any count a bake prints.
+ *
+ * What it costs is a file whose tangent frame was *derived* per corner instead of authored: a
+ * corner soup gets one triangle's frame per corner, so no two corners agree and the weld that
+ * would have merged them cannot. **The way out is not a looser key — it is to derive the frame
+ * from the welded mesh**, which is what the baker does as of 3.30.0: it passes
+ * `deriveTangents: false` to the reader and calls `deriveTangentsFor` here, afterwards.
+ *
+ * **How much it costs depends on the unwrap, and two figures in this repository disagreed about
+ * it.** The frame is normalised, so two triangles produce different frames only where the
+ * *direction* u increases in differs between them. On a separable unwrap — u from x, v from y —
+ * every triangle on a flat surface agrees and a derived frame costs almost nothing; a 253-mesh CAD
+ * export measured 728,168 vertices against 728,161 with no frame, seven vertices, and that file is
+ * not on this machine. On a rotational unwrap the direction turns with position and almost nothing
+ * merges: 9,600 corners to 9,482 vertices against 1,681, six different frames at one point at
+ * worst, measured in `tangentOrder.test.ts` and reproducible. The order is fixed for the second
+ * case; the first is why it went unnoticed.
+ */
+export function weldMesh(mesh: MeshData): MeshData {
+  const vertices = mesh.positions.length / 3;
+  if (vertices === 0) return mesh;
+
+  const map = new Map<string, number>();
+  const remap = new Uint32Array(vertices);
+  let unique = 0;
+
+  /* The attributes this mesh actually carries, resolved once and not per vertex. */
+  const present = NAMES.filter((name) => mesh[name] !== undefined);
+  /* Three floats per target per vertex, interleaved by vertex: `MeshData.morphTargets`' layout. */
+  const morphStride = mesh.morphTargets === undefined ? 0 : (mesh.morphTargetCount ?? 0) * 3;
+
+  for (let i = 0; i < vertices; i++) {
+    /*
+     * The key names every attribute, because two corners differing in any of them are
+     * genuinely different vertices — a shared position with a different normal is a hard
+     * edge, and with a different colour is a material boundary.
+     */
+    let key =
+      `${quantise(mesh.positions[i * 3] as number)},` +
+      `${quantise(mesh.positions[i * 3 + 1] as number)},` +
+      `${quantise(mesh.positions[i * 3 + 2] as number)}|` +
+      `${quantise(mesh.normals[i * 3] as number)},` +
+      `${quantise(mesh.normals[i * 3 + 1] as number)},` +
+      `${quantise(mesh.normals[i * 3 + 2] as number)}|` +
+      `${quantise(mesh.colors[i * 3] as number)},` +
+      `${quantise(mesh.colors[i * 3 + 1] as number)},` +
+      `${quantise(mesh.colors[i * 3 + 2] as number)}|` +
+      `${quantise(mesh.emissive[i] as number)}`;
+    for (const name of present) {
+      const array = mesh[name] as Float32Array;
+      const stride = ATTRIBUTES[name];
+      key += '|';
+      for (let c = 0; c < stride; c++) key += `${quantise(array[i * stride + c] as number)},`;
+    }
+    for (let c = 0; c < morphStride; c++) {
+      key += `${quantise(mesh.morphTargets?.[i * morphStride + c] as number)},`;
+    }
+
+    const found = map.get(key);
+    if (found === undefined) {
+      map.set(key, unique);
+      remap[i] = unique;
+      unique++;
+    } else {
+      remap[i] = found;
+    }
+  }
+
+  if (unique === vertices) return mesh;
+
+  const positions = new Float32Array(unique * 3);
+  const normals = new Float32Array(unique * 3);
+  const colors = new Float32Array(unique * 3);
+  const emissive = new Float32Array(unique);
+  const copies: Partial<Record<PerVertexAttribute, Float32Array>> = {};
+  for (const name of present) copies[name] = new Float32Array(unique * ATTRIBUTES[name]);
+  const morphTargets = morphStride === 0 ? undefined : new Float32Array(unique * morphStride);
+
+  const written = new Uint8Array(unique);
+  for (let i = 0; i < vertices; i++) {
+    const to = remap[i] as number;
+    if (written[to] === 1) continue;
+    written[to] = 1;
+    for (let c = 0; c < 3; c++) {
+      positions[to * 3 + c] = mesh.positions[i * 3 + c] as number;
+      normals[to * 3 + c] = mesh.normals[i * 3 + c] as number;
+      colors[to * 3 + c] = mesh.colors[i * 3 + c] as number;
+    }
+    emissive[to] = mesh.emissive[i] as number;
+    for (const name of present) {
+      const from = mesh[name] as Float32Array;
+      const into = copies[name] as Float32Array;
+      const stride = ATTRIBUTES[name];
+      for (let c = 0; c < stride; c++) into[to * stride + c] = from[i * stride + c] as number;
+    }
+    if (morphTargets !== undefined) {
+      for (let c = 0; c < morphStride; c++) {
+        morphTargets[to * morphStride + c] = mesh.morphTargets?.[i * morphStride + c] as number;
+      }
+    }
+  }
+
+  const indices = new Uint32Array(mesh.indices.length);
+  for (let i = 0; i < mesh.indices.length; i++) {
+    indices[i] = remap[mesh.indices[i] as number] as number;
+  }
+
+  return {
+    positions,
+    normals,
+    colors,
+    emissive,
+    indices,
+    ...copies,
+    /* Both or neither: an array of deltas with no count moves nothing, and a count with no
+       array is a promise about a buffer that is not there. */
+    ...(morphTargets === undefined
+      ? {}
+      : { morphTargets, morphTargetCount: mesh.morphTargetCount }),
+  };
+}
+
+/**
+ * Drop optional attributes that never vary from the engine's own default.
+ *
+ * An importer that has no material information should not invent one, and a writer should
+ * not spend a megabyte storing the same number four million times. `Mesh` already reads an
+ * absent attribute as a constant, so leaving it out is not a loss — it is the same shading
+ * through a cheaper path, with no buffer, no upload and no per-vertex fetch.
+ *
+ * The defaults are `Mesh`'s, and they are duplicated here on purpose rather than imported:
+ * this is a *bake-time* judgement about what is worth storing, and tying it to a rendering
+ * constant would make a change to one silently rewrite files produced by the other.
+ */
+const DEFAULT_SPECULAR = 0;
+const DEFAULT_ROUGHNESS = 0.4277;
+const DEFAULT_EMISSIVE_COLOR = -1;
+/** Absent grain means none, so an asset that is nowhere mineral stores nothing about it. */
+const DEFAULT_GRAIN = 0;
+/**
+ * Absent relief means a perfectly smooth surface, which is what every reader produces.
+ *
+ * Listed late and for the same reason the weld's table exists: relief landed on `MeshData` on
+ * 2026-08-21 and this function was not told, so a producer filling an array of zeroes stored four
+ * bytes a vertex saying "no relief" — the one thing an absent attribute already says.
+ */
+const DEFAULT_RELIEF = 0;
+
+export function dropDefaultAttributes(mesh: MeshData): MeshData {
+  const constant = (array: Float32Array | undefined, value: number): boolean => {
+    if (array === undefined) return false;
+    for (let i = 0; i < array.length; i++) {
+      if (Math.abs((array[i] as number) - value) > 1e-6) return false;
+    }
+    return true;
+  };
+
+  const out: MeshData = { ...mesh };
+  if (constant(mesh.specular, DEFAULT_SPECULAR)) delete (out as { specular?: unknown }).specular;
+  if (constant(mesh.roughness, DEFAULT_ROUGHNESS))
+    delete (out as { roughness?: unknown }).roughness;
+  if (constant(mesh.grain, DEFAULT_GRAIN)) delete (out as { grain?: unknown }).grain;
+  if (constant(mesh.relief, DEFAULT_RELIEF)) delete (out as { relief?: unknown }).relief;
+  if (constant(mesh.emissiveColor, DEFAULT_EMISSIVE_COLOR)) {
+    delete (out as { emissiveColor?: unknown }).emissiveColor;
+  }
+  return out;
+}

package/src/zip.ts

@@ -0,0 +1,130 @@
+/**
+ * Reading a zip container. One responsibility: name a file inside an archive, get its bytes.
+ *
+ * Shared by `.usdz` and `.3mf`, which is why it exists as its own module rather than inside
+ * either: both are zip archives of a documented layout, and a reader written twice is a
+ * reader that disagrees with itself once.
+ *
+ * **The central directory is read, not the local headers.** A zip can be scanned from the
+ * front by walking local file headers, and almost every naive reader does. It is wrong: a
+ * local header may declare a size of zero and defer the real figures to a data descriptor
+ * *after* the payload, which cannot be found without already knowing where the payload ends.
+ * The central directory at the back of the file is the authority, always carries the sizes,
+ * and is what the specification says to use.
+ *
+ * **Inflate is injected**, for the same reason as in `fbx.ts`: this module is part of an
+ * engine that runs in a browser and must not reach for Node's `zlib`. `.usdz` never needs it,
+ * because the format *requires* its entries to be stored uncompressed so they can be memory
+ * mapped, and that is why a USDZ can be read with no decompressor at all. `.3mf` is ordinary
+ * deflate and needs one.
+ */
+
+import { DrftError } from '@driftengine/drft';
+import type { Inflate } from './fbx.ts';
+
+/** One file in the archive. `bytes` is decompressed and ready to read. */
+export interface ZipEntry {
+  readonly name: string;
+  readonly bytes: Uint8Array;
+}
+
+/** Signature of a central directory record, little-endian: `PK
`. */
+const CENTRAL_SIGNATURE = 0x02014b50;
+/** Signature of the end-of-central-directory record: `PK`. */
+const END_SIGNATURE = 0x06054b50;
+/** The two compression methods that appear in practice. Anything else is refused by number. */
+const STORED = 0;
+const DEFLATED = 8;
+
+/**
+ * Find the end-of-central-directory record, which is the only fixed point in a zip.
+ *
+ * It sits at the very back, except that it carries a trailing comment of arbitrary length, so
+ * it has to be searched for backwards. The comment is at most 65535 bytes by definition, so
+ * the search is bounded rather than a scan of the whole file.
+ */
+function findEnd(view: DataView, length: number): number {
+  const earliest = Math.max(0, length - 22 - 0xffff);
+  for (let at = length - 22; at >= earliest; at--) {
+    if (view.getUint32(at, true) === END_SIGNATURE) return at;
+  }
+  throw new DrftError('zip: no end-of-central-directory record, so this is not a zip archive');
+}
+
+/**
+ * Every file in an archive, decompressed.
+ *
+ * Directory entries are skipped: they are zero-length records whose names end in a slash, and
+ * a caller asking for files does not want them.
+ */
+export function readZip(buffer: ArrayBuffer, inflate: Inflate | null = null): ZipEntry[] {
+  const bytes = new Uint8Array(buffer);
+  const view = new DataView(buffer);
+  if (buffer.byteLength < 22) throw new DrftError('zip: shorter than an empty archive');
+
+  const end = findEnd(view, buffer.byteLength);
+  const count = view.getUint16(end + 10, true);
+  let at = view.getUint32(end + 16, true);
+
+  const out: ZipEntry[] = [];
+  const decoder = new TextDecoder();
+  for (let i = 0; i < count; i++) {
+    if (at + 46 > buffer.byteLength || view.getUint32(at, true) !== CENTRAL_SIGNATURE) {
+      throw new DrftError(`zip: the central directory entry ${i} is malformed at byte ${at}`);
+    }
+    const method = view.getUint16(at + 10, true);
+    const compressedSize = view.getUint32(at + 20, true);
+    const uncompressedSize = view.getUint32(at + 24, true);
+    const nameLength = view.getUint16(at + 28, true);
+    const extraLength = view.getUint16(at + 30, true);
+    const commentLength = view.getUint16(at + 32, true);
+    const localAt = view.getUint32(at + 42, true);
+    const name = decoder.decode(bytes.subarray(at + 46, at + 46 + nameLength));
+    at += 46 + nameLength + extraLength + commentLength;
+
+    /* A directory, which carries no payload and is not a file anybody asked for. */
+    if (name.endsWith('/')) continue;
+
+    /*
+     * The local header's *own* name and extra lengths, which differ from the central
+     * directory's. Reusing the central figures here is the classic zip bug: the extra field
+     * is routinely a different length in the two places, so the payload starts somewhere
+     * else and the entry decompresses to noise.
+     */
+    if (localAt + 30 > buffer.byteLength || view.getUint32(localAt, true) !== 0x04034b50) {
+      throw new DrftError(`zip: "${name}" points at byte ${localAt}, which is not a local header`);
+    }
+    const localNameLength = view.getUint16(localAt + 26, true);
+    const localExtraLength = view.getUint16(localAt + 28, true);
+    const from = localAt + 30 + localNameLength + localExtraLength;
+    if (from + compressedSize > buffer.byteLength) {
+      throw new DrftError(
+        `zip: "${name}" claims ${compressedSize} bytes and runs past the archive`,
+      );
+    }
+    const payload = bytes.subarray(from, from + compressedSize);
+
+    if (method === STORED) {
+      out.push({ name, bytes: payload });
+      continue;
+    }
+    if (method === DEFLATED) {
+      if (inflate === null) {
+        throw new DrftError(
+          `zip: "${name}" is deflate-compressed and this reader was given no decompressor`,
+        );
+      }
+      out.push({ name, bytes: inflate(payload, uncompressedSize) });
+      continue;
+    }
+    throw new DrftError(
+      `zip: "${name}" uses compression method ${method}, and only stored and deflate are read`,
+    );
+  }
+  return out;
+}
+
+/** The first entry whose name matches, or null. Case-insensitive, since archives disagree. */
+export function findEntry(entries: readonly ZipEntry[], match: RegExp): ZipEntry | null {
+  return entries.find((entry) => match.test(entry.name)) ?? null;
+}