@rig-c/parts 1.8.0 → 1.9.1

package/src/rig.ts

@@ -103,6 +103,11 @@
  *   bone a constraint follows is declared detached from the bones it drives
  *   ({@link detachedRules}, `invariants.detached`, rigc's `A25`). Without the
  *   field, no byte of any output moves.
+ * - **The turn control**, only when the config has `turn` (issue #251,
+ *   `src/turn.ts`, {@link applyTurn}): a bone `turn` under `root` nothing
+ *   keys, a leaf twin of every bone a carried part binds, and one transform
+ *   constraint per part carrying its twins `fraction · turn.x` in world x,
+ *   after the config's own constraints. Without the field nothing is added.
  *
  * Every part image is padded by {@link PAD} transparent pixels on each side
  * before it is meshed or placed, and the padded image is what `images/`
@@ -155,6 +160,7 @@ import { EYE_GROUP_TAGS } from './propose.ts';
 import { alphaAbove, crop, pad, type Raster } from './raster/index.ts';
 import { pyRound } from './round.ts';
 import { boneHeat, heatInfluences, heatRow, type HeatRow, latticeSilhouette, tracedSilhouette } from './heat.ts';
+import { TURN_BONE, type TurnSpec, turnConstraintName, turnFractions, turnTwin } from './turn.ts';
 import { DEFAULT_LIMITS, DISTANCE_EXPONENT, type Influence, influences, type Segment } from './weights.ts';
 
 /** Transparent pixels added round every part image — the reference's `PAD`. */
@@ -441,6 +447,104 @@ export function detachedRules(constraints: readonly ConfigConstraint[]): Detache
   return out;
 }
 
