@bitefoundry/retrieviewer 0.0.0-stage → 0.0.2

package/vendor/procedural-animals/src/species/wolf/index.js

@@ -0,0 +1,107 @@
+// Grey wolf (Canis lupus). Digitigrade trot specialist with a dense double coat.
+import { wolfRig, HEAD_O } from './rig.js';
+import { sculptWolf, eyeOf } from './sculpt.js';
+import { wolfRegions } from './regions.js';
+import { wolfCoat } from './coat.js';
+import { motion } from './motion.js';
+
+const VARIANTS = [['grey', 0.6], ['black', 0.2], ['pale', 0.15], ['tawny', 0.05]];
+
+export default {
+  id: 'wolf',
+  name: 'Grey wolf',
+  latin: 'Canis lupus',
+  group: 'paws',
+  plan: 'quadruped',
+  covering: 'fur',
+  // the colour morphs (createAnimal('wolf', { variant: 'black' })); without a variant the seed picks one
+  // (grey 60 %, black 20 %, pale 15 %, tawny 5 %)
+  variants: [
+    { id: 'grey', name: 'Grey wolf', latin: 'Canis lupus' },
+    { id: 'black', name: 'Black wolf', latin: 'Canis lupus (melanistic)' },
+    { id: 'pale', name: 'Pale wolf', latin: 'Canis lupus (arctic type)' },
+    { id: 'tawny', name: 'Tawny wolf', latin: 'Canis lupus (Eurasian type)' },
+  ],
+
+  // Seeded individual. Morph (grey agouti 60 %, black 20 %, pale / arctic-type 15 %, tawny 5 %);
+  // males ~20 % heavier (+4 % withers height), broader head and muzzle, fuller ruff; pups (8-12
+  // weeks): half size, big domed head and big paws, short muzzle (~55-70 % of adult), short legs
+  // and tail, uniform sooty fluffy coat, blue-grey eyes. Individuals vary in leg length, body
+  // length, muzzle, ears, tail, saddle extent, mask contrast and colour temperature.
+  variation(R, o) {
+    const sex = o.sex || (R() < 0.5 ? 'male' : 'female');
+    const age = o.age || 'adult';
+    const juv = age === 'juvenile' ? 1 : 0;
+    const male = sex === 'male';
+    const g = () => (R() + R() + R() - 1.5) / 1.5; // ~[-1, 1], peaked
+    let variant = o.variant;
+    if (!variant) {
+      let x = R();
+      variant = 'grey';
+      for (const [name, p] of VARIANTS) { if (x < p) { variant = name; break; } x -= p; }
+    } else R();
+    const size = (male ? 1.035 : 0.965) * (variant === 'tawny' ? 0.94 : 1) * (1 + 0.035 * g()) * (juv ? 0.52 : 1);
+    const legs = 1 + 0.03 * g() - 0.1 * juv + (variant === 'pale' ? -0.03 : 0);
+    const head = (male ? 1.035 : 0.98) * (1 + 0.02 * g());
+    return {
+      sex, age, size, variant, juv,
+      muzzle: (1 + 0.04 * g()) * (juv ? 0.68 : 1) * (variant === 'pale' ? 0.96 : 1),
+      headW: (male ? 1.06 : 0.98) * (1 + 0.02 * g()) * (juv ? 1.06 : 1),
+      ear: (1 + 0.05 * g()) * (juv ? 1.12 : 1) * (variant === 'pale' ? 0.92 : 1),
+      tail: (1 + 0.04 * g()) * (juv ? 0.75 : 1),
+      tailBrush: (1 + 0.06 * g()) * (juv ? 0.85 : 1),
+      ruff: Math.max(0.85, 1 + 0.12 * g()) * (male ? 1.1 : 0.95) - 0.2 * juv,
+      saddle: 1.1 * g(),
+      mask: 1 + 0.15 * g(),
+      legLine: variant === 'grey' || variant === 'tawny' ? Math.max(0, 0.3 + 0.7 * g()) : 0,
+      frost: variant === 'black' ? Math.max(0, 0.25 + 0.5 * g()) * (juv ? 0 : 1) : 0,
+      coatWarmth: 0.6 * g(),
+      coatLightness: 0.18 * g(),
+      coatSeed: Math.floor(R() * 1e6),
+      minThick: 0.0035,
+      warps: [
+        { type: 'legs', k: legs, top: 0.45 },
+        { type: 'length', k: 1 + 0.03 * g() - 0.04 * juv, z0: -0.3, z1: 0.38 },
+        { type: 'scaleAbout', c: HEAD_O, k: head * (juv ? 1.3 : 1), r0: 0.08, r1: 0.2 },
+        // big pup paws
+        ...(juv ? [[0.056, 0.32], [-0.056, 0.32], [0.064, -0.3], [-0.064, -0.3]].map(([x, z]) => ({ type: 'scaleAbout', c: [x, 0.03, z], k: 1.22, r0: 0.035, r1: 0.075 })) : []),
+      ],
+      // grey individuals range from cream-grey (threequarter1, front1) to dark grizzled (threequarter2,
+      // face1): -1 toward the black morph .. 1 toward the pale one (drawn last: the other params keep
+      // their seeds)
+      greyTone: g(),
+    };
+  },
+  rig: (params) => wolfRig(params),
+  sculpt: (m, rig, params) => sculptWolf(m, rig, params),
+  regions: wolfRegions,
+  coat: wolfCoat,
+  eyeSpecs: (params) => [1, -1].map((side) => ({ side, spec: eyeOf(params), headOrigin: HEAD_O, bone: 'head', look: params.juv ? PUP_EYE : EYE_LOOK })),
+  motion,
+  render: {
+    markColor: [0.012, 0.01, 0.009],
+    strandDensity: 700,
+    clumpDensity: 0.8,
+    // the leather is matte, with a broad soft sheen (face1, face2; 0.42 focused the key light into one
+    // hard dot), and its marks are the nostrils (coat.js)
+    noseRoughness: 0.58,
+    noseMarks: true,
+    // (its colour from the coat: pale rims round the nostrils and a paler septum)
+    noseTint: true,
+  },
+};
+
+// Round pupil, amber iris (#c89b45 with a darker limbal ring #6b4a20), no visible sclera, black lids.
+export const EYE_LOOK = {
+  pupil: 'round',
+  lids: 'mammal',
+  iris: { inner: [0.36, 0.2, 0.035], mid: [0.58, 0.33, 0.06], hi: [0.78, 0.52, 0.13], outer: [0.15, 0.07, 0.014] },
+  sclera: { color: [0.2, 0.15, 0.11], visible: false },
+  lidColor: [0.02, 0.017, 0.015],
+  pupilSize: [0.25, 0.55],
+};
+// 8-12 week pups: blue-grey eyes (turn amber at 8-16 weeks)
+export const PUP_EYE = {
+  ...EYE_LOOK,
+  iris: { inner: [0.1, 0.13, 0.17], mid: [0.2, 0.25, 0.32], hi: [0.36, 0.42, 0.5], outer: [0.06, 0.07, 0.09] },
+};

