@bitefoundry/retrieviewer 0.0.0-stage → 0.0.2

package/vendor/procedural-animals/src/core/build/furSlope.js

@@ -0,0 +1,115 @@
+// Fur-length slope limit (shorten only), applied by the pipeline to every coat.
+//
+// The coat shells are offset copies of the skin at hair height x (0..1) x furLen, so where the hair
+// length jumps from one vertex to the next the shells stand up as a wall: a round pad with a hard
+// rim (a cheek switched from 5 to 11 mm across a plane), an eye sunk in a ring of long fur, a strand
+// pattern smeared into a smooth plate over the steep triangles. Real hair changes length gradually
+// and lies over the shorter hair around it, so the coat surface has no cliffs.
+//
+// The limit: hair may grow no faster than `slope` metres of hair per metre of skin above the hair
+// around it, U(v) = min(L(v), min_u U(u) + s(v) |p_u - p_v|) over the furred, hairy vertices of the
+// same surface (a Dijkstra sweep from the shortest hair outward: exact, one pass). Long hair may rise
+// proportionally faster, s(v) = slope x max(1, L(v) / free): every boundary then bevels over at most
+// ~free / slope of skin whatever the hair length, so manes, ruffs, forelocks and fleeces keep
+// standing off (their edge is beveled, not flattened) while a face loses its walls.
+//
+// Species control (optional):
+//   species.render.furSlope      slope for hair up to `furSlopeFree` long (default 1); false / 0: off
+//   species.render.furSlopeFree  hair length (m) above which the allowed slope grows (default 0.025)
+//   coat().furSlope              per-vertex slope (Float32Array) replacing the default at that vertex;
+//                                Infinity (or <= 0) leaves that vertex's hair as painted (a crest meant
+//                                to stand up as a wall)
+// Bare vertices (no hair, or a material without shells) neither limit nor get limited: fur may meet a
+// lid margin, the nose leather or a hoof at full length.
+
+export const FUR_SLOPE_DEFAULTS = { slope: 1.0, free: 0.025 };
+
+const HAIRY = (m) => m === 0 || m === 4 || m === 8 || m === 9; // materials that grow shells (coatMaterial.js hairy())
+
+/**
+ * Shortens furLen in place so that no hair rises faster than the slope above its neighbours.
+ * @param {Float32Array} furLen per-vertex hair length (m), modified in place
+ * @param {Float32Array} pos    per-vertex positions (reference space)
+ * @param {Uint32Array} index   triangle indices
+ * @param {number} nV           vertex count (vertices >= nV are ignored)
+ * @param {Float32Array} tint   per-vertex rgba, a = material id
+ * @param {object} o            { slope, free, perVertex }
+ * @returns {{ shortened: number, maxCut: number }} vertices shortened by more than 0.1 mm, the largest cut (m)
+ */
+export function limitFurSlope(furLen, pos, index, nV, tint, { slope = FUR_SLOPE_DEFAULTS.slope, free = FUR_SLOPE_DEFAULTS.free, perVertex = null } = {}) {
+  const res = { shortened: 0, maxCut: 0 };
+  if (!furLen || !(slope > 0) || !(free > 0)) return res;
+  const L0 = Float32Array.from(furLen.subarray(0, nV));
+  const active = new Uint8Array(nV);
+  let any = false;
+  for (let v = 0; v < nV; v++) {
+    if (L0[v] > 0 && HAIRY(Math.round(tint[v * 4 + 3]))) { active[v] = 1; any = true; }
+  }
+  if (!any) return res;
+  // the allowed slope of each vertex's hair (0 = unlimited)
+  const sOf = new Float32Array(nV);
+  for (let v = 0; v < nV; v++) {
+    if (!active[v]) continue;
+    let s = perVertex ? perVertex[v] : slope;
+    if (perVertex && !(s > 0)) s = Infinity; // a species' explicit "leave as painted"
+    sOf[v] = Number.isFinite(s) ? s * Math.max(1, L0[v] / free) : 0;
+  }
+  // adjacency (CSR) over the active vertices
+  const deg = new Uint32Array(nV + 1);
+  for (let i = 0; i < index.length; i += 3) {
+    for (let e = 0; e < 3; e++) {
+      const u = index[i + e], v = index[i + ((e + 1) % 3)];
+      if (u < nV && v < nV && active[u] && active[v]) { deg[u + 1]++; deg[v + 1]++; }
+    }
+  }
+  for (let v = 0; v < nV; v++) deg[v + 1] += deg[v];
+  const adj = new Uint32Array(deg[nV]), fill = deg.slice(0, nV);
+  for (let i = 0; i < index.length; i += 3) {
+    for (let e = 0; e < 3; e++) {
+      const u = index[i + e], v = index[i + ((e + 1) % 3)];
+      if (u < nV && v < nV && active[u] && active[v]) { adj[fill[u]++] = v; adj[fill[v]++] = u; }
+    }
+  }
+  // Dijkstra: settle vertices in increasing (limited) length; a settled vertex bounds its neighbours
+  const U = furLen;
+  let hk = new Float64Array(4096), hv = new Int32Array(4096), n = 0;
+  const push = (k, v) => {
+    if (n === hk.length) { const k2 = new Float64Array(n * 2); k2.set(hk); hk = k2; const v2 = new Int32Array(n * 2); v2.set(hv); hv = v2; }
+    let i = n++;
+    while (i > 0) { const p = (i - 1) >> 1; if (hk[p] <= k) break; hk[i] = hk[p]; hv[i] = hv[p]; i = p; }
+    hk[i] = k; hv[i] = v;
+  };
+  const pop = () => {
+    const top = hv[0], k = hk[--n], v = hv[n];
+    let i = 0;
+    for (;;) {
+      const l = 2 * i + 1;
+      if (l >= n) break;
+      const r = l + 1, m = r < n && hk[r] < hk[l] ? r : l;
+      if (hk[m] >= k) break;
+      hk[i] = hk[m]; hv[i] = hv[m]; i = m;
+    }
+    hk[i] = k; hv[i] = v;
+    return top;
+  };
+  const done = new Uint8Array(nV);
+  for (let v = 0; v < nV; v++) if (active[v]) push(U[v], v);
+  while (n) {
+    const v = pop();
+    if (done[v]) continue;
+    done[v] = 1;
+    const Uv = U[v], px = pos[v * 3], py = pos[v * 3 + 1], pz = pos[v * 3 + 2];
+    for (let k = deg[v]; k < deg[v + 1]; k++) {
+      const u = adj[k];
+      if (done[u] || sOf[u] === 0) continue;
+      const cand = Uv + sOf[u] * Math.hypot(pos[u * 3] - px, pos[u * 3 + 1] - py, pos[u * 3 + 2] - pz);
+      if (cand < U[u]) { U[u] = cand; push(cand, u); }
+    }
+  }
+  for (let v = 0; v < nV; v++) {
+    const cut = L0[v] - U[v];
+    if (cut > 0.0001) res.shortened++;
+    if (cut > res.maxCut) res.maxCut = cut;
+  }
+  return res;
+}

