rig-parts 1.73.0 → 1.74.0

package/README.md

@@ -595,7 +595,10 @@ and [`CONFIG_TURN_SURFACE_REQUIRED`](docs/AUTHORING.md#CONFIG_TURN_SURFACE_REQUI
 fields in proportion to its skin weights. Inside the existing setup alpha
 overlap with a single-group neighbour, a blended attachment's vertex takes
 that neighbour's existing emitted triangle field at its setup position (#804), without changing skin weights,
-setup or idle. Conflicting neighbour groups are refused by name. Each sibling island takes only its
+setup or idle. A `motion.blink.still` unit neighbour supplies both emitted
+pieces, each on its own bone and resolved depth; transparent padding does not
+let either piece lend its field to the other's art (#807). Missing emitted
+split support is refused by name. Conflicting neighbour groups are refused by name. Each sibling island takes only its
 own group; parts without a blended attachment keep their existing role behavior
 and output bytes. Unlisted meshes do not consume turn depth sheets. See the
 [blended surface contract](docs/AUTHORING.md#per-layer-depth-sheets-773).

package/docs/AUTHORING.md

@@ -2854,6 +2854,36 @@ shin's tip against the stage point it stands on.
   with `exponent` 6 on `legwear`, 1.6. The same dance on `demo` as tracked, whose legs ride the
   hip, reads 18.36.
 
+
+### Equal-depth units in a sampled turn
+
+With `turn.roles`, `turn.depths` remains a legacy layer-order table; it does
+not override sampled unit motion. Its See-through values (larger means farther
+back) are not interchangeable with `turn.unitDepths`, whose values are calibrated
+scalar depths in rig pixels (larger means nearer the viewer).
+
+To make a mirrored pair of `"unit"` parts travel equally, author equal
+`turn.unitDepths.<part>` values. A part entry wins over a bone entry, including
+zero. Otherwise the producer samples the primary surface at each unit's setup
+landmark, calibrating `pivot + sampledZ - surfaceZRef`; mirrored landmarks on an
+asymmetric depth sheet can therefore travel differently. Only when that sample
+is unavailable does it fall back to the unit's own sheet. No symmetry is inferred
+from part names or positions, and equal legacy `depths` do not establish it.
+
+Equal unit depths yield the same signed translation within a frame on both yaw
+and pitch; the sign reverses between negative and positive angles. Their local
+keys compensate for the parent carrier, so compare the complete inherited pose
+when measuring screen travel. For ears, the existing behind-cheek depth check
+still applies to an explicit override; use a depth at or behind both cheeks.
+
+The build report prints `WARN RIG_TURN_UNIT_DEPTH_SUPPORT` when an implicit unit
+sample lies outside the surface's source pixel-index bounds or its sampled art
+alpha is below 255. It names the unit, source surface and sheet, raw crop
+coordinate, clamped art index and support alpha. Scalar-sheet alpha is not art
+support. This warning retains the extended scalar sample, all motion arithmetic
+and existing refusal behavior; it is not a gate. Explicit `unitDepths` entries
+bypass that sample and its warning, including an explicit zero.
+
 ## 4. The command order
 
 Two steps are external: the See-through runs (by any route; the optional `comfy seethrough` adapter is only a client for a ComfyUI box). Everything else is this tool.
@@ -4528,6 +4558,7 @@ and stay absent).
 | <a id="RIG_TURN_HEAD_BONE"></a>`RIG_TURN_HEAD_BONE` | `buildRig` found no `"head"` (or body turn root) bone when emitting 2.5D turn carriers | declare `"head"` (or the body turn root bone) in `config.bones` |
 | <a id="RIG_TURN_SHARED_DEPTH_SCALE"></a>`RIG_TURN_SHARED_DEPTH_SCALE` | `"surface"` parts bound to one head or body turn declare different `near` polarities or `zScale` values | use one shared `near` and `zScale` across all `"surface"` parts in the turn group |
 | <a id="RIG_TURN_UNIT_DEPTH_REQUIRED"></a>`RIG_TURN_UNIT_DEPTH_REQUIRED` | a `"unit"` bone has neither a `unitDepths` entry nor a readable `"surface"` depth sheet | provide a `"surface"` depth sheet or an explicit `unitDepths.<part>` value |
+| <a id="RIG_TURN_UNIT_DEPTH_SUPPORT"></a>`RIG_TURN_UNIT_DEPTH_SUPPORT` | WARN only: an implicit unit depth sample is outside the source surface pixel-index bounds or its sampled art alpha is below 255 | author an explicit calibrated `unitDepths.<part>` value when this cross-part extrapolation is unintended; existing scalar sampling and refusal behavior are retained |
 | <a id="RIG_TURN_EAR_DEPTH_BEHIND_CHEEK"></a>`RIG_TURN_EAR_DEPTH_BEHIND_CHEEK` | an ear bone in `config.turn.roles` has a calibrated depth at or in front of the cheek surface depth | place the ear behind the cheek surface (for example via `config.turn.unitDepths`) |
 
 ## 7. The bars `check` enforces, and what only an eye answers today
@@ -5644,7 +5675,16 @@ Two same-group fields with incompatible emitted offsets raise
 [`RIG_TURN_SURFACE_OVERLAP_DEPTH`](#RIG_TURN_SURFACE_OVERLAP_DEPTH).
 
 Unit/rear neighbours contribute their actual emitted rigid carrier motion,
-including its resolved unit depth or rear counter field. Their own sheet is
+including its resolved unit depth or rear counter field. A unit region split by
+`motion.blink.still` supplies both emitted drawings: the lower slot and
+`<part>_still`, each with its own bone and resolved unit depth (#807). Support
+uses the shown region's image size, offsets and rotation, with transparent
+padding excluded from each piece's crop rectangle. The original source-alpha
+condition still applies; the lower piece cannot lend its depth to upper art
+through its transparent padding. A missing split slot, shown attachment,
+image or setup frame raises
+[`RIG_TURN_SURFACE_OVERLAP_SUPPORT`](#RIG_TURN_SURFACE_OVERLAP_SUPPORT);
+a slot explicitly showing nothing supplies no attachment. Their own sheet is
 not resampled to invent a spatial bend or a new refusal. Generated surface
 grids keep their Core generator: Core's grid builder and transform evaluator
 provide inspection metadata for the same existing topology and vertex field.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rig-parts",
-  "version": "1.73.0",
+  "version": "1.74.0",
   "description": "AI-authored 2D character parts from one anime painting and its See-through layer decomposition: measured parts, weighted-mesh rig specs, verified through rig-c before anything is written. A CLI for agents that cannot see the image.",
   "type": "module",
   "bin": {

package/src/build.ts

@@ -1528,6 +1528,7 @@ export function rigStage(input: RigStageInput, rigc: RigcRunner, scratch: string
   if (from !== null) log(`  animations beside the idle, from ${from.file} as written: ${Object.keys(from.table).join(', ') || 'none'}`);
   log(faceAxisLine(rig.faceAxis));
   if (rig.turn !== null) log(turnLine(rig.turn));
+  for (const w of rig.turnWarnings ?? []) log(`  WARN  ${w.code}: ${w.object} — ${w.detail}`);
   log(
     rig.idleKeys === 'ctl'
       ? `  idle keys ctl: ${rig.meshKeyed.length} mesh-driving bone(s) keyed by the idle, each keyed through a same-origin <bone>_ctl parent`

package/src/rig.ts

@@ -138,6 +138,7 @@ import { explicitAttachment, type ExplicitMeshReport } from './explicitmesh.ts';
  * order the objects are built in, and every number is rounded by `pyRound`).
  */
 import { type AutoSpec, type BoneEntry, type InfluenceMeshSpec, type WeightRule, type CharacterConfig, type ConfigConstraint, type ConfigStop, CONSTRAINT_FOLLOWS, constraintForRig, contourRegionsOf, type ContourSpec, DEFAULT_BUST_BONE_L, DEFAULT_BUST_BONE_R, type Point, type RibsSpec, ROOT_BONE, stopForRig, turnRidersByBone, weightsABone } from './config.ts';
+import { RUNTIME_PI } from 'rig-c/src/core/world.ts';
 import { type BoneTransform, computeExactFrameTransforms, computeWorldTransforms, cropToSpineY, normaliseDegrees, paintingToSetupPoint, setupToPaintingPoint, toBoneLocal, toWorld } from './coords.ts';
 import { type Problem, refuseIfAny, PartsError } from './errors.ts';
 import { recordedFocusProblems } from './setfocus.ts';
@@ -1131,6 +1132,8 @@ export interface AttachmentSetsFile {
 }
 
 export interface RigOutput {
+  /** Sample-support warnings for the build report only; no emitted-file field. */
+  turnWarnings?: Problem[];
   depthReferences?: Array<{ part: string; size: [number, number]; depth: PartDepthReference }>;
   rig: RigSpec;
   /** Internal explicit-layout provenance; serialized only as an external companion. */
@@ -3652,8 +3655,10 @@ export function buildWaistPairSource(
   for (const [bName, bEntry] of B) {
     boneLandmarks.set(bName, [bEntry.x, bEntry.y]);
   }
+  const turnWarnings: Problem[] = [];
   if (cfg.turn?.roles !== undefined || cfg.turn?.body !== undefined) {
     buildDepth25DTurn(rig, motion, {
+      warnings: turnWarnings,
       turn: cfg.turn,
       parts: parts.parts,
       images,
@@ -3662,7 +3667,7 @@ export function buildWaistPairSource(
       boneLandmarks,
       hasAlternateFaceSet,
       surfaceMeshes: turnSurfaceMeshes(cfg, rig, parts.rig_size),
-      neighbourMeshes: turnNeighbourMeshes(cfg, rig, parts),
+      neighbourMeshes: turnNeighbourMeshes(cfg, rig, parts, new Map(outImages)),
     });
   }
   bindFaceSurfaceDeform(motion, (merged) => {
@@ -3679,7 +3684,7 @@ export function buildWaistPairSource(
         boneLandmarks,
         hasAlternateFaceSet,
         surfaceMeshes: turnSurfaceMeshes(cfg, rig, parts.rig_size),
-        neighbourMeshes: turnNeighbourMeshes(cfg, rig, parts),
+        neighbourMeshes: turnNeighbourMeshes(cfg, rig, parts, new Map(outImages)),
       });
     }
     if (cfg.turn?.roles === undefined && (cfg.turn === undefined || cfg.turn.body === undefined || cfg.turn.depths !== undefined)) {
@@ -3716,6 +3721,7 @@ export function buildWaistPairSource(
     autoMotion,
     faceAxis,
     turn: turned?.rows ?? null,
+    ...(turnWarnings.length === 0 ? {} : { turnWarnings }),
     ...(sets === undefined ? {} : { sets }),
     ...(explicitLayout.plan === undefined ? {} : { layout: explicitLayout.plan }),
   };
@@ -4200,7 +4206,7 @@ function turnSurfaceMeshes(cfg: CharacterConfig, rig: RigSpec, canvas: readonly
 }
 
 /** Actual shown support; Core's own grid topology is inspection metadata only. */
-function turnNeighbourMeshes(cfg: CharacterConfig, rig: RigSpec, parts: PartsFile) {
+export function turnNeighbourMeshes(cfg: CharacterConfig, rig: RigSpec, parts: PartsFile, emittedImages: ReadonlyMap<string, Raster>) {
   const meshes: NonNullable<Parameters<typeof buildDepth25DTurn>[2]['neighbourMeshes']>[number][] = [];
   const canvas = parts.rig_size;
   const aliases = new Map<string, string>((rig.stops ?? []).flatMap(s => s.links.map(link => [`${link}_d`, link])));
@@ -4209,8 +4215,17 @@ function turnNeighbourMeshes(cfg: CharacterConfig, rig: RigSpec, parts: PartsFil
     if (cfg.meshes[part] !== undefined && [cfg.turn?.roles?.[part], cfg.turn?.body?.roles?.[part]].includes('surface')) continue;
     const record = parts.parts.find(p => p.name === part);
     if (record === undefined) continue;
+    const split = cfg.regions[part] !== undefined && cfg.motion.blink?.still?.[part] !== undefined
+      && [cfg.turn?.roles?.[part], cfg.turn?.body?.roles?.[part]].includes('unit');
+    const splitSlots = [part, `${part}${STILL_SUFFIX}`];
+    const failSupport = (name: string, detail: string): never => { throw new PartsError([{ code: 'RIG_TURN_SURFACE_OVERLAP_SUPPORT', object: `turn neighbour "${name}"`, detail }]); };
+    if (split) for (const name of splitSlots) {
+      const shown = rig.slots.find(slot => slot.name === name);
+      if (shown === undefined) failSupport(name, 'has no emitted split slot; supply both lower and still slots from the region build');
+      else if (shown.attachment !== null && rig.skins.default[name]?.[shown.attachment] === undefined) failSupport(`${name}/${shown.attachment}`, 'has no shown attachment in the default skin; supply the emitted split drawing');
+    }
     for (const slot of rig.slots) {
-      if (slot.name !== part && !slot.name.startsWith(`${part}__island`)) continue;
+      if (slot.name !== part && !slot.name.startsWith(`${part}__island`) && !(split && slot.name === splitSlots[1])) continue;
       for (const [attachment, att] of Object.entries(rig.skins.default[slot.name] ?? {})) {
         if (attachment !== slot.attachment) continue;
         if ('type' in att && att.weights !== undefined && att.weights.length > 0) { meshes.push({ part, slot: slot.name, attachment, weights: att.weights, triangles: att.triangles, canvas }); continue; }
@@ -4227,6 +4242,22 @@ function turnNeighbourMeshes(cfg: CharacterConfig, rig: RigSpec, parts: PartsFil
             weights: bound.bindings.map(row => row.map(w => ({ bone: w.bone, x: f32(w.x), y: f32(w.y), weight: f32(w.weight) }))),
             gridSamples: geometry.points.map(([x, y]) => setupToPaintingPoint(place(x, y), canvas, canvas)),
           });
+        } else if (!('type' in att) && split) {
+          const image = emittedImages.get(att.image) ?? failSupport(`${slot.name}/${attachment}`, `has no emitted image "${att.image}"; supply the split region PNG to measure its support`);
+          if (!Number.isFinite(att.x) || !Number.isFinite(att.y) || (att.rotation !== undefined && !Number.isFinite(att.rotation))
+            || !Number.isSafeInteger(image.width) || !Number.isSafeInteger(image.height) || image.width <= 2 * PAD || image.height <= 2 * PAD) failSupport(`${slot.name}/${attachment}`, `has offsets (${att.x}, ${att.y}), rotation ${att.rotation ?? 0} and image ${image.width}x${image.height}; require finite offsets/rotation and positive integer source dimensions after padding ${PAD} on each side`);
+          // Core stores the region offsets/angle as float32. Its region
+          // rotation uses RUNTIME_PI, not the bone matrix's y-column angle.
+          const angle = f32(att.rotation ?? 0) * RUNTIME_PI / 180, cos = Math.cos(angle), sin = Math.sin(angle);
+          const x = f32(att.x), y = f32(att.y), halfWidth = image.width / 2 - PAD, halfHeight = image.height / 2 - PAD;
+          // Transparent PAD belongs to neither piece's alpha support. Keeping
+          // both padded rectangles would let the lower lend its field to the
+          // upper rows (and vice versa) beside the cut. Source alpha still
+          // decides ownership inside each piece's own emitted crop rectangle.
+          const corners = [[-halfWidth, -halfHeight], [-halfWidth, halfHeight], [halfWidth, halfHeight], [halfWidth, -halfHeight]];
+          meshes.push({ part, slot: slot.name, attachment, canvas, triangles: [0, 1, 2, 0, 2, 3],
+            weights: corners.map(([px, py]) => [{ bone: slot.bone, x: px * cos + x - py * sin, y: py * cos + y + px * sin, weight: 1 }]),
+          });
         } else if (!('type' in att)) {
           const points = [[record.x - PAD, record.y - PAD], [record.x - PAD, record.y + record.h + PAD], [record.x + record.w + PAD, record.y + record.h + PAD], [record.x + record.w + PAD, record.y - PAD]];
           meshes.push({ part, slot: slot.name, attachment, canvas, triangles: [0, 1, 2, 0, 2, 3], weights: points.map(p => { const q = paintingToSetupPoint(p, canvas, canvas), local = toBoneLocal(frame, q[0], q[1]); return [{ bone: slot.bone, x: f32(local[0]), y: f32(local[1]), weight: 1 }]; }) });

package/src/turn.ts

@@ -1478,6 +1478,8 @@ export function sampleUnitPartDepth(scalar: Raster, art: Raster, ref: PartDepthR
 }
 
 export interface Depth25DTurnOptions {
+  /** Report-only diagnostics; never serialized into the rig or motion. */
+  warnings?: Problem[];
   turn: TurnSpec;
   parts: ReadonlyArray<{ name: string; x: number; y: number; w: number; h: number; depth?: PartDepthReference }>;
   images: ReadonlyMap<string, Raster>;
@@ -1684,6 +1686,23 @@ function buildDepth25DTurnGroup(
           const padY = Math.floor((ext.height - rec.h) / 2);
           const lx = Math.max(0, Math.min(ext.width - 1, Math.round(pt[0] - rec.x + padX)));
           const ly = Math.max(0, Math.min(ext.height - 1, Math.round(pt[1] - rec.y + padY)));
+          // The scalar extension has opaque alpha even where the source art
+          // supplies no opaque support. Report that extrapolation, not its value.
+          if (opts.warnings !== undefined) {
+            const art = opts.images.get(rec.name);
+            const rawX = pt[0] - rec.x, rawY = pt[1] - rec.y;
+            const outside = rawX < 0 || rawY < 0 || rawX > rec.w - 1 || rawY > rec.h - 1;
+            const artX = Math.max(0, Math.min(rec.w - 1, lx - padX));
+            const artY = Math.max(0, Math.min(rec.h - 1, ly - padY));
+            const alpha = art?.data[(artY * rec.w + artX) * 4 + 3];
+            if (alpha !== undefined && (outside || alpha !== 255)) {
+              opts.warnings.push({
+                code: 'RIG_TURN_UNIT_DEPTH_SUPPORT',
+                object: `${group.fieldPrefix}.roles.${part}`,
+                detail: `unit part "${part}" (bone "${bName}") samples surface "${rec.name}" sheet "${rec.depth.image}" at raw crop [${pt[0]}, ${pt[1]}] (${outside ? 'outside' : 'inside'} source sample bounds [${rec.x}, ${rec.y}]..[${rec.x + rec.w - 1}, ${rec.y + rec.h - 1}]); sampled art [${artX}, ${artY}] has art alpha ${alpha}, expected 255 without clamping; the existing extended scalar sample is retained; author ${group.fieldPrefix}.unitDepths.${part} for an explicit calibrated depth`,
+              });
+            }
+          }
           const zUnit = levelToDepthZ(ext.data[(ly * ext.width + lx) * 4], rec.depth);
           resolved = pyRound(pivot + (zUnit - zRef), 4);
         }