@rig-c/parts 2.26.1 → 2.27.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/src/plate.ts ADDED
@@ -0,0 +1,459 @@
1
+ /**
2
+ * Step-4 plates (issue #1183): the figure-removed background and the
3
+ * foreground matte of a full-screen painting, each with a machine receipt.
4
+ *
5
+ * Everything here is pure — no clock, no randomness, no network — so the
6
+ * purity scan covers it. The one part that drives a GPU box, the background
7
+ * inpainting run, lives in `src/comfy/plate.ts` and carries the graphs this
8
+ * file builds.
9
+ *
10
+ * 🔒 **The mask comes from a source, never a hand polygon.** Two sources are
11
+ * read, and nothing else:
12
+ *
13
+ * - `seethrough:<dir>`: a See-through run in the wrapper form (`layers.json`
14
+ * and `parts/`), the figure being every drawn layer's alpha above
15
+ * `OPAQUE_ALPHA_ABOVE`, on the run's own canvas;
16
+ * - `figure-mask:<dir>`: an assemble output whose `parts.json` declares a
17
+ * `scene`, the figure being the `figure_rig.png` assemble wrote beside it
18
+ * (opaque white inside the figure, opaque black outside).
19
+ *
20
+ * The mask is taken on its own grid and never fitted: a source whose grid is
21
+ * not the painting's size is refused by name. With no source the command
22
+ * refuses before it writes anything or reaches a box.
23
+ *
24
+ * The receipt (`rig-parts-plate-receipt/1`) names the painting, the mask, the
25
+ * model, every parameter, the graph, the GPU and the output, with the sha256
26
+ * of every file it names; `verifyPlateReceipt` reads it back against the bytes
27
+ * on disk. Every path in it is relative to the receipt's own directory.
28
+ */
29
+ import { createHash } from 'node:crypto';
30
+ import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
31
+ import { basename, dirname, join, relative, resolve } from 'node:path';
32
+ import { PartsError, type Problem } from './errors.ts';
33
+ import type { Graph } from './graphs.ts';
34
+ import { OPAQUE_ALPHA_ABOVE, readWrapperLayers } from './layers.ts';
35
+ import { FIGURE_MASK_FILE } from './parts.ts';
36
+ import { decodePngBytes, encodePngBytes } from './raster/png.ts';
37
+ import { newRaster, type Raster } from './raster/types.ts';
38
+
39
+ export const PLATE_RECEIPT_SPEC = 'rig-parts-plate-receipt/1';
40
+ export const PLATE_RECEIPT_FILE = 'receipt.json';
41
+ export const PLATE_MASK_FILE = 'mask.png';
42
+ export const PLATE_OUTPUT_FILE = 'plate.png';
43
+
44
+ /** The receipt's top-level keys, in the order they are written. */
45
+ export const PLATE_RECEIPT_KEYS = ['spec', 'mode', 'painting', 'mask', 'model', 'params', 'graph', 'gpu', 'output'] as const;
46
+
47
+ export type PlateMode = 'background' | 'foreground';
48
+ export type PlateGraph = 'lama' | 'core';
49
+ export type MaskSource = 'seethrough' | 'figure-mask';
50
+
51
+ /** The graph ids a receipt names: one per background graph, and the fixed local id of the foreground derivation. */
52
+ export const PLATE_GRAPH_IDS = {
53
+ lama: 'rig-parts/plate-background-lama/1',
54
+ core: 'rig-parts/plate-background-core/1',
55
+ foreground: 'rig-parts/plate-foreground/1',
56
+ } as const;
57
+
58
+ /** The inpainting model the `lama` graph loads unless `--model` names another. */
59
+ export const LAMA_MODEL = 'big-lama.pt';
60
+ /** Square dilation radius of the figure mask before inpainting, in painting px. */
61
+ export const DEFAULT_GROW_PX = 8;
62
+
63
+ export interface PlateReceipt {
64
+ spec: typeof PLATE_RECEIPT_SPEC;
65
+ mode: PlateMode;
66
+ painting: { path: string; sha256: string };
67
+ mask: { source: MaskSource; from: string; path: string; sha256: string };
68
+ model: { name: string; checkpoint_sha256: string; checkpoint_sha256_from: 'declared' } | null;
69
+ params: Record<string, string | number | boolean>;
70
+ graph: string;
71
+ gpu: string | null;
72
+ output: { path: string; sha256: string };
73
+ }
74
+
75
+ function fail(code: string, object: string, detail: string): never {
76
+ throw new PartsError([{ code, object, detail }]);
77
+ }
78
+
79
+ export function sha256(bytes: Uint8Array): string {
80
+ return createHash('sha256').update(bytes).digest('hex');
81
+ }
82
+
83
+ /** `--checkpoint-sha256`: 64 hex characters, stored lower-case; anything else is refused by name. */
84
+ export function declaredChecksum(value: string | undefined): string {
85
+ if (value === undefined) fail('PLATE_CHECKPOINT_SHA256', '--checkpoint-sha256', 'is absent; the sha256 of the model file the box loads, 64 hex characters, is required — the box does not report a hash, so the receipt records this declared value');
86
+ if (!/^[0-9a-fA-F]{64}$/.test(value)) fail('PLATE_CHECKPOINT_SHA256', '--checkpoint-sha256', `is ${JSON.stringify(value)}; 64 hex characters are required`);
87
+ return value.toLowerCase();
88
+ }
89
+
90
+ /** `--mask-from <source>:<dir>`, parsed; an absent or unknown source is refused by name. */
91
+ export function parseMaskFrom(value: string | undefined): { source: MaskSource; dir: string } {
92
+ if (value === undefined) {
93
+ fail('PLATE_MASK_SOURCE', '--mask-from', 'is absent; a source mask is required — seethrough:<run dir> (run `rig-parts comfy seethrough` on the painting) or figure-mask:<assemble out dir> (run `assemble` with config.scene); a hand-drawn mask is not taken');
94
+ }
95
+ const m = /^(seethrough|figure-mask):(.+)$/.exec(value);
96
+ if (m === null) fail('PLATE_MASK_SOURCE', '--mask-from', `is ${JSON.stringify(value)}; seethrough:<dir> or figure-mask:<dir> is required`);
97
+ return { source: m[1] as MaskSource, dir: m[2] };
98
+ }
99
+
100
+ /** One byte per painting pixel, 1 inside the figure. */
101
+ export interface FigureMask {
102
+ width: number;
103
+ height: number;
104
+ inside: Uint8Array;
105
+ }
106
+
107
+ /**
108
+ * The figure mask from its source, on its own grid. Refused by name: a source
109
+ * directory that holds no mask (the missing tool named), a grid that is not
110
+ * `width`x`height`, a `figure_rig.png` that is not the two values assemble
111
+ * writes, and a mask with no figure pixel.
112
+ */
113
+ export function readSourceMask(source: MaskSource, dir: string, width: number, height: number): FigureMask {
114
+ if (!existsSync(dir) || !statSync(dir).isDirectory()) {
115
+ fail('PLATE_MASK_SOURCE', `${source}:${dir}`, `is not a directory; ${source === 'seethrough' ? 'a See-through run directory (from `rig-parts comfy seethrough`)' : 'an assemble output directory with parts.json and figure_rig.png'} is required`);
116
+ }
117
+ const inside = new Uint8Array(width * height);
118
+ if (source === 'seethrough') {
119
+ if (!existsSync(join(dir, 'layers.json'))) fail('PLATE_MASK_SOURCE', `${source}:${dir}`, 'holds no layers.json; the figure layers of a See-through run are required — run `rig-parts comfy seethrough` on the painting first');
120
+ const set = readWrapperLayers(dir);
121
+ if (set.canvas.w !== width || set.canvas.h !== height) {
122
+ fail('PLATE_MASK_GRID', `${source}:${dir}`, `is a ${set.canvas.w}x${set.canvas.h} canvas; the painting's ${width}x${height} is required — the mask is never fitted, so run See-through on the painting at its own size`);
123
+ }
124
+ for (const l of set.layers) {
125
+ const w = l.right - l.left;
126
+ for (let y = 0; y < l.bottom - l.top; y++) {
127
+ const cy = l.top + y;
128
+ if (cy < 0 || cy >= height) continue;
129
+ for (let x = 0; x < w; x++) {
130
+ const cx = l.left + x;
131
+ if (cx < 0 || cx >= width) continue;
132
+ if (l.pixels.data[(y * w + x) * 4 + 3] > OPAQUE_ALPHA_ABOVE) inside[cy * width + cx] = 1;
133
+ }
134
+ }
135
+ }
136
+ } else {
137
+ const partsPath = join(dir, 'parts.json');
138
+ if (!existsSync(partsPath)) fail('PLATE_MASK_SOURCE', `${source}:${dir}`, 'holds no parts.json; an assemble output with config.scene is required — run `assemble` on the painting first');
139
+ let scene: unknown;
140
+ try {
141
+ scene = (JSON.parse(readFileSync(partsPath, 'utf8')) as Record<string, unknown>).scene;
142
+ } catch (err) {
143
+ return fail('PLATE_MASK_SOURCE', partsPath, `does not parse as JSON (${(err as Error).message})`);
144
+ }
145
+ if (typeof scene !== 'object' || scene === null || (scene as Record<string, unknown>).figure_mask !== FIGURE_MASK_FILE) {
146
+ fail('PLATE_MASK_SOURCE', partsPath, `declares no scene figure mask; a parts.json whose scene.figure_mask is "${FIGURE_MASK_FILE}" is required — assemble writes it under config.scene`);
147
+ }
148
+ const maskPath = join(dir, FIGURE_MASK_FILE);
149
+ if (!existsSync(maskPath)) fail('PLATE_MASK_SOURCE', maskPath, 'no such file; parts.json declares it, and assemble writes it beside parts.json');
150
+ const r = decodePngBytes(new Uint8Array(readFileSync(maskPath)), maskPath);
151
+ if (r.width !== width || r.height !== height) {
152
+ fail('PLATE_MASK_GRID', maskPath, `is ${r.width}x${r.height}; the painting's ${width}x${height} is required — the rig grid is not the painting's when the rig is scaled, and the mask is never fitted`);
153
+ }
154
+ for (let p = 0; p < width * height; p++) {
155
+ const [R, G, B, A] = [r.data[p * 4], r.data[p * 4 + 1], r.data[p * 4 + 2], r.data[p * 4 + 3]];
156
+ const white = R === 255 && G === 255 && B === 255, black = R === 0 && G === 0 && B === 0;
157
+ if (A !== 255 || (!white && !black)) fail('PLATE_MASK_VALUES', maskPath, `holds (${R}, ${G}, ${B}, ${A}) at pixel ${p % width},${Math.floor(p / width)}; only opaque white and opaque black, as assemble writes it, are taken`);
158
+ if (white) inside[p] = 1;
159
+ }
160
+ }
161
+ if (!inside.some((v) => v === 1)) fail('PLATE_MASK_EMPTY', `${source}:${dir}`, 'holds no figure pixel on the painting grid; a figure to remove or matte is required');
162
+ return { width, height, inside };
163
+ }
164
+
165
+ /** The mask grown by a square of side `2r+1` (two separable passes): a halo of the figure's outline is inpainted too. */
166
+ export function growMask(mask: FigureMask, r: number): FigureMask {
167
+ if (r === 0) return { ...mask, inside: mask.inside.slice() };
168
+ const { width: W, height: H } = mask;
169
+ const rows = new Uint8Array(W * H);
170
+ for (let y = 0; y < H; y++) {
171
+ let last = -Infinity;
172
+ for (let x = 0; x < W; x++) {
173
+ if (mask.inside[y * W + x] === 1) last = x;
174
+ if (x - last <= r) rows[y * W + x] = 1;
175
+ }
176
+ last = Infinity;
177
+ for (let x = W - 1; x >= 0; x--) {
178
+ if (mask.inside[y * W + x] === 1) last = x;
179
+ if (last - x <= r) rows[y * W + x] = 1;
180
+ }
181
+ }
182
+ const out = new Uint8Array(W * H);
183
+ for (let x = 0; x < W; x++) {
184
+ let last = -Infinity;
185
+ for (let y = 0; y < H; y++) {
186
+ if (rows[y * W + x] === 1) last = y;
187
+ if (y - last <= r) out[y * W + x] = 1;
188
+ }
189
+ last = Infinity;
190
+ for (let y = H - 1; y >= 0; y--) {
191
+ if (rows[y * W + x] === 1) last = y;
192
+ if (last - y <= r) out[y * W + x] = 1;
193
+ }
194
+ }
195
+ return { width: W, height: H, inside: out };
196
+ }
197
+
198
+ /** The mask as the PNG written beside the plate and uploaded to the box: opaque white inside, opaque black outside (LoadImageMask reads its red channel). */
199
+ export function maskImage(mask: FigureMask): Raster {
200
+ const r = newRaster(mask.width, mask.height);
201
+ for (let p = 0; p < mask.inside.length; p++) {
202
+ const v = mask.inside[p] === 1 ? 255 : 0;
203
+ r.data.set([v, v, v, 255], p * 4);
204
+ }
205
+ return r;
206
+ }
207
+
208
+ /**
209
+ * The background plate: the box's pixels inside the mask (opaque), the
210
+ * painting's own bytes outside it. The paste-back is done here, not on the
211
+ * box, so a pixel outside the mask is the painting's byte for byte whatever
212
+ * the box's float round trip did to it.
213
+ */
214
+ export function pasteInside(painting: Raster, inpainted: Raster, mask: FigureMask): Raster {
215
+ const out = newRaster(painting.width, painting.height);
216
+ out.data.set(painting.data);
217
+ for (let p = 0; p < mask.inside.length; p++) {
218
+ if (mask.inside[p] !== 1) continue;
219
+ out.data.set([inpainted.data[p * 4], inpainted.data[p * 4 + 1], inpainted.data[p * 4 + 2], 255], p * 4);
220
+ }
221
+ return out;
222
+ }
223
+
224
+ /** The foreground plate: the painting's own pixels inside the mask, transparent zero outside. A deterministic derivation, no model. */
225
+ export function foregroundMatte(painting: Raster, mask: FigureMask): Raster {
226
+ const out = newRaster(painting.width, painting.height);
227
+ for (let p = 0; p < mask.inside.length; p++) if (mask.inside[p] === 1) out.data.set(painting.data.subarray(p * 4, p * 4 + 4), p * 4);
228
+ return out;
229
+ }
230
+
231
+ // ---------------------------------------------------------------------------
232
+ // the two background graphs
233
+ // ---------------------------------------------------------------------------
234
+
235
+ export interface LamaParams {
236
+ seed: number;
237
+ grow_px: number;
238
+ }
239
+
240
+ export interface CoreParams {
241
+ seed: number;
242
+ grow_px: number;
243
+ steps: number;
244
+ cfg: number;
245
+ sampler: string;
246
+ scheduler: string;
247
+ denoise: number;
248
+ prompt: string;
249
+ negative: string;
250
+ }
251
+
252
+ export const CORE_DEFAULTS = { steps: 30, cfg: 6.0, sampler: 'euler_ancestral', scheduler: 'normal', denoise: 1.0, prompt: 'scenery, background, no humans', negative: 'person, figure, human, character, text, watermark' } as const;
253
+
254
+ /**
255
+ * `lama`: LoadImage + LoadImageMask -> INPAINT_LoadInpaintModel ->
256
+ * INPAINT_InpaintWithModel -> SaveImage (the comfyui-inpaint-nodes pack and
257
+ * its LaMa model).
258
+ */
259
+ export function lamaPlateGraph(painting: string, mask: string, model: string, p: LamaParams, prefix: string): Graph {
260
+ return {
261
+ '1': { class_type: 'LoadImage', inputs: { image: painting } },
262
+ '2': { class_type: 'LoadImageMask', inputs: { image: mask, channel: 'red' } },
263
+ '3': { class_type: 'INPAINT_LoadInpaintModel', inputs: { model_name: model } },
264
+ '4': { class_type: 'INPAINT_InpaintWithModel', inputs: { inpaint_model: ['3', 0], image: ['1', 0], mask: ['2', 0], seed: p.seed } },
265
+ '5': { class_type: 'SaveImage', inputs: { images: ['4', 0], filename_prefix: prefix } },
266
+ };
267
+ }
268
+
269
+ /**
270
+ * `core`: ComfyUI's own nodes only — the checkpoint, the two text encoders,
271
+ * InpaintModelConditioning over the painting and the mask (noise masked),
272
+ * KSampler, VAEDecode, SaveImage. The paste-back is `pasteInside`.
273
+ */
274
+ export function corePlateGraph(painting: string, mask: string, checkpoint: string, p: CoreParams, prefix: string): Graph {
275
+ return {
276
+ '1': { class_type: 'LoadImage', inputs: { image: painting } },
277
+ '2': { class_type: 'LoadImageMask', inputs: { image: mask, channel: 'red' } },
278
+ '3': { class_type: 'CheckpointLoaderSimple', inputs: { ckpt_name: checkpoint } },
279
+ '4': { class_type: 'CLIPTextEncode', inputs: { text: p.prompt, clip: ['3', 1] } },
280
+ '5': { class_type: 'CLIPTextEncode', inputs: { text: p.negative, clip: ['3', 1] } },
281
+ '6': { class_type: 'InpaintModelConditioning', inputs: { positive: ['4', 0], negative: ['5', 0], vae: ['3', 2], pixels: ['1', 0], mask: ['2', 0], noise_mask: true } },
282
+ '7': {
283
+ class_type: 'KSampler',
284
+ inputs: { model: ['3', 0], seed: p.seed, steps: p.steps, cfg: p.cfg, sampler_name: p.sampler, scheduler: p.scheduler, denoise: p.denoise, positive: ['6', 0], negative: ['6', 1], latent_image: ['6', 2] },
285
+ },
286
+ '8': { class_type: 'VAEDecode', inputs: { samples: ['7', 0], vae: ['3', 2] } },
287
+ '9': { class_type: 'SaveImage', inputs: { images: ['8', 0], filename_prefix: prefix } },
288
+ };
289
+ }
290
+
291
+ /** The `core` graph encodes through the VAE, which crops to multiples of 8; a painting off that grid is refused before anything is uploaded. */
292
+ export function coreGridProblem(width: number, height: number, painting: string): Problem | null {
293
+ return width % 8 === 0 && height % 8 === 0 ? null : { code: 'PLATE_CORE_GRID', object: painting, detail: `is ${width}x${height}; the core graph needs both sides a multiple of 8 (the VAE crops otherwise) — use --graph lama, or a painting on that grid` };
294
+ }
295
+
296
+ // ---------------------------------------------------------------------------
297
+ // the receipt
298
+ // ---------------------------------------------------------------------------
299
+
300
+ /** The receipt's JSON text, its keys in `PLATE_RECEIPT_KEYS` order. */
301
+ export function receiptText(r: PlateReceipt): string {
302
+ const ordered: Record<string, unknown> = {};
303
+ for (const k of PLATE_RECEIPT_KEYS) ordered[k] = r[k];
304
+ return `${JSON.stringify(ordered, null, 2)}\n`;
305
+ }
306
+
307
+ /** A path as the receipt writes it: relative to the receipt's directory, POSIX separators. */
308
+ export function receiptPath(receiptDir: string, path: string): string {
309
+ return relative(resolve(receiptDir), resolve(path)).split('\\').join('/');
310
+ }
311
+
312
+ /**
313
+ * Every problem between a receipt and the bytes on disk: its spec and key
314
+ * order, and each of the painting, mask and output whose sha256 is not that of
315
+ * the file it names (or whose file is gone).
316
+ */
317
+ export function verifyPlateReceipt(receiptFile: string): Problem[] {
318
+ const problems: Problem[] = [];
319
+ let r: Record<string, unknown>;
320
+ try {
321
+ r = JSON.parse(readFileSync(receiptFile, 'utf8')) as Record<string, unknown>;
322
+ } catch (err) {
323
+ return [{ code: 'PLATE_RECEIPT_READ', object: receiptFile, detail: `does not parse as JSON (${(err as Error).message})` }];
324
+ }
325
+ if (r.spec !== PLATE_RECEIPT_SPEC) problems.push({ code: 'PLATE_RECEIPT_SPEC', object: receiptFile, detail: `has spec ${JSON.stringify(r.spec)}; "${PLATE_RECEIPT_SPEC}" is required` });
326
+ const keys = Object.keys(r).join(',');
327
+ if (keys !== PLATE_RECEIPT_KEYS.join(',')) problems.push({ code: 'PLATE_RECEIPT_KEYS', object: receiptFile, detail: `has keys ${keys}; ${PLATE_RECEIPT_KEYS.join(',')} in that order is required` });
328
+ const base = dirname(receiptFile);
329
+ for (const field of ['painting', 'mask', 'output'] as const) {
330
+ const f = r[field] as { path?: unknown; sha256?: unknown } | undefined;
331
+ if (typeof f?.path !== 'string' || typeof f.sha256 !== 'string') {
332
+ problems.push({ code: 'PLATE_RECEIPT_KEYS', object: `${receiptFile} ${field}`, detail: 'lacks a path and a sha256' });
333
+ continue;
334
+ }
335
+ const file = join(base, f.path);
336
+ if (!existsSync(file)) {
337
+ problems.push({ code: 'PLATE_RECEIPT_FILE', object: `${receiptFile} ${field}`, detail: `names ${f.path}, which does not exist` });
338
+ continue;
339
+ }
340
+ const found = sha256(new Uint8Array(readFileSync(file)));
341
+ if (found !== f.sha256) problems.push({ code: 'PLATE_RECEIPT_HASH', object: `${receiptFile} ${field}`, detail: `records sha256 ${f.sha256} for ${f.path}; the file on disk has ${found}` });
342
+ }
343
+ return problems;
344
+ }
345
+
346
+ /** Encode a raster to PNG and return the bytes with their sha256. */
347
+ export function pngWithHash(r: Raster): { bytes: Uint8Array; sha256: string } {
348
+ const bytes = encodePngBytes(r);
349
+ return { bytes, sha256: sha256(bytes) };
350
+ }
351
+
352
+ // ---------------------------------------------------------------------------
353
+ // writing a plate
354
+ // ---------------------------------------------------------------------------
355
+
356
+ /** An `--out` that is absent or empty; anything else is refused, so one run's plate is never mixed with another's receipt. */
357
+ export function assertPlateOutFree(out: string): void {
358
+ if (existsSync(out) && (!statSync(out).isDirectory() || readdirSync(out).length > 0)) {
359
+ fail('PLATE_OUT_EMPTY', out, 'is a file or a directory that holds entries; an absent or empty directory is required');
360
+ }
361
+ }
362
+
363
+ /** What a run hands the writer: the mask and plate rasters, and the receipt less what the writer measures. */
364
+ export interface PlateWrite {
365
+ out: string;
366
+ /** A name that is this run's own, for the staging directory beside `out`. */
367
+ stageTag: string;
368
+ mode: PlateMode;
369
+ paintingPath: string;
370
+ paintingBytes: Uint8Array;
371
+ source: MaskSource;
372
+ sourceDir: string;
373
+ mask: FigureMask;
374
+ plate: Raster;
375
+ model: PlateReceipt['model'];
376
+ params: PlateReceipt['params'];
377
+ graph: string;
378
+ gpu: string | null;
379
+ }
380
+
381
+ /**
382
+ * Write `mask.png`, `plate.png` and `receipt.json` into a staging directory
383
+ * beside `out`, read the receipt back against the bytes on disk, and only
384
+ * then move the directory to `out`. A receipt that does not verify is never
385
+ * left at the path a later stage reads.
386
+ */
387
+ export function publishPlate(w: PlateWrite): PlateReceipt {
388
+ const parent = dirname(resolve(w.out));
389
+ mkdirSync(parent, { recursive: true });
390
+ const stage = join(parent, `.${basename(resolve(w.out))}.partial-${w.stageTag}`);
391
+ mkdirSync(stage, { recursive: true });
392
+ try {
393
+ const mask = pngWithHash(maskImage(w.mask));
394
+ const plate = pngWithHash(w.plate);
395
+ writeFileSync(join(stage, PLATE_MASK_FILE), mask.bytes);
396
+ writeFileSync(join(stage, PLATE_OUTPUT_FILE), plate.bytes);
397
+ const receipt: PlateReceipt = {
398
+ spec: PLATE_RECEIPT_SPEC,
399
+ mode: w.mode,
400
+ painting: { path: receiptPath(w.out, w.paintingPath), sha256: sha256(w.paintingBytes) },
401
+ mask: { source: w.source, from: receiptPath(w.out, w.sourceDir), path: PLATE_MASK_FILE, sha256: mask.sha256 },
402
+ model: w.model,
403
+ params: w.params,
404
+ graph: w.graph,
405
+ gpu: w.gpu,
406
+ output: { path: PLATE_OUTPUT_FILE, sha256: plate.sha256 },
407
+ };
408
+ writeFileSync(join(stage, PLATE_RECEIPT_FILE), receiptText(receipt));
409
+ const problems = verifyPlateReceipt(join(stage, PLATE_RECEIPT_FILE));
410
+ if (problems.length > 0) throw new PartsError(problems);
411
+ if (existsSync(w.out)) rmdirSync(w.out);
412
+ renameSync(stage, w.out);
413
+ return receipt;
414
+ } finally {
415
+ if (existsSync(stage)) rmSync(stage, { recursive: true, force: true });
416
+ }
417
+ }
418
+
419
+ /** A painting read for a plate: its bytes as on disk (hashed into the receipt) and its pixels. */
420
+ export function readPlatePainting(path: string): { bytes: Uint8Array; raster: Raster } {
421
+ if (!existsSync(path)) fail('PLATE_PAINTING_PRESENT', path, 'no such file; the painting the plate is made from is required');
422
+ const bytes = new Uint8Array(readFileSync(path));
423
+ return { bytes, raster: decodePngBytes(bytes, path) };
424
+ }
425
+
426
+ export interface ForegroundRun {
427
+ painting: string;
428
+ maskFrom: string | undefined;
429
+ out: string;
430
+ }
431
+
432
+ /**
433
+ * `comfy plate --mode foreground`: no box and no model. The source mask is
434
+ * read first (refused by name, nothing written, when there is none), then the
435
+ * painting's pixels inside it are written with alpha, transparent zero
436
+ * outside, with a receipt whose `model` and `gpu` are null and whose `graph`
437
+ * is the fixed local id.
438
+ */
439
+ export function runForeground(run: ForegroundRun): PlateReceipt {
440
+ const from = parseMaskFrom(run.maskFrom);
441
+ const painting = readPlatePainting(run.painting);
442
+ const mask = readSourceMask(from.source, from.dir, painting.raster.width, painting.raster.height);
443
+ assertPlateOutFree(run.out);
444
+ return publishPlate({
445
+ out: run.out,
446
+ stageTag: 'foreground',
447
+ mode: 'foreground',
448
+ paintingPath: run.painting,
449
+ paintingBytes: painting.bytes,
450
+ source: from.source,
451
+ sourceDir: from.dir,
452
+ mask,
453
+ plate: foregroundMatte(painting.raster, mask),
454
+ model: null,
455
+ params: { mask_alpha_above: OPAQUE_ALPHA_ABOVE },
456
+ graph: PLATE_GRAPH_IDS.foreground,
457
+ gpu: null,
458
+ });
459
+ }
package/src/rig.ts CHANGED
@@ -140,7 +140,7 @@ import { explicitAttachment, type ExplicitMeshReport } from './explicitmesh.ts';
140
140
  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';