package/vendor/procedural-animals/src/core/build/mesh.js

@@ -0,0 +1,67 @@
+// Meshing stage: turns a species' SDF sculpt into surface pieces ("regions").
+//
+// A species describes its regions as jobs (each job can run in its own worker):
+//   { name, part, bmin, bmax, h, F?, clip?(x,y,z), patches?: [{ c, R, B, h }], rigidBone? }
+//  part:     which primitives to mesh (primitives carry part: 'body' | 'jaw' | ...)
+//  h:        cell size in metres (quality tiers multiply it)
+//  clip:     keep only cells whose centre passes (used for overlapping regions that cross-fade)
+//  patches:  balls re-meshed at a finer cell size (eyelid margins); the region itself is clipped
+//            to exclude the inner ball and the two cross-fade in a thin shell
+//  rigidBone: the whole region follows one bone (a separately meshed jaw)
+import { meshSDF } from '../sdf/mesher.js';
+
+export function meshRegion(model, R) {
+  const prims = model.forPart(R.part || 'body');
+  if (!prims.length) throw new Error(`region ${R.name}: no primitives in part ${R.part}`);
+  const d2 = (x, y, z, c) => (x - c[0]) * (x - c[0]) + (y - c[1]) * (y - c[1]) + (z - c[2]) * (z - c[2]);
+  const patches = R.patches || [];
+  const baseClip = R.clip || null;
+  // The region stops one of its own cells inside the patch's inner radius: its cut is as ragged as its
+  // cells, and a cut that pokes past the middle of the cross-fade band (a cell wider than the band B) left
+  // a slit there that neither surface covered; one cell further in, the cut lies where the patch shows
+  // alone and the region's fade is ~0 (drawn nowhere).
+  const clip = patches.length
+    ? (x, y, z) => (!baseClip || baseClip(x, y, z)) && patches.every((p) => d2(x, y, z, p.c) > Math.max(0, p.R - p.B - R.h) ** 2)
+    : baseClip;
+  const parts = [meshSDF(prims, R.bmin, R.bmax, R.h, R.F || 6, null, clip)];
+  for (const p of patches) {
+    const rOut = p.R + p.B, pad = rOut + 3 * p.h;
+    parts.push(meshSDF(prims, [p.c[0] - pad, p.c[1] - pad, p.c[2] - pad], [p.c[0] + pad, p.c[1] + pad, p.c[2] + pad], p.h, 4, null, (x, y, z) => d2(x, y, z, p.c) < rOut * rOut && (!baseClip || baseClip(x, y, z))));
+  }
+  const m = parts.length > 1 ? mergeMeshes(parts) : { ...parts[0], patch: null };
+  return serialiseLists({ name: R.name, ...m });
+}
+
+export function mergeMeshes(meshes) {
+  let n = 0, ni = 0;
+  for (const m of meshes) { n += m.count; ni += m.indices.length; }
+  const positions = new Float32Array(n * 3), normals = new Float32Array(n * 3), indices = new Uint32Array(ni), patch = new Uint8Array(n);
+  const lists = new Array(n);
+  let v0 = 0, i0 = 0;
+  meshes.forEach((m, k) => {
+    positions.set(m.positions, v0 * 3);
+    normals.set(m.normals, v0 * 3);
+    for (let i = 0; i < m.indices.length; i++) indices[i0 + i] = m.indices[i] + v0;
+    for (let i = 0; i < m.count; i++) { lists[v0 + i] = m.lists[i]; patch[v0 + i] = k > 0 ? 1 : 0; }
+    v0 += m.count; i0 += m.indices.length;
+  });
+  return { positions, normals, indices, lists, count: n, patch };
+}
+
+// replace per-vertex primitive lists by ids so a region can cross a worker boundary
+function serialiseLists(p) {
+  const uniq = new Map();
+  const listIndex = new Uint32Array(p.count);
+  const listIds = [];
+  for (let v = 0; v < p.count; v++) {
+    const l = p.lists[v];
+    let k = uniq.get(l);
+    if (k === undefined) { k = listIds.length; uniq.set(l, k); listIds.push(Int16Array.from(l.map((q) => q.id))); }
+    listIndex[v] = k;
+  }
+  return { name: p.name, positions: p.positions, normals: p.normals, indices: p.indices, count: p.count, listIndex, listIds, patch: p.patch || null };
+}
+
+export function regionTransferables(parts) {
+  return parts.flatMap((p) => [p.positions.buffer, p.normals.buffer, p.indices.buffer, p.listIndex.buffer]);
+}