package/vendor/procedural-animals/src/species/wolf/motion.js

@@ -0,0 +1,80 @@
+// Wolf motion data for the quadruped engine (schema: src/core/motion/quadruped.js).
+// Numbers are for the reference individual (params.size = 1, withers ~0.75 m); the engine scales them
+// by dynamic similarity for pups and big males.
+//
+// Gaits: the wolf is a trot specialist. Lateral-sequence walk (0.5-1.5 m/s,
+// 0.9-1.4 Hz, duty 0.60-0.70); the travelling trot (1.5-3.5 m/s, 1.8-2.3 Hz, duty 0.40-0.50, hind of
+// each diagonal pair lands ~3 % first) is single-tracking: the feet converge on the midline
+// (trail straddle 8-15 cm), which `width` narrows per gait row; transverse canter / lope (4-7 m/s,
+// right lead) and a rotary gallop (LH-RH-RF-LF, 2.7-3.5 Hz, duty 0.20-0.28) with flexing spine up to
+// 15-17 m/s. Trot -> gallop transition ~3.7-4.5 m/s (1.53 M^0.24 for 40 kg).
+import { wolfUpdate } from './behaviour.js';
+
+const G = (name, v, f, D, off, o) => ({ name, v, f, D, off, ...o });
+
+export const motion = {
+  // wolf body language layered over every action (tail by mood, ears, hackles, snarl, howling)
+  hooks: { update: wolfUpdate },
+  maxSpeed: 16,
+  accel: [5.5, 9],
+  decel: 10,
+  // a walking canid turns at ~1-1.5 rad/s, leading with the head (2.6 swung the body round at 1.9 rad/s);
+  // a chasing wolf corners at ~0.8 g
+  turnRate: 1.8,
+  latAccelMax: 8,
+  gears: { walk: 1.1, trot: 2.5, canter: 5.2, gallop: 11 },
+  gallopBlend: [4.2, 8],
+  gaits: [
+    G('walk', 0.0, 0.85, 0.7, [0.25, 0.75, 0.0, 0.5], { liftF: 0.06, liftH: 0.05, bobF: 0.006, bobH: 0.006, flex: 0.0, lat: 0.05, fold: 1.0, heel: 35, tail: 0, drop: 0.0, width: 0.95 }),
+    G('walk', 1.35, 1.2, 0.62, [0.25, 0.75, 0.0, 0.5], { liftF: 0.075, liftH: 0.06, bobF: 0.01, bobH: 0.01, flex: 0.0, lat: 0.05, fold: 1.2, heel: 42, tail: 0.12, drop: 0.0, width: 0.8 }),
+    G('trot', 1.9, 1.85, 0.48, [0.53, 0.03, 0.0, 0.5], { liftF: 0.1, liftH: 0.085, bobF: 0.018, bobH: 0.018, flex: 0.02, lat: 0.015, fold: 1.45, heel: 50, tail: 0.3, drop: 0.006, width: 0.55 }),
+    G('trot', 3.6, 2.2, 0.4, [0.53, 0.03, 0.0, 0.5], { liftF: 0.12, liftH: 0.1, bobF: 0.024, bobH: 0.024, flex: 0.03, lat: 0.01, fold: 1.6, heel: 58, tail: 0.4, drop: 0.012, width: 0.5 }),
+    G('canter', 4.8, 2.35, 0.36, [0.3, 0.45, 0.0, 0.3], { liftF: 0.16, liftH: 0.14, bobF: 0.022, bobH: 0.035, flex: 0.2, lat: 0, fold: 1.8, heel: 62, tail: 0.6, drop: 0.02, width: 0.8 }),
+    G('gallop', 8, 2.7, 0.28, [0.52, 0.42, 0.0, 0.1], { liftF: 0.2, liftH: 0.18, bobF: 0.03, bobH: 0.045, flex: 0.32, lat: 0, fold: 1.9, heel: 68, tail: 0.8, drop: 0.03, width: 1 }),
+    G('gallop', 15, 3.3, 0.22, [0.52, 0.42, 0.0, 0.1], { liftF: 0.24, liftH: 0.22, bobF: 0.03, bobH: 0.05, flex: 0.42, lat: 0, fold: 2.0, heel: 72, tail: 0.9, drop: 0.05, width: 1 }),
+  ],
+  feet: {
+    front: { type: 'digitigrade', curl: 55 },
+    hind: { type: 'digitigrade', curl: 65 },
+  },
+  stance: { width: 1, gallopWidth: 0.6, sprawl: 0, crouch: 0, scuff: [11, 18, 0] },
+  // torso cross-sections (bind, reference size): centre height, half height, half width (incl. coat)
+  body: {
+    chest: { y: 0.54, hh: 0.172, hw: 0.13 },
+    pelvis: { y: 0.6, hh: 0.2, hw: 0.13 }, // incl. the folded thighs a lying wolf rests on
+    back: 0.07,
+  },
+  head: {
+    // [speed, raise (m), reach (m), pitch (rad, + = nose down)]: standing head at withers height,
+    // the travelling trot carries it low (skull at the back line, muzzle 30-45 deg down), the gallop
+    // stretches it forward
+    carriage: [[0, 0.0, 0.0, 0.1], [1.1, -0.03, 0.02, 0.22], [2.4, -0.085, 0.05, 0.38], [4.5, -0.075, 0.06, 0.3], [9, -0.07, 0.08, 0.2]],
+    stab: [[0, 0], [0.9, 0.22], [1.8, 0.3], [4.5, 0.34], [9, 0.6]],
+    neckBend: 40, neckPivot: 0.6, yaw: 1.2, pitchUp: 0.6, pitchDown: 0.7,
+  },
+  tail: {
+    // [speed, pitch per segment from horizontal (deg), base -> tip]: hangs at rest, ~level with a
+    // slight droop in the travelling trot, streams straight back in the gallop
+    carriage: [
+      [0.0, [-38, -60, -71, -76, -78, -78, -76, -72]],
+      [1.1, [-30, -50, -61, -66, -68, -67, -64, -58]],
+      [2.4, [-30, -40, -45, -47, -47, -45, -41, -36]], // ~30 deg below level, the tip swinging with the stride
+      [5.0, [-16, -20, -22, -22, -20, -17, -13, -9]],
+      [10, [-6, -8, -8, -7, -6, -4, -2, 0]],
+    ],
+    stiffness: 0.9, sway: 9, flick: 0, wag: 0, swish: 0, curl: 0,
+    balance: 0.45, // counterweight in turns and speed changes
+    radius: [0.075, 0.065], // (the brush: coat included)
+  },
+  ears: { rest: [0, 0], mobility: 1, speedFlatten: 0.6, twitch: 1, prick: 0.45 },
+  breath: { rate: 0.3, amp: 0.012, pant: true, pantRate: 3.0, pantAmp: 0.05, heatSpeed: 10 }, // pants only after a real chase (mouth closed at rest)
+  actions: {
+    attack: { style: 'bite-lunge', paws: false }, // (forefeet planted: the head and neck drive the bite)
+    eat: { style: 'tear', dropF: 0.3, dropH: 0.1, ahead: 0.8 }, // (short neck on long legs: the mouth reaches further ahead)
+    drink: { dropF: 0.35, dropH: 0.12, ahead: 0.8 },
+    jump: { height: 1.0, distance: 3.6 },
+    sit: { dropH: 0.8 },
+    lie: {},
+    sleep: { style: 'curl' },
+  },
+};

