Skip to content

Turn one illustration into an animated 2D mesh avatar with a coding agent and a local editor

17.7 KB
Raw Blame
// Each column is a coupled two-link pendulum driven by its waist acceleration.
// Link masses are proportional to their lengths; both halves have the same
// fabric density. Rendered links retain their source lengths.

import { clothGrid, sampleLine } from './cloth-grid.js';
import { pendulumSystem, stepPendulum } from './cloth-pendulum.js';
import { CLOTH_DEFAULTS, CLOTH_OPTIONAL_DEFAULTS, checkClothTuning } from './cloth-tuning.js';

/** Evenly spaced points (by arc length) along a polyline. */
function resample(line, n) {
  const lengths = [0];
  for (let i = 1; i < line.length; i++)
    lengths.push(lengths[i - 1] + Math.hypot(line[i][0] - line[i - 1][0], line[i][1] - line[i - 1][1]));
  const total = lengths.at(-1);
  return Array.from({ length: n }, (_, k) => {
    const d = total * k / (n - 1);
    let i = 1;
    while (i < line.length - 1 && lengths[i] < d) i++;
    const u = (d - lengths[i - 1]) / Math.max(1e-9, lengths[i] - lengths[i - 1]);
    return [0, 1].map(a => line[i - 1][a] + (line[i][a] - line[i - 1][a]) * u);
  });
}

/** @param {ReturnType<import('./rig.js').createRig>} engine
 * @param {import('../rig/types').Rig} rig */
