@rig-c/parts 2.51.0 → 2.52.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/cli.ts CHANGED
@@ -104,11 +104,13 @@ usage:
104
104
  Write <map>.binding.json with both file hashes; never overwrite a receipt.
105
105
  Attests the current files, not that inference used this input.
106
106
 
107
- rig-parts depth-apply --parts <assembled-dir> --manifest <manifest.json> --config <depth-recipe.json> --rig-config <config.json> --out <empty-dir>
107
+ rig-parts depth-apply --parts <assembled-dir> --manifest <manifest.json> --config <depth-recipe.json> --rig-config <config.json> --out <empty-dir> [--groups <name>[,<name>...]]
108
108
  Register floating-point JSON depth or signed normals, normalize inside
109
109
  alpha >=128, apply declared median/relief and group near/zScale/pivot,
110
110
  extend past alpha, and write parts, relocated config and depth-report.json.
111
111
  Normals require one closed convex island. See AUTHORING for the schemas.
112
+ --groups applies only the named recipe groups; the others' parts get no
113
+ sheet, and the selection is recorded in depth-report.json.
112
114
 
113
115
  rig-parts layers <dir | layers.json | file.psd>
114
116
  Read a See-through decomposition — the ComfyUI wrapper form (a directory
@@ -1247,7 +1249,7 @@ const TAKES = {
1247
1249
  'diff-drafts': { valued: ['--left', '--right', '--out'], switches: ['--help'] },
1248
1250
  'depth-bind': { valued: ['--map', '--input', '--part'], switches: ['--help'] },
1249
1251
  'depth-prepare': { valued: ['--parts', '--config', '--out'], switches: ['--help'] },
1250
- 'depth-apply': { valued: ['--parts', '--manifest', '--config', '--rig-config', '--out'], switches: ['--help'] },
1252
+ 'depth-apply': { valued: ['--parts', '--manifest', '--config', '--rig-config', '--out', '--groups'], switches: ['--help'] },
1251
1253
  layers: { valued: ['--export', '--template', '--canvas', '--full', '--source', '--config'], switches: ['--help'] },
1252
1254
  sheet: { valued: ['--source', '--layers', '--out', '--cell', '--cols'], switches: ['--help'] },
1253
1255
  rig: { valued: ['--config', '--parts', '--out', '--idle-keys', '--page-edges', '--pack-shape', '--page-size'], switches: ['--help'] },
@@ -2910,8 +2912,11 @@ function cmdDepthApply(args: string[]): number {
2910
2912
  const f = flags(args, 'depth-apply', ['--parts', '--manifest', '--config', '--rig-config', '--out']);
2911
2913
  if (typeof f === 'string') return usage(f);
2912
2914
  try {
2913
- const result = applyDepth({ parts: f.get('--parts')!, manifest: f.get('--manifest')!, config: f.get('--config')!, rigConfig: f.get('--rig-config')!, out: f.get('--out')! });
2915
+ const groups = f.get('--groups'), selected = groups === undefined ? {} : { groups: groups === '' ? [] : groups.split(',') };
2916
+ const result = applyDepth({ parts: f.get('--parts')!, manifest: f.get('--manifest')!, config: f.get('--config')!, rigConfig: f.get('--rig-config')!, out: f.get('--out')!, ...selected });
2914
2917
  for (const row of result.parts as Array<Record<string, unknown>>) console.log(`depth-apply: ${row.part} levels=${row.levels} clip=${row.clipFraction} reliefRigPixels=${row.reliefRigPixels} sign=${row.sign}`);
2918
+ const selection = result.selection as { groups: string[]; leftOut: string[] } | undefined;
2919
+ if (selection !== undefined) console.log(`depth-apply: applied groups ${selection.groups.join(', ')}; left out ${selection.leftOut.length === 0 ? 'no part' : selection.leftOut.join(', ')}, without a depth sheet`);
2915
2920
  console.log('depth-apply: wrote registered parts, config.json and depth-report.json; run rig for the core gate');
2916
2921
  return EXIT_OK;
2917
2922
  } catch (error) { return printRefusal(error); }
package/docs/AUTHORING.md CHANGED
@@ -1315,7 +1315,9 @@ mask's own path and hash. See the [refusal ledger](#EXTERNAL_RECEIPT_ARGUMENT).
1315
1315
  ### Edited rig-space parts (`assemble.edited_parts`, issue #1278)
1316
1316
 
1317
1317
  Use this block for a PNG edited at the exact crop and scale written by
1318
- `assemble`, such as an alpha edge retouch. Author-made run-space layers and
1318
+ `assemble`, such as an alpha edge retouch. An in-place overwrite of an emitted
1319
+ `parts/<name>.png` is refused by `rig` (`RIG_PNG_MATCHES_OPAQUE_PX`); edit
1320
+ through `edited-part`. Author-made run-space layers and
1319
1321
  `assemble.editor_receipts` keep their existing behavior; a receipt ledger
1320
1322
  alone does not apply a replacement.
1321
1323
 
@@ -1423,6 +1425,7 @@ counts relative to the normal assembled PNG:
1423
1425
  | `changed_counted_px` | Changed positions whose final alpha is above 8. |
1424
1426
  | `changed_excluded_px` | Changed positions whose final alpha is at most 8, including deletions. Together with `changed_counted_px`, sums to `changed_px`. |
1425
1427
  | `removed_opaque_px` | Positions whose baseline alpha was above 8 and final alpha is at most 8; a subset of `changed_excluded_px`. |
1428
+ | `removed_opaque_regions` | Where those removed positions are (issue #1383): one `{box: [x, y, w, h], px}` per 8-connected region of removed positions, the box in the part PNG's own pixels and `px` the removed positions inside it. The `px` values sum to `removed_opaque_px`; entries are sorted by `y`, `x`, `h`, `w`, `px`. Written only when `removed_opaque_px` is above 0, so an edit that removes nothing keeps its bytes. |
1426
1429
 
1427
1430
  The existing value partition is preserved:
1428
1431
  `unchanged_layer_px + hand_px + automatic_px = opaque_px`. `hand_px` counts
@@ -1437,6 +1440,34 @@ final-alpha partition and resolve replacement writer IDs through the sidecar's
1437
1440
  receipt-associated; this does not exempt other config shapes or baseline
1438
1441
  inputs from their existing source/receipt checks.
1439
1442
 
1443
+ #### Outline specks at an ownership boundary (issue #1383)
1444
+
1445
+ Projection by ownership can carry fragments of the painting's outline into a
1446
+ part along the edge where another part was visible: dark specks a part should
1447
+ not hold. Parts does not remove them. No assemble option, projection rule or
1448
+ filter decides which pixels are outline, because at the same boundary an
1449
+ outline fragment and real painting detail look alike, and a wrong deletion
1450
+ would be silent. The route is an image-editor edit with a receipt:
1451
+
1452
+ 1. Assemble, and keep the manifest (`parts.json`).
1453
+ 2. Edit the part PNG written by that assembly in an image editor: erase the
1454
+ specks (alpha 0) and keep the crop and size.
1455
+ 3. Write the receipt with `rig-parts edited-part --config <config> --parts
1456
+ <parts.json> --part <name> --file <edited.png> --from <assembled.png>
1457
+ --editor <text>` (or `--producer <json>`).
1458
+ 4. Rebuild (`assemble` or `build`) from the config that holds the receipt.
1459
+
1460
+ The rebuilt part is the edited file. An edited file whose bytes do not match
1461
+ its receipt is refused (`ASSEMBLE_EDITED_PART_SHA256`), and a file with no
1462
+ receipt row is never read, whether or not `editor_receipts.required` is set.
1463
+ A reviewer reads the part's `provenance.edited_part` in `parts.json`: the
1464
+ receipt names the editor and both file hashes, `removed_opaque_px` counts the
1465
+ erased opaque pixels, and `removed_opaque_regions` gives a box and a count for
1466
+ each connected group of them, so every removed speck can be found in the part
1467
+ PNG. With `assemble.stage_map`, `stage-map.json` carries the same record.
1468
+ Overwriting a written `parts/<name>.png` in place, without the receipt and a
1469
+ rebuild, is not this route: nothing records it.
1470
+
1440
1471
  At admission, `assemble` also prints an `edited part front colour:` measurement
1441
1472
  line for each receipted part (issue #1290): surviving pixels (`alpha > 8`) that
1442
1473
  the edit changed or added against the base part (`from_sha256`), where the
@@ -6255,6 +6286,7 @@ recorded transform. The record fields and sampling formula are specified in
6255
6286
  | --- | --- | --- |
6256
6287
  | <a id="RIG_PART_PRESENT"></a><a id="RIG_PART_ATTACHED"></a>`RIG_PART_PRESENT`, `RIG_PART_ATTACHED` | a `meshes`/`regions` key that is not in `parts.json`, a part with neither, or a `painting:` part with a mesh | the config and the plan must name the same parts; a patch is a region. A `drape_<s>` or `hand_<s>` from `full:drape-<s>` / `full:hand-<s>` is the 1.37.0 arm split's (issue #490), new to a config proposed before it: the detail names [MIGRATION](MIGRATION.md#after-1370-merged-arm-layers-are-split-issue-490), whose remedy is `propose … --write-config <config> --only-missing` (the two plan rows and the two entries) |
6257
6288
  | <a id="RIG_PNG_PRESENT"></a><a id="RIG_PNG_MATCHES_BOX"></a><a id="RIG_PART_HAS_ART"></a>`RIG_PNG_PRESENT`, `RIG_PNG_MATCHES_BOX`, `RIG_PART_HAS_ART` | a part's PNG is missing, the wrong size, or has no art pixel | re-run assemble |
6289
+ | <a id="RIG_PNG_MATCHES_OPAQUE_PX"></a>`RIG_PNG_MATCHES_OPAQUE_PX` | a part's `parts/<name>.png` has a different opaque pixel count (`alpha > 8`) than `parts.json` records as `opaque_px` (for example after an in-place overwrite of an emitted part PNG) | re-run assemble, or record the part replacement through `edited-part` (`assemble.edited_parts`) and re-run assemble |
6258
6290
  | <a id="RIG_NAME_RESOLVES"></a><a id="RIG_SEGMENT_DEFINED"></a><a id="RIG_CHAIN_POINTS"></a>`RIG_NAME_RESOLVES`, `RIG_SEGMENT_DEFINED`, `RIG_CHAIN_POINTS` | a segment names an undeclared bone, a bone with no `tip` and no next link, or a chain too short to make a link | that bone's `tip`, or write the segment out as `[bone, [x0,y0], [x1,y1]]` |
6259
6291
  | <a id="RIG_INFLUENCES_KEPT"></a>`RIG_INFLUENCES_KEPT` | a mesh's declared `influences` leaves a vertex with no bone: every capped share is under 0.03 (at or under it, for the continuous floor). The largest of k shares is at least 1/k, so this needs 34 or more kept bones; the default cap of 4 never reaches it (issue #284). The detail names the first vertex, how many more, and its largest share | declare `maxInfluences` 33 or less, or name fewer bones in `segments` |
6260
6292
  | <a id="RIG_LATTICE_STATION"></a>`RIG_LATTICE_STATION` | a requested lattice subdivision row is not finite | supply finite source-image row coordinates |
@@ -9353,6 +9385,22 @@ skeleton names remain names. A selected part whose provenance records
9353
9385
  to a transported scalar reference. Unselected authored units keep
9354
9386
  their original representation. Roles and draw order stay the author's.
9355
9387
 
9388
+ `--groups <name>[,<name>…]` (#1449) applies only the named recipe groups with
9389
+ the same manifest. A left-out group's recipe parts get no new sheet and lose
9390
+ any depth reference they carried; their maps are not read, and its
9391
+ `unitDepths` and `pivot` are not written. `config.turn.body` is required only
9392
+ when the body group is applied. A rig config that declares the turn of a
9393
+ left-out group — `turn.body` for body, `turn.roles` or `turn.depths` for head —
9394
+ is refused as [`DEPTH_GROUP_LEFT_OUT`](#DEPTH_GROUP_LEFT_OUT), since `rig`
9395
+ builds a group's dial and animation from that block. An empty list, a name the
9396
+ recipe does not declare, or a repeated name is refused as
9397
+ [`DEPTH_GROUP_SELECTION`](#DEPTH_GROUP_SELECTION); every problem in the list is
9398
+ named at once. The report then carries `selection`, after `cleared` and before
9399
+ `parts`: `{"groups": [...], "leftOut": [...]}`, groups in the recipe's order and
9400
+ parts in `parts.json` order. `recipeSha256` and `manifestSha256` are the full
9401
+ recipe's. Without the flag, `selection` is absent and every output byte is
9402
+ unchanged.
9403
+
9356
9404
  Maps are UTF-8 JSON `{"spec":"rig-parts-map/1","width":2,"height":2,
9357
9405
  "channels":1,"data":[0.125,0.25,0.5,0.875]}`: row-major finite numeric values,
9358
9406
  with channels interleaved for signed XYZ normals (`channels:3`). JSON is open,
@@ -9479,6 +9527,8 @@ by `rig`, so their output requires no alternate compiler or dependency pin.
9479
9527
  | <a id="DEPTH_NORMAL_VECTOR"></a>`DEPTH_NORMAL_VECTOR` | a sampled support normal is zero | provide nonzero signed XYZ normals |
9480
9528
  | <a id="DEPTH_NORMAL_CONVEXITY"></a>`DEPTH_NORMAL_CONVEXITY` | core/rim or its convexity sign is unresolved | larger closed convex mask or scalar source |
9481
9529
  | <a id="DEPTH_GROUP_BINDING"></a>`DEPTH_GROUP_BINDING` | part outside declared turn roles, mixed retained near/zScale, or filename collision | register exact roles and one shared scale/polarity, replace/clear conflicting sheets, use distinct names |
9530
+ | <a id="DEPTH_GROUP_SELECTION"></a>`DEPTH_GROUP_SELECTION` | `depth-apply --groups` with an empty list, a group the recipe does not declare, or a group named twice | name each group to apply once, from the recipe's `groups` |
9531
+ | <a id="DEPTH_GROUP_LEFT_OUT"></a>`DEPTH_GROUP_LEFT_OUT` | `depth-apply --groups` leaves a group out while the rig config declares that group's turn (`turn.body`; `turn.roles` or `turn.depths` for head) | remove that turn block from the rig config, or name the group in `--groups` |
9482
9532
  | <a id="DEPTH_AUTHORED_UNIT_CONFLICT"></a>`DEPTH_AUTHORED_UNIT_CONFLICT` | a selected part already records `provenance.depth.kind: "authored-unit"`; adding scalar depth would make its two representations conflict | retain the authored unit or supply an explicitly reassembled scalar-compatible input; apply never replaces the provenance automatically |
9483
9533
 
9484
9534
  ### Unit depth precedence
package/docs/DEPTH.md CHANGED
@@ -199,6 +199,23 @@ in `work/rig` or your original config is touched. Any mismatch — a recipe edit
199
199
  after prepare, a part that moved, a map of the wrong size, a part your
200
200
  `turn.roles` does not name — is refused by name before a byte is written.
201
201
 
202
+ **Apply only some groups.** A recipe prepared with a head and a body group
203
+ can answer for the head alone, with the same manifest and no new inference:
204
+
205
+ ```sh
206
+ rig-parts depth-apply --parts work/rig --manifest inference/manifest.json --config depth.json --rig-config head-config.json --out mapped-head --groups head
207
+ ```
208
+
209
+ Only the named groups' parts get sheets. A left-out group's parts keep their
210
+ art and lose any sheet they had, so nothing stale is carried into the rig,
211
+ and their maps are not read. `config.turn.body` is required only when the
212
+ body group is applied; a rig config that still declares the turn of a group
213
+ left out (`turn.body` for body, `turn.roles` or `turn.depths` for head) is
214
+ refused, because the rig builds a turn from that block and not from the
215
+ sheets. `depth-report.json` records the run under `selection`: the groups
216
+ applied and the parts left out. The recipe and manifest hashes stay those of
217
+ the full recipe.
218
+
202
219
  ### 5. Rig, and look
203
220
 
204
221
  ```sh
@@ -209,7 +226,8 @@ The rig stage is the ordinary one. With `turn.roles` declared it builds the
209
226
  depth-sampled turn: `surface` parts become grids that bend with their sheets,
210
227
  `unit` parts ride a carrier at their own depth, and the motion gains `turn` and
211
228
  `tilt` animations driven by `yaw_dial` and `pitch_dial` (a body group adds
212
- `body_yaw_dial`). On the check fixture above the compiled motion carried
229
+ a `body_turn` animation and its dial, `body_yaw_dial` unless
230
+ `turn.body.slider` names another). On the check fixture above the compiled motion carried
213
231
  `idle`, `tilt` and `turn`, and the bones `faceshift`, `face_surface`,
214
232
  `yaw_dial` and `pitch_dial` beside the head. It also writes
215
233
  `depth_sheets.json`, which names every sheet the build consumed. rig-c's gate
@@ -228,7 +246,9 @@ rigc build --rig candidate/rig.json --motion candidate/motion.json --out built -
228
246
  ```
229
247
 
230
248
  The motion comes out with `turn`, `tilt` and `body_turn`, and the rig with
231
- `yaw_dial`, `pitch_dial` and `body_dial`, so `look/config.json` is also a worked
249
+ `yaw_dial`, `pitch_dial` and `body_dial` (the name `look/config.json` gives
250
+ the body dial in `turn.body.slider`; without it the dial is `body_yaw_dial`), so
251
+ `look/config.json` is also a worked
232
252
  `turn.roles` to start your own from. To try the per-part route, run
233
253
  `depth-prepare` on `assembled/rig` with a recipe like the one above. From step 2
234
254
  on, the maps are your model's.
package/docs/STABILITY.md CHANGED
@@ -548,7 +548,7 @@ and do not certify visibility. See the
548
548
  | `diff-drafts` | `--left`, `--right`, `--out`; optional `--help` (`-h`) (issue #1369; draft-to-draft assemble comparison, `rig-parts-draft-diff/1`) |
549
549
  | `depth-prepare` | `--parts`, `--config`, `--out`; optional `--help` (`-h`) (issue #897; separate numeric-depth recipe) |
550
550
  | `depth-bind` | `--map`, `--input`, `--part`; optional `--help` (`-h`) (issue #1284; exclusive receipt creation from current file bytes) |
551
- | `depth-apply` | `--parts`, `--manifest`, `--config`, `--rig-config`, `--out`; optional `--help` (`-h`) (issue #897; original character config is read-only) |
551
+ | `depth-apply` | `--parts`, `--manifest`, `--config`, `--rig-config`, `--out`; optional `--groups` (a comma-separated list of the recipe's groups to apply, issue #1449), `--help` (`-h`) (issue #897; original character config is read-only) |
552
552
  | `layers` | one positional path: a wrapper directory, a `layers.json` or a `.psd` (a file literally named `-h` is reached as `./-h`); with it, optional `--export` (a directory to write the wrapper form into, issue #359); or `--template` with `--canvas` and no path; or a positional head run with `--full`, `--source`, `--config` together for `PLAN_HEAD_GARMENT_OVERLAP` (issue #826); or `--help` (`-h`) |
553
553
  | `sheet` | `--source`, `--layers` (repeatable), `--out`; optional `--cell`, `--cols`, `--help` (`-h`) |
554
554
  | `inputs` | `--source`, `--config`, `--out`; optional `--help` (`-h`) |
@@ -1472,11 +1472,13 @@ from the CLI), `SK04` (the skeleton), `RG03` (two lattice builds), `CW20` and
1472
1472
  loop's replay, every Stage B opt-in, a gradation, the multi-interval selection's
1473
1473
  policy path and the residual veto), `CK02`, `CK33` and `CK79` (`check`, its
1474
1474
  stretch geometry, and `check --requirements`), `DG13` (`basis.json`), `LP08`
1475
- (the indexed APNG) and `ST26` (the `compare` printout). With the public examples
1476
- fetched, the `chain` suite builds each of them and holds `parts.json`
1477
- (`CH02`), `rig.json`, `motion.json` and `mesh_report.json` (`CH03`),
1478
- `check.json` (`CH04`) and the gate file (`CH05`) to its tracked `expected/`,
1479
- field by field, with the tolerances `CH07` plants against.
1475
+ (the indexed APNG) and `ST26` (the `compare` printout). The `chain` suite builds
1476
+ the synthetic validation variants and holds `parts.json` (`CH02`), `rig.json`,
1477
+ `motion.json` and `mesh_report.json` (`CH03`), `check.json` whole (`CH04`) and the
1478
+ gate file (`CH05`) to their tracked `expected/`, with the tolerances `CH07` plants
1479
+ against. The public examples' `expected/` files are this package's own snapshots:
1480
+ `tools/regenerate_examples.ts` writes them on Linux, and CI rebuilds the fetched
1481
+ examples and compares the files whole with its `--check` (issue #1439).
1480
1482
 
1481
1483
  ### Opt-in hybrid provenance (issue #399)
1482
1484
 
@@ -1943,7 +1945,14 @@ edited base image. No new flag bypasses rig-c or existing check bars.
1943
1945
 
1944
1946
  Receipt association is additive `provenance.edited_part` metadata: the complete
1945
1947
  receipt and `dir`, `edit: "edited_parts[i]"`, `changed_px`,
1946
- `changed_counted_px`, `changed_excluded_px` and `removed_opaque_px`.
1948
+ `changed_counted_px`, `changed_excluded_px` and `removed_opaque_px`, then,
1949
+ when `removed_opaque_px` is above 0, `removed_opaque_regions` (issue #1383,
1950
+ additive): one `{box: [x, y, w, h], px}` per 8-connected region of removed
1951
+ positions, in part pixels, sorted by `y`, `x`, `h`, `w`, `px`, whose `px` sum
1952
+ to `removed_opaque_px`. An edit that removes nothing, and a build without the
1953
+ block, writes the same bytes as before. A manifest without the field reads as
1954
+ before; a reader that predates it refuses a manifest that carries it
1955
+ (`PARTS_FIELD_TYPE`).
1947
1956
  The four counts describe exact baseline-to-edited RGBA differences;
1948
1957
  `hand_px` keeps its existing final-alpha-above-8 partition meaning.
1949
1958
  The receipt covers the whole file, including unchanged and transparent
@@ -1971,7 +1980,11 @@ encoding, convexity sign and refusal remedies are in
1971
1980
  [AUTHORING](AUTHORING.md#per-part-provider-maps-897). No existing build path
1972
1981
  calls these stages; no-config builds retain their existing behavior and bytes.
1973
1982
  Group numbers and unit depths are explicit; no provider or absolute scale is
1974
- inferred. A new depth stage never replaces Core's rig gate.
1983
+ inferred. `depth-apply --groups` (#1449) applies a subset of the recipe's
1984
+ groups against the same manifest and records it in the report's `selection`
1985
+ field (`groups`, `leftOut`), written after `cleared` and before `parts`; the
1986
+ field is absent without the flag, so those reports keep their bytes, and
1987
+ `recipeSha256` and `manifestSha256` are unchanged by a selection. A new depth stage never replaces Core's rig gate.
1975
1988
  `relief` is an explicit rig-pixel value, not an implicit width multiplier.
1976
1989
  Part-width and head-referenced calibrations are authored recipe choices;
1977
1990
  changing a calibration requires preparing its recipe again. Compare the same
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@rig-c/parts",
3
- "version": "2.51.0",
3
+ "version": "2.52.0",
4
4
  "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.",
5
5
  "type": "module",
6
6
  "exports": {
@@ -6,6 +6,7 @@ import { createHash } from 'node:crypto';
6
6
  import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, statSync, writeFileSync } from 'node:fs';
7
7
  import { basename, dirname, join, relative, resolve, sep } from 'node:path';
8
8
  import { refuseStaleAssembly } from './assembly-reading.ts';
9
+ import { PartsError, type Problem } from './errors.ts';
9
10
  import { loadConfigAndAnimations, parseConfig } from './config.ts';
10
11
  import { relocateConfigReferences } from './configrelocation.ts';
11
12
  import { depthReading, readSourceDepth } from './depthsheets.ts';
@@ -213,8 +214,25 @@ function mapBinding(mapPath: string, bytes: Uint8Array, part: PreparedPart): str
213
214
  if (r.inputSha256 !== part.inputSha256) return refuse(`inference input sha found ${r.inputSha256}; required ${part.inputSha256}`);
214
215
  return undefined;
215
216
  }
216
- export function applyDepth(input: { parts: string; manifest: string; config: string; rigConfig: string; out: string }, log: (line: string) => void = console.warn): Obj {
217
- const recipe = parseDepthRecipe(readJson(input.config)), expected = preparedParts(input.parts, recipe);
217
+ /** `depth-apply --groups` (#1449): the recipe's groups the run applies, in the recipe's declaration order.
218
+ * Every problem in the list is collected and refused at once; absent, every group applies. */
219
+ function groupSelection(recipe: DepthRecipe, groups: readonly string[] | undefined): string[] | undefined {
220
+ if (groups === undefined) return undefined;
221
+ const declared = Object.keys(recipe.groups), has = `the recipe's groups are ${declared.map(g => JSON.stringify(g)).join(', ')}`;
222
+ const problems: Problem[] = [], seen = new Set<string>(), repeated = new Set<string>();
223
+ const refuse = (detail: string): void => { problems.push({ code: 'DEPTH_GROUP_SELECTION', object: 'depth-apply --groups', detail }); };
224
+ if (groups.length === 0) refuse(`found an empty list; required one or more group names, comma-separated; ${has}`);
225
+ for (const name of groups) {
226
+ if (seen.has(name)) { if (!repeated.has(name)) refuse(`found ${JSON.stringify(name)} more than once; required each group named once; ${has}`); repeated.add(name); continue; }
227
+ seen.add(name);
228
+ if (!declared.includes(name)) refuse(`found ${JSON.stringify(name)}, which the recipe does not declare; required a group the recipe declares; ${has}`);
229
+ }
230
+ if (problems.length) throw new PartsError(problems);
231
+ return declared.filter(g => seen.has(g));
232
+ }
233
+ export function applyDepth(input: { parts: string; manifest: string; config: string; rigConfig: string; out: string; groups?: readonly string[] }, log: (line: string) => void = console.warn): Obj {
234
+ const recipe = parseDepthRecipe(readJson(input.config)), selection = groupSelection(recipe, input.groups), applied = (group: string): boolean => selection === undefined || selection.includes(group);
235
+ const expected = preparedParts(input.parts, recipe);
218
236
  const supplied = readJson(input.manifest);
219
237
  if (text(supplied) !== text(expected.manifest)) fail('DEPTH_INPUT_BINDING', input.manifest, 'does not match the recipe, parts.json, art hashes, crop or padding; run depth-prepare again for these exact inputs');
220
238
  for (const p of expected.manifest.parts) {
@@ -223,11 +241,23 @@ export function applyDepth(input: { parts: string; manifest: string; config: str
223
241
  }
224
242
  emptyOutput(input.out, [input.parts, input.config, input.manifest, input.rigConfig, ...Object.values(recipe.parts).flatMap(p => { const map = resolve(dirname(input.config), p.map); return [map, map + '.binding.json']; })]);
225
243
  const rawParts = object(readJson(join(input.parts, 'parts.json')), 'parts.json'), file = readParts(join(input.parts, 'parts.json'));
226
- for (const p of file.parts) if (Object.hasOwn(recipe.parts, p.name) && p.provenance?.depth?.kind === 'authored-unit') fail('DEPTH_AUTHORED_UNIT_CONFLICT', `part "${p.name}"`, 'has provenance.depth.kind "authored-unit"; a transported scalar reference cannot coexist with authored unit depth — retain the unit declaration or supply an explicitly reassembled scalar-compatible input; no automatic transition is made');
244
+ for (const p of file.parts) if (Object.hasOwn(recipe.parts, p.name) && applied(recipe.parts[p.name].group) && p.provenance?.depth?.kind === 'authored-unit') fail('DEPTH_AUTHORED_UNIT_CONFLICT', `part "${p.name}"`, 'has provenance.depth.kind "authored-unit"; a transported scalar reference cannot coexist with authored unit depth — retain the unit declaration or supply an explicitly reassembled scalar-compatible input; no automatic transition is made');
227
245
  const { config } = loadConfigAndAnimations(input.rigConfig);
228
246
  refuseStaleAssembly(input.rigConfig, file, config);
229
247
  const raw = object(readJson(input.rigConfig), 'rig config'), turn = object(raw.turn, 'config.turn');
248
+ // A group left out must not turn: the rig builds a group's turn from its config block, not from its sheets.
249
+ // An applied body group still requires config.turn.body; every such problem is refused at once.
250
+ const turnProblems: Problem[] = [];
251
+ for (const name of Object.keys(recipe.groups)) {
252
+ if (applied(name)) {
253
+ if (name !== 'head' && (turn.body === null || typeof turn.body !== 'object' || Array.isArray(turn.body))) turnProblems.push({ code: 'DEPTH_RECIPE', object: 'config.turn.body', detail: 'requires an object with the documented fields' });
254
+ continue;
255
+ }
256
+ for (const field of name === 'head' ? ['roles', 'depths'] : ['body']) if (turn[field] !== undefined) turnProblems.push({ code: 'DEPTH_GROUP_LEFT_OUT', object: `config.turn.${field}`, detail: `declares the ${name} turn, and depth-apply --groups ${(selection as string[]).join(',')} leaves the recipe's ${name} group out; required no config.turn.${field} in the rig config when the ${name} group is left out, or ${name} named in --groups` });
257
+ }
258
+ if (turnProblems.length) throw new PartsError(turnProblems);
230
259
  for (const [name, group] of Object.entries(recipe.groups)) {
260
+ if (!applied(name)) continue;
231
261
  const target = name === 'head' ? turn : object(turn.body, 'config.turn.body'); target.pivot = group.pivot;
232
262
  if (group.unitDepths !== undefined) target.unitDepths = group.unitDepths;
233
263
  }
@@ -252,6 +282,8 @@ export function applyDepth(input: { parts: string; manifest: string; config: str
252
282
  const name = p.name, bytes = readFileSync(join(input.parts, partImageReference(p).path)), art = decodePngBytes(bytes, name), rec = recs.find(r => r.name === name) as Obj;
253
283
  writes.set(`${name}.png`, bytes);
254
284
  const declaration = Object.hasOwn(recipe.parts, name) ? recipe.parts[name] : undefined;
285
+ // A left-out group's part gets no new sheet, and any sheet it carried is dropped, never retained stale.
286
+ if (declaration !== undefined && !applied(declaration.group)) { if (p.depth !== undefined) retained.delete(depthImageReference(p.depth).path); delete rec.depth; continue; }
255
287
  if (declaration === undefined) {
256
288
  if (recipe.clear.includes(name)) { if (p.depth !== undefined) retained.delete(depthImageReference(p.depth).path); delete rec.depth; }
257
289
  else if (p.depth !== undefined) { const depthPath = join(input.parts, depthImageReference(p.depth).path); readSourceDepth(depthPath, art, null); writes.set(p.depth.image, readFileSync(depthPath)); }
@@ -285,13 +317,15 @@ export function applyDepth(input: { parts: string; manifest: string; config: str
285
317
  }
286
318
  // A replacement must share near/zScale with every retained part in its actual group.
287
319
  for (const [name, g] of Object.entries(recipe.groups)) {
320
+ if (!applied(name)) continue;
288
321
  const target = name === 'head' ? turn : object(turn.body, 'config.turn.body'), roles = object(target.roles, `config.turn.${name}.roles`);
289
322
  for (const rec of recs) if (Object.hasOwn(roles, String(rec.name)) && rec.depth !== undefined) {
290
323
  const d = rec.depth as Obj;
291
324
  if (d.near !== g.near || d.zScale !== g.zScale) fail('DEPTH_GROUP_BINDING', String(rec.name), `retained ${name} sheet near=${String(d.near)}, zScale=${String(d.zScale)}; declared group requires ${g.near}, ${g.zScale}; replace or explicitly clear that sheet`);
292
325
  }
293
326
  }
294
- const report = { spec: 'rig-parts-depth-report/1', partsSha256: expected.manifest.partsSha256, recipeSha256: expected.manifest.recipeSha256, manifestSha256: hash(readFileSync(input.manifest)), rigConfigSha256: hash(readFileSync(input.rigConfig)), alpha: 128, normalization: 'median, linear p5..p95', extension: 'nearest alpha>=128, row-major ties', cleared: recipe.clear, parts: rows };
327
+ const report = { spec: 'rig-parts-depth-report/1', partsSha256: expected.manifest.partsSha256, recipeSha256: expected.manifest.recipeSha256, manifestSha256: hash(readFileSync(input.manifest)), rigConfigSha256: hash(readFileSync(input.rigConfig)), alpha: 128, normalization: 'median, linear p5..p95', extension: 'nearest alpha>=128, row-major ties', cleared: recipe.clear,
328
+ ...(selection === undefined ? {} : { selection: { groups: selection, leftOut: file.parts.filter(p => Object.hasOwn(recipe.parts, p.name) && !applied(recipe.parts[p.name].group)).map(p => p.name) } }), parts: rows };
295
329
  mkdirSync(join(input.out, 'parts'), { recursive: true });
296
330
  for (const [file, bytes] of retained) {
297
331
  if (['parts.json', 'config.json', 'depth-report.json'].includes(file)) continue;
@@ -38,6 +38,46 @@ export interface EditedPartProvenance {
38
38
  changed_counted_px: number;
39
39
  changed_excluded_px: number;
40
40
  removed_opaque_px: number;
41
+ /**
42
+ * Issue #1383: where the removed opaque pixels are. One entry per
43
+ * 8-connected region of removed positions, as a box `[x, y, w, h]` in the
44
+ * part PNG's own pixels and the count of removed positions inside it; the
45
+ * counts sum to `removed_opaque_px`. Sorted by `y`, `x`, `h`, `w`, `px`.
46
+ * Written only when `removed_opaque_px > 0`, so an edit that removes
47
+ * nothing keeps its bytes.
48
+ */
49
+ removed_opaque_regions?: EditedPartRemovedRegion[];
50
+ }
51
+ export interface EditedPartRemovedRegion { box: [number, number, number, number]; px: number }
52
+
53
+ /** 8-connected regions of a part-sized 0/1 mask, ordered as `removed_opaque_regions` requires. */
54
+ export function removedOpaqueRegions(removed: Uint8Array, width: number, height: number): EditedPartRemovedRegion[] {
55
+ const seen = new Uint8Array(removed.length), out: EditedPartRemovedRegion[] = [];
56
+ for (let start = 0; start < removed.length; start++) {
57
+ if (removed[start] !== 1 || seen[start] === 1) continue;
58
+ let left = width, top = height, right = 0, bottom = 0, px = 0;
59
+ const stack = [start];
60
+ seen[start] = 1;
61
+ while (stack.length > 0) {
62
+ const p = stack.pop()!, x = p % width, y = Math.floor(p / width);
63
+ px++;
64
+ if (x < left) left = x;
65
+ if (y < top) top = y;
66
+ if (x + 1 > right) right = x + 1;
67
+ if (y + 1 > bottom) bottom = y + 1;
68
+ for (let dy = -1; dy <= 1; dy++) for (let dx = -1; dx <= 1; dx++) {
69
+ const nx = x + dx, ny = y + dy, q = ny * width + nx;
70
+ if (nx < 0 || ny < 0 || nx >= width || ny >= height || removed[q] !== 1 || seen[q] === 1) continue;
71
+ seen[q] = 1;
72
+ stack.push(q);
73
+ }
74
+ }
75
+ out.push({ box: [left, top, right - left, bottom - top], px });
76
+ }
77
+ return out.sort(compareRemovedRegions);
78
+ }
79
+ export function compareRemovedRegions(a: EditedPartRemovedRegion, b: EditedPartRemovedRegion): number {
80
+ return a.box[1] - b.box[1] || a.box[0] - b.box[0] || a.box[3] - b.box[3] || a.box[2] - b.box[2] || a.px - b.px;
41
81
  }
42
82
  export interface EditedPartFrontColourOwner {
43
83
  owner: string;
@@ -156,6 +196,7 @@ export function replaceEditedParts(
156
196
  const provenance: PixelProvenance = { unchanged_layer_px: 0, hand_px: 0, automatic_px: 0, edits: [], automatic: [],
157
197
  ...(record.provenance?.depth === undefined ? {} : { depth: record.provenance.depth }), edited_part: metadata };
158
198
  const counts = new Map<number, number>();
199
+ const removed = new Uint8Array(old.width * old.height);
159
200
  let opaque = 0, visible = 0, projected = 0, paintingGain = 0;
160
201
  const partOwnerIndex = owner.names.indexOf(record.name);
161
202
  const byOwner = new Map<number, { px: number; left: number; top: number; right: number; bottom: number }>();
@@ -169,7 +210,7 @@ export function replaceEditedParts(
169
210
  metadata.changed_px++;
170
211
  if (counted) metadata.changed_counted_px++; else metadata.changed_excluded_px++;
171
212
  }
172
- if (old.data[offset + 3] > OPAQUE_ALPHA_ABOVE && !counted) metadata.removed_opaque_px++;
213
+ if (old.data[offset + 3] > OPAQUE_ALPHA_ABOVE && !counted) { metadata.removed_opaque_px++; removed[p] = 1; }
173
214
  if (!counted) { next.excluded_px++; append(next.runs, EXCLUDED_PIXEL); append(next.pre_seam_writer_runs, EXCLUDED_PIXEL); continue; }
174
215
  opaque++;
175
216
  const x = record.x + p % record.w, y = record.y + Math.floor(p / record.w);
@@ -216,6 +257,7 @@ export function replaceEditedParts(
216
257
  else provenance.automatic_px++;
217
258
  counts.set(writer, (counts.get(writer) ?? 0) + 1);
218
259
  }
260
+ if (metadata.removed_opaque_px > 0) metadata.removed_opaque_regions = removedOpaqueRegions(removed, old.width, old.height);
219
261
  provenance.edits = map.edits.flatMap((edit, i) => counts.has(i + 1) ? [{ edit, px: counts.get(i + 1)! }] : []);
220
262
  provenance.automatic = (Object.keys(AUTOMATIC_WRITERS) as AutomaticWriter[]).flatMap(stage => counts.has(AUTOMATIC_WRITERS[stage]) ? [{ stage, px: counts.get(AUTOMATIC_WRITERS[stage])! }] : []);
221
263
  record.opaque_px = opaque;
package/src/parts.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  import { assemblyFieldDigest, isSplitTakeMetadataField } from './assembly-reading.ts';
2
- import { orderedEditedPartReceipt, type EditedPartReceipt } from './editedparts.ts';
2
+ import { compareRemovedRegions, orderedEditedPartReceipt, type EditedPartReceipt, type EditedPartRemovedRegion } from './editedparts.ts';
3
3
  import { parseReceiptProducer, receiptText } from './receiptproducer.ts';
4
4
  import { takenSourceProblems, type TakenLayerSource } from './takesource.ts';
5
5
  import { AUTOMATIC_WRITERS, provenanceAddsUp, type PixelProvenance, type CutOwnership } from './provenance.ts';
@@ -555,6 +555,34 @@ export function tagOf(from: string): string | null {
555
555
  return f === null || f.run === 'painting' ? null : f.tag;
556
556
  }
557
557
 
558
+ /**
559
+ * Issue #1383: `removed_opaque_regions`, when present, is a non-empty list of
560
+ * `{box: [x, y, w, h], px}` inside the part box, in the writer's order, whose
561
+ * `px` sum to `removed_opaque_px`. Absent is a manifest written before the
562
+ * field existed, or an edit that removed nothing.
563
+ */
564
+ function editedRemovedRegions(value: unknown, removed: number, w: unknown, h: unknown, object: string, fail: (code: string, object: string, detail: string) => void): void {
565
+ const int = (n: unknown): n is number => Number.isSafeInteger(n);
566
+ const rows = Array.isArray(value) ? value as unknown[] : null;
567
+ const shaped = rows !== null && rows.length > 0 && int(w) && int(h) && rows.every(r => r !== null && typeof r === 'object' && !Array.isArray(r) &&
568
+ Object.keys(r).sort().join(',') === 'box,px' && Array.isArray((r as EditedPartRemovedRegion).box) && (r as EditedPartRemovedRegion).box.length === 4 &&
569
+ (r as EditedPartRemovedRegion).box.every(int) && int((r as EditedPartRemovedRegion).px));
570
+ if (!shaped) {
571
+ fail('PARTS_FIELD_TYPE', object, `is ${show(value)}; a non-empty list of {box: [x, y, w, h], px} with safe integers is required`);
572
+ return;
573
+ }
574
+ const regions = rows as EditedPartRemovedRegion[];
575
+ regions.forEach((r, i) => {
576
+ const [x, y, bw, bh] = r.box;
577
+ if (x < 0 || y < 0 || bw < 1 || bh < 1 || x + bw > (w as number) || y + bh > (h as number) || r.px < 1 || r.px > bw * bh) {
578
+ fail('PARTS_COUNTS_ADD_UP', `${object}[${i}]`, `is box [${r.box.join(', ')}] px ${r.px}; a box of at least 1x1 inside the part's ${w as number}x${h as number} pixels and px from 1 to its area ${bw * bh} is required`);
579
+ }
580
+ if (i > 0 && compareRemovedRegions(regions[i - 1], r) > 0) fail('PARTS_FIELD_TYPE', `${object}[${i}]`, `box [${r.box.join(', ')}] follows box [${regions[i - 1].box.join(', ')}]; the order y, x, h, w, px is required`);
581
+ });
582
+ const sum = regions.reduce((n, r) => n + r.px, 0);
583
+ if (sum !== removed) fail('PARTS_COUNTS_ADD_UP', object, `px sum to ${sum}; removed_opaque_px ${removed} is required`);
584
+ }
585
+
558
586
  function validEditedPartAuthor(receipt: EditedPartReceipt): boolean {
559
587
  const keys = Object.keys(receipt).sort().join(',');
560
588
  if (keys === 'editor,file,from_sha256,part,sha256') return receiptText(receipt.editor);
@@ -617,6 +645,9 @@ function orderedProvenance(p: PixelProvenance): PixelProvenance {
617
645
  receipt: orderedEditedPartReceipt(p.edited_part.receipt),
618
646
  changed_px: p.edited_part.changed_px, changed_counted_px: p.edited_part.changed_counted_px,
619
647
  changed_excluded_px: p.edited_part.changed_excluded_px, removed_opaque_px: p.edited_part.removed_opaque_px,
648
+ ...(p.edited_part.removed_opaque_regions === undefined ? {} : {
649
+ removed_opaque_regions: p.edited_part.removed_opaque_regions.map(r => ({ box: [r.box[0], r.box[1], r.box[2], r.box[3]] as [number, number, number, number], px: r.px })),
650
+ }),
620
651
  } }) };
621
652
  }
622
653
 
@@ -835,9 +866,10 @@ function checkProvenance(raw: unknown, opaque: unknown, object: string, fail: (c
835
866
  if (v !== null && typeof v === 'object' && 'edited_part' in v) {
836
867
  const e = v.edited_part;
837
868
  const keys = 'changed_counted_px,changed_excluded_px,changed_px,dir,edit,receipt,removed_opaque_px';
869
+ const withRegions = 'changed_counted_px,changed_excluded_px,changed_px,dir,edit,receipt,removed_opaque_px,removed_opaque_regions';
838
870
  const nonempty = (value: unknown): value is string => typeof value === 'string' && value.trim().length > 0;
839
871
  const relativePath = (value: unknown): boolean => nonempty(value) && !/^(?:[\\/]|[A-Za-z]:[\\/])/.test(value);
840
- const valid = e !== null && e !== undefined && typeof e === 'object' && !Array.isArray(e) && Object.keys(e).sort().join(',') === keys &&
872
+ const valid = e !== null && e !== undefined && typeof e === 'object' && !Array.isArray(e) && [keys, withRegions].includes(Object.keys(e).sort().join(',')) &&
841
873
  typeof e.edit === 'string' && /^edited_parts\[\d+\]$/.test(e.edit) && relativePath(e.dir) &&
842
874
  [e.changed_px, e.changed_counted_px, e.changed_excluded_px, e.removed_opaque_px].every(count) &&
843
875
  e.receipt !== null && typeof e.receipt === 'object' && !Array.isArray(e.receipt) &&
@@ -852,6 +884,7 @@ function checkProvenance(raw: unknown, opaque: unknown, object: string, fail: (c
852
884
  e.removed_opaque_px > e.changed_excluded_px) {
853
885
  fail('PARTS_COUNTS_ADD_UP', object + ' edited_part', `changed_px ${e.changed_px} must equal counted ${e.changed_counted_px} + excluded ${e.changed_excluded_px}; counted must fit opaque_px ${show(opaque)}, excluded must fit the remaining box pixels (area ${area}), and removed_opaque_px ${e.removed_opaque_px} must be at most changed_excluded_px`);
854
886
  }
887
+ if ('removed_opaque_regions' in e) editedRemovedRegions(e.removed_opaque_regions, e.removed_opaque_px, identity?.w, identity?.h, object + ' edited_part.removed_opaque_regions', fail);
855
888
  }
856
889
  }
857
890
  if (v !== null && typeof v === 'object' && 'depth' in v) {
package/src/rig.ts CHANGED
@@ -177,6 +177,7 @@ import { skeletonLimbJoints } from './limbs.ts';
177
177
  import { coalesceLimbSlots } from './limbslots.ts';
178
178
  import { layoutAlias, placeLimbLayouts, type LayoutPlan } from './limblayout.ts';
179
179
  import { artCoverage, ART_ALPHA, latticeCells, latticeMesh, latticeStray, ONE_LOOP_PASSES, type LatticeMesh } from './mesh.ts';
180
+ import { OPAQUE_ALPHA_ABOVE } from './layers.ts';
180
181
  import { bindFaceSurfaceDeform, BLINK, blinkHoldMisses, blinkSpan, blinkTimes, CONTROL_SUFFIX, controlledBones, IDLE_FPS, idleMotion, type MotionSpec, moveKeysToControls } from './motion.ts';
181
182
  import { type PartRecord, type AlternateSetMap, FRONT_SUFFIX, PAINTING_RUN, type PartsFile, readFrom, tagOf } from './parts.ts';
182
183
  import { waistPairs, waistBand, waistInfluences } from './waist.ts';
@@ -1341,6 +1342,13 @@ function alphaCount(img: Raster, y0: number, y1: number): number {
1341
1342
  return n;
1342
1343
  }
1343
1344
 
1345
+ /** Pixels with alpha strictly above `OPAQUE_ALPHA_ABOVE` (8) in `img`, the count `parts.json` records as `opaque_px`. */
1346
+ function opaqueCount(img: Raster): number {
1347
+ let n = 0;
1348
+ for (let i = 3; i < img.data.length; i += 4) if (img.data[i] > OPAQUE_ALPHA_ABOVE) n++;
1349
+ return n;
1350
+ }
1351
+
1344
1352
  function same(a: Point, b: Point): boolean {
1345
1353
  return a[0] === b[0] && a[1] === b[1];
1346
1354
  }
@@ -1659,6 +1667,11 @@ export function buildWaistPairSource(
1659
1667
  if (img === undefined) fail('RIG_PNG_PRESENT', `part "${p.name}"`, `has no parts/${p.name}.png`);
1660
1668
  else if (img.width !== p.w || img.height !== p.h) {
1661
1669
  fail('RIG_PNG_MATCHES_BOX', `part "${p.name}"`, `parts/${p.name}.png is ${img.width}x${img.height}; parts.json's box is ${p.w}x${p.h}`);
1670
+ } else {
1671
+ const found = opaqueCount(img);
1672
+ if (found !== p.opaque_px) {
1673
+ fail('RIG_PNG_MATCHES_OPAQUE_PX', `part "${p.name}"`, `parts/${p.name}.png has ${found} opaque pixels; parts.json records ${p.opaque_px}`);
1674
+ }
1662
1675
  }
1663
1676
  }
1664
1677