+/** One carried part of the turn control (issue #251): its depth, its fraction, and the twins that carry it. */
+export interface TurnRow {
+  part: string;
+  depth: number;
+  fraction: number;
+  /** Each bone the part's slots and weights bind to, with the leaf twin that now carries it; empty when the fraction is 0 — the part stays with the pivot. */
+  twins: Array<{ bone: string; twin: string }>;
+}
+
+/**
+ * The turn control (issue #251, `src/turn.ts`), added to a built rig in place:
+ * the control {@link TURN_BONE} under `root` at its origin, nothing keying it;
+ * for each part `config.turn.depths` lists, in parts.json order, a leaf twin of
+ * every bone the part's slots bind (its region's bone, a blink.still piece's
+ * bone, a mesh's slot bone and every bone its weights name) — an identity child,
+ * x 0, y 0, no rotation, so its world transform is its bone's exactly and every
+ * idle key, physics step or constraint on the bone reaches it — the part's
+ * slots and weights moved onto the twins, and one transform constraint per part
+ * that adds `fraction · turn.x` to each twin's world x (`localSource`, read
+ * off the control's local x; world target; `additive`).
+ *
+ * Why its own twins and not the `<bone>_ctl` controls: a control is a parent,
+ * keyed by the idle, and carries every part on its bone and every bone under
+ * it, so it cannot hold two parts at two depths; a leaf twin per part and bone
+ * moves that part and nothing else, and nothing else keys or constrains it. A
+ * mesh moves as a whole because its weights sum to 1 and every twin it binds
+ * moves by the same world offset.
+ *
+ * At rest the control's x is 0, so each constraint adds `0 · fraction` to
+ * world x. At rest: with `turn` declared, no pixel differs by more than 1
+ * level at dial 0 (not byte-identical; the cause is float noise in the
+ * identity child bones, and the constraints add nothing); without `turn`,
+ * byte-identical. The constraints come
+ * after the config's own, so a physics constraint on a bone has run before its
+ * twin is moved. A part at the pivot depth (fraction 0) gets no twin and no
+ * constraint. A name the turn needs that is taken is refused by name
+ * (`RIG_TURN_NAME_FREE`).
+ */
+function applyTurn(
+  turn: TurnSpec,
+  order: readonly string[],
+  bones: RigBone[],
+  slots: RigSpec['slots'],
+  skin: RigSpec['skins']['default'],
+  constraints: readonly ConfigConstraint[],
+): { constraints: Array<Record<string, unknown>>; detached: DetachedRule[]; rows: TurnRow[] } {
+  const problems: Problem[] = [];
+  const taken = new Set(bones.map((b) => b.name));
+  const transforms = new Set(constraints.filter((c) => c.type === 'transform').map((c) => c.name));
+  if (taken.has(TURN_BONE)) problems.push({ code: 'RIG_TURN_NAME_FREE', object: `bone "${TURN_BONE}"`, detail: 'is the control the rig stage adds for config.turn, and the rig already has a bone of that name; rename it' });
+  const rows: TurnRow[] = [];
+  for (const f of turnFractions(turn, order)) {
+    const row: TurnRow = { ...f, twins: [] };
+    rows.push(row);
+    if (f.fraction === 0) continue;
+    const mine = slots.filter((sl) => sl.name === f.part || sl.name === `${f.part}${STILL_SUFFIX}`);
+    const bound: string[] = [];
+    const bind = (b: string): void => {
+      if (!bound.includes(b)) bound.push(b);
+    };
+    for (const sl of mine) {
+      bind(sl.bone);
+      for (const att of Object.values(skin[sl.name] ?? {})) if ('type' in att) for (const v of att.weights) for (const w of v) bind(w.bone);
+    }
+    for (const b of bound) {
+      const twin = turnTwin(f.part, b);
+      if (taken.has(twin)) problems.push({ code: 'RIG_TURN_NAME_FREE', object: `bone "${twin}"`, detail: `is the twin that carries part "${f.part}" on "${b}" under config.turn, and the rig already has a bone of that name; rename it` });
+      taken.add(twin);
+      row.twins.push({ bone: b, twin });
+    }
+    const cname = turnConstraintName(f.part);
+    if (transforms.has(cname)) problems.push({ code: 'RIG_TURN_NAME_FREE', object: `transform constraint "${cname}"`, detail: `is the constraint that carries part "${f.part}" under config.turn, and config.constraints already names a transform constraint so; rename it` });
+  }
+  refuseIfAny(problems);
+  bones.push({ name: TURN_BONE, parent: ROOT_BONE, x: 0, y: 0 });
+  const out: Array<Record<string, unknown>> = [];
+  const detached: DetachedRule[] = [];
+  for (const row of rows) {
+    if (row.twins.length === 0) continue;
+    const twinOf = new Map(row.twins.map((t) => [t.bone, t.twin]));
+    for (const t of row.twins) bones.push({ name: t.twin, parent: t.bone, x: 0, y: 0 });
+    for (const sl of slots) {
+      if (sl.name !== row.part && sl.name !== `${row.part}${STILL_SUFFIX}`) continue;
+      sl.bone = twinOf.get(sl.bone) as string;
+      const atts = skin[sl.name] ?? {};
+      for (const [k, att] of Object.entries(atts)) {
+        if ('type' in att) atts[k] = { ...att, weights: att.weights.map((v) => v.map((w) => ({ ...w, bone: twinOf.get(w.bone) as string }))) };
+      }
+    }
+    const cname = turnConstraintName(row.part);
+    out.push({ type: 'transform', name: cname, bones: row.twins.map((t) => t.twin), source: TURN_BONE, localSource: true, additive: true, properties: { x: { to: { x: { scale: row.fraction } } } } });
+    for (const t of row.twins) {
+      detached.push({ bone: TURN_BONE, notUnder: t.twin, why: `rig-parts: "${TURN_BONE}" is the source of transform constraint "${cname}" (config.turn, issue #251), and "${t.twin}" is a bone it drives; under it, driving it would move what it follows` });
+    }
+  }
+  return { constraints: out, detached, rows };
+}
+
 /**
  * Where the idle's keys on a mesh-driving bone go (`rig --idle-keys`).
  *
@@ -693,6 +797,8 @@ export interface RigOutput {
   autoMotion: AutoMotionCase[];
   /** The eye line the face bones were turned to, or why there is none (issue #239). */
   faceAxis: FaceAxis;
