@rig-c/parts 1.67.0 → 1.69.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.
@@ -0,0 +1,418 @@
1
+ /**
2
+ * Scalar input sheets for #773. This module registers authored data; it does
3
+ * not generate geometry, infer depth, or emit motion. Core consumes the emitted
4
+ * {image, near, zScale} on a generator (#763 owns production generators).
5
+ */
6
+ import { createHash } from 'node:crypto';
7
+ import { existsSync, readFileSync } from 'node:fs';
8
+ import { basename, isAbsolute, join, resolve } from 'node:path';
9
+ import { type Problem, PartsError, refuseIfAny } from './errors.ts';
10
+ import { decodePngBytes } from './raster/png.ts';
11
+ import { newRaster, type Raster } from './raster/types.ts';
12
+ import type { Layer, LayerSet } from './layers.ts';
13
+
14
+ /** Far is high: round(255*clip(raw,0,1)), never crop-local normalization.
15
+ * Source: jtydhr88/ComfyUI-See-through@98d754bf04f668647919ab750eccb0e0640faa81
16
+ * nodes.py:261–281, 875–884, 945–952. The later ordering-median adjustment does
17
+ * not rewrite this array. Its median is a reading, never a polarity gate.
18
+ */
19
+ export const SEETHROUGH_DEPTH_NEAR = 'black' as const;
20
+ export type DepthNear = 'black' | 'white';
21
+ export interface DepthReading {
22
+ orderingMedian: number | null;
23
+ sheetMedian: number | null;
24
+ relation: 'same' | 'opposite' | 'indeterminate';
25
+ }
26
+ export interface SourceDepthSheet {
27
+ file: string;
28
+ sha256: string;
29
+ pixels: Raster;
30
+ reading: DepthReading;
31
+ /** Internal copy/warp provenance, set only after declared units resolve. */
32
+ near?: DepthNear;
33
+ zScale?: number;
34
+ sources?: DepthSource[];
35
+ }
36
+ export interface UserDepthSheet { image: string; near: DepthNear; zScale: number }
37
+ export interface DepthRunConfig { layers?: Record<string, UserDepthSheet>; atlas?: UserDepthSheet }
38
+ export interface DepthConfig { zScale?: number; full?: DepthRunConfig; head?: DepthRunConfig }
39
+ /** Explicit caller context; never inferred from a filename or sheet presence. */
40
+ export interface DepthBinding { config: DepthConfig; run: 'full' | 'head'; base: string }
41
+ /** Legacy metadata retained without file I/O or value validation until opt-in. */
42
+ export interface DeferredDepthSource { filename: unknown; base: string }
43
+ export interface DepthSource {
44
+ from: string;
45
+ image: string;
46
+ sha256: string;
47
+ crop: [number, number, number, number];
48
+ reading: DepthReading;
49
+ }
50
+ export interface PartDepthReference {
51
+ image: string;
52
+ near: DepthNear;
53
+ zScale: number;
54
+ sources: DepthSource[];
55
+ }
56
+ export interface RegisteredDepth {
57
+ sheet: SourceDepthSheet;
58
+ layer: Layer;
59
+ near: DepthNear;
60
+ zScale: number;
61
+ }
62
+
63
+ /** RGB-encoded gray is a sheet; a tinted preview is not. Alpha must be 255. */
64
+ export function depthSheetProblems(p: Raster, size: readonly [number, number], at: string): Problem[] {
65
+ const out: Problem[] = [];
66
+ if (p.width !== size[0] || p.height !== size[1]) out.push({ code: 'DEPTH_SHEET_SIZE', object: at, detail: `is ${p.width}x${p.height}; source grid ${size[0]}x${size[1]} is required — supply the sheet for this layer or declared canvas` });
67
+ let color = 0, alpha = 0, firstColor = -1, firstAlpha = -1;
68
+ for (let i = 0; i < p.width * p.height; i++) {
69
+ if (p.data[i * 4] !== p.data[i * 4 + 1] || p.data[i * 4 + 1] !== p.data[i * 4 + 2]) { color++; if (firstColor < 0) firstColor = i; }
70
+ if (p.data[i * 4 + 3] !== 255) { alpha++; if (firstAlpha < 0) firstAlpha = i; }
71
+ }
72
+ if (color > 0) out.push({ code: 'DEPTH_SHEET_GREYSCALE', object: at, detail: `has ${color} color pixels, first (${firstColor % p.width}, ${Math.floor(firstColor / p.width)}); R=G=B is required — provide grayscale data, not a color preview` });
73
+ if (alpha > 0) out.push({ code: 'DEPTH_SHEET_OPAQUE', object: at, detail: `has ${alpha} nonopaque pixels, first (${firstAlpha % p.width}, ${Math.floor(firstAlpha / p.width)}); alpha 255 everywhere is required — provide a fully declared opaque sheet` });
74
+ return out;
75
+ }
76
+
77
+ /** Exact median of u8 levels on the writer's ORIGINAL art alpha>10 mask. */
78
+ export function depthReading(sheet: Raster, art: Raster, orderingMedian: number | null): DepthReading {
79
+ const histogram = new Uint32Array(256); let n = 0;
80
+ for (let i = 0; i < art.width * art.height; i++) if (art.data[i * 4 + 3] > 10) { histogram[sheet.data[i * 4]]++; n++; }
81
+ let median: number | null = null;
82
+ if (n > 0) {
83
+ const lo = Math.floor((n - 1) / 2), hi = Math.floor(n / 2); let sum = 0, a = -1, b = -1;
84
+ for (let v = 0; v < 256; v++) { sum += histogram[v]; if (a < 0 && sum > lo) a = v; if (sum > hi) { b = v; break; } }
85
+ median = (a + b) / (2 * 255);
86
+ }
87
+ const halfLevel = 0.5 / 255;
88
+ const same = median !== null && orderingMedian !== null && Math.abs(median - orderingMedian) <= halfLevel;
89
+ const opposite = median !== null && orderingMedian !== null && Math.abs(1 - median - orderingMedian) <= halfLevel;
90
+ return { orderingMedian, sheetMedian: median, relation: same === opposite ? 'indeterminate' : same ? 'same' : 'opposite' };
91
+ }
92
+
93
+ export function readSourceDepth(file: string, art: Raster, ordering: number | null): SourceDepthSheet {
94
+ if (!existsSync(file)) throw new PartsError([{ code: 'DEPTH_SHEET_PRESENT', object: file, detail: 'is missing; the declared depth PNG is required — restore it or remove the declaration deliberately, not through fallback' }]);
95
+ let bytes: Buffer; let pixels: Raster;
96
+ try { bytes = readFileSync(file); pixels = decodePngBytes(bytes, file); } catch (e) { throw new PartsError([{ code: 'DEPTH_SHEET_DECODES', object: file, detail: `is not a readable PNG: ${(e as Error).message}; supply the declared grayscale PNG` }]); }
97
+ refuseIfAny(depthSheetProblems(pixels, [art.width, art.height], file));
98
+ return { file: basename(file), sha256: createHash('sha256').update(bytes).digest('hex'), pixels, reading: depthReading(pixels, art, ordering) };
99
+ }
100
+
101
+ /** Scalar bilinear sample at pixel centres, clamp to the declared rectangular
102
+ * source grid, then round half up to u8. No color premultiplication/normalizing.
103
+ * This is the raw-level bilinear definition, matching Core depth.ts:127–157;
104
+ * quantization is parts' explicit sheet-writing step, not Core's float sample.
105
+ */
106
+ export function sampleDepthFloat(p: Raster, x: number, y: number): number {
107
+ const fx = x - 0.5, fy = y - 0.5, ix = Math.floor(fx), iy = Math.floor(fy), ax = fx - ix, ay = fy - iy;
108
+ const at = (u: number, v: number): number => p.data[(Math.max(0, Math.min(p.height - 1, v)) * p.width + Math.max(0, Math.min(p.width - 1, u))) * 4];
109
+ return (1 - ay) * ((1 - ax) * at(ix, iy) + ax * at(ix + 1, iy)) + ay * ((1 - ax) * at(ix, iy + 1) + ax * at(ix + 1, iy + 1));
110
+ }
111
+
112
+ export function sampleDepthLevel(p: Raster, x: number, y: number): number { return Math.floor(sampleDepthFloat(p, x, y) + 0.5); }
113
+
114
+ /** Strict optional part reference; only the first three fields go to Core. */
115
+ export function partDepthProblems(raw: unknown, at: string): Problem[] {
116
+ const out: Problem[] = []; const fail = (field: string, detail: string): void => { out.push({ code: 'PARTS_DEPTH_REFERENCE', object: `${at}.${field}`, detail }); };
117
+ if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) { fail('depth', 'is not an object; image, near, zScale and sources are required'); return out; }
118
+ const d = raw as Record<string, unknown>;
119
+ for (const k of Object.keys(d)) if (!['image', 'near', 'zScale', 'sources'].includes(k)) fail(k, 'is unknown; image, near, zScale and sources are the only reference fields');
120
+ if (typeof d.image !== 'string' || !/^[^/\\]+\.png$/.test(d.image)) fail('image', 'requires one PNG filename, relative to the sheet directory');
121
+ if (d.near !== 'black' && d.near !== 'white') fail('near', 'requires declared black or white');
122
+ if (typeof d.zScale !== 'number' || !Number.isFinite(d.zScale) || d.zScale <= 0) fail('zScale', 'requires positive finite authored world units');
123
+ if (!Array.isArray(d.sources) || d.sources.length === 0) fail('sources', 'requires at least one exact source/provenance record');
124
+ else for (const [i, value] of d.sources.entries()) {
125
+ if (typeof value !== 'object' || value === null || Array.isArray(value)) { fail(`sources[${i}]`, 'requires a source object'); continue; }
126
+ const s = value as Record<string, unknown>;
127
+ for (const k of Object.keys(s)) if (!['from', 'image', 'sha256', 'crop', 'reading'].includes(k)) fail(`sources[${i}].${k}`, 'is unknown; use the declared source fields');
128
+ if (typeof s.from !== 'string' || !/^(full|head):.+$/.test(s.from)) fail(`sources[${i}].from`, 'requires run:layer provenance');
129
+ if (typeof s.image !== 'string' || s.image.length === 0 || /[/\\]/.test(s.image)) fail(`sources[${i}].image`, 'requires the original source filename, without an absolute path');
130
+ if (typeof s.sha256 !== 'string' || !/^[a-f0-9]{64}$/.test(s.sha256)) fail(`sources[${i}].sha256`, 'requires the source-file SHA256');
131
+ if (!Array.isArray(s.crop) || s.crop.length !== 4 || !s.crop.every(Number.isInteger) || s.crop[0] < 0 || s.crop[1] < 0 || !(s.crop[2] > s.crop[0] && s.crop[3] > s.crop[1])) fail(`sources[${i}].crop`, 'requires a nonempty integer source rectangle [left,top,right,bottom]');
132
+ const q = s.reading;
133
+ if (typeof q !== 'object' || q === null || Array.isArray(q)) fail(`sources[${i}].reading`, 'requires orderingMedian, sheetMedian and relation');
134
+ else {
135
+ const v = q as Record<string, unknown>;
136
+ if (Object.keys(v).some(k => !['orderingMedian', 'sheetMedian', 'relation'].includes(k))) fail(`sources[${i}].reading`, 'has an unknown reading field');
137
+ for (const k of ['orderingMedian', 'sheetMedian']) if (v[k] !== null && (typeof v[k] !== 'number' || !Number.isFinite(v[k]))) fail(`sources[${i}].reading.${k}`, 'requires a finite number or explicit null');
138
+ if (!['same', 'opposite', 'indeterminate'].includes(String(v.relation))) fail(`sources[${i}].reading.relation`, 'requires same, opposite or indeterminate; this is not a gate');
139
+ }
140
+ }
141
+ return out;
142
+ }
143
+
144
+ /** Resolve sheets once per input run. Declared files never fall through. */
145
+ export function registerDepthRun(set: LayerSet, run: 'full' | 'head', cfg: DepthConfig | undefined, base: string): Map<string, RegisteredDepth> {
146
+ const out = new Map<string, RegisteredDepth>(), problems: Problem[] = [];
147
+ if (cfg === undefined) return out;
148
+ for (const hidden of set.hidden) if (hidden.depthHint !== undefined) problems.push({ code: 'DEPTH_SHEET_FILENAME', object: `hidden layer "${hidden.name}" depth_filename`, detail: 'active scalar inputs require a drawn layer; remove the hidden-art depth declaration' });
149
+ const user = cfg?.[run];
150
+ if (user?.atlas !== undefined && user.layers !== undefined && Object.keys(user.layers).length > 0) problems.push({ code: 'DEPTH_SOURCE_AMBIGUOUS', object: `config.depth.${run}`, detail: 'declares both a canvas atlas and per-layer sheets; choose one fallback route explicitly' });
151
+ for (const name of Object.keys(user?.layers ?? {})) if (!set.layers.some(l => l.name === name)) problems.push({ code: 'DEPTH_SOURCE_RESOLVES', object: `config.depth.${run}.layers.${name}`, detail: 'names no source layer in this run; use an exact layer name' });
152
+ let atlas: SourceDepthSheet | null = null;
153
+ if (user?.atlas !== undefined && (set.layers.length === 0 || set.layers.some(l => l.depthSheet?.sources === undefined || l.depthSheet.near === undefined || l.depthSheet.zScale === undefined))) {
154
+ try { atlas = readSourceDepth(resolve(base, user.atlas.image), newRaster(set.canvas.w, set.canvas.h), null); } catch (e) { if (e instanceof PartsError) problems.push(...e.problems); else throw e; }
155
+ }
156
+ for (const layer of set.layers) {
157
+ const from = `${run}:${layer.name}`, supplied = user?.layers?.[layer.name] ?? user?.atlas;
158
+ try {
159
+ let sheet = layer.depthSheet;
160
+ // Copied material already bound before art operations keeps its original
161
+ // provenance and units. Never reopen its original file on a changed grid.
162
+ if (sheet?.sources !== undefined && sheet.near !== undefined && sheet.zScale !== undefined) {
163
+ problems.push(...depthSheetProblems(sheet.pixels, [layer.pixels.width, layer.pixels.height], from));
164
+ if (!Number.isFinite(sheet.zScale) || sheet.zScale <= 0) problems.push({ code: 'DEPTH_ZSCALE_REQUIRED', object: from, detail: 'bound source requires positive finite world units; restore its declared zScale' });
165
+ if (sheet.near !== 'black' && sheet.near !== 'white') problems.push({ code: 'DEPTH_NEAR_REQUIRED', object: from, detail: 'bound source requires explicit black or white polarity; restore its declaration' });
166
+ out.set(from, { sheet, layer, near: sheet.near, zScale: sheet.zScale });
167
+ continue;
168
+ }
169
+ const hint = layer.depthHint;
170
+ if (hint !== undefined) {
171
+ const file = hint.filename;
172
+ if (typeof file !== 'string' || file === '' || isAbsolute(file) || /[\\/]/.test(file) || file === '..') throw new PartsError([{ code: 'DEPTH_SHEET_FILENAME', object: `${from} depth_filename`, detail: 'active writer source requires a drawn layer plain depth PNG filename' }]);
173
+ const paths = [join(hint.base, file), join(hint.base, 'parts', `${layer.name}_depth.png`)];
174
+ const found = paths.filter(p => existsSync(p));
175
+ if (found.length === 2 && !readFileSync(found[0]).equals(readFileSync(found[1]))) throw new PartsError([{ code: 'DEPTH_SHEET_UNAMBIGUOUS', object: from, detail: `${paths.join(' and ')} differ; keep one source or identical bytes` }]);
176
+ sheet = readSourceDepth(found[0] ?? paths[0], layer.pixels, layer.depth);
177
+ }
178
+ if (sheet !== undefined && supplied !== undefined) throw new PartsError([{ code: 'DEPTH_SOURCE_AMBIGUOUS', object: from, detail: 'has both depth_filename and a user declaration; the writer file is authoritative — remove the unused fallback for this layer' }]);
179
+ let near: DepthNear = sheet?.near ?? SEETHROUGH_DEPTH_NEAR, zScale = sheet?.zScale ?? cfg?.zScale;
180
+ if (sheet === undefined && supplied !== undefined) {
181
+ near = supplied.near; zScale = supplied.zScale;
182
+ if (user?.layers?.[layer.name] !== undefined) sheet = readSourceDepth(resolve(base, supplied.image), layer.pixels, layer.depth);
183
+ else if (atlas !== null) {
184
+ const p = newRaster(layer.pixels.width, layer.pixels.height);
185
+ for (let y = 0; y < p.height; y++) for (let x = 0; x < p.width; x++) p.data.set(atlas.pixels.data.subarray(((y + layer.top) * atlas.pixels.width + x + layer.left) * 4, ((y + layer.top) * atlas.pixels.width + x + layer.left) * 4 + 4), (y * p.width + x) * 4);
186
+ sheet = { ...atlas, pixels: p, reading: depthReading(p, layer.pixels, layer.depth) };
187
+ }
188
+ }
189
+ if (sheet === undefined) continue;
190
+ if (zScale === undefined || !Number.isFinite(zScale) || zScale <= 0) throw new PartsError([{ code: 'DEPTH_ZSCALE_REQUIRED', object: from, detail: 'has a depth image but no positive finite config.depth.zScale; declare world units, never derive scale from eight bits' }]);
191
+ out.set(from, { sheet, layer, near, zScale });
192
+ } catch (e) { if (e instanceof PartsError) problems.push(...e.problems); else throw e; }
193
+ }
194
+ refuseIfAny(problems); return out;
195
+ }
196
+
197
+ export interface DepthTransport {
198
+ map: (run: 'full' | 'head') => { sx: number; tx: number; ty: number };
199
+ width: number;
200
+ /** Same last-writer ownership used for the art's merge/cut provenance. */
201
+ extend: readonly string[];
202
+ owner: Int32Array;
203
+ ring: Uint8Array;
204
+ region: Uint8Array | null;
205
+ unsupported?: string;
206
+ copiedSource?: (x: number, y: number) => { key: string; ring: boolean } | null;
207
+ }
208
+ /** Resample on the FINAL unpadded part grid. Visible synthesized/unsupported
209
+ * material refuses; transparent cells and later PAD4 use explicit edge clamp.
210
+ * No geometry, art pixels, source field or calibration are changed here.
211
+ */
212
+ export function transportPartDepth(
213
+ part: { name: string; from: string; x: number; y: number; w: number; h: number },
214
+ art: Raster,
215
+ registered: ReadonlyMap<string, RegisteredDepth>,
216
+ transport: DepthTransport,
217
+ ): { reference: PartDepthReference; image: Raster } | undefined {
218
+ const keys = [part.from, ...transport.extend];
219
+ const initial = keys.map(k => registered.get(k)).find((s): s is RegisteredDepth => s !== undefined);
220
+ if (initial === undefined) return undefined;
221
+ const fail = (detail: string): never => { throw new PartsError([{ code: 'DEPTH_PART_SUPPORT', object: `part "${part.name}"`, detail }]); };
222
+ if (transport.unsupported !== undefined) fail(`${transport.unsupported}; an exact source-bound scalar transport is required`);
223
+ const image = newRaster(part.w, part.h), used = new Map<string, RegisteredDepth>();
224
+ for (let y = 0; y < part.h; y++) for (let x = 0; x < part.w; x++) {
225
+ const rx = part.x + x, ry = part.y + y, pos = ry * transport.width + rx;
226
+ const visible = art.data[(y * part.w + x) * 4 + 3] > 0;
227
+ const copied = transport.copiedSource?.(rx, ry);
228
+ const own = transport.owner[pos], key = copied?.key ?? (own < 0 ? part.from : transport.extend[own]);
229
+ const source = registered.get(key);
230
+ if (visible && (source === undefined || (copied === undefined || copied === null ? transport.ring[pos] !== 0 : copied.ring) || (copied == null && transport.region?.[pos] === 0))) fail(`rig pixel (${rx},${ry}) has ${source === undefined ? `no declared sheet for ${key}` : transport.ring[pos] !== 0 ? 'a synthesized merge rim' : 'replacement under-art outside the original cut material'}; provide a source sheet/registration for this material, never a background depth`);
231
+ const input = source ?? initial;
232
+ if (input.near !== initial.near || input.zScale !== initial.zScale) fail(`source ${key} uses near=${input.near}, zScale=${input.zScale}; a merged sheet requires the same declared convention and units as ${initial.near}/${initial.zScale}, not implicit per-source remapping`);
233
+ const sourceKey = source === undefined ? keys.find(k => registered.get(k) === initial) as string : key;
234
+ const run = sourceKey.startsWith('head:') ? 'head' : 'full';
235
+ const m = transport.map(run), px = (rx - m.tx) / m.sx - input.layer.left + 0.5, py = (ry - m.ty) / m.sx - input.layer.top + 0.5;
236
+ if (visible && (px < 0 || py < 0 || px > input.sheet.pixels.width || py > input.sheet.pixels.height)) fail(`rig pixel (${rx},${ry}) maps to source (${px},${py}) outside ${input.sheet.pixels.width}x${input.sheet.pixels.height}; source art filtering/generated material has no declared depth there`);
237
+ const level = sampleDepthLevel(input.sheet.pixels, px, py);
238
+ image.data.set([level, level, level, 255], (y * part.w + x) * 4);
239
+ if (visible && source !== undefined) used.set(key, source);
240
+ }
241
+ return { image, reference: {
242
+ image: `${part.name}_depth.png`, near: initial.near, zScale: initial.zScale,
243
+ sources: [...new Map([...used].flatMap(([from, s]) => s.sheet.sources ?? [{ from, image: s.sheet.file, sha256: s.sheet.sha256, crop: [s.layer.left, s.layer.top, s.layer.right, s.layer.bottom] as [number, number, number, number], reading: s.sheet.reading }]).map(s => [`${s.from}:${s.sha256}`, s])).values()],
244
+ } };
245
+ }
246
+
247
+ /** Four-pixel rig padding repeats the part sheet's edge, exactly Core's clamp
248
+ * at the old boundary. This is not silhouette extrapolation/nearest-core fill.
249
+ */
250
+ export function padDepthSheet(source: Raster, pad: number): Raster {
251
+ const result = newRaster(source.width + 2 * pad, source.height + 2 * pad);
252
+ for (let y = 0; y < result.height; y++) for (let x = 0; x < result.width; x++) {
253
+ const v = sampleDepthLevel(source, x - pad + 0.5, y - pad + 0.5);
254
+ result.data.set([v, v, v, 255], (y * result.width + x) * 4);
255
+ }
256
+ return result;
257
+ }
258
+
259
+ /**
260
+ * Extend a part's depth sheet across its transparent and semi-transparent
261
+ * margin from the nearest opaque texel (`alpha === 255`, falling back to
262
+ * `alpha > 0` when a part has no fully opaque texel), before `padDepthSheet`
263
+ * edge-clamps into the `PAD` border.
264
+ *
265
+ * A `grid` generator spans the part's rectangular bounding box, so any vertex
266
+ * outside the opaque silhouette would otherwise sample the monocular estimator's
267
+ * background cliff and fold the border triangles at small turn angles.
268
+ *
269
+ * Exact Euclidean nearest seed, ties broken deterministically by row-major seed
270
+ * index. Any interior seed whose 8-neighbours are all seeds is strictly farther
271
+ * from every non-seed texel than its step neighbour toward that texel, so
272
+ * scanning 8-boundary seeds yields the identical minimum and tie-break as
273
+ * scanning all seeds.
274
+ */
275
+ export function extendDepthSilhouette(source: Raster, art: Raster): Raster {
276
+ if (source.width !== art.width || source.height !== art.height) {
277
+ throw new PartsError([{
278
+ code: 'DEPTH_SILHOUETTE_SIZE_MISMATCH',
279
+ object: 'depth silhouette extension',
280
+ detail: `source sheet is ${source.width}x${source.height}; art is ${art.width}x${art.height}`,
281
+ }]);
282
+ }
283
+ const w = source.width, h = source.height, n = w * h;
284
+ const seedMask = new Uint8Array(n);
285
+ let seedCount = 0;
286
+ for (let i = 0; i < n; i++) {
287
+ if (art.data[i * 4 + 3] === 255) {
288
+ seedMask[i] = 1;
289
+ seedCount++;
290
+ }
291
+ }
292
+ if (seedCount === 0) {
293
+ for (let i = 0; i < n; i++) {
294
+ if (art.data[i * 4 + 3] > 0) {
295
+ seedMask[i] = 1;
296
+ seedCount++;
297
+ }
298
+ }
299
+ }
300
+ const result = newRaster(w, h);
301
+ result.data.set(source.data);
302
+ if (seedCount === 0 || seedCount === n) return result;
303
+
304
+ const bx: number[] = [];
305
+ const by: number[] = [];
306
+ const bLevel: number[] = [];
307
+ for (let y = 0; y < h; y++) {
308
+ for (let x = 0; x < w; x++) {
309
+ const idx = y * w + x;
310
+ if (seedMask[idx] === 0) continue;
311
+ let boundary = x === 0 || x === w - 1 || y === 0 || y === h - 1;
312
+ if (!boundary) {
313
+ for (let dy = -1; dy <= 1 && !boundary; dy++) {
314
+ for (let dx = -1; dx <= 1; dx++) {
315
+ if (dx === 0 && dy === 0) continue;
316
+ if (seedMask[(y + dy) * w + (x + dx)] === 0) {
317
+ boundary = true;
318
+ break;
319
+ }
320
+ }
321
+ }
322
+ }
323
+ if (boundary) {
324
+ bx.push(x);
325
+ by.push(y);
326
+ bLevel.push(source.data[idx * 4]);
327
+ }
328
+ }
329
+ }
330
+ const bCount = bx.length;
331
+ for (let y = 0; y < h; y++) {
332
+ for (let x = 0; x < w; x++) {
333
+ const idx = y * w + x;
334
+ if (seedMask[idx] !== 0) continue;
335
+ let bestDist = Infinity;
336
+ let bestLevel = source.data[idx * 4];
337
+ for (let i = 0; i < bCount; i++) {
338
+ const dx = x - bx[i];
339
+ const dy = y - by[i];
340
+ const d2 = dx * dx + dy * dy;
341
+ if (d2 < bestDist) {
342
+ bestDist = d2;
343
+ bestLevel = bLevel[i];
344
+ }
345
+ }
346
+ const off = idx * 4;
347
+ result.data[off] = bestLevel;
348
+ result.data[off + 1] = bestLevel;
349
+ result.data[off + 2] = bestLevel;
350
+ result.data[off + 3] = 255;
351
+ }
352
+ }
353
+ return result;
354
+ }
355
+
356
+ /**
357
+ * Pad a turn-bound surface part's depth sheet: extend the opaque silhouette
358
+ * across the unpadded box first, then edge-clamp into the `pad`-pixel border.
359
+ */
360
+ export function padTurnDepthSheet(source: Raster, art: Raster, pad: number): Raster {
361
+ return padDepthSheet(extendDepthSilhouette(source, art), pad);
362
+ }
363
+
364
+
365
+ /** Bind units once, before the existing art operators. Their scalar copies
366
+ * retain the ORIGINAL source rectangle/readings instead of remeasuring it.
367
+ */
368
+ export function bindDepthRun(set: LayerSet, run: 'full' | 'head', cfg: DepthConfig | undefined, base: string): LayerSet {
369
+ if (cfg === undefined) return set.layers.some(l => l.depthSheet !== undefined)
370
+ ? { ...set, layers: set.layers.map(({ depthSheet: _sheet, ...layer }) => layer) }
371
+ : set;
372
+ const registered = registerDepthRun(set, run, cfg, base);
373
+ if (registered.size === 0) return set;
374
+ return { ...set, layers: set.layers.map(layer => {
375
+ const from = `${run}:${layer.name}`, r = registered.get(from);
376
+ return r === undefined ? layer : { ...layer, depthSheet: { ...r.sheet, near: r.near, zScale: r.zScale, sources: [{ from, image: r.sheet.file, sha256: r.sheet.sha256, crop: [layer.left, layer.top, layer.right, layer.bottom] as [number, number, number, number], reading: r.sheet.reading }] } };
377
+ }) };
378
+ }
379
+
380
+ export interface DepthCopyTap { layer: Layer; x: number; y: number; weight: number }
381
+ /** Follow an EXISTING art copy/composite, using its actual source coordinates
382
+ * and weights. These weights belong to the operator, not a depth fit. Scalar
383
+ * levels are never multiplied by their own coverage alpha or renormalized.
384
+ */
385
+ export function copyDepthMaterial(target: Layer, inputs: readonly Layer[], taps: (x: number, y: number) => DepthCopyTap[]): Layer {
386
+ const firstLayer = inputs.find(l => l.depthSheet !== undefined);
387
+ const first = firstLayer?.depthSheet;
388
+ if (first === undefined || firstLayer === undefined) return target;
389
+ const p = newRaster(target.pixels.width, target.pixels.height), sources = new Map<string, DepthSource>();
390
+ const fail = (detail: string): never => { throw new PartsError([{ code: 'DEPTH_PART_SUPPORT', object: `layer "${target.name}"`, detail }]); };
391
+ for (let y = 0; y < p.height; y++) for (let x = 0; x < p.width; x++) {
392
+ const visible = target.pixels.data[(y * p.width + x) * 4 + 3] > 0;
393
+ const samples = taps(x + target.left + 0.5, y + target.top + 0.5).filter(t => t.weight > 0);
394
+ if (visible && samples.length === 0) fail(`source copy at (${x + target.left},${y + target.top}) has no owner; exact source material is required`);
395
+ if (!visible) {
396
+ // Unpainted output cells use the first available declared coordinate,
397
+ // otherwise the first source rectangle's clamp; never a zero fill.
398
+ const tap = samples.find(t => t.layer.depthSheet !== undefined);
399
+ const layer = tap?.layer ?? firstLayer, sheet = layer.depthSheet as SourceDepthSheet;
400
+ const v = sampleDepthLevel(sheet.pixels, (tap?.x ?? x + target.left + 0.5) - layer.left, (tap?.y ?? y + target.top + 0.5) - layer.top);
401
+ p.data.set([v, v, v, 255], (y * p.width + x) * 4); continue;
402
+ }
403
+ let level = 0;
404
+ for (const t of samples) {
405
+ const sheet = t.layer.depthSheet;
406
+ if (sheet === undefined) { if (visible) fail(`source copy from "${t.layer.name}" at (${t.x},${t.y}) has no declared sheet`); continue; }
407
+ if (sheet.near !== first.near || sheet.zScale !== first.zScale) fail('composited sources have different declared near/units; explicit common units are required');
408
+ const sx = t.x - t.layer.left, sy = t.y - t.layer.top;
409
+ if (visible && (sx < 0 || sy < 0 || sx > sheet.pixels.width || sy > sheet.pixels.height)) fail(`copy from "${t.layer.name}" maps to (${sx},${sy}) outside ${sheet.pixels.width}x${sheet.pixels.height}; depth for this filtered source material is undeclared`);
410
+ level += t.weight * sampleDepthFloat(sheet.pixels, sx, sy);
411
+ if (visible) for (const source of sheet.sources ?? []) sources.set(`${source.from}:${source.sha256}`, source);
412
+ }
413
+ // No owner on a transparent cell: explicitly repeat the source grid edge.
414
+ if (samples.length === 0) level = sampleDepthFloat(first.pixels, x + 0.5, y + 0.5);
415
+ const v = Math.floor(level + 0.5); p.data.set([v, v, v, 255], (y * p.width + x) * 4);
416
+ }
417
+ return { ...target, depthSheet: { ...first, pixels: p, sources: [...sources.values()] } };
418
+ }
package/src/layers.ts CHANGED
@@ -31,6 +31,7 @@
31
31
  * (`src/tags.ts`, `AUTHOR_PREFIX`): read with `group` "author", it has no
