@driftengine/assets 3.61.0

package/src/obj.ts

@@ -0,0 +1,386 @@
+/**
+ * Wavefront OBJ, with its `.mtl` companion.
+ *
+ * Tier 1, and the cheapest thing on the list to put there: the format was specified in the
+ * eighties, has not changed since, and is plain text. There is no version to track and no
+ * vendor to follow, so a complete reader written once stays correct — which is worth more
+ * than a partial reader for a format that moves.
+ *
+ * One `MeshData` per material group, matching the glTF path: a group is the unit carrying
+ * a single material, and `MeshData` holds one material's worth of vertex attributes.
+ */
+
+import type { MeshData } from '@driftengine/drft';
+import { DrftError } from '@driftengine/drft';
+import type { DrftMaterial } from '@driftengine/drft';
+import type { AssetReference } from './assetPath.ts';
+
+interface ObjMaterial {
+  diffuse: [number, number, number];
+  emissive: [number, number, number];
+  /** Highlight strength, from `Ks`/`Ns` or the PBR `Pm` extension. */
+  specular: number;
+  /** Highlight width, from the PBR `Pr` extension, or derived from `Ns`. */
+  roughness: number;
+  /** The colour map this material names, as declared, or null. */
+  albedo: string | null;
+  /** 1 is opaque. `d` states it directly and `Tr` states its inverse. */
+  opacity: number;
+}
+
+const DEFAULT_MATERIAL: ObjMaterial = {
+  diffuse: [0.8, 0.8, 0.8],
+  emissive: [0, 0, 0],
+  specular: 0,
+  roughness: 0.5,
+  albedo: null,
+  opacity: 1,
+};
+
+const clamp01 = (value: number): number =>
+  Number.isFinite(value) ? Math.min(1, Math.max(0, value)) : 1;
+
+/**
+ * The filename out of a `map_*` line, past whatever options precede it.
+ *
+ * A map line is not just a path: `map_Kd -s 1 1 1 -bm 0.2 brick.png` is legal and common,
+ * and taking `parts[1]` gets `-s`. The options are skipped by shape rather than by a table
+ * of every flag, since the flags differ per exporter and their arity is not consistent:
+ * anything that begins with a dash, parses as a number, or is `on`/`off` is an option or an
+ * option's argument, and the first token that is none of those begins the name.
+ *
+ * The rest is joined rather than taken as one token, because a texture path may contain
+ * spaces and the line has already been split on them.
+ */
+function mapPath(parts: readonly string[]): string {
+  let at = 1;
+  while (at < parts.length) {
+    const token = parts[at] as string;
+    if (
+      token.startsWith('-') ||
+      token === 'on' ||
+      token === 'off' ||
+      !Number.isNaN(Number(token))
+    ) {
+      at++;
+      continue;
+    }
+    break;
+  }
+  const name = parts.slice(at).join(' ').trim();
+  return name;
+}
+
+/**
+ * Parse a `.mtl`.
+ *
+ * `Pr` and `Pm` are the widely used PBR extension rather than the original specification,
+ * and they are preferred where present because they say directly what this engine shades
+ * with. Where they are absent, `Ns` — a Phong exponent — is converted, since an exponent
+ * and a roughness describe the same thing from opposite ends.
+ *
+ * `d` and `Tr` are the same quantity written in opposite directions: `d` is how much of the
+ * surface is *there* and `Tr` is how much of it is not. Reading either as the other inverts
+ * every transparent material in a file, turning solid geometry invisible and glass solid,
+ * so both are read explicitly rather than one being assumed.
+ */
+export function parseMtl(text: string): Map<string, ObjMaterial> {
+  const materials = new Map<string, ObjMaterial>();
+  let current: ObjMaterial | null = null;
+
+  for (const rawLine of text.split('\n')) {
+    const line = rawLine.trim();
+    if (line.length === 0 || line.startsWith('#')) continue;
+    const parts = line.split(/\s+/);
+    const keyword = parts[0] as string;
+    const numbers = parts.slice(1).map(Number);
+
+    if (keyword === 'newmtl') {
+      current = { ...DEFAULT_MATERIAL, diffuse: [0.8, 0.8, 0.8], emissive: [0, 0, 0] };
+      materials.set(parts.slice(1).join(' '), current);
+      continue;
+    }
+    if (current === null) continue;
+
+    if (keyword === 'Kd') current.diffuse = [numbers[0] ?? 0, numbers[1] ?? 0, numbers[2] ?? 0];
+    else if (keyword === 'Ke')
+      current.emissive = [numbers[0] ?? 0, numbers[1] ?? 0, numbers[2] ?? 0];
+    else if (keyword === 'Pr') current.roughness = numbers[0] ?? 0.5;
+    else if (keyword === 'Pm') current.specular = numbers[0] ?? 0;
+    else if (keyword === 'Ns') {
+      /*
+       * A Phong exponent is a width expressed backwards: 0 is a mirror-flat surface with a
+       * broad lobe and 1000 is a pinpoint. Mapped rather than ignored, so a file with no
+       * PBR extension still arrives with its highlights roughly the right size.
+       */
+      const exponent = Math.max(numbers[0] ?? 0, 0);
+      current.roughness = Math.min(1, Math.max(0.02, Math.sqrt(2 / (exponent + 2))));
+    } else if (keyword === 'map_Kd') current.albedo = mapPath(parts);
+    else if (keyword === 'd') current.opacity = clamp01(numbers[0] ?? 1);
+    else if (keyword === 'Tr') current.opacity = clamp01(1 - (numbers[0] ?? 0));
+    else if (keyword === 'Ks' && current.specular === 0) {
+      current.specular = Math.max(numbers[0] ?? 0, numbers[1] ?? 0, numbers[2] ?? 0);
+    }
+  }
+  return materials;
+}
+
+/** A face vertex: indices into the three pools, already resolved to zero-based. */
+interface FaceVertex {
+  position: number;
+  uv: number;
+  normal: number;
+}
+
+function resolveIndex(raw: string, poolLength: number): number {
+  if (raw === '') return -1;
+  const value = Number.parseInt(raw, 10);
+  if (Number.isNaN(value)) return -1;
+  /* Negative indices count back from the end, which the format allows and exporters use. */
+  return value < 0 ? poolLength + value : value - 1;
+}
+
+/**
+ * Parse an OBJ. `materials` is the parsed `.mtl`, if the caller resolved one.
+ *
+ * Faces with more than three vertices are triangulated as a fan. That is correct for the
+ * convex polygons OBJ files actually contain, and the format offers nothing that would let
+ * a reader do better for a concave one.
+ */
+export function parseObj(
+  text: string,
+  materials: Map<string, ObjMaterial> = new Map(),
+): {
+  meshes: MeshData[];
+  warnings: string[];
+  materials: DrftMaterial[];
+  textures: AssetReference[];
+} {
+  const positions: number[] = [];
+  const normals: number[] = [];
+  const uvs: number[] = [];
+  const warnings: string[] = [];
+
+  /* Faces accumulate per material, so each group becomes one mesh. */
+  const groups = new Map<string, FaceVertex[]>();
+  let currentMaterial = '';
+  const faceFor = (name: string): FaceVertex[] => {
+    let list = groups.get(name);
+    if (list === undefined) {
+      list = [];
+      groups.set(name, list);
+    }
+    return list;
+  };
+
+  for (const rawLine of text.split('\n')) {
+    const line = rawLine.trim();
+    if (line.length === 0 || line.startsWith('#')) continue;
+    const parts = line.split(/\s+/);
+    const keyword = parts[0] as string;
+
+    if (keyword === 'v') {
+      positions.push(Number(parts[1]), Number(parts[2]), Number(parts[3]));
+    } else if (keyword === 'vn') {
+      normals.push(Number(parts[1]), Number(parts[2]), Number(parts[3]));
+    } else if (keyword === 'vt') {
+      uvs.push(Number(parts[1]), Number(parts[2] ?? 0));
+    } else if (keyword === 'usemtl') {
+      currentMaterial = parts.slice(1).join(' ');
+    } else if (keyword === 'f') {
+      const corners: FaceVertex[] = [];
+      for (let i = 1; i < parts.length; i++) {
+        const [p = '', t = '', n = ''] = (parts[i] as string).split('/');
+        corners.push({
+          position: resolveIndex(p, positions.length / 3),
+          uv: resolveIndex(t, uvs.length / 2),
+          normal: resolveIndex(n, normals.length / 3),
+        });
+      }
+      if (corners.length < 3) {
+        warnings.push(`skipped a face with ${corners.length} vertices`);
+        continue;
+      }
+      const list = faceFor(currentMaterial);
+      for (let i = 1; i + 1 < corners.length; i++) {
+        list.push(corners[0] as FaceVertex, corners[i] as FaceVertex, corners[i + 1] as FaceVertex);
+      }
+    }
+  }
+
+  if (positions.length === 0) throw new DrftError('obj: no vertices');
+
+  const meshes: MeshData[] = [];
+  const perMesh: DrftMaterial[] = [];
+  /* Deduplicated: several materials commonly share one map, and embedding it twice would
+     put the same megabytes in the file twice and give a consumer two names for one image. */
+  const textures: AssetReference[] = [];
+  const textureIndex = new Map<string, number>();
+
+  for (const [name, corners] of groups) {
+    if (corners.length === 0) continue;
+    const material = materials.get(name) ?? DEFAULT_MATERIAL;
+    let albedo = -1;
+    if (material.albedo !== null && material.albedo !== '') {
+      const existing = textureIndex.get(material.albedo);
+      if (existing === undefined) {
+        albedo = textures.length;
+        textureIndex.set(material.albedo, albedo);
+        textures.push({ name: material.albedo });
+      } else {
+        albedo = existing;
+      }
+    }
+    meshes.push(buildGroup(corners, positions, normals, uvs, material, warnings, name));
+    perMesh.push({
+      name,
+      color: material.diffuse,
+      specular: material.specular,
+      roughness: material.roughness,
+      emissive: Math.min(
+        1,
+        Math.max(material.emissive[0], material.emissive[1], material.emissive[2]),
+      ),
+      emissiveColor:
+        Math.max(material.emissive[0], material.emissive[1], material.emissive[2]) > 0
+          ? material.emissive
+          : [-1, -1, -1],
+      opacity: material.opacity,
+      /* `Pm` is the PBR extension's metalness and the only thing an mtl says about
+         reflection, so it feeds this as well as the highlight. */
+      reflectivity: Math.min(1, Math.max(0, material.specular)),
+      normalMap: -1,
+      ormMap: -1,
+      emissiveMap: -1,
+      roughnessScale: 1,
+      metallicScale: 1,
+      occlusionStrength: 0,
+      cutout: 0,
+      albedo,
+    });
+  }
+  if (meshes.length === 0) throw new DrftError('obj: no faces');
+  return { meshes, warnings, materials: perMesh, textures };
+}
+
+function buildGroup(
+  corners: readonly FaceVertex[],
+  positions: readonly number[],
+  normals: readonly number[],
+  uvs: readonly number[],
+  material: ObjMaterial,
+  warnings: string[],
+  name: string,
+): MeshData {
+  const count = corners.length;
+  const outPositions = new Float32Array(count * 3);
+  const outNormals = new Float32Array(count * 3);
+  const outColors = new Float32Array(count * 3);
+  const outUvs = new Float32Array(count * 2);
+  const indices = new Uint32Array(count);
+  let hasUvs = false;
+  let missingNormals = false;
+
+  for (let i = 0; i < count; i++) {
+    const corner = corners[i] as FaceVertex;
+    const p = corner.position * 3;
+    outPositions[i * 3] = positions[p] ?? 0;
+    outPositions[i * 3 + 1] = positions[p + 1] ?? 0;
+    outPositions[i * 3 + 2] = positions[p + 2] ?? 0;
+
+    if (corner.normal >= 0) {
+      const n = corner.normal * 3;
+      outNormals[i * 3] = normals[n] ?? 0;
+      outNormals[i * 3 + 1] = normals[n + 1] ?? 0;
+      outNormals[i * 3 + 2] = normals[n + 2] ?? 0;
+    } else {
+      missingNormals = true;
+    }
+
+    if (corner.uv >= 0) {
+      hasUvs = true;
+      const t = corner.uv * 2;
+      outUvs[i * 2] = uvs[t] ?? 0;
+      /*
+       * V is flipped, once, here.
+       *
+       * **OBJ puts the texture origin at the bottom left by specification** and this engine
+       * uploads with it at the top left (`surfaceTexture.ts` sets `UNPACK_FLIP_Y_WEBGL`), which
+       * is the same single correction `fbx.ts` and `usd.ts` both make and document. This reader
+       * was the one of the four that did not, so every textured `.obj` imported upside down on
+       * its maps while the same asset's `.fbx` sibling was correct, which is exactly what made
+       * it read as a model fault rather than a reader one.
+       *
+       * Found from outside on a bought Formula 1 bundle, whose airbox lettering was inverted.
+       * glTF needs no flip and has none: its origin is top left already.
+       */
+      outUvs[i * 2 + 1] = 1 - (uvs[t + 1] ?? 0);
+    }
+
+    outColors[i * 3] = material.diffuse[0];
+    outColors[i * 3 + 1] = material.diffuse[1];
+    outColors[i * 3 + 2] = material.diffuse[2];
+    indices[i] = i;
+  }
+
+  /*
+   * A file with no `vn` gets face normals computed here rather than a buffer of zeroes.
+   * A zero normal is not a neutral value — every lighting term multiplies by it, so the
+   * geometry would arrive black and look like a shading bug rather than a missing
+   * attribute.
+   */
+  if (missingNormals) {
+    warnings.push(`${name === '' ? 'obj' : name}: no vertex normals, so faces are shaded flat`);
+    for (let i = 0; i + 2 < count; i += 3) {
+      const ax = outPositions[i * 3] as number;
+      const ay = outPositions[i * 3 + 1] as number;
+      const az = outPositions[i * 3 + 2] as number;
+      const ux = (outPositions[(i + 1) * 3] as number) - ax;
+      const uy = (outPositions[(i + 1) * 3 + 1] as number) - ay;
+      const uz = (outPositions[(i + 1) * 3 + 2] as number) - az;
+      const vx = (outPositions[(i + 2) * 3] as number) - ax;
+      const vy = (outPositions[(i + 2) * 3 + 1] as number) - ay;
+      const vz = (outPositions[(i + 2) * 3 + 2] as number) - az;
+      let nx = uy * vz - uz * vy;
+      let ny = uz * vx - ux * vz;
+      let nz = ux * vy - uy * vx;
+      const length = Math.hypot(nx, ny, nz) || 1;
+      nx /= length;
+      ny /= length;
+      nz /= length;
+      for (let c = 0; c < 3; c++) {
+        if (
+          outNormals[(i + c) * 3] === 0 &&
+          outNormals[(i + c) * 3 + 1] === 0 &&
+          outNormals[(i + c) * 3 + 2] === 0
+        ) {
+          outNormals[(i + c) * 3] = nx;
+          outNormals[(i + c) * 3 + 1] = ny;
+          outNormals[(i + c) * 3 + 2] = nz;
+        }
+      }
+    }
+  }
+
+  const emissiveStrength = Math.max(...material.emissive);
+  const emissive = new Float32Array(count).fill(emissiveStrength);
+  const emissiveColor = new Float32Array(count * 3);
+  for (let i = 0; i < count; i++) {
+    const named = emissiveStrength > 0;
+    emissiveColor[i * 3] = named ? material.emissive[0] : -1;
+    emissiveColor[i * 3 + 1] = named ? material.emissive[1] : -1;
+    emissiveColor[i * 3 + 2] = named ? material.emissive[2] : -1;
+  }
+
+  return {
+    positions: outPositions,
+    normals: outNormals,
+    colors: outColors,
+    emissive,
+    specular: new Float32Array(count).fill(material.specular),
+    roughness: new Float32Array(count).fill(material.roughness),
+    emissiveColor,
+    indices,
+    ...(hasUvs ? { uvs: outUvs } : {}),
+  };
+}