+  /** The turn control's parts (issue #251), in parts.json order; null when the config has no `turn`. */
+  turn: TurnRow[] | null;
 }
 
 /**
@@ -1637,6 +1743,9 @@ export function buildRig(
     });
   }
   refuseIfAny(problems);
+  // ---- the turn control (issue #251) -------------------------------------
+  // Only when the config has `turn`: every other build adds nothing here, so no byte moves.
+  const turned = cfg.turn === undefined ? null : applyTurn(cfg.turn, parts.parts.map((p) => p.name), bones, slots, skin, cfg.constraints ?? []);
 
   const name = `${cfg.key}_painting`;
   const rig: RigSpec = {
@@ -1649,7 +1758,8 @@ export function buildRig(
     skins: { default: skin },
   };
   if (cfg.constraints !== undefined) rig.constraints = cfg.constraints.map(constraintForRig);
-  const detached = detachedRules(cfg.constraints ?? []);
+  if (turned !== null) rig.constraints = [...(rig.constraints ?? []), ...turned.constraints];
+  const detached = [...detachedRules(cfg.constraints ?? []), ...(turned?.detached ?? [])];
   if (idleKeys === 'direct' && meshKeyed.length > 0) rig.invariants = { idleDrivesMeshes: { why: IDLE_DRIVES_MESHES_WHY } };
   if (detached.length > 0) rig.invariants = { ...rig.invariants, detached };
   // issue #126 item 3: an automatic part whose author set motion.deformMayFold — written only then, so no other rig moves.
@@ -1658,7 +1768,7 @@ export function buildRig(
   // issue #239: the face's line, written only when the face bones were turned to one, so no other rig moves.
   const axes = [faceAxis.axis, faceAxis.tipAxis].flatMap((x) => (x === null ? [] : [x]));
   if (axes.length > 0) rig.invariants = { ...rig.invariants, axes };
-  return { rig, motion, meshReport, images: outImages, controls, meshKeyed, idleKeys, loopPasses, autoMotion, faceAxis };
+  return { rig, motion, meshReport, images: outImages, controls, meshKeyed, idleKeys, loopPasses, autoMotion, faceAxis, turn: turned?.rows ?? null };
 }
 
 /**

package/src/skeleton.ts

@@ -35,6 +35,7 @@
  * latent size scales every point by `w / 832`, `h / 1216`.
  */
 import { newRaster, type Raster } from './raster/types.ts';
+import { edgeLength } from './length.ts';
 
 export type SkeletonName = 'stand_sides' | 'stand_clasp';
 
@@ -391,7 +392,7 @@ export function renderSkeleton(pose: SkeletonName | PosePoints, w: number, h: nu
     const [x1, y1] = kp[i1 - 1];
     const [x2, y2] = kp[i2 - 1];
     const angle = Math.atan2(y1 - y2, x1 - x2) * RAD_TO_DEG;
-    const poly = ellipsePoly((x1 + x2) / 2, (y1 + y2) / 2, Math.hypot(x1 - x2, y1 - y2) / 2, sw, angle);
+    const poly = ellipsePoly((x1 + x2) / 2, (y1 + y2) / 2, edgeLength(x1 - x2, y1 - y2) / 2, sw, angle);
     const c = COLORS[i];
     pilFillPolygon(r, poly, [Math.trunc(c[0] * 0.6), Math.trunc(c[1] * 0.6), Math.trunc(c[2] * 0.6)]);
   });

package/src/structure.ts