package/vendor/procedural-animals/src/core/build/pipeline.js

@@ -0,0 +1,272 @@
+// The build pipeline: species data -> seeded individual -> SDF sculpt -> meshed regions -> skin
+// weights -> coat -> proportion warp and size -> packed, transferable arrays.
+//
+// Every stage is deterministic in (species, seed, options), so a worker can redo `prepare` from the
+// species id and seed instead of receiving functions.
+import { SDFModel } from '../sdf/sdf.js';
+import { meshRegion } from './mesh.js';
+import { computeWeights } from './weights.js';
+import { composeWarps, warpMesh, warpScaleAt } from './warp.js';
+import { transformRig } from '../rig/rig.js';
+import { rng } from '../math/vec.js';
+import { eyeFrameOf } from '../sdf/eyeSocket.js';
+import { limitFurSlope, FUR_SLOPE_DEFAULTS } from './furSlope.js';
+import { measureSeams } from './seams.js';
+import { sharpenFinEdges } from './finEdges.js';
+
+export const FORMAT_VERSION = 1;
+
+// Mesh resolution multiplier and render settings per quality tier.
+export const QUALITY = {
+  hero: { res: 1.0, shells: 40, fins: true, eyePatches: true },
+  high: { res: 1.3, shells: 28, fins: true, eyePatches: true },
+  medium: { res: 2.0, shells: 16, fins: false, eyePatches: false },
+  low: { res: 3.0, shells: 8, fins: false, eyePatches: false },
+  crowd: { res: 4.2, shells: 0, fins: false, eyePatches: false },
+};
+
+export function normaliseOptions(opts = {}) {
+  const quality = QUALITY[opts.quality] ? opts.quality : 'high';
+  return { seed: (opts.seed ?? 1) >>> 0, quality, sex: opts.sex, age: opts.age, variant: opts.variant, overrides: opts.overrides || {} };
+}
+
+export function prepare(species, opts) {
+  const o = normaliseOptions(opts);
+  const R = rng(o.seed * 2654435761 + 12345);
+  const params = { ...species.variation(R, o), ...o.overrides };
+  params.seed = o.seed;
+  const rig = species.rig(params);
+  const model = new SDFModel();
+  species.sculpt(model, rig, params);
+  if (params.minThick) inflateThin(model, QUALITY[o.quality].res, params.minThick);
+  const Q = QUALITY[o.quality];
+  const reg = species.regions(rig, params, Q);
+  return { o, params, rig, model, reg, Q };
+}
+
+// primitives tagged thin (ears, tail tips) are inflated at coarse tiers so they do not vanish
+function inflateThin(model, res, minThick) {
+  if (res < 1.9) return;
+  const t = minThick * res;
+  for (const p of model.prims) {
+    if (!p.thin || p.carve) continue;
+    if (p.type === 0) for (let i = 12; i < 15; i++) p.P[i] = Math.max(p.P[i], t);
+    if (p.type === 3) { p.P[12] = Math.max(p.P[12], t); p.P[13] = Math.max(p.P[13], Math.min(t, p.P[12])); }
+  }
+}
+
+export function meshJob(species, opts, jobIndex, prep = prepare(species, opts)) {
+  return prep.reg.jobs[jobIndex].map((R) => meshRegion(prep.model, R));
+}
+
+export function jobCount(species, opts) {
+  return prepare(species, opts).reg.jobs.length;
+}
+
+export function finish(species, opts, meshedJobs, prep = prepare(species, opts), onProgress = () => {}) {
+  const t0 = now();
+  const { rig, model, reg, params, o, Q } = prep;
+  const order = reg.jobs.flat().map((r) => r.name);
+  const regDef = Object.fromEntries(reg.jobs.flat().map((r) => [r.name, r]));
+  const parts = meshedJobs.flat().sort((a, b) => order.indexOf(a.name) - order.indexOf(b.name));
+  let nV = 0, nI = 0;
+  for (const p of parts) { p.v0 = nV; nV += p.count; nI += p.indices.length; }
+  let pos = new Float32Array(nV * 3), nrm = new Float32Array(nV * 3);
+  let index = new Uint32Array(nI);
+  const lists = new Array(nV);
+  const regionOf = new Uint8Array(nV);
+  const patchOf = new Uint8Array(nV);
+  const rigidBone = new Int16Array(nV).fill(-1);
+  let io = 0;
+  parts.forEach((p, pi) => {
+    pos.set(p.positions, p.v0 * 3);
+    nrm.set(p.normals, p.v0 * 3);
+    if (p.patch) patchOf.set(p.patch, p.v0);
+    for (let i = 0; i < p.indices.length; i++) index[io++] = p.indices[i] + p.v0;
+    const L = p.listIds.map((ids) => Array.from(ids, (id) => model.prims[id]));
+    const rb = regDef[p.name].rigidBone ? rig.BONE[regDef[p.name].rigidBone].index : -1;
+    for (let i = 0; i < p.count; i++) { lists[p.v0 + i] = L[p.listIndex[i]]; regionOf[p.v0 + i] = pi; rigidBone[p.v0 + i] = rb; }
+  });
+  const regionNames = parts.map((p) => p.name);
+  // fin slabs tagged `sharpen` get knife edges below the cell size (finEdges.js; opt-in)
+  if (model.prims.some((pr) => pr.sharpen)) sharpenFinEdges({ pos, nrm, index, lists, nV, regionOf }, parts.map((p) => regDef[p.name].h));
+  onProgress('weights');
+  const weights = computeWeights({ pos, nrm, index, lists, rigidBone, nV }, rig);
+  const t1 = now();
+  // cross-fade of overlapping regions
+  let fade = new Float32Array(nV).fill(1);
+  if (reg.fade) for (let v = 0; v < nV; v++) fade[v] = reg.fade(pos[v * 3], pos[v * 3 + 1], pos[v * 3 + 2], regionNames[regionOf[v]], patchOf[v]);
+  // how far the overlapping surfaces lie apart at their hand-over: the depth of the renderer's seam
+  // skirt (seams.js)
+  const seams = measureSeams({ pos, nrm, index, nV, fade, regionOf, patchOf, hOf: parts.map((p) => regDef[p.name].h) });
+  onProgress('coat');
+  const coat = species.coat({ model, rig, params, pos, nrm, index, lists, regionOf, regionNames, patchOf, rigidBone, weights, nV, fade, rng: rng(o.seed * 7919 + 17), quality: o.quality, Q });
+  // (species.render may be a function of the individual: a mark colour that follows the morph)
+  const hints = (typeof species.render === 'function' ? species.render(params) : species.render) || {};
+  // no fur walls: hair may not rise faster than the render hint's slope above the hair around it
+  // (furSlope.js; the crowd tier draws no shells)
+  let furSlope = null;
+  if (Q.shells > 0 && coat.furLen && coat.tint && hints.furSlope !== false) {
+    furSlope = limitFurSlope(coat.furLen, pos, index, nV, coat.tint, {
+      slope: hints.furSlope ?? FUR_SLOPE_DEFAULTS.slope, free: hints.furSlopeFree ?? FUR_SLOPE_DEFAULTS.free, perVertex: coat.furSlope || null,
+    });
+  }
+  if (Q.shells <= 0) prefilterPattern(coat, index, nV, pos, hints.markColor || [0.016, 0.0105, 0.0075]);
+  const t2 = now();
+
+  // ---- extra (non-SDF) surfaces: feather cards etc., rigidly skinned, with their own attributes
+  const extra = species.surfaces ? species.surfaces({ rig, params, Q, quality: o.quality, model }) : null;
+  let skinIndex = weights.skinIndex, skinWeight = weights.skinWeight;
+  if (extra && extra.nV) {
+    const n0 = nV, n1 = nV + extra.nV;
+    const cat = (a, b, k, T = Float32Array) => { const r = new T(n1 * k); r.set(a.subarray(0, n0 * k)); r.set(b, n0 * k); return r; };
+    const idx = new Uint32Array(index.length + extra.index.length);
+    idx.set(index); for (let i = 0; i < extra.index.length; i++) idx[index.length + i] = extra.index[i] + n0;
+    pos = cat(pos, extra.pos, 3); nrm = cat(nrm, extra.nrm, 3); index = idx;
+    skinIndex = cat(skinIndex, extra.skinIndex, 4, Uint16Array); skinWeight = cat(skinWeight, extra.skinWeight, 4);
+    coat.comb = cat(coat.comb, extra.comb, 3); coat.tint = cat(coat.tint, extra.tint, 4);
+    coat.pattern = cat(coat.pattern || new Float32Array(n0).fill(1), extra.pattern, 1);
+    coat.mark = cat(coat.mark || new Float32Array(n0).fill(1), extra.mark, 1);
+    coat.furLen = cat(coat.furLen || new Float32Array(n0), extra.furLen, 1);
+    coat.patternColor = cat(coat.patternColor || constant4(n0, [0.016, 0.0105, 0.0075, 1]), extra.patternColor, 4);
+    coat.surf = cat(coat.surf || new Float32Array(n0 * 4), extra.surf, 4);
+    fade = cat(fade, new Float32Array(extra.nV).fill(1), 1);
+    nV = n1; nI = index.length;
+  }
+
+  // ---- proportion warps and size, applied to the finished surface and the skeleton
+  const size = params.size || 1;
+  const warps = [...(params.warps || [])];
+  if (size !== 1) warps.push({ type: 'scale', k: size });
+  const W = composeWarps(warps);
+  let rigOut = rig;
+  let eyes = (species.eyeSpecs ? species.eyeSpecs(params, rig) : []).map((e) => {
+    const f = eyeFrameOf(e.spec, e.headOrigin, e.side);
+    return { ...e, frame: f, scale: 1 };
+  });
+  const scaleLen = (arr, k) => { if (arr && k !== 1) for (let i = 0; i < arr.length; i++) arr[i] *= k; };
+  if (W) {
+    warpMesh(pos, nrm, W);
+    rigOut = transformRig(rig, W);
+    eyes = eyes.map((e) => ({ ...e, frame: { ...e.frame, c: W(e.frame.c) }, scale: warpScaleAt(W, e.frame.c) }));
+    scaleLen(coat.pattern, size);
+    scaleLen(coat.mark, size);
+    scaleLen(coat.furLen, Math.pow(size, 0.35));
+  }
+
+  const out = {
+    version: FORMAT_VERSION,
+    species: species.id,
+    seed: o.seed,
+    quality: o.quality,
+    params: jsonSafe(params),
+    nV,
+    pos, nrm, index,
+    skinIndex,
+    skinWeight,
+    comb: coat.comb,
+    tint: coat.tint,
+    coat: interleave(nV, coat.pattern, coat.mark, coat.furLen, fade),
+    pat: coat.patternColor || constant4(nV, [0.016, 0.0105, 0.0075, 1]),
+    surf: coat.surf || new Float32Array(nV * 4),
+    // seam skirt depth (m, final size; the warps are within ~15 %): coatMaterial sinks the handed-over
+    // half of every cross-fade band by up to this much under the surface taking over
+    seamSink: +(seams.sink * size * 1.15).toFixed(6),
+    joints: rigOut.J,
+    bones: rigOut.BONES.map((b) => ({ name: b.name, parent: b.parent, headJ: b.headJ, tailJ: b.tailJ, region: b.region, group: b.group })),
+    refJoints: rig.J,
+    eyes: eyes.map((e) => ({ side: e.side, bone: e.bone || 'head', c: e.frame.c, x: e.frame.x, y: e.frame.y, z: e.frame.z, scale: e.scale * (size !== 1 && !W ? size : 1), spec: e.spec, look: e.look || {} })),
+    prims: model.prims.map((p) => ({ type: p.type, P: Array.from(p.P), bone: p.bone, group: p.group, part: p.part, carve: p.carve, tag: p.tag, k: p.k })),
+    stats: {
+      nV, tris: nI / 3, prims: model.prims.length, bones: rig.BONES.length, weightsMs: Math.round(t1 - t0), coatMs: Math.round(t2 - t1),
+      ...(furSlope ? { furSlopeShortened: furSlope.shortened, furSlopeMaxCutMm: +(furSlope.maxCut * 1000).toFixed(1) } : {}),
+      ...(seams.samples ? { seamMaxMm: +(seams.max * 1000).toFixed(2), seamSinkMm: +(seams.sink * 1000).toFixed(2) } : {}),
+      ...(coat.stats || {}),
+    },
+  };
+  return out;
+}
+
+export function buildSync(species, opts, onProgress = () => {}) {
+  const t0 = now();
+  const prep = prepare(species, opts);
+  const jobs = prep.reg.jobs.map((_, i) => { onProgress('mesh ' + i); return meshJob(species, opts, i, prep); });
+  const d = finish(species, opts, jobs, prep, onProgress);
+  d.stats.buildMs = Math.round(now() - t0);
+  return d;
+}
+
+const now = () => (typeof performance !== 'undefined' ? performance.now() : Date.now());
+
+// Crowd tier (no shells, ~2 cm cells): the pattern and mark fields are signed distances sampled per
+// vertex, and features are about the size of a cell (spot centres even sit on vertices), so the
+// crisp zero level aliases: dense small spots (paws, lower legs) cover every vertex and turn whole
+// paws black, spots become polygons, a tail tip ring swallows the white tip. Prefilter like a mip
+// level: per vertex, the fraction of its surrounding triangles the (linearly interpolated) field
+// covers. Spots are then drawn as that coverage (pattern inside everywhere, the pattern colour's
+// intensity scaled by the coverage: soft blobs of the right size and tone); crisp marks (tear lines,
+// tail rings) are mixed into the base colour by their coverage.
+function prefilterPattern(coat, index, nV, pos, markColor) {
+  // per vertex: area-weighted fraction of the incident triangles the linear field covers, capped by
+  // the size of the features around it (a vertex on a 4 mm spot centre, with neighbours on other
+  // small spots, reads fully covered although the spots cover ~15 % of its area): the deepest
+  // inside value in its 1-ring is taken as the local feature radius r, coverage <= (r / (h / 2))^2
+  const coverage = (f) => {
+    const acc = new Float64Array(nV), wsum = new Float64Array(nV), deep = new Float64Array(nV), hsum = new Float64Array(nV), hn = new Float64Array(nV);
+    for (let i = 0; i < index.length; i += 3) {
+      const a = index[i], b = index[i + 1], c = index[i + 2];
+      const ux = pos[b * 3] - pos[a * 3], uy = pos[b * 3 + 1] - pos[a * 3 + 1], uz = pos[b * 3 + 2] - pos[a * 3 + 2];
+      const vx = pos[c * 3] - pos[a * 3], vy = pos[c * 3 + 1] - pos[a * 3 + 1], vz = pos[c * 3 + 2] - pos[a * 3 + 2];
+      const area = 0.5 * Math.hypot(uy * vz - uz * vy, uz * vx - ux * vz, ux * vy - uy * vx);
+      const fr = negFraction(f[a], f[b], f[c]);
+      const d = Math.max(0, -f[a], -f[b], -f[c]), h = Math.hypot(ux, uy, uz) + Math.hypot(vx, vy, vz);
+      for (const v of [a, b, c]) { acc[v] += area * fr; wsum[v] += area; deep[v] = Math.max(deep[v], d); hsum[v] += h; hn[v] += 2; }
+    }
+    return Float32Array.from(acc, (x, v) => {
+      if (!(wsum[v] > 0)) return 0;
+      const h = hsum[v] / hn[v];
+      return Math.min(x / wsum[v], Math.min(1, (deep[v] / (0.5 * h)) ** 2));
+    });
+  };
+  if (coat.pattern) {
+    const cov = coverage(coat.pattern);
+    const pc = coat.patternColor || (coat.patternColor = new Float32Array(nV * 4).map((_, i) => [0.016, 0.0105, 0.0075, 1][i % 4]));
+    // (a contrast curve keeps the blobs reading as spots rather than a stain)
+    for (let v = 0; v < nV; v++) { const k = Math.min(1, Math.max(0, (cov[v] - 0.12) / 0.43)); pc[v * 4 + 3] *= k * k * (3 - 2 * k); coat.pattern[v] = -1; }
+  }
+  if (coat.mark && coat.tint) {
+    // crisp marks have no intensity channel: their coverage goes into the base colour instead
+    const cov = coverage(coat.mark), t = coat.tint;
+    for (let v = 0; v < nV; v++) {
+      const k = cov[v];
+      for (let i = 0; i < 3; i++) t[v * 4 + i] += (markColor[i] - t[v * 4 + i]) * k;
+      coat.mark[v] = 1;
+    }
+  }
+}
+// area fraction of a triangle where the linear interpolation of the vertex values is negative
+function negFraction(a, b, c) {
+  const neg = (a < 0) + (b < 0) + (c < 0);
+  if (neg === 0) return 0;
+  if (neg === 3) return 1;
+  let n, p1, p2;
+  if (neg === 1) { [n, p1, p2] = a < 0 ? [a, b, c] : b < 0 ? [b, a, c] : [c, a, b]; return (n * n) / ((n - p1) * (n - p2)); }
+  [n, p1, p2] = a >= 0 ? [a, b, c] : b >= 0 ? [b, a, c] : [c, a, b]; // n: the single non-negative one
+  return 1 - (n * n) / ((n - p1) * (n - p2));
+}
+
+function interleave(n, a, b, c, d) {
+  const out = new Float32Array(n * 4);
+  for (let v = 0; v < n; v++) { out[v * 4] = a ? a[v] : 1; out[v * 4 + 1] = b ? b[v] : 1; out[v * 4 + 2] = c ? c[v] : 0; out[v * 4 + 3] = d ? d[v] : 1; }
+  return out;
+}
+function constant4(n, c) {
+  const out = new Float32Array(n * 4);
+  for (let v = 0; v < n; v++) out.set(c, v * 4);
+  return out;
+}
+function jsonSafe(o) { return JSON.parse(JSON.stringify(o, (k, v) => (typeof v === 'function' ? undefined : v))); }
+
+// Arrays that can be transferred from a worker (or written to a bake file).
+export const ARRAY_KEYS = ['pos', 'nrm', 'index', 'skinIndex', 'skinWeight', 'comb', 'tint', 'coat', 'pat', 'surf'];
+export function transferables(d) { return ARRAY_KEYS.map((k) => d[k].buffer); }