32
32
  * role, and its place in the draw order is read like any other layer's.
33
33
  */
34
+ import { bindDepthRun, type DepthBinding, type DeferredDepthSource, type SourceDepthSheet } from './depthsheets.ts';
34
35
  import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
35
36
  import { basename, dirname, join } from 'node:path';
36
37
  import { initializeCanvas, type Layer as PsdLayer, readPsd, writePsd } from 'ag-psd';
@@ -65,6 +66,10 @@ export interface Layer {
65
66
  bottom: number;
66
67
  /** See-through's `depth_median` (larger = further back), or null where the input carries none. */
67
68
  depth: number | null;
69
+ /** Optional scalar source; ordering remains the separate depth_median. */
70
+ depthSheet?: SourceDepthSheet;
71
+ /** An unbound legacy hint; reading art must not touch its file. */
72
+ depthHint?: DeferredDepthSource;
68
73
  /** 0 is drawn first (furthest back). */
69
74
  drawOrder: number;
70
75
  /** Pixels with alpha above `OPAQUE_ALPHA_ABOVE`. */
@@ -77,6 +82,8 @@ export interface Layer {
77
82
  * so it carries no tag reading, no depth and no draw order.
78
83
  */
79
84
  export interface HiddenLayer {
85
+ /** Legacy hint, retained but never interpreted while depth is inactive. */
86
+ depthHint?: DeferredDepthSource;
80
87
  /** `<of>:hidden`. */
81
88
  name: string;
82
89
  /** The drawn layer of the same input it belongs to. */
@@ -210,7 +217,7 @@ const DEPTH_RULE = 'a finite number (See-through\'s depth, larger = further back
210
217
  * order, a scale) that silently ignoring would get wrong — so the reader says
211
218
  * which key it does not know and stops.
212
219
  */
213
- export function readWrapperLayers(path: string): LayerSet {
220
+ export function readWrapperLayers(path: string, binding?: DepthBinding): LayerSet {
214
221
  const manifestPath = existsSync(path) && statSync(path).isDirectory() ? join(path, 'layers.json') : path;
215
222
  const dir = dirname(manifestPath);
216
223
  const problems: Problem[] = [];
@@ -362,7 +369,7 @@ export function readWrapperLayers(path: string): LayerSet {
362
369
  return;
363
370
  }
364
371
  if (hiddenOf !== null) {
365
- hidden.push({ name, of: hiddenOf.of, file: present[0], pixels, left, top, right, bottom, opaquePx: opaque(pixels) });
372
+ hidden.push({ name, of: hiddenOf.of, file: present[0], pixels, left, top, right, bottom, opaquePx: opaque(pixels), ...(!('depth_filename' in e) ? {} : { depthHint: { filename: e.depth_filename, base: dir } }) });
366
373
  return;
367
374
  }
368
375
  read.push({
@@ -370,6 +377,7 @@ export function readWrapperLayers(path: string): LayerSet {
370
377
  tag: tag as LayerTagReading,
371
378
  file: present[0],
372
379
  pixels,
380
+ ...(!('depth_filename' in e) ? {} : { depthHint: { filename: e.depth_filename, base: dir } }),
373
381
  left,
374
382
  top,
375
383
  right,
@@ -390,13 +398,14 @@ export function readWrapperLayers(path: string): LayerSet {
390
398
  // Stable: Array.prototype.sort is stable, so equal depths keep manifest order — and with no depth at all (every
391
399
  // depth null), the manifest's own order is the draw order.
392
400
  const ordered = withDepth.length === 0 ? read : [...read].sort((a, b) => (b.depth as number) - (a.depth as number));
393
- return {
401
+ const set: LayerSet = {
394
402
  form: 'wrapper',
395
403
  source: manifestPath,
396
404
  canvas: { w: W, h: H },
397
405
  layers: ordered.map(({ index: _index, ...rest }, drawOrder) => ({ ...rest, drawOrder })),
398
406
  hidden,
399
407
  };
408
+ return binding === undefined ? set : bindDepthRun(set, binding.run, binding.config, binding.base);
400
409
  }
401
410
 
402
411
  /** Every hidden-art layer must belong to a drawn layer the same input holds (issue #359): `LAYERS_HIDDEN_OF_PRESENT`. */
@@ -556,9 +565,9 @@ export function readPsdLayers(path: string): LayerSet {
556
565
  }
557
566
 
558
567
  /** Read whichever form `path` is: a `.psd` file, or a wrapper directory / `layers.json`. */
559
- export function readLayers(path: string): LayerSet {
560
- if (/\.psd$/i.test(path)) return readPsdLayers(path);
561
- if (existsSync(path) && (statSync(path).isDirectory() || basename(path) === 'layers.json')) return readWrapperLayers(path);
568
+ export function readLayers(path: string, binding?: DepthBinding): LayerSet {
569
+ if (/\.psd$/i.test(path)) { const set = readPsdLayers(path); return binding === undefined ? set : bindDepthRun(set, binding.run, binding.config, binding.base); }
570
+ if (existsSync(path) && (statSync(path).isDirectory() || basename(path) === 'layers.json')) return readWrapperLayers(path, binding);
562
571
  refuseIfAny([
563
572
  {
564
573
  code: 'LAYERS_INPUT_KIND',
@@ -588,15 +597,16 @@ export function exportFileName(index: number, count: number, name: string): stri
588
597
  }
589
598
 
590
599
  /** The wrapper manifest `exportLayers` writes, as text: fixed key order, two-space indent, a trailing newline. */
591
- export function exportManifestText(set: LayerSet): string {
592
- const all: Array<{ name: string; left: number; top: number; right: number; bottom: number; depth: number | null }> = [
593
- ...set.layers.map((l) => ({ name: l.name, left: l.left, top: l.top, right: l.right, bottom: l.bottom, depth: l.depth })),
600
+ export function exportManifestText(set: LayerSet, binding?: DepthBinding): string {
601
+ set = bindDepthRun(set, binding?.run ?? 'full', binding?.config, binding?.base ?? '');
602
+ const all: Array<{ name: string; left: number; top: number; right: number; bottom: number; depth: number | null; depthSheet?: SourceDepthSheet }> = [
603
+ ...set.layers.map((l) => ({ name: l.name, left: l.left, top: l.top, right: l.right, bottom: l.bottom, depth: l.depth, ...(l.depthSheet === undefined ? {} : { depthSheet: l.depthSheet }) })),
594
604
  ...set.hidden.map((h) => ({ name: h.name, left: h.left, top: h.top, right: h.right, bottom: h.bottom, depth: null })),
595
605
  ];
596
606
  const manifest = {
597
607
  width: set.canvas.w,
598
608
  height: set.canvas.h,
599
- layers: all.map((l, i) => ({ name: l.name, filename: exportFileName(i, all.length, l.name), left: l.left, top: l.top, right: l.right, bottom: l.bottom, depth_median: l.depth })),
609
+ layers: all.map((l, i) => ({ name: l.name, filename: exportFileName(i, all.length, l.name), left: l.left, top: l.top, right: l.right, bottom: l.bottom, depth_median: l.depth, ...(l.depthSheet === undefined ? {} : { depth_filename: exportFileName(i, all.length, `${l.name}_depth`) }) })),
600
610
  };
601
611
  return `${JSON.stringify(manifest, null, 2)}\n`;
602
612
  }
@@ -617,7 +627,7 @@ export function exportManifestText(set: LayerSet): string {
617
627
  * `parts/<name>.png` the reader also looks for — could be read in place of
618
628
  * the one written now. Writes nothing until that has passed.
619
629
  */
620
- export function exportLayers(set: LayerSet, dir: string): { manifest: string; files: string[] } {
630
+ export function exportLayers(set: LayerSet, dir: string, binding?: DepthBinding): { manifest: string; files: string[] } {
621
631
  if (existsSync(dir) && (!statSync(dir).isDirectory() || readdirSync(dir).length > 0)) {
622
632
  refuseIfAny([
623
633
  {
@@ -627,7 +637,8 @@ export function exportLayers(set: LayerSet, dir: string): { manifest: string; fi
627
637
  },
628
638
  ]);
629
639
  }
630
- const text = exportManifestText(set);
640
+ set = bindDepthRun(set, binding?.run ?? 'full', binding?.config, binding?.base ?? '');
641
+ const text = exportManifestText(set, binding);
631
642
  const entries = (JSON.parse(text) as { layers: Array<{ filename: string }> }).layers;
632
643
  const pixels = [...set.layers.map((l) => l.pixels), ...set.hidden.map((h) => h.pixels)];
633
644
  mkdirSync(dir, { recursive: true });
@@ -636,6 +647,7 @@ export function exportLayers(set: LayerSet, dir: string): { manifest: string; fi
636
647
  writeFileSync(path, encodePngBytes(pixels[i]));
637
648
  return path;
638
649
  });
650
+ set.layers.forEach((l, i) => { if (l.depthSheet !== undefined) { const file = join(dir, exportFileName(i, set.layers.length + set.hidden.length, `${l.name}_depth`)); writeFileSync(file, encodePngBytes(l.depthSheet.pixels)); files.push(file); } });
639
651
  const manifest = join(dir, 'layers.json');
640
652
  writeFileSync(manifest, text);
641
653
  return { manifest, files };
package/src/limblayout.ts CHANGED
@@ -50,10 +50,10 @@ function segmentSources(limbs: Readonly<Record<string, Limb>>, bones: RigSpec['b
50
50
  }
51
51
 
52
52
  function bindings(slot: RigSpec['slots'][number], skin: RigSpec['skins']['default']): string[][] {
53
- return Object.values(skin[slot.name] ?? {}).map((a) => 'type' in a ? a.weights.flatMap((v) => v.map((w) => w.bone)) : [slot.bone]);
53
+ return Object.values(skin[slot.name] ?? {}).map((a) => 'type' in a && 'weights' in a && a.weights !== undefined ? a.weights.flatMap((v) => v.map((w) => w.bone)) : [slot.bone]);
54
54
  }
55
55
  function bindingDetail(slots: RigSpec['slots'], skin: RigSpec['skins']['default'], sources: LayoutPlan['sources']): string {
56
- return JSON.stringify(slots.map((s) => ({ slot: s.name, attachments: Object.entries(skin[s.name] ?? {}).map(([attachment, a]) => ({ attachment, bones: ('type' in a ? a.weights.flatMap((v) => v.map((w) => w.bone)) : [s.bone]).map((bone) => ({ bone, sources: sources.get(bone) ?? [] })) })) })));
56
+ return JSON.stringify(slots.map((s) => ({ slot: s.name, attachments: Object.entries(skin[s.name] ?? {}).map(([attachment, a]) => ({ attachment, bones: ('type' in a && 'weights' in a && a.weights !== undefined ? a.weights.flatMap((v) => v.map((w) => w.bone)) : [s.bone]).map((bone) => ({ bone, sources: sources.get(bone) ?? [] })) })) })));
57
57
  }
58
58
  function owned(slot: RigSpec['slots'][number], skin: RigSpec['skins']['default'], sources: LayoutPlan['sources'], limb: string, parts: readonly string[], moving?: ReadonlyMap<string, readonly string[]>): boolean {
59
59
  const bs = bindings(slot, skin);
package/src/limbslots.ts CHANGED
@@ -71,7 +71,7 @@ export function coalesceLimbSlots(
71
71
  const owners: LimbSlotOwner[] = slots.map((slot) => {
72
72
  const bindings = Object.entries(skin[slot.name] ?? {}).map(([attachment, att]) => ({
73
73
  attachment,
74
- bones: 'type' in att ? [...new Set(att.weights.flatMap((v) => v.map((w) => w.bone)))] : [slot.bone],
74
+ bones: 'type' in att && 'weights' in att && att.weights !== undefined ? [...new Set(att.weights.flatMap((v) => v.map((w) => w.bone)))] : [slot.bone],
75
75
  }));
76
76
  const mine = new Set<string>();
77
77
  const outside = new Set<string>();
package/src/motion.ts CHANGED
@@ -142,7 +142,10 @@ export interface MotionSpec {
142
142
  cut: string;
143
143
  easings: Record<string, [number, number, number, number]>;
144
144
  groups: Record<string, string[]>;
145
- animations: { idle: { duration: number; loop: true; note: string; tracks: MotionTrack[] } };
145
+ animations: {
146
+ idle: { duration: number; loop: true; note: string; tracks: MotionTrack[] };
147
+ [name: string]: unknown;
148
+ };
146
149
  }
147
150
 
148
151
  const FACE_DEFORM_HOOK = new WeakMap<MotionSpec, (merged: MotionSpec & { animations: Record<string, unknown> }) => void>();