@@ -74,6 +74,7 @@ import { parseRigSpec, RIG_SPEC_VERSION, type RigBone as RigcBone, type RigSpec
 import { type ConfigConstraint, CONSTRAINT_FOLLOWS, parseConfig, parseProposalSections, type Point, ROOT_BONE, type SkeletonSections, weightsABone } from './config.ts';
 import { computeExactFrameTransforms, cropToSpineY, normaliseDegrees, toWorld } from './coords.ts';
 import { PartsError, type Problem, refuseIfAny } from './errors.ts';
+import { edgeLength } from './length.ts';
 
 // ---------------------------------------------------------------------------
 // the normal form
@@ -633,16 +634,16 @@ function pairRow(l: NormalBone, r: NormalBone, left: Skeleton, right: Skeleton,
     return sides;
   };
   const originWhy = geometric(l.originWhy, r.originWhy);
-  const origin: Figure = originWhy !== null || l.origin === null || r.origin === null ? { skip: originWhy ?? '' } : { value: Math.hypot(carry(l.origin)[0] - r.origin[0], carry(l.origin)[1] - r.origin[1]) };
+  const origin: Figure = originWhy !== null || l.origin === null || r.origin === null ? { skip: originWhy ?? '' } : { value: edgeLength(carry(l.origin)[0] - r.origin[0], carry(l.origin)[1] - r.origin[1]) };
   const tipWhy = geometric(l.tipWhy, r.tipWhy);
   const lo = l.origin;
   const ro = r.origin;
   const lt = l.tip;
   const rt = r.tip;
   const both = lo !== null && ro !== null && lt !== null && rt !== null;
-  const tip: Figure = tipWhy !== null || !both ? { skip: tipWhy ?? '' } : { value: Math.hypot(carry(lt)[0] - rt[0], carry(lt)[1] - rt[1]) };
-  const ll = lo !== null && lt !== null ? Math.hypot(lt[0] - lo[0], lt[1] - lo[1]) : null;
-  const rl = ro !== null && rt !== null ? Math.hypot(rt[0] - ro[0], rt[1] - ro[1]) : null;
+  const tip: Figure = tipWhy !== null || !both ? { skip: tipWhy ?? '' } : { value: edgeLength(carry(lt)[0] - rt[0], carry(lt)[1] - rt[1]) };
+  const ll = lo !== null && lt !== null ? edgeLength(lt[0] - lo[0], lt[1] - lo[1]) : null;
+  const rl = ro !== null && rt !== null ? edgeLength(rt[0] - ro[0], rt[1] - ro[1]) : null;
   const difference: Figure = tipWhy !== null || ll === null || rl === null ? { skip: tipWhy ?? '' } : { value: rl - scale * ll };
   const dir: Figure = tipWhy !== null || !both ? { skip: tipWhy ?? '' } : { value: normaliseDegrees(direction(ro, rt) - direction(lo, lt)) };
   return { left: l.name, right: r.name, origin, parent: parentVerdict(l, r, left, right, fwd, inv), tip, length: { left: ll, right: rl, difference }, direction: dir };

package/src/turn.ts

@@ -0,0 +1,99 @@
+/**
+ * The turn control (issue #251): one bone nothing keys, and each part carried
+ * sideways a fraction of that bone's offset, the fraction ordered by the part's
+ * See-through depth — nearest furthest, the pivot depth staying put.
+ *
+ * 🧭 **The law is a turn's, not a chosen curve.** A figure turned by a small
+ * angle θ about a vertical axis standing at depth `pivot`, seen without
+ * perspective, moves each point sideways by `sin θ · (pivot − depth)` in depth
+ * units: linear in depth, zero at the pivot, opposite signs on either side of
+ * it. The depth unit's size in pixels is nothing See-through states, so the
+ * dial is normalised by the nearest part instead:
+ *
+ *     fraction(part) = (pivot − depth(part)) / (pivot − depth(nearest))
+ *
+ * The nearest part (the smallest `depth_median`, larger being further back)
+ * travels exactly the control's offset, the pivot depth 0, a part behind the
+ * pivot the other way. The dial's unit is therefore the nearest part's travel
+ * in rig px, and how far a consumer turns it is the consumer's.
+ *
+ * ⚖️ **The pivot `propose` drafts** ({@link turnPivot}) is the mean of the
+ * carried parts' depths weighted by their `opaque_px`: the one depth at which
+ * `Σ opaque_px · fraction = 0`, so the painted pixels' centroid does not slide
+ * under the dial — the figure turns about its own middle rather than drifting
+ * with it. It is a config field (`turn.pivot`), so a person corrects it there;
+ * the rig stage recomputes every fraction from it.
+ *
+ * Depths are See-through's per-layer `depth_median` only. Issue #250 measured
+ * that the depth maps do not carry relief inside a layer, so a part moves as
+ * one piece. Pure: no file, no clock.
+ */
+import { pyRound } from './round.ts';
+
+/** The control bone the rig stage adds under `root` when the config has `turn`: nothing keys it, and its local x is the dial. */
+export const TURN_BONE = 'turn';
+
+/** The places a pivot and a fraction are written to. */
+export const TURN_PLACES = 6;
+
+/** `config.turn`: the pivot depth and each carried part's See-through `depth_median`. */
+export interface TurnSpec {
+  pivot: number;
+  depths: Record<string, number>;
+}
+
+/** One carried part: its depth and the fraction of the control's offset it travels. */
+export interface TurnFraction {
+  part: string;
+  depth: number;
+  fraction: number;
+}
+
+/** The nearest part of a turn: the smallest depth, the first such part in `depths`' key order. */
+export function turnNearest(depths: Readonly<Record<string, number>>): { part: string; depth: number } | null {
+  let best: { part: string; depth: number } | null = null;
+  for (const [part, depth] of Object.entries(depths)) if (best === null || depth < best.depth) best = { part, depth };
+  return best;
+}
+
+/**
+ * `(pivot − depth) / (pivot − nearest)`, to {@link TURN_PLACES} places, with a
+ * negative zero written as 0. The caller holds `pivot > nearest` (the loader
+ * refuses anything else, `CONFIG_TURN_PIVOT_BEHIND_NEAREST`).
+ */
+export function turnFraction(pivot: number, nearest: number, depth: number): number {
+  const f = pyRound((pivot - depth) / (pivot - nearest), TURN_PLACES);
+  return f === 0 ? 0 : f;
+}
+
+/** Every carried part's fraction, in `order` (parts.json's draw order); a name in `order` the spec does not list is not carried. */
+export function turnFractions(spec: TurnSpec, order: readonly string[]): TurnFraction[] {
+  const nearest = turnNearest(spec.depths);
+  if (nearest === null) return [];
+  return order.filter((p) => Object.hasOwn(spec.depths, p)).map((part) => ({ part, depth: spec.depths[part], fraction: turnFraction(spec.pivot, nearest.depth, spec.depths[part]) }));
+}
+
+/**
+ * The pivot `propose` drafts: `Σ area · depth / Σ area` over the carried
+ * parts, to {@link TURN_PLACES} places — the depth at which the painted
+ * pixels' centroid does not move under the dial. Null with no area.
+ */
+export function turnPivot(rows: ReadonlyArray<{ depth: number; area: number }>): number | null {
+  let a = 0;
+  let ad = 0;
+  for (const r of rows) {
+    a += r.area;
+    ad += r.area * r.depth;
+  }
+  return a > 0 ? pyRound(ad / a, TURN_PLACES) : null;
+}
+
+/** The leaf bone that carries `part`'s share of `bone` under the turn: an identity child of `bone`, so it follows everything `bone` does. */
+export function turnTwin(part: string, bone: string): string {
+  return `${TURN_BONE}_${part}_${bone}`;
+}
+
+/** The transform constraint that carries `part`. */
+export function turnConstraintName(part: string): string {
+  return `${TURN_BONE}_${part}`;
+}