package/vendor/procedural-animals/src/species/wolf/regions.js

@@ -0,0 +1,57 @@
+// Meshing plan: body at 5.2 mm, head at 2.5 mm (overlapping across the upper neck and cross-faded),
+// eyelid patches at 1 mm, and the lower jaw as its own surface so the mouth can open.
+import { wolfJoints, HEAD_O } from './rig.js';
+import { eyeOf } from './sculpt.js';
+import { eyeFrameOf } from '../../core/sdf/eyeSocket.js';
+import { lerp, norm, sub, smoothstep } from '../../core/math/vec.js';
+
+// the neck cut is fixed in reference space (joints of the reference individual)
+const J0 = wolfJoints();
+export const NECK_CUT = (() => {
+  const d = norm(sub(J0.occiput, J0.neckMid));
+  const c = lerp(J0.neckMid, J0.occiput, 0.5);
+  return { c, d, band: 0.02 };
+})();
+export const neckS = (x, y, z) => (x - NECK_CUT.c[0]) * NECK_CUT.d[0] + (y - NECK_CUT.c[1]) * NECK_CUT.d[1] + (z - NECK_CUT.c[2]) * NECK_CUT.d[2];
+
+export const eyeCentres = (params) => [1, -1].map((s) => eyeFrameOf(eyeOf(params), HEAD_O, s).c);
+const PATCH = { R: 0.021, B: 0.004, h: 0.001 };
+// Eyelid patches at hero, high and medium: medium's 5 mm face cells drew the 22 x 10.5 mm lid aperture
+// as a jagged crown; its patches are meshed at 2 mm, with the cross-fade band a face cell wide.
+export const eyePatchOf = (Q) => (Q.eyePatches || Q.res <= 2 ? { R: PATCH.R, B: Math.max(PATCH.B, 0.0025 * Q.res), h: PATCH.h * Math.max(1, Q.res) * (Q.eyePatches ? 1 : 1.25) } : null);
+function eyePatchWeight(centres, P, x, y, z) {
+  let dmin = 1e9;
+  for (const c of centres) dmin = Math.min(dmin, Math.hypot(x - c[0], y - c[1], z - c[2]));
+  return 1 - smoothstep(P.R - P.B, P.R + P.B, dmin);
+}
+
+export function wolfRegions(rig, params, Q) {
+  const B = NECK_CUT.band, r = Q.res, OV = 0.006 * Math.max(1, r / 2);
+  const centres = eyeCentres(params);
+  const EP = eyePatchOf(Q);
+  const patches = EP ? centres.map((c) => ({ c, R: EP.R, B: EP.B, h: EP.h })) : [];
+  const zN = rig.J.nose[2] + 0.03;
+  return {
+    jobs: [
+      // (each clip lies a full cell past its surface's visible half of the band (fade midpoint at +-OV):
+      // a clip nearer than one cell dropped a row of visible cells at the coarse tiers, a ring of holes
+      // round the top of the neck at crowd)
+      [{ name: 'body', part: 'body', bmin: [-0.2, -0.03, -0.9], bmax: [0.2, 0.9, 0.66], h: 0.0052 * r, F: 4, clip: (x, y, z) => neckS(x, y, z) < B + OV + 0.0052 * r }],
+      [
+        { name: 'head', part: 'body', bmin: [-0.13, 0.55, 0.22], bmax: [0.13, 0.96, zN], h: 0.0025 * r, F: 6, clip: (x, y, z) => neckS(x, y, z) > -B - OV - 0.0025 * r, patches },
+        { name: 'jaw', part: 'jaw', bmin: [-0.065, 0.63, 0.52], bmax: [0.065, 0.73, zN], h: 0.0025 * r, F: 6, rigidBone: 'jaw' },
+      ],
+    ],
+    fade(x, y, z, name, patch) {
+      const sN = neckS(x, y, z);
+      // the two surfaces overlap by OV (both drawn) so no crack opens where they are not coincident
+      if (name === 'body') return 1 - smoothstep(-B, B, sN - OV);
+      if (name === 'head') {
+        let f = smoothstep(-B, B, sN + OV);
+        if (patches.length) { const ew = eyePatchWeight(centres, EP, x, y, z); f *= patch ? ew : 1 - ew; }
+        return f;
+      }
+      return 1;
+    },
+  };
+}

