spine-parts 2.27.2 → 2.29.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
@@ -24,7 +24,7 @@ import { proposeNeck } from './tools/neck-propose.ts';
24
24
  import { parseAltArg } from './tools/alternate-cli.ts';
25
25
  import { type AlternateCliInput, assembleStage, build, checkStage, ERROR_MAP_FILE, loopStage, readRuns, readSource, rigStage, suppliedCheckFlag } from './src/build.ts';
26
26
  import { ACCEPTABLE_BARS, DEFAULT_PACK_SHAPE, DEFAULT_PAGE_EDGES, findRigc, PACK_SHAPES, rigcRunnerAt, type PackShape, PAGE_EDGES, type PageEdges, PARTS_HOME_SENTENCE, RIGC_GEOMETRY_VERSION, rigcRanClause, type RigcRunner, NO_PARTS_SENTENCE, SEAM_MEAN_BAR, SOURCE_SENTENCE, SEAM_PX_BAR, SEAM_PX_LEVEL, SPINEBOY_YARDSTICK, TEXTURE_STRETCH_CEILING } from './src/check.ts';
27
- import { ComfyClient, resolveHost, runBackground, runPainting, runSeeThrough } from './src/comfy/index.ts';
27
+ import { ComfyClient, resolveHost, runBackground, runMatte, runPainting, runSeeThrough } from './src/comfy/index.ts';
28
28
  import { DEFAULT_GROW_PX, runForeground } from './src/plate.ts';
29
29
  import { type CharacterConfig, loadClothConfig, loadConfig, loadEarlyConfig, loadPaintConfig } from './src/config.ts';
30
30
  import { configWriteLines, readConfigWriteTarget, separateConfigWriteTarget, stageConfigWrite, type StagedConfigWrite } from './tools/configwrite.ts';
@@ -868,8 +868,17 @@ usage:
868
868
  is set. The pose words are generation.pose, or the control skeleton's own.
869
869
  The config needs only key and generation here; the rest comes later.
870
870
 
871
+ rig-parts comfy matte --painting <png> --out <dir>
872
+ --node BiRefNetRMBG --model BiRefNet-HR-matting --checkpoint-sha256 <hex>
873
+ [--resolution 1024] [--threshold 10] [--host <url>]
874
+ [--wait 1800] [--timeout 3600] [--poll 3]
875
+ A receipted model source: raw model-mask.png, painting-grid mask.png and
876
+ receipt.json. No blur, dilation or cleanup. Threshold is grayscale > value;
877
+ non-square inputs use the recorded square transform, square uploads stay
878
+ unchanged. A selector alone is not installation: model files are checked.
879
+
871
880
  rig-parts comfy plate --mode background|foreground --painting <png>
872
- --mask-from seethrough:<dir>|figure-mask:<dir> --out <dir>
881
+ --mask-from seethrough:<dir>|figure-mask:<dir>|matte:<dir> --out <dir>
873
882
  [--graph lama|core] [--model <name>] [--checkpoint-sha256 <hex>]
874
883
  [--seed 0] [--grow 8] [--steps 30] [--prompt <text>] [--negative <text>]
875
884
  [--host <url>] [--wait 1800] [--timeout 3600] [--poll 3]