package/vendor/procedural-animals/src/core/build/seams.js

@@ -0,0 +1,183 @@
+// Cross-fade seams: how far two overlapping surfaces lie apart where they hand over.
+//
+// Regions overlap and cross-fade (a fine head over the coarse neck, eyelid patches over the face):
+// the base of each surface is drawn where its fade >= 0.5, the two halves meeting at the midline of
+// the band. The surfaces approximate the same SDF at different cell sizes, so at the midline they do
+// not coincide: the coarse one bridges creases and cuts chords inside convex skin, by up to ~0.4 of
+// its cell in a crease. Seen at a grazing angle the step between them is a thin slit into the body
+// (a red line in the 'holes' debug view).
+//
+// The renderer closes it with a skirt (render/coatMaterial.js): past the midline, down to fade 0.1,
+// the base sinks along its normal (quadratically, by up to `sink` metres) instead of stopping, so the
+// surface that is handing over dives under the one taking over (which wins the depth test) and every
+// ray through the step lands on skin. `measureSeams` sizes the sink from the real mismatch of this individual's
+// surfaces (bind pose, reference space): rays along the normal of every band vertex against the
+// other surfaces' band triangles. Shells and fins keep cross-fading on the true surfaces.
+import { smoothstep } from '../math/vec.js';
+
+// groups: a region's main surface and its eyelid patches are separate surfaces
+const groupOf = (regionOf, patchOf, v) => regionOf[v] * 2 + (patchOf && patchOf[v] ? 1 : 0);
+
+/**
+ * @param {object} m { pos, nrm, index, nV, fade, regionOf, patchOf, hOf: region index -> cell size (m) }
+ * @returns {{ sink: number, max: number, p99: number, samples: number, hBand: number }} metres (reference space)
+ */
+export function measureSeams({ pos, nrm, index, nV, fade, regionOf, patchOf, hOf }) {
+  const res = { sink: 0, max: 0, p99: 0, samples: 0, hBand: 0 };
+  // band triangles (some vertex fades, some vertex shows) and the coarsest cell of a banded region
+  const tri = [];
+  let hBand = 0;
+  for (let i = 0; i < index.length; i += 3) {
+    const a = index[i], b = index[i + 1], c = index[i + 2];
+    if (a >= nV || b >= nV || c >= nV) continue;
+    const fm = Math.min(fade[a], fade[b], fade[c]), fM = Math.max(fade[a], fade[b], fade[c]);
+    if (fM <= 0.02 || fm >= 0.98) continue;
+    tri.push(i);
+    hBand = Math.max(hBand, hOf[regionOf[a]] || 0);
+  }
+  if (!tri.length || !(hBand > 0)) return res;
+  res.hBand = hBand;
+  const range = 0.75 * hBand; // search depth along the normal
+  // hash grid of band triangles
+  const G = Math.max(range, 0.004), grid = new Map();
+  const key = (x, y, z) => (Math.floor(x / G) + 4096) * 67108864 + (Math.floor(y / G) + 4096) * 8192 + (Math.floor(z / G) + 4096);
+  for (let t = 0; t < tri.length; t++) {
+    const i = tri[t], a = index[i], b = index[i + 1], c = index[i + 2];
+    const x0 = Math.floor(Math.min(pos[a * 3], pos[b * 3], pos[c * 3]) / G), x1 = Math.floor(Math.max(pos[a * 3], pos[b * 3], pos[c * 3]) / G);
+    const y0 = Math.floor(Math.min(pos[a * 3 + 1], pos[b * 3 + 1], pos[c * 3 + 1]) / G), y1 = Math.floor(Math.max(pos[a * 3 + 1], pos[b * 3 + 1], pos[c * 3 + 1]) / G);
+    const z0 = Math.floor(Math.min(pos[a * 3 + 2], pos[b * 3 + 2], pos[c * 3 + 2]) / G), z1 = Math.floor(Math.max(pos[a * 3 + 2], pos[b * 3 + 2], pos[c * 3 + 2]) / G);
+    for (let x = x0; x <= x1; x++) for (let y = y0; y <= y1; y++) for (let z = z0; z <= z1; z++) {
+      const k = (x + 4096) * 67108864 + (y + 4096) * 8192 + (z + 4096);
+      let l = grid.get(k);
+      if (!l) grid.set(k, (l = []));
+      l.push(t);
+    }
+  }
+  const offs = [];
+  const seen = new Set();
+  for (let v = 0; v < nV; v++) {
+    const f = fade[v];
+    if (!(f > 0.3 && f < 0.7)) continue;
+    const g = groupOf(regionOf, patchOf, v);
+    const ox = pos[v * 3], oy = pos[v * 3 + 1], oz = pos[v * 3 + 2], nx = nrm[v * 3], ny = nrm[v * 3 + 1], nz = nrm[v * 3 + 2];
+    seen.clear();
+    let best = Infinity;
+    for (let s = -1; s <= 1.001; s += 0.25) {
+      const k = key(ox + nx * s * range, oy + ny * s * range, oz + nz * s * range);
+      const l = grid.get(k);
+      if (!l) continue;
+      for (const t of l) {
+        if (seen.has(t)) continue;
+        seen.add(t);
+        const i = tri[t], a = index[i], b = index[i + 1], c = index[i + 2];
+        if (groupOf(regionOf, patchOf, a) === g) continue;
+        // Moller-Trumbore, both directions along the normal
+        const e1x = pos[b * 3] - pos[a * 3], e1y = pos[b * 3 + 1] - pos[a * 3 + 1], e1z = pos[b * 3 + 2] - pos[a * 3 + 2];
+        const e2x = pos[c * 3] - pos[a * 3], e2y = pos[c * 3 + 1] - pos[a * 3 + 1], e2z = pos[c * 3 + 2] - pos[a * 3 + 2];
+        const px = ny * e2z - nz * e2y, py = nz * e2x - nx * e2z, pz = nx * e2y - ny * e2x;
+        const det = e1x * px + e1y * py + e1z * pz;
+        if (Math.abs(det) < 1e-14) continue;
+        const tx = ox - pos[a * 3], ty = oy - pos[a * 3 + 1], tz = oz - pos[a * 3 + 2];
+        const u = (tx * px + ty * py + tz * pz) / det;
+        if (u < 0 || u > 1) continue;
+        const qx = ty * e1z - tz * e1y, qy = tz * e1x - tx * e1z, qz = tx * e1y - ty * e1x;
+        const w = (nx * qx + ny * qy + nz * qz) / det;
+        if (w < 0 || u + w > 1) continue;
+        const d = (e2x * qx + e2y * qy + e2z * qz) / det;
+        if (Math.abs(d) > range || Math.abs(d) >= Math.abs(best)) continue;
+        // the surface taking over here: its fade complements this one (not the far side of a thin part)
+        const fo = fade[a] * (1 - u - w) + fade[b] * u + fade[c] * w;
+        if (Math.abs(f + fo - 1) > 0.3) continue;
+        best = d;
+      }
+    }
+    if (Number.isFinite(best)) offs.push(Math.abs(best));
+  }
+  res.samples = offs.length;
+  if (!offs.length) { res.sink = 0.1 * hBand; return res; }
+  offs.sort((x, y) => x - y);
+  res.max = offs[offs.length - 1];
+  res.p99 = offs[Math.min(offs.length - 1, Math.floor(0.99 * offs.length))];
+  // cover the creases (99th percentile: a few hits land on another fold of the skin) with room for
+  // skinning differences in motion; never deeper than 0.4 of the coarse cell
+  res.sink = Math.min(0.4 * hBand, Math.max(0.1 * hBand, 1.5 * res.p99));
+  return res;
+}
+
+// The head and the body surfaces of a region plan overlap across a cut and cross-fade there, and the core smooths each
+// surface's skin weights over its own mesh, so where the weights curve the two surfaces at one place take bone shares a
+// few per cent apart. Posed (the head bent against the neck), they part by millimetres, and the fur rooted on the
+// surface lying under the other's skin loses its roots: a crisp edge across the coat (a cat's cheek, a dog's throat).
+// The body surface near the cut takes the head surface's weights at the same place (the closest point on the finer head
+// mesh, barycentric), in full across the cross-fade band and fading back to its own over the next 8 mm on the body side.
+// sideOf(x, y, z): signed distance from the cut (> 0 on the head side); band: the cross-fade half-width. Called from a
+// species' coat (the core passes it the weights and uses them after it).
+export function harmonizeSeamWeights({ pos, index, regionOf, regionNames, weights, nV }, sideOf, band) {
+  const { skinIndex, skinWeight } = weights;
+  const bodyR = regionNames.indexOf('body'), headR = regionNames.indexOf('head');
+  if (bodyR < 0 || headR < 0) return 0;
+  const B = band, R = B + 0.008, C = 0.004;
+  const sOf = (v) => sideOf(pos[v * 3], pos[v * 3 + 1], pos[v * 3 + 2]);
+  // head triangles near the cut, in a hash grid by centroid
+  const grid = new Map(), key = (i, j, k) => `${i},${j},${k}`;
+  for (let t = 0; t < index.length; t += 3) {
+    const a = index[t], b = index[t + 1], c = index[t + 2];
+    if (a >= nV || regionOf[a] !== headR || regionOf[b] !== headR || regionOf[c] !== headR) continue;
+    if (Math.abs(sOf(a)) > R + 0.006) continue;
+    const g = [0, 1, 2].map((k) => Math.floor((pos[a * 3 + k] + pos[b * 3 + k] + pos[c * 3 + k]) / 3 / C));
+    const kk = key(...g); let l = grid.get(kk); if (!l) grid.set(kk, (l = [])); l.push(t);
+  }
+  const W0 = Float32Array.from(skinWeight), I0 = Uint16Array.from(skinIndex);
+  const P3 = (v) => [pos[v * 3], pos[v * 3 + 1], pos[v * 3 + 2]];
+  let changed = 0;
+  for (let v = 0; v < nV; v++) {
+    if (regionOf[v] !== bodyR) continue;
+    const s = sOf(v);
+    if (s < -R || s > R) continue;
+    const kMix = s > -B ? 1 : smoothstep(-R, -B, s);
+    if (kMix <= 0) continue;
+    const p = P3(v), g = p.map((x) => Math.floor(x / C));
+    let best = null, bd = 0.004;
+    for (let a = -1; a <= 1; a++) for (let b = -1; b <= 1; b++) for (let c = -1; c <= 1; c++) {
+      const l = grid.get(key(g[0] + a, g[1] + b, g[2] + c)); if (!l) continue;
+      for (const t of l) {
+        const q = closestOnTri(p, P3(index[t]), P3(index[t + 1]), P3(index[t + 2]));
+        if (q.d < bd) { bd = q.d; best = [t, q.u, q.v, q.w]; }
+      }
+    }
+    if (!best) continue;
+    const acc = new Map();
+    const add = (u, f) => { for (let k = 0; k < 4; k++) { const w = W0[u * 4 + k]; if (w > 0) acc.set(I0[u * 4 + k], (acc.get(I0[u * 4 + k]) || 0) + w * f); } };
+    add(v, 1 - kMix);
+    add(index[best[0]], kMix * best[1]); add(index[best[0] + 1], kMix * best[2]); add(index[best[0] + 2], kMix * best[3]);
+    const top = [...acc.entries()].sort((x, y) => y[1] - x[1]).slice(0, 4);
+    let sum = 0; for (const [, w] of top) sum += w;
+    for (let k = 0; k < 4; k++) {
+      if (k < top.length) { skinIndex[v * 4 + k] = top[k][0]; skinWeight[v * 4 + k] = top[k][1] / sum; } else { skinIndex[v * 4 + k] = 0; skinWeight[v * 4 + k] = 0; }
+    }
+    changed++;
+  }
+  return changed;
+}
+
+// closest point on triangle abc to p: distance and barycentric weights (Ericson, Real-Time Collision Detection 5.1.5)
+function closestOnTri(p, a, b, c) {
+  const sub3 = (x, y) => [x[0] - y[0], x[1] - y[1], x[2] - y[2]], dot3 = (x, y) => x[0] * y[0] + x[1] * y[1] + x[2] * y[2];
+  const ab = sub3(b, a), ac = sub3(c, a), ap = sub3(p, a);
+  const d1 = dot3(ab, ap), d2 = dot3(ac, ap);
+  let u, v, w;
+  if (d1 <= 0 && d2 <= 0) { u = 1; v = 0; w = 0; } else {
+    const bp = sub3(p, b), d3 = dot3(ab, bp), d4 = dot3(ac, bp);
+    const cp = sub3(p, c), d5 = dot3(ab, cp), d6 = dot3(ac, cp);
+    const vc = d1 * d4 - d3 * d2, vb = d5 * d2 - d1 * d6, va = d3 * d6 - d5 * d4;
+    if (d3 >= 0 && d4 <= d3) { u = 0; v = 1; w = 0; }
+    else if (d6 >= 0 && d5 <= d6) { u = 0; v = 0; w = 1; }
+    else if (vc <= 0 && d1 >= 0 && d3 <= 0) { const t = d1 / (d1 - d3); u = 1 - t; v = t; w = 0; }
+    else if (vb <= 0 && d2 >= 0 && d6 <= 0) { const t = d2 / (d2 - d6); u = 1 - t; v = 0; w = t; }
+    else if (va <= 0 && d4 - d3 >= 0 && d5 - d6 >= 0) { const t = (d4 - d3) / (d4 - d3 + (d5 - d6)); u = 0; v = 1 - t; w = t; }
+    else { const den = 1 / (va + vb + vc); v = vb * den; w = vc * den; u = 1 - v - w; }
+  }
+  const q = [0, 1, 2].map((k) => a[k] * u + b[k] * v + c[k] * w);
+  return { d: Math.hypot(p[0] - q[0], p[1] - q[1], p[2] - q[2]), u, v, w };
+}
+