package/vendor/procedural-animals/src/species/wolf/rig.js

@@ -0,0 +1,87 @@
+// Grey wolf skeleton in bind pose (metres). Forward = +Z, up = +Y, the animal's left = +X.
+//
+// Reference individual: an average adult (between the sexes), withers height ~0.75 m, nose to tail
+// base ~1.08 m (straight line), tail vertebrae ~0.40 m (+ ~0.08 m of brush beyond the tip).
+// Limb segments from wolf long-bone series: scapula 0.19, humerus 0.215,
+// radius 0.22, metacarpus 0.09, femur 0.23, tibia 0.245, metatarsus 0.10 m. Standing angles from
+// side photos: scapula ~57 deg to horizontal, shoulder ~110 deg, elbow under the withers, metacarpus
+// ~80 deg to the ground; hip ~100, stifle ~120, hock ~135 deg with a near-vertical metatarsus.
+// The head is modelled level in its own frame (HEAD_O); its carriage comes from the motion data.
+import { buildRig } from '../../core/rig/rig.js';
+import { quadrupedBones, quadrupedLimbs, tailChain } from '../../core/rig/quadruped.js';
+
+export const TAIL_SEGS = 8;
+export const HEAD_O = [0, 0.752, 0.6]; // head-local origin (mid cranium, between eyes and ears)
+export const HS = 1.11; // head-local scale (landmarks below are for a 0.25 m skull; with skin and coat ~0.27 m)
+export const SH = 0.75; // reference withers height
+export const MUZZLE_Z0 = 0.035; // head-local z where the muzzle starts (muzzle length variation acts ahead of it)
+
+// head-local -> reference space, with a per-individual muzzle length factor (pups, individuals)
+export const hlOf = (m = 1, w = 1) => (v) => [HEAD_O[0] + v[0] * w * HS, HEAD_O[1] + v[1] * HS, HEAD_O[2] + HS * (v[2] > MUZZLE_Z0 ? MUZZLE_Z0 + (v[2] - MUZZLE_Z0) * m : v[2])];
+
+export function wolfJoints(params = {}) {
+  const hl = hlOf(params.muzzle || 1);
+  const earK = params.ear || 1;
+  const J = {
+    nose: hl([0, -0.012, 0.155]),
+    occiput: hl([0, 0.02, -0.095]),
+    neckMid: [0, 0.685, 0.45],
+    neckBase: [0, 0.615, 0.4],
+    chestMid: [0, 0.635, 0.21],
+    thoraxRear: [0, 0.645, 0.03],
+    lumbarMid: [0, 0.655, -0.1],
+    lumbosacral: [0, 0.65, -0.21],
+    tailBase: [0, 0.635, -0.31],
+    scapTopL: [0.042, 0.675, 0.315],
+    shoulderL: [0.076, 0.516, 0.418],
+    elbowL: [0.068, 0.344, 0.29],
+    wristL: [0.058, 0.125, 0.305],
+    mcpL: [0.056, 0.036, 0.32],
+    ftoeL: [0.056, 0.016, 0.37],
+    hipL: [0.07, 0.545, -0.255],
+    kneeL: [0.088, 0.33, -0.173],
+    hockL: [0.068, 0.14, -0.327],
+    mtpL: [0.064, 0.037, -0.315],
+    htoeL: [0.064, 0.016, -0.268],
+    jawHinge: hl([0, -0.035, -0.035]),
+    jawTip: hl([0, -0.058, 0.128]),
+    // ears set wide, on the upper corners of the skull (bases ~1.7x the eye spacing apart, tips ~2x:
+    // face1 / face2), ~0.1 m from notch to tip; 4 mm higher with the raised crown
+    earBaseL: hl([0.054, 0.046, -0.048]),
+    earTipL: hl([0.054 + 0.03 * earK, 0.046 + 0.084 * earK, -0.048 - 0.006 * earK]),
+  };
+  // bind tail held out behind (~ the trot carriage), clear of the buttocks so the skin of the rump
+  // and the brush do not merge; the relaxed hanging carriage comes from the motion data
+  const tk = params.tail || 1;
+  // (vertebrae 0.43 m: the research mean is 0.45 m for males, 0.35-0.52 m; with the tip hair the brush
+  // hangs to about the hock)
+  tailChain(J, 'tailBase', [-14, -24, -31, -37, -41, -44, -45, -45], [0.06, 0.057, 0.054, 0.051, 0.048, 0.045, 0.042, 0.039].map((l) => l * 1.08 * tk));
+  return J;
+}
+
+export function wolfRig(params = {}) {
+  const J = wolfJoints(params);
+  return buildRig({
+    joints: J,
+    unit: SH / 0.76,
+    headOrigin: HEAD_O,
+    bones: quadrupedBones({ tailSegs: TAIL_SEGS, ears: true, jaw: true }),
+    axial: {
+      points: ['nose', 'occiput', 'neckMid', 'neckBase', 'chestMid', 'thoraxRear', 'lumbarMid', 'lumbosacral', 'tailBase', ...Array.from({ length: TAIL_SEGS }, (_, i) => 'tail' + (i + 1))],
+      bones: ['head', 'neck2', 'neck1', 'chest', 'spine3', 'spine2', 'spine1', 'pelvis', ...Array.from({ length: TAIL_SEGS }, (_, i) => 'tail' + i)],
+      // the skull's influence reaches back into the nape and the cheek ruff, and hands over to the neck
+      // over 23 cm (was 17: the tighter sleep curl pushed the throat's stretch > 3x to 3.95 % of 4)
+      blend: { 1: [-0.07, 0.16, 2] }, // (3rd value: wider with the distance from the axis: the throat)
+      bodyTail: 0, // the brush hangs behind the thighs: their skin blends into it only at the tail base
+    },
+    limbs: quadrupedLimbs({
+      front: { tCore: 0.55, aCore: 0.04, aBody: -0.07, midX: 0.0 },
+      hind: { tCore: 0.52, aCore: 0.022, aBody: -0.045, midX: 0.008 },
+    }),
+    appendages: [
+      { group: 'earL', bone: 'earL', blend: [-0.006, 0.014] },
+      { group: 'earR', bone: 'earR', blend: [-0.006, 0.014] },
+    ],
+    webTags: ['flankfold', 'thighfront', 'scapmuscle'],
+  });
+}