rig-parts 1.73.1 → 1.74.0

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rig-parts",
-  "version": "1.73.1",
+  "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

@@ -1132,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. */
@@ -3653,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,
@@ -3717,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 }),
   };

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);
         }