@@ -1171,6 +1180,7 @@ const TAKES = {
1171
1180
  assemble: { valued: ['--source', '--full', '--head', '--config', '--out', '--seam', '--project', '--alt', '--write-config', '--requirements'], switches: ['--propose-plan'] },
1172
1181
  'comfy seethrough': { valued: ['--image', '--out', '--resolution', '--steps', '--seed', '--prefix', '--host', '--wait', '--timeout', '--poll', '--config', '--depth-run'], switches: ['--offload', '--no-offload', '--lama', '--nf4'] },
1173
1182
  'comfy paint': { valued: ['--config', '--out', '--seeds', '--seed0', '--host', '--wait', '--timeout', '--poll'], switches: [] },
1183
+ 'comfy matte': { valued: ['--painting', '--out', '--node', '--model', '--checkpoint-sha256', '--resolution', '--threshold', '--host', '--wait', '--timeout', '--poll'], switches: [] },
1174
1184
  'comfy plate': { valued: ['--mode', '--painting', '--mask-from', '--out', '--graph', '--model', '--checkpoint-sha256', '--seed', '--grow', '--steps', '--prompt', '--negative', '--host', '--wait', '--timeout', '--poll'], switches: [] },
1175
1185
  inputs: { valued: ['--source', '--config', '--out'], switches: [] },
1176
1186
  build: { valued: ['--config', '--source', '--full', '--head', '--out', '--seam', '--project', '--page-edges', '--pack-shape', '--requirements', '--idle-keys', '--lead-in', '--alt', '--set', '--environment', '--wind-band'], switches: ['--loop', '--seam-pairs', '--keep-stills', '--all-sets', '--no-extremes'] },
@@ -1922,7 +1932,7 @@ function cmdAssemble(args: string[]): number {
1922
1932
  }
1923
1933
 
1924
1934
  /** Parse `--flag value` pairs and bare `--switch`es, as the command's {@link TAKES} row names them; a string is a usage error. */
1925
- function comfyFlags(args: string[], command: 'comfy seethrough' | 'comfy paint' | 'comfy plate'): { v: Map<string, string>; on: Set<string> } | string {
1935
+ function comfyFlags(args: string[], command: 'comfy seethrough' | 'comfy paint' | 'comfy plate' | 'comfy matte'): { v: Map<string, string>; on: Set<string> } | string {
1926
1936
  const switches: readonly string[] = TAKES[command].switches;
1927
1937
  const v = new Map<string, string>();
1928
1938
  const on = new Set<string>();
@@ -2003,12 +2013,34 @@ async function cmdComfyPlate(v: Map<string, string>): Promise<number> {
2003
2013
  }
2004
2014
  }
2005
2015
 
2016
+ async function cmdComfyMatte(v: Map<string, string>): Promise<number> {
2017
+ const painting = v.get('--painting');
2018
+ const out = v.get('--out');
2019
+ if (painting === undefined || out === undefined) return usage('comfy matte needs --painting <png> and --out <dir>');
2020
+ const resolution = intFlag(v, '--resolution', 1024, 64);
2021
+ const threshold = intFlag(v, '--threshold', 10, 0);
2022
+ const wait = secondsFlag(v, '--wait', 1800);
2023
+ const timeout = secondsFlag(v, '--timeout', 3600);
2024
+ const poll = secondsFlag(v, '--poll', 3);
2025
+ for (const n of [resolution, threshold, wait, timeout, poll]) if (typeof n === 'string') return usage(n);
2026
+ try {
2027
+ const receipt = await runMatte(
2028
+ () => new ComfyClient(resolveHost(v.get('--host'), process.env.COMFY_HOST), { poll: poll as number, request: 30 }),
2029
+ { painting, out, node: v.get('--node'), model: v.get('--model'), checkpointSha256: v.get('--checkpoint-sha256'), resolution: resolution as number, threshold: threshold as number, wait: wait as number, timeout: timeout as number },
2030
+ line => console.log(line),
2031
+ );
2032
+ console.log(` wrote model-mask.png, mask.png and receipt.json; mask sha256 ${receipt.output.sha256}; checkpoint sha256 declared`);
2033
+ return EXIT_OK;
2034
+ } catch (err) { return printRefusal(err); }
2035
+ }
2036
+
2006
2037
  async function cmdComfy(args: string[]): Promise<number> {
2007
2038
  const [sub, ...rest] = args;
2008
- if (sub !== 'seethrough' && sub !== 'paint' && sub !== 'plate') return usage(`comfy takes seethrough, paint or plate; got ${sub === undefined ? 'nothing' : `"${sub}"`}`);
2039
+ if (sub !== 'seethrough' && sub !== 'paint' && sub !== 'plate' && sub !== 'matte') return usage(`comfy takes seethrough, paint, plate or matte; got ${sub === undefined ? 'nothing' : `"${sub}"`}`);
2009
2040
  const f = comfyFlags(rest, `comfy ${sub}`);
2010
2041
  if (typeof f === 'string') return usage(f);
2011
2042
  if (sub === 'plate') return cmdComfyPlate(f.v);
2043
+ if (sub === 'matte') return cmdComfyMatte(f.v);
2012
2044
  const { v, on } = f;
2013
2045
  if (on.has('--offload') && on.has('--no-offload')) return usage('--offload and --no-offload cannot be combined');
2014
2046
  const wait = secondsFlag(v, '--wait', 1800);
package/docs/AUTHORING.md CHANGED
@@ -5355,8 +5355,12 @@ or a joint.
5355
5355
  inpaints it on a ComfyUI box. `--graph lama` (the default) uses the
5356
5356
  comfyui-inpaint-nodes pack and its LaMa model (`--model`, default
5357
5357
  `big-lama.pt`). `--graph core` uses ComfyUI's own nodes and the checkpoint
5358
- `--model` names, with `--steps`, `--prompt` and `--negative`; it needs a
5359
- painting whose sides are multiples of 8. Every node, input and model of the
5358
+ `--model` names, with `--steps`, `--prompt` and `--negative`; when a painting's
5359
+ width or height is not a multiple of 8, it pads the uploaded painting (`edge-replicate`)
5360
+ and grown mask (`zero`, kept as context) on the right and bottom (`pad: [0, 0]`)
5361
+ to the next multiple of 8, crops the box's output back at `[0, 0]` before
5362
+ pasting inside the mask, and records `grid_transform` in `receipt.json`
5363
+ (on-grid paintings run unpadded and omit `grid_transform`). Every node, input and model of the
5360
5364
  graph is checked against the box's `/object_info` before anything is
5361
5365
  uploaded, so a box without the pack refuses `lama` and still runs `core`. The
5362
5366
  job is appended behind any other job: never put in front, nothing reordered,
@@ -5379,28 +5383,37 @@ plate pass from this command is a recorded source step, not a repair.
5379
5383
  ### See-through mask grid mapping
5380
5384
 
5381
5385
  For non-square paintings, `comfy seethrough` prepares the configured square
5382
- before upload and records `input_transform` in `meta.json`, bound to the
5383
- original PNG by `image_sha256`. `seethrough:` samples the union of layer
5384
- alpha masks at transformed painting pixel centres with nearest sampling,
5385
- using the recorded offsets and scale. Exactness holds for representable
5386
- masks, and detail below the See-through grid's resolution is not recovered.
5387
- The model receives the padded area as opaque black RGB because LoadImage
5388
- separates alpha and GenerateLayers adds opaque alpha. The old wrapper-internal
5389
- pad was transparent, so non-square model inputs differ from before.
5390
- Square uploads omit the transform and retain the existing path. A legacy
5391
- run on another grid still refuses `PLATE_MASK_GRID`; regenerate it through
5392
- `comfy seethrough` to obtain a recorded transform. The record fields and
5393
- sampling formula are specified in [STABILITY](STABILITY.md).
5386
+ before upload and records `input_transform` (`pad_fill: "rgba-zero"`) in
5387
+ `meta.json`, bound to the original PNG by `image_sha256` (readers also accept
5388
+ `pad_fill: "rgb-black-opaque"` from 2.27.2 records). `seethrough:` samples the
5389
+ union of layer alpha masks at transformed painting pixel centres with nearest
5390
+ sampling, using the recorded offsets and scale. Exactness holds for
5391
+ representable masks, and detail below the See-through grid's resolution is not
5392
+ recovered. `workflows/seethrough.json` rejoins `LoadImage`'s `IMAGE` and `MASK`
5393
+ through `JoinImageWithAlpha` before `SeeThrough_GenerateLayers`, so the padded
5394
+ area reaches the model with transparent alpha (`alpha = 0`). Square uploads
5395
+ omit the transform and retain the existing upload bytes (an opaque square
5396
+ reaches the model unchanged; a square carrying transparent pixels now forwards
5397
+ its alpha through `JoinImageWithAlpha`). A legacy run on another grid still
5398
+ refuses `PLATE_MASK_GRID`; regenerate it through `comfy seethrough` to obtain a
5399
+ recorded transform. The record fields and sampling formula are specified in
5400
+ [STABILITY](STABILITY.md).
5394
5401
 
5395
5402
  | rule | means | change |
5396
5403
  | --- | --- | --- |
5397
5404
  | <a id="PLATE_MASK_SOURCE"></a><a id="PLATE_MASK_GRID"></a><a id="PLATE_MASK_VALUES"></a><a id="PLATE_MASK_EMPTY"></a>`PLATE_MASK_SOURCE`, `PLATE_MASK_GRID`, `PLATE_MASK_VALUES`, `PLATE_MASK_EMPTY` | no `--mask-from`, or a source directory holding no See-through run or no scene figure mask; a source on another grid without a valid recorded `input_transform`; a `figure_rig.png` holding other than opaque white and black; a mask with no figure pixel | run `comfy seethrough` on the original painting to record its input transform, or `assemble` with `config.scene` at the painting grid |
5398
5405
  | <a id="PLATE_MASK_RUN"></a>`PLATE_MASK_RUN` | the figure source has no readable `rig-run/1` assemble `run.json`, or its `figure_rig.png`, `parts.json` or declared `painting_in_rig.png` lacks exactly one matching output hash; or the See-through source has no readable `meta.json` with `image_sha256` and `layers` hashes, or a layer PNG on disk lacks a matching `layers` entry | re-run `assemble` with the source config to regenerate `run.json` and its `rig/` files together, or re-run `comfy seethrough` on the painting to regenerate `meta.json` and `parts/` together |
5399
5406
  | <a id="PLATE_MASK_PAINTING"></a>`PLATE_MASK_PAINTING` | `parts.json` has an invalid `painting_in_rig` declaration, its recorded painting is missing, undecodable or differs from its declared hash, or the supplied painting differs from the recorded opaque RGB; or the supplied painting's SHA-256 differs from a See-through source's `meta.json` `image_sha256` | use the original `--painting` file for this source, or re-run `assemble` or `comfy seethrough` on this painting |
5400
- | <a id="PLATE_CHECKPOINT_SHA256"></a><a id="PLATE_MODEL_GIVEN"></a><a id="PLATE_CORE_GRID"></a>`PLATE_CHECKPOINT_SHA256`, `PLATE_MODEL_GIVEN`, `PLATE_CORE_GRID` | `--checkpoint-sha256` absent or not 64 hex characters; `--graph core` without `--model`; a painting off the multiple-of-8 grid under `--graph core` | the flag, or `--graph lama` |
5407
+ | <a id="PLATE_CHECKPOINT_SHA256"></a><a id="PLATE_MODEL_GIVEN"></a>`PLATE_CHECKPOINT_SHA256`, `PLATE_MODEL_GIVEN` | `--checkpoint-sha256` absent or not 64 hex characters; `--graph core` without `--model` | the flag |
5408
+ | <a id="PLATE_CORE_GRID"></a>PLATE_CORE_GRID *(retired)* | retired in 2.x: off-grid `core` now pads to the next multiple of 8 and records `grid_transform`; see [STABILITY](STABILITY.md#plate-receipt) | none |
5401
5409
  | <a id="PLATE_PAINTING_PRESENT"></a><a id="PLATE_OUT_EMPTY"></a>`PLATE_PAINTING_PRESENT`, `PLATE_OUT_EMPTY` | no `--painting` file, or an `--out` that already holds entries | `--painting`, `--out` |
5402
- | <a id="COMFY_GPU_NAMED"></a><a id="COMFY_PLATE_SIZE"></a>`COMFY_GPU_NAMED`, `COMFY_PLATE_SIZE` | `/system_stats` does not name exactly one device; the box's image is not the painting's size | the box |
5403
- | <a id="PLATE_RECEIPT_READ"></a><a id="PLATE_RECEIPT_SPEC"></a><a id="PLATE_RECEIPT_KEYS"></a><a id="PLATE_RECEIPT_FILE"></a><a id="PLATE_RECEIPT_HASH"></a>`PLATE_RECEIPT_READ`, `PLATE_RECEIPT_SPEC`, `PLATE_RECEIPT_KEYS`, `PLATE_RECEIPT_FILE`, `PLATE_RECEIPT_HASH` | the receipt read back before it is published is not JSON, not this spec, not in its key order, names a file that is gone, or records a sha256 that is not the file's | nothing to change by hand: the run is refused and `<out>` is not written |
5410
+ | <a id="COMFY_GPU_NAMED"></a><a id="COMFY_PLATE_SIZE"></a>`COMFY_GPU_NAMED`, `COMFY_PLATE_SIZE` | `/system_stats` does not name exactly one device; the box's image is not the painting's size (or, for off-grid `core`, the padded size) | the box |
5411
+ | <a id="PLATE_RECEIPT_READ"></a><a id="PLATE_RECEIPT_SPEC"></a><a id="PLATE_RECEIPT_KEYS"></a><a id="PLATE_RECEIPT_FILE"></a><a id="PLATE_RECEIPT_HASH"></a><a id="PLATE_RECEIPT_GRID_TRANSFORM"></a>`PLATE_RECEIPT_READ`, `PLATE_RECEIPT_SPEC`, `PLATE_RECEIPT_KEYS`, `PLATE_RECEIPT_FILE`, `PLATE_RECEIPT_HASH`, `PLATE_RECEIPT_GRID_TRANSFORM` | the receipt read back before it is published is not JSON, not this spec, not in its key order, names a file that is gone, records a sha256 that is not the file's, or has a missing, unexpected, malformed or mismatched `grid_transform` | nothing to change by hand: the run is refused and `<out>` is not written |
5412
+ | <a id="MATTE_MODEL"></a><a id="MATTE_MODEL_INSTALLED"></a>`MATTE_MODEL`, `MATTE_MODEL_INSTALLED` | absent or unsupported explicit node/model, or the supported weight file is absent from the server model listing | use `--node BiRefNetRMBG --model BiRefNet-HR-matting` with installed weights |
5413
+ | <a id="MATTE_PARAMS"></a>`MATTE_PARAMS` | resolution is outside [64,2048] or not a multiple of 8, or threshold is outside integer [0,254] | set `--resolution` and `--threshold` within these bounds |
5414
+ | <a id="MATTE_RECEIPT"></a><a id="MATTE_PAINTING"></a><a id="MATTE_HASH"></a>`MATTE_RECEIPT`, `MATTE_PAINTING`, `MATTE_HASH` | `matte:<dir>` lacks a complete ordered receipt, names another painting, or raw/final mask bytes differ from their recorded hashes | re-run `comfy matte` on the supplied painting and keep its receipt and both masks together |
5415
+ | <a id="MATTE_GRID"></a><a id="MATTE_VALUES"></a><a id="MATTE_EMPTY"></a>`MATTE_GRID`, `MATTE_VALUES`, `MATTE_EMPTY` | mask geometry, prepared input hash or recorded transform is inconsistent, model output is not opaque grayscale, final mask differs from its recorded derivation, or mapped foreground is empty | re-run the model on the painting. The #1197 `input_transform.pad_fill` describes the model's input after `LoadImage` IMAGE separates RGB from alpha. |
5416
+ | <a id="MATTE_OUT_EMPTY"></a>`MATTE_OUT_EMPTY` | matte output is a file or a nonempty directory | choose an absent or empty `--out` |
5404
5417
 
5405
5418
  ### assemble
5406
5419
 
package/docs/STABILITY.md CHANGED
@@ -213,7 +213,8 @@ defaults are the help's too, and none is guessed from the art.
213
213
  | `sheet` | `--source`, `--layers` (repeatable), `--out`; optional `--cell`, `--cols` |
214
214
  | `inputs` | `--source`, `--config`, `--out` |
215
215
  | `comfy` | `paint`: `--config`, `--out`; optional `--seeds`, `--seed0`, `--host`, `--wait`, `--timeout`, `--poll` |
216
- | `comfy` | `plate`: `--mode` (`background` or `foreground`), `--painting`, `--mask-from` (`seethrough:<dir>` or `figure-mask:<dir>`), `--out`; with `--mode background` also `--checkpoint-sha256` (required) and optional `--graph` (`lama` or `core`), `--model` (required with `core`), `--seed`, `--grow`, `--steps`, `--prompt`, `--negative` (the last three with `core` only), `--host`, `--wait`, `--timeout`, `--poll` (issue #1183, additive) |
216
+ | `comfy` | `matte`: `--painting`, `--out`, `--node` (`BiRefNetRMBG`), `--model` (`BiRefNet-HR-matting`), `--checkpoint-sha256` (declared, required); optional `--resolution`, `--threshold`, `--host`, `--wait`, `--timeout`, `--poll` (issue #1204) |
217
+ | `comfy` | `plate`: `--mode` (`background` or `foreground`), `--painting`, `--mask-from` (`seethrough:<dir>`, `figure-mask:<dir>` or `matte:<dir>`), `--out`; with `--mode background` also `--checkpoint-sha256` (required) and optional `--graph` (`lama` or `core`), `--model` (required with `core`), `--seed`, `--grow`, `--steps`, `--prompt`, `--negative` (the last three with `core` only), `--host`, `--wait`, `--timeout`, `--poll` (issue #1183, additive) |
217
218
  | `comfy` | `seethrough`: `--image`, `--out`; optional `--resolution`, `--steps`, `--seed`, `--prefix`, `--offload`, `--no-offload`, `--lama`, `--nf4`, `--host`, `--wait`, `--timeout`, `--poll`, `--config` (See-through settings and optional depth block), `--depth-run` (`full` or `head`, required with the block) |
218
219
  | `assemble` | `--propose-plan` with `--source`, `--full`, `--config`, optional `--head`, `--write-config` (must name `--config` itself, issue #356); or `--source`, `--full`, `--config`, `--out`, optional `--head` (without it, one run: issue #359), `--seam` (near-white, silhouette), `--project` (core, visible), `--alt` (repeatable `<name>=<source>:<full>[:<head>]`, issue #454), `--requirements` (source-bound cut-material evidence only when the file declares `cut_material`, issue #888) |
219
220
  | `head-crop-preflight` | `--full`, `--canvas`, `--head-box` (JSON coordinate array); read-only advice before the head run, original alpha > 8 samples (issue #1082) |
@@ -445,15 +446,64 @@ new spec version. Every path in it is relative to the receipt's directory.
445
446
  | `spec` | `"rig-parts-plate-receipt/1"` |
446
447
  | `mode` | `"background"` or `"foreground"` |
447
448
  | `painting` | `{ path, sha256 }` of the painting read |
448
- | `mask` | `{ source, from, path, sha256 }`: `source` is `"seethrough"` or `"figure-mask"`, `from` the source directory, `path` the mask actually used (`mask.png`, opaque white inside) |
449
+ | `mask` | `{ source, from, path, sha256 }`: `source` is `"seethrough"`, `"figure-mask"` or `"matte"`, `from` the source directory, `path` the mask actually used (`mask.png`, opaque white inside) |
449
450
  | `model` | `{ name, checkpoint_sha256, checkpoint_sha256_from }`, or null for `foreground`. `checkpoint_sha256` is the `--checkpoint-sha256` value, lower-cased; `checkpoint_sha256_from` is `"declared"`: the box reports no hash, so this field is **declared, not measured** |
450
451
  | `params` | every parameter of the run, the seed included, in a fixed order per graph: `lama` — `seed`, `grow_px`, `mask_alpha_above`; `core` — `seed`, `grow_px`, `steps`, `cfg`, `sampler`, `scheduler`, `denoise`, `prompt`, `negative`, `mask_alpha_above`; `foreground` — `mask_alpha_above` |
451
452
  | `graph` | `"rig-parts/plate-background-lama/1"`, `"rig-parts/plate-background-core/1"`, or the fixed local id `"rig-parts/plate-foreground/1"` |
452
453
  | `gpu` | the device `/system_stats` names (the same seed gives other pixels on another GPU), or null for `foreground` |
454
+ | `grid_transform` | present only when `mode` is `"background"`, `graph` is `"rig-parts/plate-background-core/1"`, and the painting's width or height is not a multiple of 8 (issue #1209, additive): `{ source: [width, height], padded: [ceil(width/8)*8, ceil(height/8)*8], pad: [0, 0], pad_fill: "edge-replicate", mask_pad_fill: "zero", inverse: "crop" }` in that key order. Omitted for on-grid `core`, `lama`, and `foreground` |
453
455
  | `output` | `{ path, sha256 }` of `plate.png` |
454
456
 
455
457
  The receipt is read back against the bytes on disk before `<out>` is published;
456
- a hash that is not its file's refuses the run.
458
+ a hash that is not its file's refuses the run. `verifyPlateReceipt` also
459
+ re-derives `grid_transform` from the decoded painting, `mode` and `graph`, and
460
+ refuses a missing, unexpected, malformed or mismatched transform as
461
+ `PLATE_RECEIPT_GRID_TRANSFORM`. For off-grid `--graph core` paintings, the
462
+ uploaded painting is padded on the right and bottom by replicating its edge
463
+ pixels (`pad_fill: "edge-replicate"`), the uploaded grown mask is padded with
464
+ zero (`mask_pad_fill: "zero"`, kept as context outside the hole), the box's
465
+ output is required at `padded` dimensions (`COMFY_PLATE_SIZE` otherwise) and
466
+ cropped at `[0, 0]` back to `source` before pasting inside the native mask, so
467
+ pixels outside the hole equal the painting byte for byte. On-grid `core`
468
+ paintings retain their original upload bytes, graph and 9-key receipt. Because
469
+ every painting grid is covered by this transform, `PLATE_CORE_GRID` is retired.
470
+
471
+ ### Matte source receipt
472
+
473
+ `comfy matte` writes `model-mask.png` (the exact downloaded grayscale model
474
+ output), `mask.png` (opaque binary mask on the painting grid) and `receipt.json`,
475
+ spec `rig-parts-matte-receipt/1`. Node and model are explicit flags. The supported
476
+ pair is `BiRefNetRMBG` / `BiRefNet-HR-matting`. The model file must also appear in
477
+ `/models/RMBG` before any upload. Queue submission appends behind existing jobs.
478
+ The node has blur and offset zero, inversion and foreground refinement disabled.
479
+
480
+ The ordered receipt keys are `spec`, `painting`, `model`, `params`, `graph`,
481
+ `gpu`, `input_transform`, `input_sha256`, `raw_output`, `output`. `painting`
482
+ records its relative path and the SHA-256 of the source file bytes. `model`
483
+ records node, name, `checkpoint_sha256` and `checkpoint_sha256_from: "declared"`.
484
+ `params` records every node option, resolution, threshold and
485
+ `mask_rule: "red-above-threshold"`. `graph` records
486
+ `id: "rig-parts/matte-BiRefNetRMBG/1"`, the submitted API graph and its SHA-256
487
+ (over UTF-8 `JSON.stringify(api)`). `gpu` is the device the server names.
488
+ `raw_output` and `output` each record a fixed relative path, SHA-256, width and
489
+ height. Paths to output masks cannot redirect the reader to another file.
490
+
491
+ For a non-square painting, `input_transform` uses the #1197 shape documented
492
+ below. Its `pad_fill` describes the model's input after `LoadImage` IMAGE
493
+ separates alpha from RGB. The matte graph feeds that IMAGE output to the model.
494
+ `input_sha256` binds the prepared PNG upload. Square paintings retain their
495
+ original upload bytes and record a null transform. Resolution defaults to 1024
496
+ and applies to the non-square prepared square. It must be a multiple of 8 in
497
+ [64,2048]. The threshold defaults to 10 and must be an integer in [0,254].
498
+ Each grayscale byte strictly above the threshold becomes foreground. The recorded
499
+ nearest-pixel-centre inverse maps that classification to the painting grid.
500
+
501
+ `--mask-from matte:<dir>` binds the supplied painting's exact bytes, both mask
502
+ file hashes, the prepared input, the complete graph, and the final mask's exact
503
+ reproduction from the raw mask and recorded parameters. Missing or legacy
504
+ receipts, another painting, tampering, inconsistent geometry and empty masks
505
+ are named refusals before any plate output or network request. A matte source is
506
+ available to both plate modes. Staged output is read back before publication.
457
507
 
458
508
  ### Head-crop preflight stdout
459
509
 
@@ -570,19 +620,26 @@ plate` with `--mask-from seethrough:<dir>` binds every layer file read and
570
620
  `--painting` against those hashes and refuses a legacy `meta.json` that lacks
571
621
  them.
572
622
 
573
- Non-square inputs are prepared by parts before upload (issue #1197).
623
+ Non-square inputs are prepared by parts before upload (issues #1197, #1205).
574
624
  Their additive `input_transform` records `source: [width,height]`,
575
625
  `padded: [side,side]`, `pad: [left,top]` in padded pixels, `scale` (target
576
626
  side divided by padded side), `resample: "parts-lanczos3-rgba"`,
577
- `pad_fill: "rgb-black-opaque"`, `target: [resolution,resolution]` and `inverse: "nearest-pixel-centres"`.
627
+ `pad_fill: "rgba-zero"` (`"rgb-black-opaque"` for a graph that reads `LoadImage`
628
+ IMAGE only, and on 2.27.2 `seethrough` records, which readers continue to accept),
629
+ `target: [resolution,resolution]` and `inverse: "nearest-pixel-centres"`.
578
630
  The enclosing `image_sha256` is the single source-image hash. Preparation
579
631
  zero-fills the square, places the source at floor-centred offsets, and runs
580
632
  parts' RGBA Lanczos3 resampler. The wrapper receives the configured square.
581
- LoadImage separates the PNG's alpha from RGB, and GenerateLayers adds opaque
582
- alpha to that RGB. The model therefore receives the padded area as opaque
583
- black RGB. The old wrapper-internal pad was transparent, so non-square model
584
- inputs differ from before.
585
- Square inputs keep the existing upload bytes and omit `input_transform`.
633
+ In `workflows/seethrough.json`, `LoadImage`'s `IMAGE` (output 0) and `MASK`
634
+ (output 1) rejoin through ComfyUI's core `JoinImageWithAlpha` node before
635
+ `SeeThrough_GenerateLayers`, so the 4-channel RGBA image reaches the model
636
+ with `alpha = 0` on the padded area and `page_alpha` masks layer alpha to zero
637
+ outside the source rectangle, matching the wrapper's internal pad semantics.
638
+ Square inputs keep the existing upload bytes, omit `input_transform`, and for
639
+ opaque square inputs (whether RGBA or RGB-only PNG) reach the model with the
640
+ same `alpha = 255` tensor as before; a square input that itself carries
641
+ transparent pixels now has that transparency forwarded to the model instead of
642
+ dropped at `LoadImage`.
586
643
  For each source pixel `(x,y)`, the inverse samples the layer union at
587
644
  `floor((x+left+0.5)*scale), floor((y+top+0.5)*scale)`.
588
645
  Exactness holds for representable masks, and detail below the See-through
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "spine-parts",
3
- "version": "2.27.2",
3
+ "version": "2.29.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": {
@@ -100,6 +100,15 @@ export class ComfyClient {
100
100
  return s;
101
101
  }
102
102
 
103
+ /** Listed model files, not the node selector's advertised vocabulary. */
104
+ async modelFiles(folder: string): Promise<string[]> {
105
+ const files = await this.json('GET', `/models/${encodeURIComponent(folder)}`);
106
+ if (!Array.isArray(files) || !files.every((f): f is string => typeof f === 'string')) {
107
+ refuse('MATTE_MODEL_INSTALLED', folder, 'the model listing is not an array of file names; installed weights must be established before upload');
108
+ }
109
+ return files;
110
+ }
111
+
103
112
  /** Free VRAM per device in GB (two decimals), keyed by the device name's first word; empty when the box does not say. */
104
113
  async vramFree(): Promise<Record<string, number>> {
105
114
  const s = await this.systemStats();
@@ -18,3 +18,5 @@ export { ComfyClient, type ClientTiming, resolveHost } from './client.ts';
18
18
  export { runPainting, type PaintRun, type Painted } from './painting.ts';
19
19
  export { runBackground, type BackgroundRun } from './plate.ts';
20
20
  export { runSeeThrough, type SeeThroughResult, type SeeThroughRun } from './seethrough.ts';
21
+
22
+ export { runMatte, type MatteRun } from './matte.ts';
@@ -0,0 +1,51 @@
1
+ /** Optional GPU matte adapter. Local validation precedes host resolution. */
2
+ import { refuseIfAny } from '../errors.ts';
3
+ import { checkGraph } from '../graphs.ts';
4
+ import { assertMatteOutFree, matteGraph, matteGraphHash, matteParams, matteSelection, MATTE_GRAPH_ID, MATTE_MODEL, MATTE_MODEL_FILE, MATTE_NODE, publishMatte, type MatteReceipt } from '../matte.ts';
5
+ import { declaredChecksum, readPlatePainting, sha256 } from '../plate.ts';
6
+ import { encodePngBytes } from '../raster/png.ts';
7
+ import { prepareSeeThroughInput } from '../seethrough-transform.ts';
8
+ import { ComfyClient, historyImages, refuse } from './client.ts';
9
+ import { gpuName } from './plate.ts';
10
+
11
+ export interface MatteRun {
12
+ painting: string;
13
+ out: string;
14
+ node: string | undefined;
15
+ model: string | undefined;
16
+ checkpointSha256: string | undefined;
17
+ resolution: number;
18
+ threshold: number;
19
+ wait: number;
20
+ timeout: number;
21
+ }
22
+ export async function runMatte(connect: () => ComfyClient, run: MatteRun, say: (line: string) => void): Promise<MatteReceipt> {
23
+ matteSelection(run.node, run.model);
24
+ const params = matteParams(run.resolution, run.threshold);
25
+ const checkpoint = declaredChecksum(run.checkpointSha256);
26
+ const painting = readPlatePainting(run.painting);
27
+ assertMatteOutFree(run.out);
28
+ const prepared = prepareSeeThroughInput(painting.raster, run.resolution, 'rgb-black-opaque');
29
+ const input = prepared.transform === undefined ? painting.bytes : encodePngBytes(prepared.image);
30
+ const client = connect();
31
+ const gpu = gpuName(await client.systemStats(), client.host);
32
+ const prefix = `rig_parts_matte_${crypto.randomUUID().slice(0, 8)}`;
33
+ const info = await client.objectInfo();
34
+ refuseIfAny(checkGraph(matteGraph(`${prefix}.png`, prefix), info, client.host, new Set(['1.image'])));
35
+ const files = await client.modelFiles('RMBG');
36
+ if (!files.some(f => f.replaceAll('\\', '/') === MATTE_MODEL_FILE)) refuse('MATTE_MODEL_INSTALLED', MATTE_MODEL_FILE, 'is absent from /models/RMBG; a selector entry alone does not establish installed weights, and automatic download is not permitted');
37
+ const image = await client.uploadImage(input, `${prefix}.png`);
38
+ const graph = matteGraph(image, prefix);
39
+ const id = await client.submit(graph, 'rig-parts');
40
+ say(` appended matte prompt ${id} behind all queued jobs`);
41
+ const { entry } = await client.waitBehind(id, run.wait, run.timeout, say);
42
+ const outputs = historyImages(entry);
43
+ if (outputs.length !== 1) refuse('COMFY_HISTORY_OUTPUTS', `matte prompt ${id}`, `lists ${outputs.length} images; exactly one saved model mask is required`);
44
+ const output = outputs[0];
45
+ const raw = await client.view(output.filename, output.subfolder, output.type);
46
+ return publishMatte(run.out, run.painting, painting.bytes, raw, {
47
+ model: { node: MATTE_NODE, name: MATTE_MODEL, checkpoint_sha256: checkpoint, checkpoint_sha256_from: 'declared' },
48
+ params, graph: { id: MATTE_GRAPH_ID, api: graph, sha256: matteGraphHash(graph) }, gpu,
49
+ input_transform: prepared.transform ?? null, input_sha256: sha256(input),
50
+ });
51
+ }
@@ -6,17 +6,20 @@
6
6
  *
7
7
  * 1. the source mask is read (`src/plate.ts`); with none, the run is refused
8
8
  * before anything is written and before the host is reached;
9
- * 2. the declared checkpoint sha256 and, for `core`, the painting's grid are
9
+ * 2. the declared checkpoint sha256 and, for `core`, the checkpoint name are
10
10
  * checked;
11
11
  * 3. the box answers `/system_stats` and names its GPU;
12
12
  * 4. every node, input and model of the chosen graph is on the box's
13
13
  * `/object_info` (`checkGraph`) — a box without the inpaint pack is refused
14
14
  * here for `lama`, before anything is uploaded;
15
- * 5. the painting and the grown mask are uploaded and the graph is appended
15
+ * 5. the painting and the grown mask (for off-grid `core`, padded to the next
16
+ * multiple of 8 on the right and bottom with `grid_transform` recorded) are
17
+ * uploaded and the graph is appended
16
18
  * to the queue: behind every other job, never in front, nothing reordered
17
19
  * and nothing cancelled; a wait past `--wait` while pending is refused
18
20
  * naming the job's place (`COMFY_QUEUE_BEHIND`);
19
- * 6. the box's image is read back, required at the painting's size, pasted
21
+ * 6. the box's image is read back, required at the uploaded size (then cropped
22
+ * at `[0, 0]` back to the painting's size for off-grid `core`), pasted
20
23
  * into the painting inside the mask only, and written with its receipt
21
24
  * through `publishPlate` (staged, read back, then moved).
22
25
  */
@@ -26,8 +29,8 @@ import {
26
29
  assertPlateOutFree,
27
30
  CORE_DEFAULTS,
28
31
  type CoreParams,
29
- coreGridProblem,
30
32
  corePlateGraph,
33
+ cropCoreGrid,
31
34
  declaredChecksum,
32
35
  type FigureMask,
33
36
  growMask,
@@ -40,6 +43,7 @@ import {
40
43
  PLATE_GRAPH_IDS,
41
44
  type PlateGraph,
42
45
  type PlateReceipt,
46
+ prepareCoreGrid,
43
47
  publishPlate,
44
48
  readPlatePainting,
45
49
  readSourceMask,
@@ -77,19 +81,20 @@ export function gpuName(stats: Record<string, unknown>, host: string): string {
77
81
 
78
82
  /** `connect` is called only after every local check has passed, so a refused run never resolves a host or reaches a box. */
79
83
  export async function runBackground(connect: () => ComfyClient, run: BackgroundRun, say: (line: string) => void): Promise<PlateReceipt> {
80
- // Local first: no source mask, a bad checksum or an off-grid painting is refused before the box is reached.
84
+ // Local first: no source mask, a bad checksum or a missing checkpoint is refused before the box is reached.
81
85
  const from = parseMaskFrom(run.maskFrom);
82
86
  const painting = readPlatePainting(run.painting);
83
87
  const { width: W, height: H } = painting.raster;
84
88
  const source: FigureMask = readSourceMask(from.source, from.dir, W, H, painting.raster, painting.bytes);
85
89
  const checkpoint = declaredChecksum(run.checkpointSha256);
86
- if (run.graph === 'core') {
87
- if (run.model === undefined) refuse('PLATE_MODEL_GIVEN', '--model', 'is absent; the core graph needs the checkpoint the box loads, by its name on the box — there is no default checkpoint');
88
- const grid = coreGridProblem(W, H, run.painting);
89
- if (grid !== null) refuseIfAny([grid]);
90
+ if (run.graph === 'core' && run.model === undefined) {
91
+ refuse('PLATE_MODEL_GIVEN', '--model', 'is absent; the core graph needs the checkpoint the box loads, by its name on the box — there is no default checkpoint');
90
92
  }
91
93
  assertPlateOutFree(run.out);
92
94
  const mask = growMask(source, run.growPx);
95
+ const prepared = run.graph === 'core' ? prepareCoreGrid(painting.raster, mask) : { painting: painting.raster, mask };
96
+ const uploadPaintingBytes = prepared.transform === undefined ? painting.bytes : encodePngBytes(prepared.painting);
97
+ const uploadMaskBytes = encodePngBytes(maskImage(prepared.mask));
93
98
  const model = run.model ?? LAMA_MODEL;
94
99
  const lama: LamaParams = { seed: run.seed, grow_px: run.growPx };
95
100
  const core: CoreParams = { seed: run.seed, grow_px: run.growPx, steps: run.steps, cfg: CORE_DEFAULTS.cfg, sampler: CORE_DEFAULTS.sampler, scheduler: CORE_DEFAULTS.scheduler, denoise: CORE_DEFAULTS.denoise, prompt: run.prompt ?? CORE_DEFAULTS.prompt, negative: run.negative ?? CORE_DEFAULTS.negative };
@@ -102,9 +107,9 @@ export async function runBackground(connect: () => ComfyClient, run: BackgroundR
102
107
  refuseIfAny(checkGraph(build(`${prefix}_painting.png`, `${prefix}_mask.png`), info, client.host, new Set(['1.image', '2.image'])));
103
108
  say(` box: every node, input and model of the ${run.graph} graph is on its /object_info; GPU ${gpu}`);
104
109
 
105
- const paintingRef = await client.uploadImage(painting.bytes, `${prefix}_painting.png`);
106
- const maskRef = await client.uploadImage(encodePngBytes(maskImage(mask)), `${prefix}_mask.png`);
107
- say(` uploaded ${run.painting} (${W}x${H}) and its mask (${mask.inside.reduce((a, b) => a + b, 0)} px, grown ${run.growPx} px)`);
110
+ const paintingRef = await client.uploadImage(uploadPaintingBytes, `${prefix}_painting.png`);
111
+ const maskRef = await client.uploadImage(uploadMaskBytes, `${prefix}_mask.png`);
112
+ say(` uploaded ${run.painting} (${prepared.painting.width}x${prepared.painting.height}) and its mask (${mask.inside.reduce((a, b) => a + b, 0)} px, grown ${run.growPx} px)`);
108
113
  const id = await client.submit(build(paintingRef, maskRef), 'rig-parts');
109
114
  say(` appended prompt ${id} to the queue (behind any other job; nothing reordered or cancelled)`);
110
115
  const { entry, elapsed } = await client.waitBehind(id, run.wait, run.timeout, say);
@@ -112,7 +117,15 @@ export async function runBackground(connect: () => ComfyClient, run: BackgroundR
112
117
  const images = historyImages(entry);
113
118
  if (images.length !== 1) refuse('COMFY_HISTORY_OUTPUTS', `prompt ${id}`, `lists ${images.length} image(s); the graph's one SaveImage is required to have saved exactly one`);
114
119
  const got = decodePngBytes(await client.view(images[0].filename, images[0].subfolder, images[0].type), images[0].filename);
115
- if (got.width !== W || got.height !== H) refuse('COMFY_PLATE_SIZE', `prompt ${id} ${images[0].filename}`, `is ${got.width}x${got.height}; the painting's ${W}x${H} is required — the plate is pasted into the painting pixel for pixel, never resized`);
120
+ const [expectedW, expectedH] = prepared.transform === undefined ? [W, H] : prepared.transform.padded;
121
+ if (got.width !== expectedW || got.height !== expectedH) {
122
+ refuse(
123
+ 'COMFY_PLATE_SIZE',
124
+ `prompt ${id} ${images[0].filename}`,
125
+ `is ${got.width}x${got.height}; ${prepared.transform === undefined ? `the painting's ${W}x${H}` : `the padded core grid ${expectedW}x${expectedH} (for painting ${W}x${H})`} is required — the plate is pasted into the painting pixel for pixel, never resized`,
126
+ );
127
+ }
128
+ const inpainted = prepared.transform === undefined ? got : cropCoreGrid(got, prepared.transform);
116
129
 
117
130
  return publishPlate({
118
131
  out: run.out,
@@ -123,10 +136,11 @@ export async function runBackground(connect: () => ComfyClient, run: BackgroundR
123
136
  source: from.source,
124
137
  sourceDir: from.dir,
125
138
  mask,
126
- plate: pasteInside(painting.raster, got, mask),
139
+ plate: pasteInside(painting.raster, inpainted, mask),
127
140
  model: { name: model, checkpoint_sha256: checkpoint, checkpoint_sha256_from: 'declared' },
128
141
  params: run.graph === 'lama' ? { ...lama, mask_alpha_above: OPAQUE_ALPHA_ABOVE } : { ...core, mask_alpha_above: OPAQUE_ALPHA_ABOVE },
129
142
  graph: PLATE_GRAPH_IDS[run.graph],
130
143
  gpu,
144
+ gridTransform: prepared.transform,
131
145
  });
132
146
  }
@@ -84,7 +84,7 @@ export async function runSeeThrough(client: ComfyClient, run: SeeThroughRun, say
84
84
  const bytes = new Uint8Array(readFileSync(run.image));
85
85
  const img = decodePngBytes(bytes, run.image);
86
86
  assertOutFree(run.out);
87
- const prepared = prepareSeeThroughInput(img, run.resolution);
87
+ const prepared = prepareSeeThroughInput(img, run.resolution, 'rgba-zero');
88
88
  const uploadBytes = prepared.transform === undefined ? bytes : encodePngBytes(prepared.image);
89
89
 
90
90
  await client.systemStats();
package/src/matte.ts ADDED
@@ -0,0 +1,171 @@
1
+ /** Receipted model masks, bound to the exact painting bytes; no pixel repair. */
2
+ import { createHash } from 'node:crypto';
3
+ import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, renameSync, rmdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
4
+ import { basename, dirname, join, relative, resolve } from 'node:path';
5
+ import { PartsError } from './errors.ts';
6
+ import type { Graph } from './graphs.ts';
7
+ import { decodePngBytes, encodePngBytes } from './raster/png.ts';
8
+ import { newRaster, type Raster } from './raster/types.ts';
9
+ import { inverseSeeThroughMask, isSeeThroughTransform, prepareSeeThroughInput as prepareMatteInput, type SeeThroughTransform } from './seethrough-transform.ts';
10
+
11
+ export const MATTE_SPEC = 'rig-parts-matte-receipt/1';
12
+ export const MATTE_KEYS = ['spec', 'painting', 'model', 'params', 'graph', 'gpu', 'input_transform', 'input_sha256', 'raw_output', 'output'] as const;
13
+ export const MATTE_NODE = 'BiRefNetRMBG';
14
+ export const MATTE_MODEL = 'BiRefNet-HR-matting';
15
+ export const MATTE_MODEL_FILE = 'BiRefNet/BiRefNet-HR-matting.safetensors';
16
+ export const MATTE_GRAPH_ID = 'rig-parts/matte-BiRefNetRMBG/1';
17
+ const NODE_PARAMS = { mask_blur: 0, mask_offset: 0, invert_output: false, refine_foreground: false, background: 'Alpha', background_color: '#222222' } as const;
18
+ interface Artifact {
19
+ path: string;
20
+ sha256: string;
21
+ width: number;
22
+ height: number;
23
+ }
24
+ export interface MatteReceipt {
25
+ spec: typeof MATTE_SPEC;
26
+ painting: { path: string; sha256: string };
27
+ model: { node: string; name: string; checkpoint_sha256: string; checkpoint_sha256_from: 'declared' };
28
+ params: typeof NODE_PARAMS & { resolution: number; threshold: number; mask_rule: 'red-above-threshold'; };
29
+ graph: { id: typeof MATTE_GRAPH_ID; api: Graph; sha256: string };
30
+ gpu: string;
31
+ input_transform: SeeThroughTransform | null;
32
+ input_sha256: string;
33
+ raw_output: Artifact;
34
+ output: Artifact;
35
+ }
36
+ const hash = (bytes: Uint8Array): string => createHash('sha256').update(bytes).digest('hex');
37
+ function fail(code: string, object: string, detail: string): never {
38
+ throw new PartsError([{ code, object, detail }]);
39
+ }
40
+ const record = (v: unknown): v is Record<string, unknown> => typeof v === 'object' && v !== null && !Array.isArray(v);
41
+ const hex = (v: unknown): v is string => typeof v === 'string' && /^[0-9a-f]{64}$/.test(v);
42
+
43
+ /** Only the isolated-probe winner is admitted; an enum is not a runnable-node receipt. */
44
+ export function matteSelection(node: string | undefined, model: string | undefined): void {
45
+ if (node !== MATTE_NODE || model !== MATTE_MODEL) fail('MATTE_MODEL', '--node / --model', `got ${JSON.stringify(node)} / ${JSON.stringify(model)}; explicitly name ${MATTE_NODE} / ${MATTE_MODEL}, the supported graph; no model is guessed`);
46
+ }
47
+ export function matteParams(resolution: number, threshold: number): MatteReceipt['params'] {
48
+ if (!Number.isSafeInteger(resolution) || resolution < 64 || resolution > 2048 || resolution % 8 !== 0 || !Number.isInteger(threshold) || threshold < 0 || threshold > 254) {
49
+ fail('MATTE_PARAMS', '--resolution / --threshold', `got ${resolution} / ${threshold}; resolution must be a multiple of 8 in [64,2048], threshold an integer in [0,254]`);
50
+ }
51
+ return { ...NODE_PARAMS, resolution, threshold, mask_rule: 'red-above-threshold' };
52
+ }
53
+ export function matteGraph(image: string, prefix: string): Graph {
54
+ return {
55
+ '1': { class_type: 'LoadImage', inputs: { image } },
56
+ '2': { class_type: MATTE_NODE, inputs: { image: ['1', 0], model: MATTE_MODEL, ...NODE_PARAMS } },
57
+ '3': { class_type: 'MaskToImage', inputs: { mask: ['2', 1] } },
58
+ '4': { class_type: 'SaveImage', inputs: { images: ['3', 0], filename_prefix: prefix } },
59
+ };
60
+ }
61
+ export function matteGraphHash(graph: Graph): string { return hash(new TextEncoder().encode(JSON.stringify(graph))); }
62
+
63
+ /** Model output is grayscale and opaque. Thresholding is the sole classification. */
64
+ export function matteMask(raw: Raster, width: number, height: number, threshold: number, transform: SeeThroughTransform | null): Raster {
65
+ if ((transform === null && (raw.width !== width || raw.height !== height)) || (transform !== null && !isSeeThroughTransform(transform, width, height, raw.width, raw.height))) {
66
+ fail('MATTE_GRID', 'model mask / input_transform', `model grid ${raw.width}x${raw.height}, painting ${width}x${height}; an identical grid or valid recorded square transform is required`);
67
+ }
68
+ let inside: Uint8Array = new Uint8Array(raw.width * raw.height);
69
+ for (let p = 0; p < inside.length; p++) {
70
+ const i = p * 4;
71
+ if (raw.data[i] !== raw.data[i + 1] || raw.data[i] !== raw.data[i + 2] || raw.data[i + 3] !== 255) fail('MATTE_VALUES', 'model-mask.png', `pixel ${p} is not opaque grayscale; MaskToImage output is required`);
72
+ inside[p] = raw.data[i] > threshold ? 1 : 0;
73
+ }
74
+ if (transform !== null) inside = inverseSeeThroughMask(inside, transform);
75
+ if (!inside.some(v => v === 1)) fail('MATTE_EMPTY', 'mask.png', 'has no foreground pixel after threshold and inverse mapping; a nonempty model mask is required');
76
+ const out = newRaster(width, height);
77
+ for (let p = 0; p < inside.length; p++) out.data.set([inside[p] * 255, inside[p] * 255, inside[p] * 255, 255], p * 4);
78
+ return out;
79
+ }
80
+ export function assertMatteOutFree(out: string): void {
81
+ if (existsSync(out) && (!statSync(out).isDirectory() || readdirSync(out).length !== 0)) fail('MATTE_OUT_EMPTY', out, 'is a file or nonempty directory; an absent or empty output is required');
82
+ }
83
+
84
+ /** Validate the complete receipt before trusting any cast or output file. */
85
+ function parseReceipt(value: unknown, file: string): MatteReceipt {
86
+ if (!record(value) || Object.keys(value).join(',') !== MATTE_KEYS.join(',') || value.spec !== MATTE_SPEC ||
87
+ !record(value.painting) || typeof value.painting.path !== 'string' || value.painting.path === '' || !hex(value.painting.sha256) ||
88
+ !record(value.model) || value.model.node !== MATTE_NODE || value.model.name !== MATTE_MODEL || !hex(value.model.checkpoint_sha256) || value.model.checkpoint_sha256_from !== 'declared' ||
89
+ !record(value.params) || !record(value.graph) || value.graph.id !== MATTE_GRAPH_ID || !record(value.graph.api) || !hex(value.graph.sha256) ||
90
+ typeof value.gpu !== 'string' || value.gpu === '' || !hex(value.input_sha256)) {
91
+ fail('MATTE_RECEIPT', file, `requires the complete ordered ${MATTE_SPEC} receipt, painting, model, declared checkpoint hash, params, graph and GPU; legacy or unbound masks are refused`);
92
+ }
93
+ const params = matteParams(value.params.resolution as number, value.params.threshold as number);
94
+ if (JSON.stringify(value.params) !== JSON.stringify(params)) fail('MATTE_RECEIPT', file, 'params differ from the fixed node graph and recorded threshold rule; re-run comfy matte');
95
+ for (const [field, expected] of [['raw_output', 'model-mask.png'], ['output', 'mask.png']] as const) {
96
+ const a = value[field];
97
+ if (!record(a) || a.path !== expected || !hex(a.sha256) || !Number.isSafeInteger(a.width) || !Number.isSafeInteger(a.height) || (a.width as number) <= 0 || (a.height as number) <= 0) fail('MATTE_RECEIPT', file, `${field} requires fixed path ${expected}, lowercase sha256 and positive integer dimensions`);
98
+ }
99
+ const api = value.graph.api;
100
+ if (!record(api['1']) || !record(api['1'].inputs) || typeof api['1'].inputs.image !== 'string' ||
101
+ !record(api['4']) || !record(api['4'].inputs) || typeof api['4'].inputs.filename_prefix !== 'string' ||
102
+ JSON.stringify(api) !== JSON.stringify(matteGraph(api['1'].inputs.image, api['4'].inputs.filename_prefix)) ||
103
+ value.graph.sha256 !== matteGraphHash(api as Graph)) fail('MATTE_RECEIPT', file, 'submitted graph or its sha256 differs from the versioned matte graph');
104
+ return value as unknown as MatteReceipt;
105
+ }
106
+
107
+ /** Bind supplied painting bytes, both saved masks, geometry and the exact derivation. */
108
+ export function readMatteSource(dir: string, paintingBytes: Uint8Array | undefined, width: number, height: number): Raster {
109
+ const file = join(dir, 'receipt.json');
110
+ let value: unknown;
111
+ try { value = JSON.parse(readFileSync(file, 'utf8')); }
112
+ catch { return fail('MATTE_RECEIPT', file, 'cannot read a JSON receipt; re-run comfy matte on the painting'); }
113
+ const r = parseReceipt(value, file);
114
+ if (paintingBytes === undefined || hash(paintingBytes) !== r.painting.sha256) fail('MATTE_PAINTING', file, `supplied painting sha256 ${paintingBytes === undefined ? 'absent' : hash(paintingBytes)} differs from recorded ${r.painting.sha256}; use the painting this matte run read`);
115
+ const source = decodePngBytes(paintingBytes, 'painting');
116
+ if (source.width !== width || source.height !== height) fail('MATTE_GRID', file, `supplied painting decodes as ${source.width}x${source.height}, requested ${width}x${height}; identical dimensions are required`);
117
+ const artifacts: Raster[] = [];
118
+ for (const a of [r.raw_output, r.output]) {
119
+ let bytes: Uint8Array;
120
+ try { bytes = new Uint8Array(readFileSync(join(dir, a.path))); }
121
+ catch { return fail('MATTE_HASH', a.path, 'recorded mask file is absent; re-run comfy matte'); }
122
+ if (hash(bytes) !== a.sha256) fail('MATTE_HASH', a.path, `file sha256 ${hash(bytes)} differs from recorded ${a.sha256}; re-run comfy matte`);
123
+ const raster = decodePngBytes(bytes, a.path);
124
+ if (raster.width !== a.width || raster.height !== a.height) fail('MATTE_GRID', a.path, `decoded ${raster.width}x${raster.height} differs from recorded ${a.width}x${a.height}`);
125
+ artifacts.push(raster);
126
+ }
127
+ // Recreate preparation, including its square fast path, using the recorded resolution.
128
+ const prepared = prepareMatteInput(source, r.params.resolution, 'rgb-black-opaque');
129
+ const inputBytes = prepared.transform === undefined ? paintingBytes : encodePngBytes(prepared.image);
130
+ if (hash(inputBytes) !== r.input_sha256 || JSON.stringify(prepared.transform ?? null) !== JSON.stringify(r.input_transform)) fail('MATTE_GRID', file, 'recorded input hash or transform differs from preparation of the bound painting; re-run comfy matte');
131
+ if (artifacts[0].width !== prepared.image.width || artifacts[0].height !== prepared.image.height) fail('MATTE_GRID', 'model-mask.png', `requires prepared input grid ${prepared.image.width}x${prepared.image.height}; got ${artifacts[0].width}x${artifacts[0].height}`);
132
+ const expected = matteMask(artifacts[0], width, height, r.params.threshold, r.input_transform);
133
+ const final = artifacts[1];
134
+ if (final.width !== width || final.height !== height || !expected.data.every((v, i) => v === final.data[i])) fail('MATTE_VALUES', 'mask.png', 'differs from the recorded raw-mask threshold and inverse mapping; no pixel repair is accepted');
135
+ return final;
136
+ }
137
+
138
+ /** Stage, verify against frozen input bytes, then publish without replacing prior output. */
139
+ export function publishMatte(out: string, paintingPath: string, paintingBytes: Uint8Array, rawBytes: Uint8Array, receipt: Omit<MatteReceipt, 'spec' | 'painting' | 'raw_output' | 'output'>): MatteReceipt {
140
+ assertMatteOutFree(out);
141
+ const painting = decodePngBytes(paintingBytes, paintingPath);
142
+ const raw = decodePngBytes(rawBytes, 'model-mask.png');
143
+ const mask = matteMask(raw, painting.width, painting.height, receipt.params.threshold, receipt.input_transform);
144
+ const maskBytes = encodePngBytes(mask);
145
+ const parent = dirname(resolve(out));
146
+ mkdirSync(parent, { recursive: true });
147
+ const stage = mkdtempSync(join(parent, `.${basename(resolve(out))}.partial-`));
148
+ try {
149
+ const r: MatteReceipt = {
150
+ spec: MATTE_SPEC, painting: { path: relative(resolve(out), resolve(paintingPath)).split('\\').join('/'), sha256: hash(paintingBytes) },
151
+ ...receipt,
152
+ raw_output: { path: 'model-mask.png', sha256: hash(rawBytes), width: raw.width, height: raw.height },
153
+ output: { path: 'mask.png', sha256: hash(maskBytes), width: mask.width, height: mask.height },
154
+ };
155
+ writeFileSync(join(stage, 'model-mask.png'), rawBytes);
156
+ writeFileSync(join(stage, 'mask.png'), maskBytes);
157
+ writeFileSync(join(stage, 'receipt.json'), `${JSON.stringify(r, null, 2)}\n`);
158
+ readMatteSource(stage, paintingBytes, painting.width, painting.height);
159
+ assertMatteOutFree(out);
160
+ try {
161
+ if (existsSync(out)) rmdirSync(out);
162
+ renameSync(stage, out);
163
+ } catch (error) {
164
+ if (['ENOTEMPTY', 'EEXIST', 'ENOTDIR', 'EISDIR'].includes((error as NodeJS.ErrnoException).code ?? '')) {
165
+ fail('MATTE_OUT_EMPTY', out, 'became a file or nonempty directory before publication; an absent or empty output is required');
166
+ }
167
+ throw error;
168
+ }
169
+ return r;
170
+ } finally { if (existsSync(stage)) rmSync(stage, { recursive: true, force: true }); }
171
+ }
package/src/plate.ts CHANGED
@@ -7,7 +7,7 @@
7
7
  * inpainting run, lives in `src/comfy/plate.ts` and carries the graphs this
8
8
  * file builds.
9
9
  *
10
- * 🔒 **The mask comes from a source, never a hand polygon.** Two sources are
10
+ * 🔒 **The mask comes from a source, never a hand polygon.** Three sources are
11
11
  * read, and nothing else:
12
12
  *
13
13
  * - `seethrough:<dir>`: a See-through run in the wrapper form (`layers.json`
@@ -15,7 +15,9 @@
15
15
  * `OPAQUE_ALPHA_ABOVE`, on the run's own canvas;
16
16
  * - `figure-mask:<dir>`: an assemble output whose `parts.json` declares a
17
17
  * `scene`, the figure being the `figure_rig.png` assemble wrote beside it
18
- * (opaque white inside the figure, opaque black outside).
18
+ * (opaque white inside the figure, opaque black outside);
19
+ * - `matte:<dir>`: a model mask whose receipt binds both raw and final masks
20
+ * to the exact painting bytes and the recorded threshold/transform.
19
21
  *
20
22
  * The mask is taken on its own grid and never fitted: a source whose grid is
21
23
  * not the painting's size is refused by name. With no source the command
@@ -26,6 +28,7 @@
26
28
  * of every file it names; `verifyPlateReceipt` reads it back against the bytes
27
29
  * on disk. Every path in it is relative to the receipt's own directory.
28
30
  */
31
+ import { readMatteSource } from './matte.ts';
29
32
  import { isSeeThroughTransform, inverseSeeThroughMask } from './seethrough-transform.ts';
30
33
  import { createHash } from 'node:crypto';
31
34
  import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, renameSync, rmdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
@@ -43,12 +46,25 @@ export const PLATE_RECEIPT_FILE = 'receipt.json';
43
46
  export const PLATE_MASK_FILE = 'mask.png';
44
47
  export const PLATE_OUTPUT_FILE = 'plate.png';
45
48
 
46
- /** The receipt's top-level keys, in the order they are written. */
49
+ /** The receipt's top-level keys when `grid_transform` is absent, in the order they are written. */
47
50
  export const PLATE_RECEIPT_KEYS = ['spec', 'mode', 'painting', 'mask', 'model', 'params', 'graph', 'gpu', 'output'] as const;
51
+ /** The receipt's top-level keys when `grid_transform` is present (off-grid `core`), in the order they are written. */
52
+ export const PLATE_RECEIPT_GRID_TRANSFORM_KEYS = ['spec', 'mode', 'painting', 'mask', 'model', 'params', 'graph', 'gpu', 'grid_transform', 'output'] as const;
53
+ /** The `grid_transform` object's keys, in the order they are written. */
54
+ export const CORE_GRID_TRANSFORM_KEYS = ['source', 'padded', 'pad', 'pad_fill', 'mask_pad_fill', 'inverse'] as const;
48
55
 
49
56
  export type PlateMode = 'background' | 'foreground';
50
57
  export type PlateGraph = 'lama' | 'core';
51
- export type MaskSource = 'seethrough' | 'figure-mask';
58
+ export type MaskSource = 'seethrough' | 'figure-mask' | 'matte';
59
+
60
+ export interface CoreGridTransform {
61
+ source: [number, number];
62
+ padded: [number, number];
63
+ pad: [0, 0];
64
+ pad_fill: 'edge-replicate';
65
+ mask_pad_fill: 'zero';
66
+ inverse: 'crop';
67
+ }
52
68
 
53
69
  /** The graph ids a receipt names: one per background graph, and the fixed local id of the foreground derivation. */
54
70
  export const PLATE_GRAPH_IDS = {
@@ -71,6 +87,7 @@ export interface PlateReceipt {
71
87
  params: Record<string, string | number | boolean>;
72
88
  graph: string;
73
89
  gpu: string | null;
90
+ grid_transform?: CoreGridTransform;
74
91
  output: { path: string; sha256: string };
75
92
  }
76
93
 
@@ -92,10 +109,10 @@ export function declaredChecksum(value: string | undefined): string {
92
109
  /** `--mask-from <source>:<dir>`, parsed; an absent or unknown source is refused by name. */
93
110
  export function parseMaskFrom(value: string | undefined): { source: MaskSource; dir: string } {
94
111
  if (value === undefined) {
95
- 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');
112
+ 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), or matte:<matte out dir> (run `rig-parts comfy matte`); a hand-drawn mask is not taken');
96
113
  }
97
- const m = /^(seethrough|figure-mask):(.+)$/.exec(value);
98
- if (m === null) fail('PLATE_MASK_SOURCE', '--mask-from', `is ${JSON.stringify(value)}; seethrough:<dir> or figure-mask:<dir> is required`);
114
+ const m = /^(seethrough|figure-mask|matte):(.+)$/.exec(value);
115
+ if (m === null) fail('PLATE_MASK_SOURCE', '--mask-from', `is ${JSON.stringify(value)}; seethrough:<dir>, figure-mask:<dir> or matte:<dir> is required`);
99
116
  return { source: m[1] as MaskSource, dir: m[2] };
100
117
  }
101
118
 
@@ -224,7 +241,11 @@ function bindFigureSource(dir: string, parts: Record<string, unknown>, partsByte
224
241
  */
225
242
  export function readSourceMask(source: MaskSource, dir: string, width: number, height: number, painting?: Raster, paintingBytes?: Uint8Array): FigureMask {
226
243
  if (!existsSync(dir) || !statSync(dir).isDirectory()) {
227
- 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`);
244
+ fail('PLATE_MASK_SOURCE', `${source}:${dir}`, `is not a directory; ${source === 'seethrough' ? 'a See-through run directory (from `rig-parts comfy seethrough`)' : source === 'matte' ? 'a comfy matte directory with receipt.json, model-mask.png and mask.png' : 'an assemble output directory with parts.json and figure_rig.png'} is required`);
245
+ }
246
+ if (source === 'matte') {
247
+ const mask = readMatteSource(dir, paintingBytes, width, height);
248
+ return { width, height, inside: Uint8Array.from({ length: width * height }, (_, p) => mask.data[p * 4] === 255 ? 1 : 0) };
228
249
  }
229
250
  let inside: Uint8Array = new Uint8Array(width * height);
230
251
  if (source === 'seethrough') {
@@ -405,19 +426,91 @@ export function corePlateGraph(painting: string, mask: string, checkpoint: strin
405
426
  };
406
427
  }
407
428
 
408
- /** The `core` graph encodes through the VAE, which crops to multiples of 8; a painting off that grid is refused before anything is uploaded. */
409
- export function coreGridProblem(width: number, height: number, painting: string): Problem | null {
410
- 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` };
429
+ /** The pad-to-8 transform for an off-grid painting on the `core` background graph; `undefined` when already a multiple of 8. */
430
+ export function coreGridTransform(width: number, height: number): CoreGridTransform | undefined {
431
+ if (width % 8 === 0 && height % 8 === 0) return undefined;
432
+ return {
433
+ source: [width, height],
434
+ padded: [Math.ceil(width / 8) * 8, Math.ceil(height / 8) * 8],
435
+ pad: [0, 0],
436
+ pad_fill: 'edge-replicate',
437
+ mask_pad_fill: 'zero',
438
+ inverse: 'crop',
439
+ };
440
+ }
441
+
442
+ /** Validate a recorded `grid_transform` against the bound painting's `width`x`height` and key order. */
443
+ export function isCoreGridTransform(value: unknown, width: number, height: number): value is CoreGridTransform {
444
+ if (typeof value !== 'object' || value === null || Array.isArray(value)) return false;
445
+ const v = value as Record<string, unknown>;
446
+ if (Object.keys(v).join(',') !== CORE_GRID_TRANSFORM_KEYS.join(',')) return false;
447
+ const pair = (p: unknown): p is [number, number] => Array.isArray(p) && p.length === 2 && p.every((n) => Number.isSafeInteger(n));
448
+ if (!pair(v.source) || !pair(v.padded) || !pair(v.pad)) return false;
449
+ const expected = coreGridTransform(width, height);
450
+ if (expected === undefined) return false;
451
+ return (
452
+ v.source[0] === expected.source[0] &&
453
+ v.source[1] === expected.source[1] &&
454
+ v.padded[0] === expected.padded[0] &&
455
+ v.padded[1] === expected.padded[1] &&
456
+ v.pad[0] === 0 &&
457
+ v.pad[1] === 0 &&
458
+ v.pad_fill === 'edge-replicate' &&
459
+ v.mask_pad_fill === 'zero' &&
460
+ v.inverse === 'crop'
461
+ );
462
+ }
463
+
464
+ /**
465
+ * Pad an off-grid painting and its grown mask to the next multiple of 8 on
466
+ * the right and bottom (`pad: [0, 0]`): the painting replicates its right and
467
+ * bottom edges (`edge-replicate`), and the mask pads with `0` (kept as
468
+ * context, never inside the hole). On-grid paintings return unchanged with no
469
+ * transform.
470
+ */
471
+ export function prepareCoreGrid(painting: Raster, mask: FigureMask): { painting: Raster; mask: FigureMask; transform?: CoreGridTransform } {
472
+ const transform = coreGridTransform(painting.width, painting.height);
473
+ if (transform === undefined) return { painting, mask };
474
+ const [W, H] = transform.source;
475
+ const [paddedW, paddedH] = transform.padded;
476
+ const paddedPainting = newRaster(paddedW, paddedH);
477
+ for (let y = 0; y < paddedH; y++) {
478
+ const sy = Math.min(y, H - 1);
479
+ for (let x = 0; x < paddedW; x++) {
480
+ const sx = Math.min(x, W - 1);
481
+ const src = (sy * W + sx) * 4;
482
+ const dst = (y * paddedW + x) * 4;
483
+ paddedPainting.data.set(painting.data.subarray(src, src + 4), dst);
484
+ }
485
+ }
486
+ const paddedMask: FigureMask = { width: paddedW, height: paddedH, inside: new Uint8Array(paddedW * paddedH) };
487
+ for (let y = 0; y < H; y++) {
488
+ paddedMask.inside.set(mask.inside.subarray(y * W, (y + 1) * W), y * paddedW);
489
+ }
490
+ return { painting: paddedPainting, mask: paddedMask, transform };
491
+ }
492
+
493
+ /** Crop a padded `core` output back to the painting's exact `source` grid at `transform.pad` (`[0, 0]`). */
494
+ export function cropCoreGrid(padded: Raster, transform: CoreGridTransform): Raster {
495
+ const [W, H] = transform.source;
496
+ const [padX, padY] = transform.pad;
497
+ const out = newRaster(W, H);
498
+ for (let y = 0; y < H; y++) {
499
+ const src = ((y + padY) * padded.width + padX) * 4;
500
+ out.data.set(padded.data.subarray(src, src + W * 4), y * W * 4);
501
+ }
502
+ return out;
411
503
  }
412
504
 
413
505
  // ---------------------------------------------------------------------------
414
506
  // the receipt
415
507
  // ---------------------------------------------------------------------------
416
508
 
417
- /** The receipt's JSON text, its keys in `PLATE_RECEIPT_KEYS` order. */
509
+ /** The receipt's JSON text, its keys in `PLATE_RECEIPT_KEYS` (or `PLATE_RECEIPT_GRID_TRANSFORM_KEYS` when `grid_transform` is present) order. */
418
510
  export function receiptText(r: PlateReceipt): string {
419
511
  const ordered: Record<string, unknown> = {};
420
- for (const k of PLATE_RECEIPT_KEYS) ordered[k] = r[k];
512
+ const keys = r.grid_transform === undefined ? PLATE_RECEIPT_KEYS : PLATE_RECEIPT_GRID_TRANSFORM_KEYS;
513
+ for (const k of keys) ordered[k] = r[k];
421
514
  return `${JSON.stringify(ordered, null, 2)}\n`;
422
515
  }
423
516
 
@@ -428,21 +521,28 @@ export function receiptPath(receiptDir: string, path: string): string {
428
521
 
429
522
  /**
430
523
  * Every problem between a receipt and the bytes on disk: its spec and key
431
- * order, and each of the painting, mask and output whose sha256 is not that of
432
- * the file it names (or whose file is gone).
524
+ * order, each of the painting, mask and output whose sha256 is not that of
525
+ * the file it names (or whose file is gone), and `grid_transform` re-derived
526
+ * from the decoded painting, mode and graph.
433
527
  */
434
528
  export function verifyPlateReceipt(receiptFile: string): Problem[] {
435
529
  const problems: Problem[] = [];
436
530
  let r: Record<string, unknown>;
437
531
  try {
438
- r = JSON.parse(readFileSync(receiptFile, 'utf8')) as Record<string, unknown>;
532
+ const parsed: unknown = JSON.parse(readFileSync(receiptFile, 'utf8'));
533
+ if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
534
+ return [{ code: 'PLATE_RECEIPT_READ', object: receiptFile, detail: 'does not parse as a JSON object' }];
535
+ }
536
+ r = parsed as Record<string, unknown>;
439
537
  } catch (err) {
440
538
  return [{ code: 'PLATE_RECEIPT_READ', object: receiptFile, detail: `does not parse as JSON (${(err as Error).message})` }];
441
539
  }
442
540
  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` });
443
541
  const keys = Object.keys(r).join(',');
444
- 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` });
542
+ const expectedKeys = 'grid_transform' in r ? PLATE_RECEIPT_GRID_TRANSFORM_KEYS : PLATE_RECEIPT_KEYS;
543
+ if (keys !== expectedKeys.join(',')) problems.push({ code: 'PLATE_RECEIPT_KEYS', object: receiptFile, detail: `has keys ${keys}; ${expectedKeys.join(',')} in that order is required` });
445
544
  const base = dirname(receiptFile);
545
+ let paintingRaster: Raster | undefined;
446
546
  for (const field of ['painting', 'mask', 'output'] as const) {
447
547
  const f = r[field] as { path?: unknown; sha256?: unknown } | undefined;
448
548
  if (typeof f?.path !== 'string' || typeof f.sha256 !== 'string') {
@@ -454,8 +554,42 @@ export function verifyPlateReceipt(receiptFile: string): Problem[] {
454
554
  problems.push({ code: 'PLATE_RECEIPT_FILE', object: `${receiptFile} ${field}`, detail: `names ${f.path}, which does not exist` });
455
555
  continue;
456
556
  }
457
- const found = sha256(new Uint8Array(readFileSync(file)));
557
+ const bytes = new Uint8Array(readFileSync(file));
558
+ const found = sha256(bytes);
458
559
  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}` });
560
+ if (field === 'painting') {
561
+ try { paintingRaster = decodePngBytes(bytes, file); } catch { /* hash/read already covers invalid bytes */ }
562
+ }
563
+ }
564
+ if (paintingRaster !== undefined) {
565
+ const expectedTransform = r.mode === 'background' && r.graph === PLATE_GRAPH_IDS.core ? coreGridTransform(paintingRaster.width, paintingRaster.height) : undefined;
566
+ if (expectedTransform !== undefined) {
567
+ if (!('grid_transform' in r) || r.grid_transform === undefined) {
568
+ problems.push({
569
+ code: 'PLATE_RECEIPT_GRID_TRANSFORM',
570
+ object: `${receiptFile} grid_transform`,
571
+ detail: `is absent; off-grid core painting (${paintingRaster.width}x${paintingRaster.height}) requires ${JSON.stringify(expectedTransform)}`,
572
+ });
573
+ } else if (!isCoreGridTransform(r.grid_transform, paintingRaster.width, paintingRaster.height)) {
574
+ problems.push({
575
+ code: 'PLATE_RECEIPT_GRID_TRANSFORM',
576
+ object: `${receiptFile} grid_transform`,
577
+ detail: `is ${JSON.stringify(r.grid_transform)}; off-grid core painting (${paintingRaster.width}x${paintingRaster.height}) requires ${JSON.stringify(expectedTransform)} in ${CORE_GRID_TRANSFORM_KEYS.join(',')} order`,
578
+ });
579
+ }
580
+ } else if ('grid_transform' in r) {
581
+ problems.push({
582
+ code: 'PLATE_RECEIPT_GRID_TRANSFORM',
583
+ object: `${receiptFile} grid_transform`,
584
+ detail: `is ${JSON.stringify(r.grid_transform)}; no grid_transform is permitted for ${r.mode === 'background' && r.graph === PLATE_GRAPH_IDS.core ? `on-grid painting ${paintingRaster.width}x${paintingRaster.height}` : `mode ${JSON.stringify(r.mode)} graph ${JSON.stringify(r.graph)}`}`,
585
+ });
586
+ }
587
+ } else if ('grid_transform' in r && (typeof r.grid_transform !== 'object' || r.grid_transform === null || Array.isArray(r.grid_transform) || Object.keys(r.grid_transform as object).join(',') !== CORE_GRID_TRANSFORM_KEYS.join(','))) {
588
+ problems.push({
589
+ code: 'PLATE_RECEIPT_GRID_TRANSFORM',
590
+ object: `${receiptFile} grid_transform`,
591
+ detail: `is ${JSON.stringify(r.grid_transform)}; a valid grid_transform in ${CORE_GRID_TRANSFORM_KEYS.join(',')} order is required`,
592
+ });
459
593
  }
460
594
  return problems;
461
595
  }
@@ -493,6 +627,7 @@ export interface PlateWrite {
493
627
  params: PlateReceipt['params'];
494
628
  graph: string;
495
629
  gpu: string | null;
630
+ gridTransform?: CoreGridTransform;
496
631
  }
497
632
 
498
633
  let foregroundStageSeq = 0;
@@ -521,6 +656,7 @@ export function publishPlate(w: PlateWrite): PlateReceipt {
521
656
  params: w.params,
522
657
  graph: w.graph,
523
658
  gpu: w.gpu,
659
+ ...(w.gridTransform === undefined ? {} : { grid_transform: w.gridTransform }),
524
660
  output: { path: PLATE_OUTPUT_FILE, sha256: plate.sha256 },
525
661
  };
526
662
  writeFileSync(join(stage, PLATE_RECEIPT_FILE), receiptText(receipt));
@@ -1,6 +1,8 @@
1
1
  import { newRaster, type Raster } from './raster/types.ts';
2
2
  import { resize } from './raster/resize.ts';
3
3
 
4
+ export type SeeThroughPadFill = 'rgba-zero' | 'rgb-black-opaque';
5
+
4
6
  /** image_sha256 in the enclosing run record binds the source PNG bytes. */
5
7
  export interface SeeThroughTransform {
6
8
  source: [number, number];
@@ -8,13 +10,17 @@ export interface SeeThroughTransform {
8
10
  pad: [number, number];
9
11
  scale: number;
10
12
  resample: 'parts-lanczos3-rgba';
11
- pad_fill: 'rgb-black-opaque';
13
+ pad_fill: SeeThroughPadFill;
12
14
  target: [number, number];
13
15
  inverse: 'nearest-pixel-centres';
14
16
  }
15
17
 
16
18
  /** Prepare only non-square images. Square inputs keep their original upload bytes. */
17
- export function prepareSeeThroughInput(source: Raster, resolution: number): { image: Raster; transform?: SeeThroughTransform } {
19
+ export function prepareSeeThroughInput(
20
+ source: Raster,
21
+ resolution: number,
22
+ padFill: SeeThroughPadFill,
23
+ ): { image: Raster; transform?: SeeThroughTransform } {
18
24
  if (source.width === source.height) return { image: source };
19
25
  const side = Math.max(source.width, source.height);
20
26
  const left = Math.floor((side - source.width) / 2);
@@ -27,7 +33,7 @@ export function prepareSeeThroughInput(source: Raster, resolution: number): { im
27
33
  image: resize(padded, resolution, resolution, 'lanczos3'),
28
34
  transform: {
29
35
  source: [source.width, source.height], padded: [side, side], pad: [left, top],
30
- scale: resolution / side, resample: 'parts-lanczos3-rgba', pad_fill: 'rgb-black-opaque', target: [resolution, resolution], inverse: 'nearest-pixel-centres',
36
+ scale: resolution / side, resample: 'parts-lanczos3-rgba', pad_fill: padFill, target: [resolution, resolution], inverse: 'nearest-pixel-centres',
31
37
  },
32
38
  };
33
39
  }
@@ -43,7 +49,9 @@ export function isSeeThroughTransform(value: unknown, width: number, height: num
43
49
  side === Math.max(width, height) && v.padded[1] === side &&
44
50
  v.pad[0] >= 0 && v.pad[1] >= 0 && v.pad[0] + width <= side && v.pad[1] + height <= side &&
45
51
  v.target[0] === targetWidth && v.target[1] === targetHeight && targetWidth > 0 && targetWidth === targetHeight &&
46
- v.scale === targetWidth / side && v.resample === 'parts-lanczos3-rgba' && v.pad_fill === 'rgb-black-opaque' && v.inverse === 'nearest-pixel-centres';
52
+ v.scale === targetWidth / side && v.resample === 'parts-lanczos3-rgba' &&
53
+ (v.pad_fill === 'rgba-zero' || v.pad_fill === 'rgb-black-opaque') &&
54
+ v.inverse === 'nearest-pixel-centres';
47
55
  }
48
56
 
49
57
  /** Sample the union at transformed source pixel centres. Sub-grid detail cannot be recovered. */
@@ -1,9 +1,13 @@
1
1
  {
2
- "_comment": "API-format graph for jtydhr88/ComfyUI-See-through (its node classes and inputs as a box running the wrapper lists them on /object_info; the adapter checks every node and input against the box's own /object_info before it submits). Every %NAME% string is filled by src/graphs.ts fillSeeThrough, and a placeholder nothing fills is refused before submission. The LoadImage 'upload' widget of the UI format is left out: it is not an input /object_info lists. Top-level keys starting with _ are annotations and are dropped before /prompt. SeeThrough_SavePSD writes one PNG per layer and a <prefix>_<timestamp>_layers.json manifest into the box's output directory, and records that manifest's file name in output/seethrough_psd_info.log; the two SaveImage nodes are previews and are what /history lists.",
2
+ "_comment": "API-format graph for jtydhr88/ComfyUI-See-through (its node classes and inputs as a box running the wrapper lists them on /object_info; the adapter checks every node and input against the box's own /object_info before it submits). Every %NAME% string is filled by src/graphs.ts fillSeeThrough, and a placeholder nothing fills is refused before submission. The LoadImage 'upload' widget of the UI format is left out: it is not an input /object_info lists. LoadImage's IMAGE (output 0) and MASK (output 1) rejoin through JoinImageWithAlpha so a 4-channel RGBA image reaches SeeThrough_GenerateLayers. Top-level keys starting with _ are annotations and are dropped before /prompt. SeeThrough_SavePSD writes one PNG per layer and a <prefix>_<timestamp>_layers.json manifest into the box's output directory, and records that manifest's file name in output/seethrough_psd_info.log; the two SaveImage nodes are previews and are what /history lists.",
3
3
  "1": {
4
4
  "class_type": "LoadImage",
5
5
  "inputs": { "image": "%IMAGE%" }
6
6
  },
7
+ "10": {
8
+ "class_type": "JoinImageWithAlpha",
9
+ "inputs": { "image": ["1", 0], "alpha": ["1", 1] }
10
+ },
7
11
  "2": {
8
12
  "class_type": "SeeThrough_LoadLayerDiffModel",
9
13
  "inputs": {
@@ -19,7 +23,7 @@
19
23
  "3": {
20
24
  "class_type": "SeeThrough_GenerateLayers",
21
25
  "inputs": {
22
- "image": ["1", 0],
26
+ "image": ["10", 0],
23
27
  "layerdiff_model": ["2", 0],
24
28
  "seed": "%SEED%",
25
29
  "resolution": "%RESOLUTION%",