@ikijs/editor 0.7.0 → 0.8.1

package/README.md

@@ -123,7 +123,12 @@ decodes with canvas, `@ikijs/mcp` decodes with `sharp`, and both feed the same
 pure function — including the optional `rowHalfWidths` (one entry per crop row,
 half that row's opaque span in canvas px), which `@ikijs/mcp` measures for the
 face so the plate turns on a radius that varies by row; absent, it turns on one
-constant radius.
+constant radius. It also takes the optional `denseCore`, the tight box of a
+layer's alpha ≥ 128 pixels in image coords, not grown, which `@ikijs/mcp`
+measures for the nose: its centre and width are the nose's turn landmark, so a
+shaded nose is fitted by its drawing rather than its soft feather, and its top
+edge at its centre x is the bridge top the nose tilts 6° about on the turn, its
+tip toward the far side; absent, the crop stands in for both.
 
 `*_L` / `*_R` are the **character's** sides — `eye_L` is the character's left
 eye, which appears on the viewer's right.

package/dist/index.d.mts

@@ -888,6 +888,24 @@ interface LayerInput {
      * [0, cropW / 2], the most an inclusive span inside the crop can be.
      */
     rowHalfWidths?: number[];
+    /**
+     * The tight box of the layer's alpha ≥ 128 pixels, in image coords like
+     * `bbox` and NOT grown: the drawing a viewer reads inside a soft feather,
+     * which the crop's alpha ≥ 8 rule takes in whole. Optional, and only the
+     * NOSE's is read: its centre and width are the nose's turn landmark
+     * (`turnLandmarks`), so a shaded nose is fitted by the drawing rather than
+     * by its feather, and its top edge at its centre x is the bridge top the
+     * nose tilts about on the turn (`NOSE_TURN_TILT_DEG`). Absent — as the
+     * editor's own import leaves it — the crop stands in for both. Validated
+     * before anything reads it: a plain object whose x, y, w and h are finite,
+     * w and h positive, and the box inside `bbox`.
+     */
+    denseCore?: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
 }
 /**
  * Map an array of raw filenames to canonical `{ role, fileName }` pairs.
@@ -949,12 +967,18 @@ interface IrisStrand {
  *
  * What happens when the layer set cannot reach a target depends on where the
  * target came from. A number the CALLER passed is a measurement, so an
- * unreachable one throws, naming the field and what was on offer. A number this
- * module filled in — a default, or a nose/mouth derived from the eyes — is a
- * style prior, not a promise about this character: it is CLAMPED to what the
- * layer set can do and the rig is built. The alternative is a generator that
- * refuses its own defaults, which would leave a perfectly good layer set with
- * no model at all. `solveTurnModel` reports which fields it clamped.
+ * unreachable one throws, naming the field and what was on offer — except a
+ * `silhouetteRatio` when no ratio in its own [0.5, 1.5] range renders on this
+ * layer set: that throw names the field and the whole range instead of an
+ * offer, since there is none narrower. Leaving the field out still rigs,
+ * because a defaulted one clamps.
+ *
+ * A number this module filled in — a default, or a nose/mouth derived from the
+ * eyes — is a style prior, not a promise about this character: it is CLAMPED
+ * to what the layer set can do and the rig is built. The alternative is a
+ * generator that refuses its own defaults, which would leave a perfectly good
+ * layer set with no model at all. `solveTurnModel` reports which fields it
+ * clamped.
  *
  * One measurement is clamped too: an `eyeShift` past the room the art leaves
  * the far eye — the face plate's edge, and the bangs' side strand when

package/dist/index.d.ts

@@ -888,6 +888,24 @@ interface LayerInput {
      * [0, cropW / 2], the most an inclusive span inside the crop can be.
      */
     rowHalfWidths?: number[];
+    /**
+     * The tight box of the layer's alpha ≥ 128 pixels, in image coords like
+     * `bbox` and NOT grown: the drawing a viewer reads inside a soft feather,
+     * which the crop's alpha ≥ 8 rule takes in whole. Optional, and only the
+     * NOSE's is read: its centre and width are the nose's turn landmark
+     * (`turnLandmarks`), so a shaded nose is fitted by the drawing rather than
+     * by its feather, and its top edge at its centre x is the bridge top the
+     * nose tilts about on the turn (`NOSE_TURN_TILT_DEG`). Absent — as the
+     * editor's own import leaves it — the crop stands in for both. Validated
+     * before anything reads it: a plain object whose x, y, w and h are finite,
+     * w and h positive, and the box inside `bbox`.
+     */
+    denseCore?: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
 }
 /**
  * Map an array of raw filenames to canonical `{ role, fileName }` pairs.
@@ -949,12 +967,18 @@ interface IrisStrand {
  *
  * What happens when the layer set cannot reach a target depends on where the
  * target came from. A number the CALLER passed is a measurement, so an
- * unreachable one throws, naming the field and what was on offer. A number this
- * module filled in — a default, or a nose/mouth derived from the eyes — is a
- * style prior, not a promise about this character: it is CLAMPED to what the
- * layer set can do and the rig is built. The alternative is a generator that
- * refuses its own defaults, which would leave a perfectly good layer set with
- * no model at all. `solveTurnModel` reports which fields it clamped.
+ * unreachable one throws, naming the field and what was on offer — except a
+ * `silhouetteRatio` when no ratio in its own [0.5, 1.5] range renders on this
+ * layer set: that throw names the field and the whole range instead of an
+ * offer, since there is none narrower. Leaving the field out still rigs,
+ * because a defaulted one clamps.
+ *
+ * A number this module filled in — a default, or a nose/mouth derived from the
+ * eyes — is a style prior, not a promise about this character: it is CLAMPED
+ * to what the layer set can do and the rig is built. The alternative is a
+ * generator that refuses its own defaults, which would leave a perfectly good
+ * layer set with no model at all. `solveTurnModel` reports which fields it
+ * clamped.
  *
  * One measurement is clamped too: an `eyeShift` past the room the art leaves
  * the far eye — the face plate's edge, and the bangs' side strand when

package/dist/index.js

@@ -1837,6 +1837,45 @@ function validateLayerInputs(layers, canvas) {
         }
       }
     }
+    if (layer.denseCore !== void 0) {
+      const where = `auto-rig: validateLayerInputs: role "${role}" denseCore`;
+      const core = layer.denseCore;
+      if (typeof core !== "object" || core === null || Array.isArray(core)) {
+        throw new Error(`${where} must be a plain object { x, y, w, h }`);
+      }
+      for (const field of ["x", "y", "w", "h"]) {
+        const v = core[field];
+        const size = field === "w" || field === "h";
+        if (typeof v !== "number" || !Number.isFinite(v) || size && v <= 0) {
+          throw new Error(
+            `${where}.${field} is ${String(v)}, not a finite number${size ? " > 0" : ""}`
+          );
+        }
+      }
+      const { x, y, w, h } = layer.denseCore;
+      const right = bbox.x + bbox.w;
+      const bottom = bbox.y + bbox.h;
+      if (x < bbox.x) {
+        throw new Error(
+          `${where}.x (${x}) lies left of the bbox's left edge (${bbox.x})`
+        );
+      }
+      if (y < bbox.y) {
+        throw new Error(
+          `${where}.y (${y}) lies above the bbox's top edge (${bbox.y})`
+        );
+      }
+      if (x + w > right) {
+        throw new Error(
+          `${where}.w (${w}) puts its right edge at ${x + w}, past the bbox's right edge (${right})`
+        );
+      }
+      if (y + h > bottom) {
+        throw new Error(
+          `${where}.h (${h}) puts its bottom edge at ${y + h}, past the bbox's bottom edge (${bottom})`
+        );
+      }
+    }
   }
 }
 function validateStrandEdges(layers, strandEdges) {
@@ -2013,6 +2052,7 @@ function meshCellsFor(w, h) {
 }
 var FACE_PLATE_CELLS = 10;
 var FEATURE_GRID_CELLS = 4;
+var MOUTH_GRID_CELL_PX = 32;
 var TURN_LATTICE_CELL_PX = 16;
 var GRID_MARGIN = 0.12;
 var HEAD_CYLINDER_RADIUS_FACTOR = 0.6 / 0.5;
@@ -2163,31 +2203,33 @@ function turnColumnMap(grid, faceCenterX, radiusX, angleX, travel) {
       x + boundedCylinderBend(x - faceCenterX, radiusX, theta) + slide
     );
   }
-  const cellFor = (v, edges) => {
+  const cellFor = (x) => {
     let lo = 0;
     let hi = grid.cols - 1;
     while (lo < hi) {
       const mid = lo + hi >> 1;
-      if (v < edges[mid + 1]) hi = mid;
+      if (x < restX[mid + 1]) hi = mid;
       else lo = mid + 1;
     }
     return lo;
   };
-  const sample = (edges, values, v) => {
-    const c = cellFor(v, edges);
-    const s = Math.max(
-      0,
-      Math.min(1, (v - edges[c]) / (edges[c + 1] - edges[c]))
-    );
-    if (s === 0) return values[c];
-    if (s === 1) return values[c + 1];
-    return values[c] + (values[c + 1] - values[c]) * s;
-  };
   return {
     restX,
     warpedX,
-    mapX: (x) => sample(restX, warpedX, x),
-    invertX: (X) => sample(warpedX, restX, X)
+    // Piecewise-linear read of `warpedX` over `restX`, the within-cell
+    // fraction clamped to [0,1] as sampleWarpGrid clamps (s, t). A node reads
+    // its own warped x: `warpedX[c] + Δ·1` is `warpedX[c + 1]` only to an
+    // ulp, and the columns a bake reads are nodes.
+    mapX: (x) => {
+      const c = cellFor(x);
+      const s = Math.max(
+        0,
+        Math.min(1, (x - restX[c]) / (restX[c + 1] - restX[c]))
+      );
+      if (s === 0) return warpedX[c];
+      if (s === 1) return warpedX[c + 1];
+      return warpedX[c] + (warpedX[c + 1] - warpedX[c]) * s;
+    }
   };
 }
 function renderedLandingX(part, vertexLanding, px, py) {
@@ -2293,7 +2335,7 @@ function plateLandingOn(plate, mapAt) {
     y
   );
 }
-function plateGuardRowsFor(face, hairFront) {
+function plateGuardRowsFor(face, hairFront, widestY = -Infinity) {
   const rowsOf = (part, y) => {
     const { rows } = meshCellsFor(part.cropW, part.cropH);
     return Array.from(
@@ -2308,7 +2350,7 @@ function plateGuardRowsFor(face, hairFront) {
   return [
     ...faceRows,
     ...rowsOf(hairFront, hairFront.centerY).map(
-      (y) => Math.max(bottom, Math.min(top, y))
+      (y) => Math.max(bottom, Math.min(top, Math.max(y, widestY)))
     )
   ];
 }
@@ -2320,7 +2362,7 @@ function plateGuardsOf(carriers, faceHalfWidth, profile, hairFront) {
   return {
     plate,
     edgeAt: profile === void 0 ? () => faceHalfWidth : profile.at,
-    plateGuardRows: plateGuardRowsFor(plate.part, hairFront)
+    plateGuardRows: plateGuardRowsFor(plate.part, hairFront, profile?.widestY)
   };
 }
 var TurnTargetError = class extends Error {
@@ -2391,12 +2433,17 @@ function resolveTurnTargets(targets = {}) {
     defaulted
   };
 }
+function noseDrawnBox(layer) {
+  return layer.denseCore ?? layer.bbox;
+}
 function turnLandmarks(layers, carriers) {
   const markOf = (role) => {
     const layer = layers.find((l) => l.role === role);
     if (!layer) return void 0;
-    const t = bboxToTransform(layer.bbox, layer.canvasW, layer.canvasH, role);
-    const mark = { x: t.x, y: t.y, w: layer.cropW };
+    const drawn = role === "nose" ? noseDrawnBox(layer) : layer.bbox;
+    const t = bboxToTransform(drawn, layer.canvasW, layer.canvasH, role);
+    const w = drawn === layer.bbox ? layer.cropW : drawn.w;
+    const mark = { x: t.x, y: t.y, w };
     const carrier = carriers?.get(role);
     if (carrier !== void 0) mark.carrier = carrier;
     return mark;
@@ -2493,14 +2540,15 @@ var TURN_SWEEP_SAMPLES = 32;
 var HOLD_CLEARANCE = 1;
 var TURN_HOLD_SAMPLES = 16;
 var TURN_SETTLE_PASSES = 24;
-function hairFrontHoldTarget(x, y, deg, faceCenterX, plateLandingAt, edgeAt, holdBase, holdEdge) {
+function hairFrontHoldTarget(x, y, deg, faceCenterX, plateLandingAt, edgeAt, holdBase, holdEdge, widestY = -Infinity) {
   const local = x - faceCenterX;
   const dist = Math.abs(local);
   const side = Math.sign(local);
-  const painted = edgeAt(y);
-  if (dist <= painted) return plateLandingAt(deg, x, y);
+  const row = Math.max(y, widestY);
+  const painted = edgeAt(row);
+  if (dist <= painted) return plateLandingAt(deg, x, row);
   if (dist <= holdBase) {
-    const inner = plateLandingAt(deg, faceCenterX + side * painted, y);
+    const inner = plateLandingAt(deg, faceCenterX + side * painted, row);
     const u = (dist - painted) / (holdBase - painted);
     return inner + (faceCenterX + side * holdEdge - inner) * u;
   }
@@ -2605,7 +2653,8 @@ function evaluateTurnCandidate(ctx, radius) {
       plateLandingAt,
       ctx.edgeAt,
       hold.holdBase,
-      hold.holdEdgeAt(deg)
+      hold.holdEdgeAt(deg),
+      ctx.profile?.widestY
     ),
     leadShift
   );
@@ -3347,6 +3396,7 @@ function solveTurnModel(targets, landmarks, lattice, faceCenterX, faceHalfWidth,
 var EYE_STACK_PREFIXES = ["eye_", "iris_", "pupil_", "highlight_"];
 var HAIR_FRONT_DEPTH = 0.1;
 var MOUTH_TURN_TILT_DEG = 5;
+var NOSE_TURN_TILT_DEG = 6;
 var NOD_TRAVEL = 30;
 var NOD_BEND = 0.5;
 var HAIR_BACK_NOD_DEPTH = -0.135;
@@ -3579,7 +3629,7 @@ function plateReachAt(plateLandingAt, faceCenterX, edgeAt, plateGuardRows, deg)
     )
   );
 }
-function bakeHairFrontSilhouetteWarp(mesh, partX, partY, faceCenterX, plateLandingAt, edgeAt, holdBase, holdEdgeAt, plateGuardRows) {
+function bakeHairFrontSilhouetteWarp(mesh, partX, partY, faceCenterX, plateLandingAt, edgeAt, holdBase, holdEdgeAt, plateGuardRows, widestY = -Infinity) {
   if (holdEdgeAt(0) !== holdBase) {
     throw new Error(
       `auto-rig: bakeHairFrontSilhouetteWarp: holdEdgeAt(0) is ${holdEdgeAt(0)}, not the hold edge's own rest distance ${holdBase}, so the bangs would move in the rest pose`
@@ -3617,7 +3667,8 @@ function bakeHairFrontSilhouetteWarp(mesh, partX, partY, faceCenterX, plateLandi
           plateLandingAt,
           edgeAt,
           holdBase,
-          holdEdge
+          holdEdge,
+          widestY
         ) - x,
         0
       );
@@ -3796,7 +3847,7 @@ function defaultPoseOf(bindings) {
     return binding.from + (binding.to - binding.from) * t;
   });
 }
-function groupGridFor(members, cells, turnShiftPx, nodShiftPx) {
+function groupGridFor(members, cells, turnShiftPx, nodShiftPx, cellPx) {
   let minX = Infinity;
   let maxX = -Infinity;
   let minY = Infinity;
@@ -3831,24 +3882,50 @@ function groupGridFor(members, cells, turnShiftPx, nodShiftPx) {
       }
     }
   }
+  const extentMinX = minX;
+  const extentMaxX = maxX;
   minX -= turnShiftPx;
   maxX += turnShiftPx;
   minY -= nodShiftPx;
   maxY += nodShiftPx;
   const marginX = (maxX - minX) * GRID_MARGIN + 1;
   const marginY = (maxY - minY) * GRID_MARGIN + 1;
-  return {
-    cols: cells,
-    rows: cells,
-    points: generateGridPoints(
-      cells,
-      cells,
-      minX - marginX,
-      maxX + marginX,
-      minY - marginY,
-      maxY + marginY
-    )
-  };
+  const points = generateGridPoints(
+    cells,
+    cells,
+    minX - marginX,
+    maxX + marginX,
+    minY - marginY,
+    maxY + marginY
+  );
+  if (cellPx === void 0) return { cols: cells, rows: cells, points };
+  const stride = cells + 1;
+  const uniformXs = Array.from({ length: stride }, (_, c) => points[c * 2]);
+  const ys = Array.from(
+    { length: stride },
+    (_, r) => points[r * stride * 2 + 1]
+  );
+  const xs = [uniformXs[0]];
+  for (let c = 0; c < cells; c++) {
+    const left = uniformXs[c];
+    const right = uniformXs[c + 1];
+    const from = Math.max(left, extentMinX);
+    const to = Math.min(right, extentMaxX);
+    if (right - left > cellPx && from < to) {
+      const steps = Math.ceil((to - from) / cellPx);
+      if (from > left) xs.push(from);
+      for (let k = 1; k < steps; k++) {
+        xs.push(from + k * (to - from) / steps);
+      }
+      if (to < right) xs.push(to);
+    }
+    xs.push(right);
+  }
+  const merged = [];
+  for (const y of ys) {
+    for (const x of xs) merged.push(x, y);
+  }
+  return { cols: xs.length - 1, rows: cells, points: merged };
 }
 function eyelidFoldFor(layers, layer, mesh, t) {
   const side = ROLE_TABLE[layer.role].eyeSide;
@@ -3949,7 +4026,8 @@ function turnSetup(layers) {
         own,
         isPlate ? FACE_PLATE_CELLS : FEATURE_GRID_CELLS,
         isPlate ? 0 : turnShift[turnFamily(role)],
-        nodShiftPx
+        nodShiftPx,
+        group === "mouthWarp" ? MOUTH_GRID_CELL_PX : void 0
       )
     );
   }
@@ -3959,11 +4037,31 @@ function turnSetup(layers) {
     y: mouthAt.y,
     tiltDeg: MOUTH_TURN_TILT_DEG
   };
+  const noseLayer = layers.find((l) => l.role === "nose");
+  let noseAnchor;
+  if (noseLayer) {
+    const drawn = noseDrawnBox(noseLayer);
+    const at = bboxToTransform(
+      drawn,
+      noseLayer.canvasW,
+      noseLayer.canvasH,
+      "nose"
+    );
+    noseAnchor = {
+      x: at.x,
+      y: at.y + drawn.h / 2,
+      tiltDeg: NOSE_TURN_TILT_DEG
+    };
+  }
   const carriers = new Map(
-    members.map((m) => [
-      m.role,
-      m.group === "mouthWarp" ? { grid: groupGrids.get(m.group), part: m.part, anchor: mouthAnchor } : { grid: groupGrids.get(m.group), part: m.part }
-    ])
+    members.map((m) => {
+      const grid = groupGrids.get(m.group);
+      const anchor = m.group === "mouthWarp" ? mouthAnchor : m.group === "noseWarp" ? noseAnchor : void 0;
+      return [
+        m.role,
+        anchor === void 0 ? { grid, part: m.part } : { grid, part: m.part, anchor }
+      ];
+    })
   );
   const maxShift = Math.max(turnShift.eye, turnShift.nose, turnShift.mouth);
   let reach = 0;
@@ -4269,7 +4367,8 @@ function generateIkiFromLayerSet(layers, canvas, options = {}) {
               edgeAt,
               holdBase,
               turn?.holdEdgeAt ?? (() => holdBase),
-              plateGuardRows
+              plateGuardRows,
+              profile?.widestY
             )
           );
           ownWarps.push(