spine-parts 2.21.0 → 2.22.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/docs/AUTHORING.md CHANGED
@@ -4596,6 +4596,46 @@ path. Declarations apply to the **base painting only** and are not inherited
4596
4596
  into alternate paintings. Native setup and animation boundary checks remain
4597
4597
  consumer acceptance work; assembly provenance does not establish motion quality.
4598
4598
 
4599
+ ### Per-pixel stage map
4600
+
4601
+ Declare `assemble.stage_map: true` to emit `stage-map.json` beside `parts.json`
4602
+ (`assemble --out work` writes `work/rig/stage-map.json`). Omitted or `false`
4603
+ disables it. Reusing an output directory with the option off removes its old map.
4604
+ The observer shares the aggregate classifier and leaves the other output bytes
4605
+ unchanged.
4606
+
4607
+ The JSON schema is `rig-parts-stage-map/1`. `rig_size` gives the rig width and
4608
+ height. `automatic` maps stage names to negative writer IDs. Positive ID `n`
4609
+ resolves to `edits[n - 1]`. Zero means final RGBA equals the part's original
4610
+ normalized source at the same rig-grid coordinate. `-2147483648` means excluded,
4611
+ final alpha at most 8. Other negative IDs name the last value-changing writer,
4612
+ including the explicit `unattributed` stage when lineage is unavailable.
4613
+
4614
+ `parts` follows the output draw order. Each row has `name`, `x`, `y`, `w`, `h`,
4615
+ `excluded_px` and `runs`. Each run is `[writer ID, length]`, with positive integer
4616
+ length. Expand runs consecutively in row-major order across row boundaries into
4617
+ exactly `w * h` cells. Cell index `k` is at rig coordinate
4618
+ `(x + k % w, y + floor(k / w))`, top-left origin, y down. Excluded cells have
4619
+ an independent count. The remaining histogram equals `unchanged_layer_px`,
4620
+ `hand_px`, `automatic_px` and every edit/stage subtotal in the part's provenance.
4621
+ `alternates`, when present, contains `{name, map}` rows with the same schema and
4622
+ only the records emitted for that set. Their part names match the alternate's
4623
+ `records`, and its `slots` resolve the emitted PNG names.
4624
+
4625
+ `pre_seam_writer_runs` uses the same RLE layout. Where the last-writer channel
4626
+ is `seamOverride`, it records the buffer's writer immediately before that seam
4627
+ change. Elsewhere `-2147483647` means no surviving override, and excluded cells
4628
+ use `-2147483648`. In this companion channel, zero means the prior buffer had
4629
+ no recorded writer. The writer before the seam override is a sparse boundary
4630
+ observation of that boundary alone. Only `runs`
4631
+ reconciles with aggregate provenance. A seam change that restores the raw
4632
+ source is classified unchanged and has no surviving override in this report.
4633
+
4634
+ Only final alpha above 8 is attributed. Cleared pixels and transient writes are
4635
+ outside this report. A final value restored to its original source is unchanged.
4636
+ A pixel changed by `seamOverride` after `paintingEdge` is attributed to
4637
+ `seamOverride`. The map records attribution and cannot determine intent.
4638
+
4599
4639
  ### Source before scissors
4600
4640
 
4601
4641
  <a id="source-before-scissors-issue-819"></a>
package/docs/STABILITY.md CHANGED
@@ -153,7 +153,7 @@ part name, `[i]` an entry of a list):
153
153
  - **generation.control.skeleton**, the pose file it names when it is no built-in — required: `width`, `height`, `points`
154
154
  - **seethrough** — required: `resolution`, `steps`, `seed`, `offload`; optional: `head_box`, `arm_split`