package/src/orient.ts

@@ -0,0 +1,262 @@
+/**
+ * Turn an imported asset into the engine's frame. One responsibility: orientation.
+ *
+ * **This lives on the intermediate, not in a reader, and that placement is the point.** Every
+ * format arrives here eventually — glTF, OBJ, STL, FBX, and whatever is added next — and each
+ * one has its own idea of which way is up: glTF specifies Y-up and means it, STL specifies
+ * nothing at all, FBX records a convention per file and its exporters disagree about how to
+ * honour it. If each reader carried its own correction, the engine would slowly acquire one
+ * format's habits as its defaults, and the next reader would be written to match the last
+ * one's quirks rather than its own specification. So a reader's job is to report what its
+ * file says, faithfully and with no opinion, and the single opinionated step happens once,
+ * here, where it is written down and testable.
+ *
+ * **Why an override exists at all.** A file can be internally consistent and still disagree
+ * with itself: an asset whose `GlobalSettings` declare Y-up while every node in it was
+ * exported a half turn away is not malformed, and no amount of reading it more carefully
+ * reveals which of the two statements the author meant. That is not a defect a reader can
+ * repair, because the information is genuinely absent from the file — so it is supplied from
+ * outside, by somebody who has looked at the model, and the baker prints what it was told.
+ *
+ * Every turn here is a **rotation**, never a mirror. A reflection would flip the handedness
+ * of the geometry, which turns every triangle inside out and shades the model dark where it
+ * should be lit, and it is not obvious in a bounding box — the numbers look right and the
+ * render does not. Each entry in `TURNS` has determinant +1, so the winding a reader produced
+ * is still the winding the rasteriser wants, and the index buffers are passed through
+ * untouched.
+ */
+
+import type { DrftNode, MeshData } from '@driftengine/drft';
+import { DrftError } from '@driftengine/drft';
+
+/** Which way is up in the asset, as a signed axis of the engine's own frame. */
+export type UpAxis = '+x' | '-x' | '+y' | '-y' | '+z' | '-z';
+
+export const UP_AXES: readonly UpAxis[] = ['+x', '-x', '+y', '-y', '+z', '-z'];
+
+/**
+ * The rotation that carries each axis onto the engine's `+y`, row-major 3x3.
+ *
+ * `-y` is the one genuinely ambiguous case: a half turn about X and a half turn about Z both
+ * stand the asset up, and they differ by a half turn of yaw, which no amount of measurement
+ * on the model can decide. X is the choice, because for an asset whose parts were exported
+ * with a quarter turn already baked into them it reduces those to exactly the conventional
+ * Z-up conversion rather than to that conversion plus an unexplained yaw.
+ */
+const TURNS: Readonly<Record<UpAxis, { readonly m: readonly number[]; readonly says: string }>> = {
+  '+y': { m: [1, 0, 0, 0, 1, 0, 0, 0, 1], says: 'already the engine frame, so nothing is turned' },
+  '-y': { m: [1, 0, 0, 0, -1, 0, 0, 0, -1], says: 'a half turn about X' },
+  '+z': {
+    m: [1, 0, 0, 0, 0, 1, 0, -1, 0],
+    says: 'a quarter turn about X, the conventional Z-up conversion',
+  },
+  '-z': { m: [1, 0, 0, 0, 0, -1, 0, 1, 0], says: 'a quarter turn about X, the other way' },
+  '+x': { m: [0, -1, 0, 1, 0, 0, 0, 0, 1], says: 'a quarter turn about Z' },
+  '-x': { m: [0, 1, 0, -1, 0, 0, 0, 0, 1], says: 'a quarter turn about Z, the other way' },
+};
+
+/** Read an axis a person typed. `z` and `+z` mean the same thing; anything else is refused. */
+export function parseUpAxis(text: string): UpAxis {
+  const cleaned = text.trim().toLowerCase();
+  const signed = cleaned.startsWith('+') || cleaned.startsWith('-') ? cleaned : `+${cleaned}`;
+  const found = UP_AXES.find((axis) => axis === signed);
+  if (found === undefined) {
+    throw new DrftError(`"${text}" is not an axis. Use one of: ${UP_AXES.join(', ')}.`);
+  }
+  return found;
+}
+
+/** What the turn does, in words, for the line the baker prints. */
+export function describeUpAxis(up: UpAxis): string {
+  return (TURNS[up] as { says: string }).says;
+}
+
+function turnTriples(source: Float32Array, m: readonly number[]): Float32Array {
+  const out = new Float32Array(source.length);
+  const m0 = m[0] as number;
+  const m1 = m[1] as number;
+  const m2 = m[2] as number;
+  const m3 = m[3] as number;
+  const m4 = m[4] as number;
+  const m5 = m[5] as number;
+  const m6 = m[6] as number;
+  const m7 = m[7] as number;
+  const m8 = m[8] as number;
+  for (let i = 0; i + 2 < source.length; i += 3) {
+    const x = source[i] as number;
+    const y = source[i + 1] as number;
+    const z = source[i + 2] as number;
+    out[i] = m0 * x + m1 * y + m2 * z;
+    out[i + 1] = m3 * x + m4 * y + m5 * z;
+    out[i + 2] = m6 * x + m7 * y + m8 * z;
+  }
+  return out;
+}
+
+/**
+ * Stand an asset up, given which of its axes points at the sky.
+ *
+ * Normals take the same matrix as positions rather than an inverse transpose, and that is
+ * exact rather than an approximation: for a rotation the two are the same matrix. There is
+ * no scale here by construction, which is the other half of why.
+ */
+export function orientMeshes(meshes: readonly MeshData[], assetUp: UpAxis): MeshData[] {
+  const { m } = TURNS[assetUp];
+  return meshes.map((mesh) => ({
+    ...mesh,
+    positions: turnTriples(mesh.positions, m),
+    normals: turnTriples(mesh.normals, m),
+  }));
+}
+
+/**
+ * Which way round a format's coordinate system is.
+ *
+ * **Every format read here is right-handed**, including the one that was declared left-handed for
+ * two releases on the strength of the graphics API its authoring tool targets, and whose frame is
+ * measured in the reader that reports it. The pair below is what a genuinely left-handed format
+ * gets.
+ */
+export type Handedness = 'right' | 'left';
+
+/**
+ * Mirror an asset into the engine's right-handed frame, in place.
+ *
+ * **This is the one thing the `TURNS` table above deliberately cannot do**, and the paragraph at
+ * the top of this file explaining why is still correct: an up-axis correction must be a rotation,
+ * or it flips geometry that was already the right way round. A *handedness* conversion is the
+ * opposite case — the geometry is genuinely mirrored, and refusing to mirror it is what would
+ * leave it wrong. Keeping the two apart is what lets each stay honest about what it does.
+ *
+ * **Three changes, and all three or none.** Negating X alone turns every triangle inside out;
+ * reversing the winding without flipping the bitangent sign lights every normal-mapped surface
+ * backwards. Doing them together, here, is why this is a function and not three lines inside a
+ * reader — the next left-handed format gets the same conversion and the same tests.
+ *
+ * UVs are untouched. A mirror moves the surface, not its parameterisation.
+ */
+export function convertHandedness(meshes: readonly MeshData[]): void {
+  for (const mesh of meshes) {
+    for (let at = 0; at < mesh.positions.length; at += 3) {
+      mesh.positions[at] = -(mesh.positions[at] as number);
+    }
+    for (let at = 0; at < mesh.normals.length; at += 3) {
+      mesh.normals[at] = -(mesh.normals[at] as number);
+    }
+    const tangents = mesh.tangents;
+    if (tangents !== undefined) {
+      for (let at = 0; at < tangents.length; at += 4) {
+        tangents[at] = -(tangents[at] as number);
+        tangents[at + 3] = -(tangents[at + 3] as number);
+      }
+    }
+    for (let at = 0; at + 2 < mesh.indices.length; at += 3) {
+      const middle = mesh.indices[at + 1] as number;
+      mesh.indices[at + 1] = mesh.indices[at + 2] as number;
+      mesh.indices[at + 2] = middle;
+    }
+  }
+}
+
+/**
+ * Mirror an asset's hierarchy by the same reflection `convertHandedness` mirrors its geometry by.
+ *
+ * **The pair to `convertHandedness`, exactly as `orientNodes` is the pair to `orientMeshes`**, and
+ * it did not exist: the one caller that mirrored a graph negated each node's translation X inline
+ * and left the rotations alone. A hierarchy with rotations then places its parts where the
+ * geometry is not — measured on a real car at **1.385 m apart and on the other side of the
+ * model** — while both halves stay individually well formed, which is the worst shape this can
+ * take and the reason the two functions now sit together.
+ *
+ * **The rotation is conjugated, not negated.** Reflecting a rotation `R` by a mirror `M` gives
+ * `M R M`, which is a rotation about the mirrored axis in the opposite sense; as a quaternion that
+ * is `(x, −y, −z, w)` for a reflection about the YZ plane. A scale is untouched, because `M S M`
+ * is `S` for any diagonal.
+ *
+ * **Every node, not only the roots**, which is the one place this differs from `orientNodes`. A
+ * rotation applied to a root already carries its descendants, so applying it to a child would
+ * apply it twice. A reflection is a conjugation and conjugation distributes over the product —
+ * `M (A B) M = (M A M)(M B M)` — so leaving a child alone drops the mirror out of the composition
+ * rather than avoiding a double application.
+ */
+export function mirrorNodes(nodes: readonly DrftNode[]): DrftNode[] {
+  return nodes.map((node) => ({
+    ...node,
+    translation: [-node.translation[0], node.translation[1], node.translation[2]],
+    rotation: [node.rotation[0], -node.rotation[1], -node.rotation[2], node.rotation[3]],
+  }));
+}
+
+/**
+ * Turn an asset's hierarchy by the same rotation `orientMeshes` turns its geometry by.
+ *
+ * **Without this, `--up` silently desynchronises the two.** The meshes rotate and the graph does
+ * not, so every node then claims a part is somewhere it no longer is — and nothing downstream can
+ * detect it, because both halves are individually well formed. That is the worst shape a bug can
+ * take in a bake, so the two turns happen together or the hierarchy is wrong.
+ *
+ * **Only roots are turned**, and that is not an optimisation: a child's transform is relative to
+ * its parent, so rotating the parent already carries every descendant with it. Turning a child too
+ * would apply the rotation twice.
+ */
+export function orientNodes(nodes: readonly DrftNode[], assetUp: UpAxis): DrftNode[] {
+  const { m } = TURNS[assetUp];
+  if (assetUp === '+y') return [...nodes];
+  const turn = (v: readonly [number, number, number]): [number, number, number] => [
+    (m[0] as number) * v[0] + (m[1] as number) * v[1] + (m[2] as number) * v[2],
+    (m[3] as number) * v[0] + (m[4] as number) * v[1] + (m[5] as number) * v[2],
+    (m[6] as number) * v[0] + (m[7] as number) * v[1] + (m[8] as number) * v[2],
+  ];
+
+  /* The turn as a quaternion, so a root's own rotation composes with it. */
+  const trace = (m[0] as number) + (m[4] as number) + (m[8] as number);
+  let q: [number, number, number, number];
+  if (trace > 0) {
+    const s = Math.sqrt(trace + 1) * 2;
+    q = [
+      ((m[7] as number) - (m[5] as number)) / s,
+      ((m[2] as number) - (m[6] as number)) / s,
+      ((m[3] as number) - (m[1] as number)) / s,
+      s / 4,
+    ];
+  } else if ((m[0] as number) > (m[4] as number) && (m[0] as number) > (m[8] as number)) {
+    const s = Math.sqrt(1 + (m[0] as number) - (m[4] as number) - (m[8] as number)) * 2;
+    q = [
+      s / 4,
+      ((m[1] as number) + (m[3] as number)) / s,
+      ((m[2] as number) + (m[6] as number)) / s,
+      ((m[7] as number) - (m[5] as number)) / s,
+    ];
+  } else if ((m[4] as number) > (m[8] as number)) {
+    const s = Math.sqrt(1 + (m[4] as number) - (m[0] as number) - (m[8] as number)) * 2;
+    q = [
+      ((m[1] as number) + (m[3] as number)) / s,
+      s / 4,
+      ((m[5] as number) + (m[7] as number)) / s,
+      ((m[2] as number) - (m[6] as number)) / s,
+    ];
+  } else {
+    const s = Math.sqrt(1 + (m[8] as number) - (m[0] as number) - (m[4] as number)) * 2;
+    q = [
+      ((m[2] as number) + (m[6] as number)) / s,
+      ((m[5] as number) + (m[7] as number)) / s,
+      s / 4,
+      ((m[3] as number) - (m[1] as number)) / s,
+    ];
+  }
+
+  return nodes.map((node) => {
+    if (node.parent >= 0) return node;
+    const [bx, by, bz, bw] = node.rotation;
+    return {
+      ...node,
+      translation: turn(node.translation),
+      rotation: [
+        q[3] * bx + q[0] * bw + q[1] * bz - q[2] * by,
+        q[3] * by - q[0] * bz + q[1] * bw + q[2] * bx,
+        q[3] * bz + q[0] * by - q[1] * bx + q[2] * bw,
+        q[3] * bw - q[0] * bx - q[1] * by - q[2] * bz,
+      ],
+    };
+  });
+}