141
141
  import { RUNTIME_PI } from '@rig-c/core/core';
142
142
  import { type BoneTransform, computeExactFrameTransforms, computeWorldTransforms, cropToSpineY, normaliseDegrees, paintingToSetupPoint, setupToPaintingPoint, toBoneLocal, toWorld } from './coords.ts';
143
- import { type Problem, refuseIfAny, PartsError } from './errors.ts';
143
+ import { foldName, type Problem, refuseIfAny, PartsError } from './errors.ts';
144
144
  import { recordedFocusProblems } from './setfocus.ts';
145
145
  import { eyeLineDegrees } from './headframe.ts';
146
146
  import type { RigBoneInherit, RigStop } from '@rig-c/core/rig';
@@ -1612,7 +1612,7 @@ export function buildWaistPairSource(
1612
1612
  if (bl !== undefined) problems.push(...blinkHoldProblems(BLINK.shut, BLINK.hold, IDLE_FPS));
1613
1613
  // ---- blink.still: a blinking region cut at a row ----------------------
1614
1614
  const stills = bl?.still ?? {};
1615
- const partNames = new Set(parts.parts.map((p) => p.name));
1615
+ const partNames = new Map(parts.parts.map((p) => [foldName(p.name), p.name]));
1616
1616
  for (const [part, st] of Object.entries(stills)) {
1617
1617
  const at = `config.motion.blink.still.${part}`;
1618
1618
  const p = byPart.get(part);
@@ -1620,7 +1620,7 @@ export function buildWaistPairSource(
1620
1620
  if (!B.has(st.bone)) fail('RIG_NAME_RESOLVES', `${at}.bone`, `names the bone "${st.bone}", which config.bones does not declare`);
1621
1621
  if (p === undefined) continue;
1622
1622
  const still = `${part}${STILL_SUFFIX}`;
1623
- if (partNames.has(still)) fail('RIG_STILL_NAME_FREE', at, `the still piece is drawn by the slot "${still}", and parts.json already holds a part of that name; rename that part`);
1623
+ if (partNames.has(foldName(still))) fail('RIG_STILL_NAME_FREE', at, `the still piece is drawn by the slot "${still}" ("${still}.png"), and parts.json already holds part "${partNames.get(foldName(still))}" ("${partNames.get(foldName(still))}.png"); rename that part`);
1624
1624
  if (!(st.row > p.y && st.row < p.y + p.h)) {
1625
1625
  fail('RIG_STILL_ROW_INSIDE_PART', `${at}.row`, `is ${st.row}; "${part}" spans rows ${p.y}..${p.y + p.h - 1}, so a row with part rows on both sides, ${p.y + 1}..${p.y + p.h - 1}, is required`);
1626
1626
  continue;
@@ -1925,8 +1925,8 @@ export function buildWaistPairSource(
1925
1925
  const outImages: Array<[string, Raster]> = [];
1926
1926
  const depthReferences: NonNullable<RigOutput['depthReferences']> = [];
1927
1927
  const emitDepth = (part: string, reference: PartDepthReference, scalar: Raster): void => {
1928
- if (outImages.some(([file]) => file === reference.image)) {
1929
- fail('DEPTH_SHEET_UNAMBIGUOUS', reference.image, 'collides with an emitted asset; choose noncolliding part/sheet names');
1928
+ const prev = outImages.find(([file]) => foldName(file) === foldName(reference.image)); if (prev !== undefined) {
1929
+ fail('DEPTH_SHEET_UNAMBIGUOUS', reference.image, `part "${part}" sheet "${reference.image}" and "${prev[0]}" collides with an emitted asset; choose noncolliding part/sheet names`);
1930
1930
  return;
1931
1931
  }
1932
1932
  const art = images.get(part);
@@ -2461,7 +2461,7 @@ export function buildWaistPairSource(
2461
2461
  if (scalar === undefined) fail('DEPTH_SHEET_PRESENT', p.depth.image, `part "${p.name}" declares a sheet; the unpadded source sheet must be handed to buildRig`);
2462
2462
  else {
2463
2463
  problems.push(...depthSheetProblems(scalar, [p.w, p.h], p.depth.image));
2464
- if (parts.parts.some(q => `${q.name}.png` === p.depth?.image)) fail('DEPTH_SHEET_UNAMBIGUOUS', p.depth.image, 'collides with artwork; use noncolliding part names');
2464
+ const hit = parts.parts.find(q => foldName(`${q.name}.png`) === foldName(p.depth!.image)); if (hit !== undefined) fail('DEPTH_SHEET_UNAMBIGUOUS', p.depth.image, `part "${p.name}" sheet "${p.depth.image}" and part "${hit.name}" ("${hit.name}.png") collides with artwork; use noncolliding part names`);
2465
2465
  else if (cfg.meshes[p.name] !== undefined || stills[p.name] === undefined) emitDepth(p.name, p.depth, scalar);
2466
2466
  }
2467
2467
  }
@@ -3648,9 +3648,9 @@ export function buildWaistPairSource(
3648
3648
  // decide which drawing or measurement survives on disk.
3649
3649
  const assetIndices = new Map<string, number>();
3650
3650
  outImages.forEach(([file], index) => {
3651
- const previous = assetIndices.get(file);
3652
- if (previous !== undefined) fail('DEPTH_SHEET_UNAMBIGUOUS', file, `output assets[${previous}] and [${index}] require the same filename; choose distinct base, still, alternate and sheet names`);
3653
- else assetIndices.set(file, index);
3651
+ const previous = assetIndices.get(foldName(file));
3652
+ if (previous !== undefined) fail('DEPTH_SHEET_UNAMBIGUOUS', file, `output assets[${previous}] ("${outImages[previous][0]}") and [${index}] ("${file}") require the same filename; choose distinct base, still, alternate and sheet names`);
3653
+ else assetIndices.set(foldName(file), index);
3654
3654
  });
3655
3655
  refuseIfAny(problems);
3656
3656
  const name = `${cfg.key}_painting`;