export function createCloth(engine, rig) {
  const { baseWeights, deformBase } = engine;
  const TUNE = { bounceHz: 2.6, zeta: 0.25 };

  // Adult hip-to-ankle length≈0.8m; if joints are unavailable, assume the
  // illustration spans a 1.6m figure. Cropped/stylized art can override mm/px.
  const metersPerPixel = rig.legs
    ? 0.8 / ((Math.hypot(...rig.legs.left.ankle.map((v, i) => v - rig.legs.left.hip[i]))
      + Math.hypot(...rig.legs.right.ankle.map((v, i) => v - rig.legs.right.hip[i]))) / 2)
    : 1.6 / rig.image.height;
  // Effective length 2L/3 for a uniform rigid strip, L for a tip-heavy point
  // mass. 0.8L approximates fabric with extra mass in a ruffled hem.
  const inertiaLength = 0.8;

  const garments = (rig.cloth ?? []).map(c => {
    const grid = clothGrid(c);
    const cols = grid.custom ? grid.cols : (c.columns ?? 8), rows = grid.custom ? grid.rows : (c.rows ?? 5);
    const top = resample(c.waist, cols), bot = resample(c.hem, cols);
    const rest = new Float64Array(rows * cols * 2);
    for (let r = 0; r < rows; r++) for (let k = 0; k < cols; k++) {
      const v = r / (rows - 1), i = (r * cols + k) * 2;
      rest[i] = top[k][0] + (bot[k][0] - top[k][0]) * v;
      rest[i + 1] = top[k][1] + (bot[k][1] - top[k][1]) * v;
    }
    if (grid.custom) rest.set(grid.rest);
    return {
      grid, pendulums: /** @type {ReturnType<typeof pendulumSystem>[]} */ ([]), systemKey: null,
      c, gravity: 9.80665 / (c.scale === undefined ? metersPerPixel : c.scale / 1000),
      tuning: Object.fromEntries(Object.entries({ ...CLOTH_DEFAULTS, ...CLOTH_OPTIONAL_DEFAULTS }).map(([key, value]) => [key, c[key] ?? value])),
      cols, rows, rest, top: grid.custom ? grid.top : top, weights: (grid.custom ? grid.top : top).map(([x, y]) => baseWeights(x, y, 0)),
      target: new Float64Array(rest.length), previous: null, pivotVelocity: new Float64Array(cols * 2),
      angle: new Float64Array(cols), angularVelocity: new Float64Array(cols),
      lowerAngle: new Float64Array(cols), lowerAngularVelocity: new Float64Array(cols),
      bounce: new Float64Array(cols), bounceVelocity: new Float64Array(cols),
      out: Float64Array.from(rest), physicalOut: Float64Array.from(rest), parent: null, parentLoc: null, meshes: [],
    };
  });
  const byName = Object.fromEntries(garments.map(g => [g.c.name, g]));

  // Grid coordinates of a point: the cell and its bilinear (s, t). Points outside the grid get
  // the nearest cell, extrapolated, so ruffles past the waist or hem line still follow it.
  function locate(g, x, y) {
    let best = null;
    for (let r = 0; r < g.rows - 1; r++) for (let k = 0; k < g.cols - 1; k++) {
      const q = [(r * g.cols + k) * 2, (r * g.cols + k + 1) * 2, ((r + 1) * g.cols + k + 1) * 2, ((r + 1) * g.cols + k) * 2];
      const [ax, ay, bx, by, cx, cy, dx, dy] = q.flatMap(i => [g.rest[i], g.rest[i + 1]]);
      let s = 0.5, t = 0.5;
      for (let it = 0; it < 10; it++) {
        const fx = ax * (1 - s) * (1 - t) + bx * s * (1 - t) + cx * s * t + dx * (1 - s) * t - x;
        const fy = ay * (1 - s) * (1 - t) + by * s * (1 - t) + cy * s * t + dy * (1 - s) * t - y;
        const sx = (bx - ax) * (1 - t) + (cx - dx) * t, sy = (by - ay) * (1 - t) + (cy - dy) * t;
        const tx = (dx - ax) * (1 - s) + (cx - bx) * s, ty = (dy - ay) * (1 - s) + (cy - by) * s;
        const det = sx * ty - sy * tx;
        if (Math.abs(det) < 1e-9) break;
        s -= (fx * ty - fy * tx) / det;
        t -= (sx * fy - sy * fx) / det;
      }
      let miss = Math.max(0, -s, s - 1) + Math.max(0, -t, t - 1);
      if (g.grid.custom) {
        const u = Math.max(0, Math.min(1, s)), v = Math.max(0, Math.min(1, t));
        const px = ax * (1 - u) * (1 - v) + bx * u * (1 - v) + cx * u * v + dx * (1 - u) * v;
        const py = ay * (1 - u) * (1 - v) + by * u * (1 - v) + cy * u * v + dy * (1 - u) * v;
        miss = Math.hypot(px - x, py - y);
      }
      if (!best || miss < best.miss) best = { q, s, t, miss };
    }
    best.s = Math.min(g.grid.custom ? 1 : 4, Math.max(g.grid.custom ? 0 : -3, best.s));
    best.t = Math.min(g.grid.custom ? 1 : 4, Math.max(g.grid.custom ? 0 : -3, best.t));
    if (g.grid.custom) {
      const point = [0, 0]; place(g.rest, best, point);
      best.offset = [x - point[0], y - point[1]];
    }
    return best;
  }
  function place(p, loc, out) {
    const { q, s, t } = loc, w = [(1 - s) * (1 - t), s * (1 - t), s * t, (1 - s) * t];
    out[0] = loc.offset?.[0] ?? 0; out[1] = loc.offset?.[1] ?? 0;
    for (let j = 0; j < 4; j++) { out[0] += p[q[j]] * w[j]; out[1] += p[q[j] + 1] * w[j]; }
    return out;
  }
  for (const g of garments) if (g.c.parent) {
    g.parent = byName[g.c.parent];
    g.parentLoc = g.top.map(([x, y]) => locate(g.parent, x, y));
  }

  class Cloth {
    constructor() {
      this.gain = 1;
      this.time = 0;
    }

    setTuning(name, tuning) {
      checkClothTuning(tuning);
      if (name !== null && !Object.hasOwn(byName, name)) throw new RangeError(`Unknown cloth: ${name}`);
      for (const g of garments) if (name === null || g.c.name === name) Object.assign(g.tuning, tuning);
    }

    /** Skin a layer mesh (rest/pos arrays in source px) to the named garment. */
    attach(name, mesh) {
      const g = byName[name];
      const locs = [];
      for (let i = 0; i < mesh.rest.length; i += 2) locs.push(locate(g, mesh.rest[i], mesh.rest[i + 1]));
      g.meshes.push({ mesh, locs });
    }

    step(P, dt, phys) {
      if (dt < 0) return;
      const elapsed = Math.min(dt, 0.05), sub = Math.max(1, Math.ceil(elapsed * 240)), h = elapsed / sub;
      const a = [0, 0];
      for (const g of garments) {
        const { cols, rows, rest, target, out, angle, angularVelocity, lowerAngle, lowerAngularVelocity, bounce, bounceVelocity } = g;
        const { stiffness, damping, max, swing, follow, cohesion, wind, responseGain, tierGain, highModeDamping } = g.tuning;
        const gain = this.gain * (responseGain ?? 1);
        const pivots = new Float64Array(cols * 2), renderPivots = new Float64Array(cols * 2), acceleration = new Float64Array(cols * 2);
        for (let k = 0; k < cols; k++) {
          if (g.parent) place(g.parent.physicalOut, g.parentLoc[k], a);
          else deformBase(g.top[k][0], g.top[k][1], g.weights[k], P, phys, a);
          pivots[k * 2] = a[0]; pivots[k * 2 + 1] = a[1];
          // Parent response exaggeration affects the visible attachment only;
          // the child solver receives the unexaggerated physical acceleration.
          if (g.parent) place(g.parent.out, g.parentLoc[k], a);
          renderPivots[k * 2] = a[0]; renderPivots[k * 2 + 1] = a[1];
          for (let axis = 0; axis < 2; axis++) {
            const i = k * 2 + axis;
            const velocity = g.previous && elapsed > 0 ? (pivots[i] - g.previous[i]) / elapsed : 0;
            acceleration[i] = elapsed > 0 ? (velocity - g.pivotVelocity[i]) / elapsed : 0;
            g.pivotVelocity[i] = velocity;
          }
          for (let r = 0; r < rows; r++) {
            const i = (r * cols + k) * 2;
            target[i] = rest[i] + a[0] - g.top[k][0];
            target[i + 1] = rest[i + 1] + a[1] - g.top[k][1];
          }
        }
        g.previous = pivots;
        const frequencyMultiplier = swing * Math.sqrt(stiffness);
        const verticalOmega = 2 * Math.PI * TUNE.bounceHz;
        if (g.grid.custom) {
          const key = `${frequencyMultiplier}:${damping}:${highModeDamping}`;
          if (g.systemKey !== key) {
            const previous = g.pendulums;
            g.pendulums = g.grid.lengths.map((length, k) => {
              const js = g.grid.joints[k];
              const state = pendulumSystem(js.slice(1).map((v, j) => (v - js[j]) * length * inertiaLength), g.gravity * frequencyMultiplier ** 2, TUNE.zeta * damping, highModeDamping);
              if (previous[k]) { state.angles = previous[k].angles; state.velocities = previous[k].velocities; }
              return state;
            });
            g.systemKey = key;
          }
          // Resolve the highest normal mode as well as the shortest geometric link.
          const highest = Math.max(...g.pendulums.flatMap(p => p.frequencies));
          const count = Math.max(sub, Math.ceil(elapsed * highest * 32)), step = elapsed / count;
          for (let n = 0; n < count; n++) {
            const t = this.time + (n + 1) * step;
            const breeze = (Math.sin(t * 1.1) * 0.6 + Math.sin(t * 2.3) * 0.4) * max * wind;
            for (let k = 0; k < cols; k++) {
              const ay = acceleration[k * 2 + 1], effectiveGravity = Math.max(g.gravity * 0.1, g.gravity - ay);
              const ax = Math.max(-8 * g.gravity, Math.min(8 * g.gravity, acceleration[k * 2])) - effectiveGravity * breeze / g.grid.lengths[k];
              stepPendulum(g.pendulums[k], step, ax, effectiveGravity / g.gravity);
              bounceVelocity[k] += (-(verticalOmega ** 2) * bounce[k] - 2 * verticalOmega * bounceVelocity[k] - ay * 0.15) * step;
              bounce[k] += bounceVelocity[k] * step;
            }
          }
          for (let pass = 0; elapsed > 0 && pass < cohesion; pass++) for (const field of ['angles', 'velocities']) {
            const previous = g.pendulums.map(p => [...p[field]]);
            g.pendulums.forEach((p, k) => { p[field] = previous[k].map((v, j) => 0.5 * v + 0.25 * (previous[Math.max(0, k - 1)][j] + previous[Math.min(cols - 1, k + 1)][j])); });
          }
          const renderCustom = (destination, anchors, renderGain, bendGain = 1) => {
            for (let k = 0; k < cols; k++) {
              const js = g.grid.joints[k], seam = g.grid.seams[k], length = g.grid.lengths[k];
              const vertical = max * 0.1 * Math.tanh(bounce[k] * renderGain / (max * 0.1));
              const limit = 2 * Math.asin(Math.min(0.95, (max - Math.abs(vertical)) / (2 * length)));
              const root = g.pendulums[k].angles[0];
              const angles = g.pendulums[k].angles.map(v => {
                const displayed = bendGain === 1 ? v : root + (v - root) * bendGain;
                return limit * Math.tanh(displayed * renderGain / limit);
              });
              const joints = [Array.from(anchors.slice(k * 2, k * 2 + 2))];
              for (let j = 0; j < angles.length; j++) {
                const a = sampleLine(seam, js[j]), b = sampleLine(seam, js[j + 1]), x = b[0] - a[0], y = b[1] - a[1], theta = angles[j];
                joints.push([joints[j][0] + x * Math.cos(theta) + y * Math.sin(theta), joints[j][1] - x * Math.sin(theta) + y * Math.cos(theta)]);
              }
              for (let r = 0; r < rows; r++) {
                const v = g.grid.fractions[k][r]; let j = 0; while (j < angles.length - 1 && v > js[j + 1] + 1e-9) j++;
                const a = sampleLine(seam, js[j]), b = sampleLine(seam, v), u = (v - js[j]) / (js[j + 1] - js[j]);
                const theta = angles[j] * (1 - 0.1 * (1 - follow) * (1 - u)), x = b[0] - a[0], y = b[1] - a[1], i = (r * cols + k) * 2;
                destination[i] = joints[j][0] + x * Math.cos(theta) + y * Math.sin(theta);
                destination[i + 1] = joints[j][1] - x * Math.sin(theta) + y * Math.cos(theta) + vertical * v;
              }
            }
          };
          renderCustom(g.physicalOut, pivots, 1); renderCustom(out, renderPivots, gain, tierGain);
          continue;
        }
        for (let n = 0; n < sub; n++) {
          const t = this.time + (n + 1) * h;
          // One coherent breeze for the whole sheet, never a travelling wave.
          const breeze = (Math.sin(t * 1.1) * 0.6 + Math.sin(t * 2.3) * 0.4) * max * wind;
          for (let k = 0; k < cols; k++) {
            const i = k * 2, bottom = ((rows - 1) * cols + k) * 2;
            const length = Math.max(1, Math.hypot(rest[bottom] - rest[i], rest[bottom + 1] - rest[i + 1]));
            // Source y points down: upward pivot acceleration adds apparent
            // gravity, so g_eff=g-a_y. A small floor guards downward teleports.
            const effectiveGravity = Math.max(g.gravity * 0.1, g.gravity - acceleration[i + 1]);
            const link = inertiaLength * length / 2;
            const omega2 = effectiveGravity / link * frequencyMultiplier * frequencyMultiplier;
            const omega = Math.sqrt(omega2), zeta = TUNE.zeta * damping;
            const low = omega * Math.sqrt(2 - Math.SQRT2), high = omega * Math.sqrt(2 + Math.SQRT2);
            // Rayleigh damping gives both small-angle normal modes the same
            // damping ratio. M=[[2,cos(delta)],[cos(delta),1]], equal half masses.
            const alpha = 2 * zeta * low * high / (low + high), beta = 2 * zeta / (low + high);
            const delta = angle[k] - lowerAngle[k], c = Math.cos(delta), s = Math.sin(delta);
            const v1 = angularVelocity[k], v2 = lowerAngularVelocity[k];
            // Only discontinuous teleports can exceed8g; keep these finite
            // without limiting accelerations in the reviewed motion range.
            const ax = Math.max(-8 * g.gravity, Math.min(8 * g.gravity, acceleration[i]));
            const force = (ax - effectiveGravity * breeze / length) / link;
            const damp1 = alpha * (2 * v1 + c * v2) + beta * 2 * omega2 * v1;
            const damp2 = alpha * (c * v1 + v2) + beta * omega2 * v2;
            const b1 = -2 * omega2 * Math.sin(angle[k]) - s * v2 * v2 - 2 * force * Math.cos(angle[k]) - damp1;
            const b2 = -omega2 * Math.sin(lowerAngle[k]) + s * v1 * v1 - force * Math.cos(lowerAngle[k]) - damp2;
            const determinant = 2 - c * c;
            angularVelocity[k] += (b1 - c * b2) / determinant * h;
            lowerAngularVelocity[k] += (2 * b2 - c * b1) / determinant * h;
            angle[k] += angularVelocity[k] * h;
            lowerAngle[k] += lowerAngularVelocity[k] * h;
            // A much smaller, heavily damped vertical response to pivot acceleration.
            bounceVelocity[k] += (-verticalOmega * verticalOmega * bounce[k] - 2 * verticalOmega * bounceVelocity[k]
              - acceleration[i + 1] * 0.15) * h;
            bounce[k] += bounceVelocity[k] * h;
          }
        }
        // Smooth the column angles and their velocities, rather than delayed rows.
        for (let pass = 0; elapsed > 0 && pass < cohesion; pass++) for (const values of [angle, angularVelocity, lowerAngle, lowerAngularVelocity]) {
          const previous = values.slice();
          for (let k = 0; k < cols; k++) values[k] = previous[k] * 0.5
            + (previous[Math.max(0, k - 1)] + previous[Math.min(cols - 1, k + 1)]) * 0.25;
        }
        const render = (destination, anchors, renderGain) => {
          for (let k = 0; k < cols; k++) {
          const top = k * 2, bottom = ((rows - 1) * cols + k) * 2;
          const length = Math.max(1, Math.hypot(rest[bottom] - rest[top], rest[bottom + 1] - rest[top + 1]));
          const vertical = max * 0.1 * Math.tanh(bounce[k] * renderGain / (max * 0.1));
          const limit = 2 * Math.asin(Math.min(0.95, (max - Math.abs(vertical)) / (2 * length)));
          const theta = limit * Math.tanh(angle[k] * renderGain / limit);
          const lower = limit * Math.tanh(lowerAngle[k] * renderGain / limit);
          // Angles are relative to the world-rest shape, not the rotating
          // waist line: the cloth counter-rotates relative to a tilted pelvis.
          // follow=1 is rigid; lower values allow up to 10% extra quadratic bend.
          const bend = 0.1 * (1 - follow);
          const halfX = (rest[bottom] - rest[top]) / 2, halfY = (rest[bottom + 1] - rest[top + 1]) / 2;
          const jointX = anchors[top] + halfX * Math.cos(theta) + halfY * Math.sin(theta);
          const jointY = anchors[top + 1] - halfX * Math.sin(theta) + halfY * Math.cos(theta);
          for (let r = 0; r < rows; r++) {
            const v = r / (rows - 1), i = (r * cols + k) * 2, first = v <= 0.5;
            const u = first ? v * 2 : (v - 0.5) * 2;
            const rotation = (first ? theta : lower) * (1 - bend + bend * u), c = Math.cos(rotation), s = Math.sin(rotation);
            const x = halfX * u, y = halfY * u;
            destination[i] = (first ? anchors[top] : jointX) + x * c + y * s;
            destination[i + 1] = (first ? anchors[top + 1] : jointY) - x * s + y * c + vertical * v;
          }
        }
        };
        render(g.physicalOut, pivots, 1);
        render(out, renderPivots, gain);
      }
      this.time += elapsed;
    }

    deform() {
      const p = [0, 0];
      for (const g of garments) for (const { mesh, locs } of g.meshes) {
        for (let v = 0; v < locs.length; v++) {
          place(g.out, locs[v], p);
          mesh.pos[v * 2] = p[0]; mesh.pos[v * 2 + 1] = p[1];
        }
      }
    }

    /** Grid nodes per garment, for debug overlays. */
    get grids() { return garments.map(g => ({ name: g.c.name, cols: g.cols, rows: g.rows, nodes: g.out })); }
  }

  return { Cloth, garments };
}