155
155
  - **seethrough.arm_split** — required: `order`, and one of `x` or `line` (issue #439)
156
- - **assemble** — required: `rig_scale`, `plan` (from plain `assemble` on); optional: `seam`, `project`, `ground`, `extend_below_crop`, `patches`, `cuts`, `alternates`, `head_face_underfill`, `yield_refused`, `keep_under_occluders`, `require_hidden_extent`, `extend_painting`, `take`, `editor_receipts`
156
+ - **assemble** — required: `rig_scale`, `plan` (from plain `assemble` on); optional: `seam`, `project`, `ground`, `extend_below_crop`, `patches`, `cuts`, `alternates`, `head_face_underfill`, `yield_refused`, `stage_map`, `keep_under_occluders`, `require_hidden_extent`, `extend_painting`, `take`, `editor_receipts`
157
157
  - **assemble.require_hidden_extent[i]** — required: `part`, `occluder`
158
158
  - **assemble.alternates[i]** — required: `name`; optional: `source`, `full`, `head`, `parts`, `hides`, `head_box`, `cuts`, `skeleton`, `anchor`, `base_anchor`, `drawn`, `tips`, `front`, `layers`, `focus` (issues #454, #465, #543, #652, #664, #666, #719, #780). `focus` is an authored finite `[x, y]` in painting pixels, within its canvas (edges included), refused as CONFIG_SET_FOCUS before assemble output when invalid; only when present, `parts.json` records it with focus_source_size and `sets.json` emits it in setup-world coordinates through the actual rig resize and `src/coords.ts`. Absent focus emits no field or inferred value; changing/removing it requires reassembly
159
159
  - **assemble.extend_below_crop[i]** — required: `part`, `run`, `tag`; optional: `edges` (left, right, top, bottom; explicit edges require a head-run part and the full-run layer of the same tag)
@@ -299,6 +299,7 @@ resolution before resizing; it can differ for non-opaque paintings.
299
299
 
300
300
  | file | written by | what is stable |
301
301
  | --- | --- | --- |
302
+ | `stage-map.json` | `assemble`, `build`, under `assemble.stage_map: true` | `rig-parts-stage-map/1`, cropped last-writer and pre-seam RLE maps with writer dictionaries and excluded counts. See [Per-pixel stage map](AUTHORING.md#per-pixel-stage-map). |
302
303
  | `parts.json`, `parts/<name>.png` | `assemble`, `build` | one record per part: `from` (`<run>:<tag>` with a See-through v3 tag, `<run>:author:<label>` for a layer the author made — issue #256, read by no role rule — or `painting:<name>` for a patch), `cut_from` on a cut's piece only (the plan part it was cut from, issue #230), `limb` on a limb segment's part only (issue #349: `name`, `segment`, `of`, `bone`, and below a joint `joint`, `range` when the config segment declares one (issue #360), and `cap` — `at`, `width`, `radius`, `box`, `layer_px`, `image_px` with a cap image, `image_layer` after it when that image was a hidden-art layer — issue #359, `<run>:<layer>:hidden` — `missing_px`, `short_px` (`left`, `right`) after it only when `missing_px` is above 0 (issue #557, additive), `excluded_px` after them only on a subset set's limb part whose cap the set exclusion took a pixel of (issue #603, additive: each pixel taken out of the count it was in, so the cap's counts are the written PNG's), then `shape` and `upper_px` under the segment's `cap_shape` — `upper_px` without the shape only when the upper segment gave a pixel (issue #557, additive) — and after them `lower_px`, `lower_kept_px` and `lower_missing_px` under `cap_shape: "ball"` (issue #579, additive), and `edge`, `feather_radius` and `feathered_px` under its `edge`, and `cut_band`, `cut_offset`, `cut_at`, `cut_crossed`, `joint_crossed`, `band_px` and `stroke_luma_max` (when the band has a split) under its `cut_band`, issue #360), the box `x`, `y`, `w`, `h` (rig px), the pixel counts `src/parts.ts` documents (`opaque_px`, `visible_px`, `occluded_px`, `projected_core_px`, `source_px_taken`, `visible_not_projected_px`, `refused_drift_px`, `merged_px` — on a subset set's limb part counted after the set exclusion, issue #603 — `seam_override_px`, and `fringe_pushed_back` when not empty); per-part `provenance` (`unchanged_layer_px`, `hand_px`, `automatic_px`, `edits`, `automatic`, additive, issue #823); optional top-level `motion_seams`, `alternates` and `cut_ownership` (one row per cut, independent of RGBA equality, issue #823); `rig_size`, `scale_rig_per_source`, `ghost_px`, `recomposite`, and `scene` (`figure_alpha_above`, `figure_px`, `figure_mask`) under `config.scene` only, with the figure's mask `figure_rig.png` beside the recomposite (issue #242); `single_run_pad` (`file_size`, `side`, `left`, `top`) last, only for one run whose file is not the `seethrough.resolution` square (issue #366) |
303
304
  | `rig/rig.json`, `rig/motion.json`, `rig/images/` | `rig`, `build`, `compose` | rig-c's rig spec and motion spec, `spec` `rigc-rig/1` and `rigc-motion/1`: the format is rig-c's, and this package writes only what rig-c's parser accepts; a bone carries `inherit` only where config.bones declares one, rig-c's mode name as written (issue #348) |
304
305
  | `rig/mesh_report.json` | `rig`, `build` | one row per mesh: `part`, `vertices`, `triangles`, `hull`, `bones` (the sorted names the attachment's weights bind in the written `rig.json`, in every mode — since 1.49.1 (issue #536) a rig with `turn` or `stops` names the twins and `<link>_d` bones there, where the row named the segment bones they replace: a fix of a wrong name, not a format change; a rig with neither writes the bytes it wrote), `max_influences`, `mean_influences`, `art_coverage`, then `grid` (a lattice); or `mode` "explicit" with `image_sha256` and `region_sha256` (the verified guards; counts and coverage are measured from the supplied mesh, no legacy generator report is adopted); `mode` "contour" with `params`, `contour`, `regions` (`params.maxEdge` and `contour.outlineCut` only when the mesh declares `contour.maxEdge`; `params.bridges` and `contour.bridges` — `islands`, `units`, `joins`, and `faint` only when an island was left out as faint — only when it declares `contour.bridges`); or `mode` "influence" with `influence` (as declared), `reach` (`farthest`, `at`, `nearest`, `capped`, `widest`) and `lattice` (rig-c's `SegmentsLatticeReport`: `cols`, `rows`, `artCells`, `keptCells`, `passes`, `islands`) (issue #378); or `mode` "auto" with `settings`, `source`, `result`, `residuals`, `worst_residual`, `worst_region`, `motion_amplitude`, `termination`, `weights`, `regions`, `deformation`, `quality_report` (rig-c's `mesh-quality-report/1` document whole), `motion_report`, and, only when they apply, `stray_cleared` (after `source`, when `source.stray` is declared), `skinning_residual` and `replay` (`AutoMeshReport` in `src/rig.ts`); in every mode, `exponent` when the mesh declares one (after `grid`, or after `mode`); `influences`, as declared, when a lattice or contour mesh declares it (after `exponent`, or where `exponent` would be); `stray` and `stray_cleared` when a lattice mesh declares `stray` (after `influences`, or where `influences` would be); `ribs` when a contour or auto mesh declares them (after `exponent`, or after `mode`), and then `contour.ribs` (`source.contour.ribs` in the automatic mode) |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "spine-parts",
3
- "version": "2.21.0",
3
+ "version": "2.22.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
  "bin": {
package/src/assemble.ts CHANGED
@@ -10,7 +10,7 @@ import { materialSource, type MaterialSource, materialRows, polygonMaterialEdges
10
10
  import { unionTakenSources } from './takesource.ts';
11
11
  import { authoredUnitDepths, type AuthoredUnitDepth } from './authoredunit.ts';
12
12
  import { paintingExtensionMasks, paintingExtensionProblems, type PaintingExtension } from './paintingextension.ts';
13
- import { AUTOMATIC_WRITERS as AW, compactValueBaseline, pixelProvenance, rgbaEqual, type ValueBaseline } from './provenance.ts';
13
+ import { AUTOMATIC_WRITERS as AW, compactValueBaseline, pixelProvenance, rgbaEqual, type ValueBaseline, type StageMap } from './provenance.ts';
14
14
  import { bindDepthRun, copyDepthMaterial, registerDepthRun, transportPartDepth, type DepthConfig, type RegisteredDepth } from './depthsheets.ts';
15
15
  /**
16
16
  * The assemble stage: two See-through runs over one painting — a FULL-body run
@@ -364,6 +364,8 @@ export interface AssembleInput {
364
364
  headFaceUnderfill?: boolean;
365
365
  /** `assemble.yield_refused`, default false; transfer of refused cores/rims, finishing nearby accepted projection RGB. */
366
366
  yieldRefused?: boolean;
367
+ /** Report-only last-writer sidecar, default off. */
368
+ stageMap?: boolean;
367
369
  /** Plan parts whose own samples survive source re-take beneath soft front cover. */
368
370
  keepUnderOccluders?: readonly string[];
369
371
  /** Original selected material must cover its enclosed holes beneath this source pair. */
@@ -4720,6 +4722,8 @@ export function softOcclusionLine(r: SoftOcclusionReading): string {
4720
4722
  }
4721
4723
 
4722
4724
  export interface AssembleResult {
4725
+ /** Compressed per-pixel classification, present only when requested. */
4726
+ stageMap?: StageMap;
4723
4727
  /** The already-resampled opaque painting used by this assembly. */
4724
4728
  paintingInRig: Raster;
4725
4729
  /** Report-only residual candidates, present after the visible edge pass. */
@@ -6023,16 +6027,48 @@ function assembleParts(input: AssembleInput, targets?: ReadonlySet<string>, befo
6023
6027
  const map = runMap(frame, run), dx = single ? frame.fullPad : 0, dy = single ? frame.fullPadTop : 0;
6024
6028
  for (const layer of set.layers) if (layer.regionSelection !== undefined) regionSupport.set(`${run}:${layer.name}`, warpSupport(layer.regionSelection, { sx: map.sx, sy: map.sx, tx: map.tx + dx * map.sx, ty: map.ty + dy * map.sx }, W, H, map.k < 1 ? 'bilinear' : 'bicubic'));
6025
6029
  }
6026
- seamOverride(placed, srcr, seamRule, seamRule === 'silhouette' ? silhouette : null, keepInOrder, input.turnMovingPair ?? null, (i, p) => { writersInOrder[i][p] = AW.seamOverride; }, counterfactual === undefined ? undefined : beforeTake === null ? { record: counterfactual.seam } : { baseline: counterfactual.seam, support: regionSupport });
6030
+ const preSeamWriters = input.stageMap === true ? new Map<number, Map<number, number>>() : undefined;
6031
+ seamOverride(placed, srcr, seamRule, seamRule === 'silhouette' ? silhouette : null, keepInOrder, input.turnMovingPair ?? null, (i, p) => {
6032
+ if (preSeamWriters !== undefined) {
6033
+ const changed = preSeamWriters.get(i) ?? new Map<number, number>();
6034
+ changed.set(p, writersInOrder[i][p]);
6035
+ preSeamWriters.set(i, changed);
6036
+ }
6037
+ writersInOrder[i][p] = AW.seamOverride;
6038
+ }, counterfactual === undefined ? undefined : beforeTake === null ? { record: counterfactual.seam } : { baseline: counterfactual.seam, support: regionSupport });
6039
+ const stageMap: StageMap | undefined = input.stageMap !== true ? undefined : {
6040
+ schema: 'rig-parts-stage-map/1', rig_size: [W, H], automatic: AW, edits: [...editNames], parts: [],
6041
+ };
6027
6042
  placed.forEach((p, i) => {
6028
- p.record.provenance = pixelProvenance(p.image, p.record.x, p.record.y, W, writersInOrder[i], editNames, 0, valueBaselines.get(p.record.from) ?? null);
6043
+ const map = stageMap === undefined ? undefined : {
6044
+ name: p.record.name, x: p.record.x, y: p.record.y, w: p.record.w, h: p.record.h,
6045
+ excluded_px: 0, runs: [] as Array<[number, number]>, pre_seam_writer_runs: [] as Array<[number, number]>,
6046
+ };
6047
+ p.record.provenance = pixelProvenance(p.image, p.record.x, p.record.y, W, writersInOrder[i], editNames, 0, valueBaselines.get(p.record.from) ?? null, map, preSeamWriters?.get(i));
6048
+ if (map !== undefined) stageMap!.parts.push(map);
6029
6049
  const depth = authoredDepths.get(p.record.name);
6030
6050
  if (depth !== undefined) p.record.provenance.depth = depth;
6031
6051
  });
6032
- if (beforeTake !== null) retainRegionNeighbours(placed, beforeTake.images, targets!);
6052
+ if (beforeTake !== null) {
6053
+ retainRegionNeighbours(placed, beforeTake.images, targets!);
6054
+ if (stageMap !== undefined) stageMap.parts = stageMap.parts.map(p => {
6055
+ if (targets!.has(p.name)) return p;
6056
+ const previous = beforeTake.stageMap!;
6057
+ const original = previous.parts.find(q => q.name === p.name)!;
6058
+ const remap = ([id, length]: [number, number]): [number, number] => {
6059
+ if (id <= 0) return [id, length];
6060
+ const edit = previous.edits[id - 1];
6061
+ let index = stageMap.edits.indexOf(edit);
6062
+ if (index < 0) { index = stageMap.edits.length; stageMap.edits.push(edit); }
6063
+ return [index + 1, length];
6064
+ };
6065
+ return { ...original, runs: original.runs.map(remap), pre_seam_writer_runs: original.pre_seam_writer_runs.map(remap) };
6066
+ });
6067
+ }
6033
6068
  // Provenance is now numbers/labels only. No later raster/figure operation
6034
6069
  // reads report buffers; release all aliases before recomposite/error work.
6035
6070
  valueBaselines.clear();
6071
+ preSeamWriters?.clear();
6036
6072
  writersInOrder.length = 0;
6037
6073
  patchWriters.length = 0;
6038
6074
  for (const group of [built, pieces, cutSources, limbPieces]) for (const b of group) if (b !== null) b.writers = undefined;
@@ -6070,6 +6106,7 @@ function assembleParts(input: AssembleInput, targets?: ReadonlySet<string>, befo
6070
6106
  ...(softOcclusion.length === 0 ? {} : { softOcclusion }),
6071
6107
  ...(!single ? { cropClipped: cropClippedLines(plan, extend, (run, tag) => rig.get(`${run}:${tag}`) ?? null, frame) } : {}),
6072
6108
  paintingInRig: srcr,
6109
+ ...(stageMap === undefined ? {} : { stageMap }),
6073
6110
  parts: {
6074
6111
  rig_size: [W, H],
6075
6112
  scale_rig_per_source: frame.S,
@@ -7008,6 +7045,8 @@ export function stageFields(
7008
7045
  headFaceUnderfill?: boolean;
7009
7046
  /** `assemble.yield_refused`, default false; transfer of refused cores/rims, finishing nearby accepted projection RGB. */
7010
7047
  yieldRefused?: boolean;
7048
+ /** Report-only last-writer sidecar, default off. */
7049
+ stageMap?: boolean;
7011
7050
  /** Plan parts whose own samples survive source re-take beneath soft front cover. */
7012
7051
  keepUnderOccluders?: readonly string[];
7013
7052
  /** Original selected material must cover its enclosed holes beneath this source pair. */
@@ -7041,6 +7080,7 @@ export function stageFields(
7041
7080
  ...(keySkeleton === undefined ? {} : { keySkeleton }),
7042
7081
  ...(cfg.assemble.head_face_underfill === undefined ? {} : { headFaceUnderfill: cfg.assemble.head_face_underfill }),
7043
7082
  ...(cfg.assemble.yield_refused === undefined ? {} : { yieldRefused: cfg.assemble.yield_refused }),
7083
+ ...(cfg.assemble.stage_map === undefined ? {} : { stageMap: cfg.assemble.stage_map }),
7044
7084
  ...(cfg.assemble.keep_under_occluders === undefined ? {} : { keepUnderOccluders: cfg.assemble.keep_under_occluders }),
7045
7085
  ...(cfg.assemble.require_hidden_extent === undefined ? {} : { requireHiddenExtent: cfg.assemble.require_hidden_extent }),
7046
7086
  ...(cfg.assemble.ground === undefined ? {} : { ground: cfg.assemble.ground }),
package/src/build.ts CHANGED
@@ -1,3 +1,4 @@
1
+ import { STAGE_MAP_FILE } from './provenance.ts';
1
2
  import { withoutCheckRows } from './checkrow.ts';
2
3
  import { readSetupFigureMask } from './setupfiguremask.ts';
3
4
  import { EDGE_RESIDUAL_FILE, edgeResidualLines } from './edgeresidual.ts';
@@ -727,6 +728,7 @@ export function assembleStage(input: AssembleStageInput, outs: AssembleOutputs,
727
728
  ...(fields.armSplit !== undefined && altPlan.some((e) => e[1] === 'full' && (e[2] === 'handwear-r' || e[2] === 'handwear-l')) ? { armSplit: fields.armSplit } : {}),
728
729
  ...(fields.headFaceUnderfill === undefined ? {} : { headFaceUnderfill: fields.headFaceUnderfill }),
729
730
  ...(fields.yieldRefused === undefined ? {} : { yieldRefused: fields.yieldRefused }),
731
+ ...(fields.stageMap === undefined ? {} : { stageMap: fields.stageMap }),
730
732
  ...(fields.ground === undefined ? {} : { ground: fields.ground }),
731
733
  ...(alternateFigure === undefined ? {} : { declaredFigure: alternateFigure }),
732
734
  ...(fields.turnMovingPair === undefined ? {} : { turnMovingPair: fields.turnMovingPair }),
@@ -753,6 +755,10 @@ export function assembleStage(input: AssembleStageInput, outs: AssembleOutputs,
753
755
  .filter(({ record }) => coveredSet.has(record.name))
754
756
  .flatMap(({ record, image, depthImage }) => [{ name: `${alt.name}_${record.name}`, image }, ...(depthImage === undefined || record.depth === undefined ? [] : [{ name: `${alt.name}_${record.depth.image.slice(0, -4)}`, image: depthImage }])]);
755
757
  const keptRecords = altRes.parts.parts.filter((p) => coveredSet.has(p.name)).map(p => p.depth === undefined ? p : { ...p, depth: { ...p.depth, image: `${alt.name}_${p.depth.image}` } });
758
+ if (result.stageMap !== undefined && altRes.stageMap !== undefined) {
759
+ altRes.stageMap.parts = altRes.stageMap.parts.filter(p => coveredSet.has(p.name));
760
+ (result.stageMap.alternates ??= []).push({ name: alt.name, map: altRes.stageMap });
761
+ }
756
762
  const slots: Record<string, string> = {};
757
763
  for (const r of keptRecords) slots[altFront.has(r.name) ? `${r.name}${FRONT_SUFFIX}` : r.name] = `${alt.name}_${r.name}`;
758
764
  let altRecomposite = altRes.parts.recomposite as RecompositeRecord;
@@ -834,6 +840,9 @@ export function assembleStage(input: AssembleStageInput, outs: AssembleOutputs,
834
840
  sha256: createHash('sha256').update(paintingBytes).digest('hex'), resample: 'lanczos3-rgb-opaque' };
835
841
  writeFileSync(join(dirname(outs.partsJson), PAINTING_IN_RIG_FILE), paintingBytes);
836
842
  writeParts(outs.partsJson, result.parts);
843
+ const stageMapPath = join(dirname(outs.partsJson), STAGE_MAP_FILE);
844
+ if (result.stageMap === undefined) rmSync(stageMapPath, { force: true });
845
+ else writeFileSync(stageMapPath, JSON.stringify(result.stageMap) + '\n');
837
846
  const residualPath = join(dirname(outs.partsJson), EDGE_RESIDUAL_FILE);
838
847
  if (result.edgeResiduals === undefined) rmSync(residualPath, { force: true });
839
848
  else writeFileSync(residualPath, JSON.stringify(result.edgeResiduals, null, 2) + '\n');
package/src/config.ts CHANGED
@@ -332,6 +332,8 @@ export interface Assemble {
332
332
  head_face_underfill?: boolean;
333
333
  /** Opt-in: yield original drift-refused front cores and connected non-core rims to an opaque behind holder matching the painting. */
334
334
  yield_refused?: boolean;
335
+ /** Emit the report-only last-writer sidecar; absent or false is off. */
336
+ stage_map?: boolean;
335
337
  /** Named plan parts retain their own pixels beneath a drawn-in-front soft occluder. */
336
338
  keep_under_occluders?: string[];
337
339
  /** Require original material in enclosed source holes beneath a named moving cover. */
@@ -1674,7 +1676,7 @@ export interface EarlyConfig {
1674
1676
  depth?: DepthConfig;
1675
1677
  key: string;
1676
1678
  seethrough: SeeThrough;
1677
- assemble: { rig_scale: number; seam?: SeamRule; project?: ProjectRule; ground?: Ground; take?: TakeDeclaration[]; editor_receipts?: EditorReceipts; head_face_underfill?: boolean; yield_refused?: boolean; keep_under_occluders?: string[]; require_hidden_extent?: HiddenExtentDeclaration[]; extend_painting?: PaintingExtension[] };
1679
+ assemble: { rig_scale: number; seam?: SeamRule; project?: ProjectRule; ground?: Ground; take?: TakeDeclaration[]; editor_receipts?: EditorReceipts; head_face_underfill?: boolean; yield_refused?: boolean; stage_map?: boolean; keep_under_occluders?: string[]; require_hidden_extent?: HiddenExtentDeclaration[]; extend_painting?: PaintingExtension[] };
1678
1680
  }
1679
1681
 
1680
1682
  /** What plain `assemble` reads: the early config plus the plan `--propose-plan` printed. */
@@ -1752,13 +1754,16 @@ function parseEarlyConfigFrom(raw: Json, door: EarlyDoor, base: string | null, p
1752
1754
  if (door === 'layers') {
1753
1755
  if ('seethrough' in t) checkSeeThrough(c, t.seethrough);
1754
1756
  if ('assemble' in t) {
1755
- const a = c.object('config.assemble', t.assemble, sectionRequired(door, 'assemble'), ['plan', 'extend_below_crop', 'patches', 'cuts', 'alternates', 'head_face_underfill', 'yield_refused', 'keep_under_occluders', 'require_hidden_extent', 'extend_painting', 'take', 'seam', 'project', 'ground', 'editor_receipts']);
1757
+ const a = c.object('config.assemble', t.assemble, sectionRequired(door, 'assemble'), ['plan', 'extend_below_crop', 'patches', 'cuts', 'alternates', 'head_face_underfill', 'yield_refused', 'stage_map', 'keep_under_occluders', 'require_hidden_extent', 'extend_painting', 'take', 'seam', 'project', 'ground', 'editor_receipts']);
1756
1758
  if (a !== null) {
1757
1759
  checkAssembleRules(c, a);
1758
1760
  if ('rig_scale' in a) c.number('config.assemble.rig_scale', a.rig_scale, 'positive');
1759
1761
  if ('head_face_underfill' in a && typeof a.head_face_underfill !== 'boolean') {
1760
1762
  c.fail('CONFIG_FIELD_TYPE', 'config.assemble.head_face_underfill', `is ${show(a.head_face_underfill)}; true or false is required`);
1761
1763
  }
1764
+ if ('stage_map' in a && typeof a.stage_map !== 'boolean') {
1765
+ c.fail('CONFIG_FIELD_TYPE', 'config.assemble.stage_map', `is ${show(a.stage_map)}; true or false is required`);
1766
+ }
1762
1767
  checkKeepUnderOccluders(c, a, null);
1763
1768
  checkRequiredHiddenExtent(c, a, null);
1764
1769
  if ('extend_painting' in a) checkPaintingExtensions(c, a.extend_painting);
@@ -2627,7 +2632,7 @@ function checkAssembleRules(c: Check, a: Record<string, Json>): void {
2627
2632
 
2628
2633
  function checkAssemble(c: Check, v: Json, door: 'assemble' | 'full'): { parts: string[]; patches: string[]; cuts: string[] } {
2629
2634
  const required = sectionRequired(door, 'assemble');
2630
- const a = c.object('config.assemble', v, required.filter((k) => k !== 'plan'), ['plan', 'extend_below_crop', 'patches', 'cuts', 'alternates', 'head_face_underfill', 'yield_refused', 'keep_under_occluders', 'require_hidden_extent', 'extend_painting', 'take', 'seam', 'project', 'ground', 'editor_receipts']);
2635
+ const a = c.object('config.assemble', v, required.filter((k) => k !== 'plan'), ['plan', 'extend_below_crop', 'patches', 'cuts', 'alternates', 'head_face_underfill', 'yield_refused', 'stage_map', 'keep_under_occluders', 'require_hidden_extent', 'extend_painting', 'take', 'seam', 'project', 'ground', 'editor_receipts']);
2631
2636
  if (a === null) return { parts: [], patches: [], cuts: [] };
2632
2637
  checkAssembleRules(c, a);
2633
2638
  if (required.includes('plan') && !('plan' in a)) {
@@ -2641,6 +2646,9 @@ function checkAssemble(c: Check, v: Json, door: 'assemble' | 'full'): { parts: s
2641
2646
  if ('yield_refused' in a && typeof a.yield_refused !== 'boolean') {
2642
2647
  c.fail('CONFIG_FIELD_TYPE', `${p}.yield_refused`, `is ${show(a.yield_refused)}; true or false is required`);
2643
2648
  }
2649
+ if ('stage_map' in a && typeof a.stage_map !== 'boolean') {
2650
+ c.fail('CONFIG_FIELD_TYPE', `${p}.stage_map`, `is ${show(a.stage_map)}; true or false is required`);
2651
+ }
2644
2652
  const parts: string[] = [];
2645
2653
  if ('plan' in a && c.array(`${p}.plan`, a.plan, true)) {
2646
2654
  const seenPart = new Map<string, number>();
package/src/provenance.ts CHANGED
@@ -11,6 +11,32 @@ export const AUTOMATIC_WRITERS = {
11
11
  seamOverride: -9, armSplit: -10, headFaceUnderfill: -11, ghostCleanup: -12, unattributed: -13, paintingExtension: -14, paintingEdge: -15,
12
12
  } as const;
13
13
  export type AutomaticWriter = keyof typeof AUTOMATIC_WRITERS;
14
+ /** Sidecar codes share provenance's writer IDs. Excluded has a separate code. */
15
+ export const EXCLUDED_PIXEL = -2147483648;
16
+ export const NOT_OVERRIDDEN_PIXEL = -2147483647;
17
+ export const STAGE_MAP_FILE = 'stage-map.json';
18
+ export interface PartStageMap {
19
+ name: string;
20
+ x: number;
21
+ y: number;
22
+ w: number;
23
+ h: number;
24
+ excluded_px: number;
25
+ /** [writer ID, run length], row-major in the cropped part, across row boundaries. */
26
+ runs: Array<[number, number]>;
27
+ /** Prior buffer writer only where a final seamOverride classification survives. */
28
+ pre_seam_writer_runs: Array<[number, number]>;
29
+ }
30
+ export interface StageMap {
31
+ schema: 'rig-parts-stage-map/1';
32
+ rig_size: [number, number];
33
+ automatic: typeof AUTOMATIC_WRITERS;
34
+ /** Positive ID n resolves to edits[n - 1]. */
35
+ edits: string[];
36
+ parts: PartStageMap[];
37
+ alternates?: Array<{ name: string; map: StageMap }>;
38
+ }
39
+
14
40
  export interface PixelProvenance {
15
41
  /** Scalar transport omitted only for fully explicit unit consumers (#877). */
16
42
  depth?: AuthoredUnitDepth;
@@ -43,14 +69,21 @@ export function compactValueBaseline(raw: Raster): ValueBaseline {
43
69
  /** Value equality with the raw normalized See-through baseline wins first.
44
70
  * Otherwise the last stage that CHANGED RGBA wins; buffer copies inherit IDs.
45
71
  * A null baseline is explicit for authored layers/painting patches. */
46
- export function pixelProvenance(image: Raster, x: number, y: number, width: number, writers: Int32Array | null, edits: readonly string[], patchId = 0, baseline: Raster | ValueBaseline | null = null): PixelProvenance {
72
+ export function pixelProvenance(image: Raster, x: number, y: number, width: number, writers: Int32Array | null, edits: readonly string[], patchId = 0, baseline: Raster | ValueBaseline | null = null, map?: PartStageMap, beforeSeam?: ReadonlyMap<number, number>): PixelProvenance {
47
73
  const out: PixelProvenance = { unchanged_layer_px: 0, hand_px: 0, automatic_px: 0, edits: [], automatic: [] };
48
74
  const counts = new Map<number, number>();
49
75
  const reference = baseline === null ? null : 'image' in baseline ? baseline.image : baseline;
50
76
  const bx = baseline !== null && 'image' in baseline ? baseline.x : 0;
51
77
  const by = baseline !== null && 'image' in baseline ? baseline.y : 0;
52
78
  for (let j = 0; j < image.height; j++) for (let i = 0; i < image.width; i++) {
53
- if (image.data[(j * image.width + i) * 4 + 3] <= OPAQUE_ALPHA_ABOVE) continue;
79
+ if (image.data[(j * image.width + i) * 4 + 3] <= OPAQUE_ALPHA_ABOVE) {
80
+ if (map !== undefined) {
81
+ appendStageRun(map.runs, EXCLUDED_PIXEL);
82
+ appendStageRun(map.pre_seam_writer_runs, EXCLUDED_PIXEL);
83
+ map.excluded_px++;
84
+ }
85
+ continue;
86
+ }
54
87
  const q = (y + j) * width + x + i;
55
88
  const u = x + i - bx, v = y + j - by;
56
89
  const same = reference !== null && u >= 0 && v >= 0 && u < reference.width && v < reference.height &&
@@ -58,6 +91,11 @@ export function pixelProvenance(image: Raster, x: number, y: number, width: numb
58
91
  const previous = writers?.[q] ?? patchId;
59
92
  // Unknown lineage is reported explicitly, never invented as unchanged.
60
93
  const id = same ? 0 : previous === 0 ? AUTOMATIC_WRITERS.unattributed : previous;
94
+ if (map !== undefined) {
95
+ appendStageRun(map.runs, id);
96
+ appendStageRun(map.pre_seam_writer_runs, id === AUTOMATIC_WRITERS.seamOverride
97
+ ? beforeSeam?.get(q) ?? NOT_OVERRIDDEN_PIXEL : NOT_OVERRIDDEN_PIXEL);
98
+ }
61
99
  if (id > 0) out.hand_px++;
62
100
  else if (id < 0) out.automatic_px++;
63
101
  else out.unchanged_layer_px++;
@@ -68,6 +106,13 @@ export function pixelProvenance(image: Raster, x: number, y: number, width: numb
68
106
  return out;
69
107
  }
70
108
 
109
+ /** Append directly to compressed output without a second rig-grid buffer. */
110
+ function appendStageRun(runs: Array<[number, number]>, id: number): void {
111
+ const last = runs[runs.length - 1];
112
+ if (last !== undefined && last[0] === id) last[1]++;
113
+ else runs.push([id, 1]);
114
+ }
115
+
71
116
  /** The reader and selftests share this arithmetic check; no hand-edit gate. */
72
117
  export function provenanceAddsUp(p: PixelProvenance, opaque: number): boolean {
73
118
  return p.unchanged_layer_px + p.hand_px + p.automatic_px === opaque &&