@rig-c/parts 0.0.0-stage → 1.5.4

package/src/tags.ts

@@ -0,0 +1,121 @@
+/**
+ * See-through's layer vocabulary, as the tags a layer arrives named by.
+ *
+ * ⭐ These are the **v3** tags — the vocabulary `pipeline.unet.get_tag_version()`
+ * reports on the `seethroughv0.0.2_layerdiff3d` weights, read out of the
+ * upstream code: 13 body tags and 11 head tags, 24 in all. The older v2
+ * vocabulary has 19 tags and a single `hair` tag; it is not what the published
+ * v0.0.2 weights emit, and a layer named by it is refused as unknown rather
+ * than mapped, because a mapping would be a guess about which v3 tag it meant.
+ *
+ * Six tags are split left/right by upstream (`_tag_lr_split`, which needs the
+ * tag's mask to be two separate blobs): `handwear`, `eyewhite`, `irides`,
+ * `eyelash`, `eyebrow`, `ears`. A split layer is named `<tag>-r` / `<tag>-l`.
+ * **[observed]** on wrapper output: `-r` is the half at the smaller image x —
+ * the character's right as they face the viewer — and the wrapper emits both
+ * halves even when one is a few pixels (a 6x6 `handwear-l` beside a 275x352
+ * `handwear-r`), so "both halves present" says nothing about the split having
+ * found two real blobs.
+ *
+ * `head` is in the v3 list but is not emitted as a layer: upstream's README
+ * says the pipeline "stratifies the character into up to 23 semantic layers"
+ * (24 tags less `head`, whose pass arrives as its parts), and **[observed]**
+ * no wrapper output read so far carries one. It stays in the vocabulary
+ * because it is upstream's word.
+ *
+ * Nothing downstream classifies a part by its NAME. The role of a part — what
+ * a proposer may do with it — is read from the tag it came from, which is why
+ * `parts.json` records `from` for every part.
+ */
+
+export const BODY_TAGS = [
+  'front hair',
+  'back hair',
+  'head',
+  'neck',
+  'neckwear',
+  'topwear',
+  'handwear',
+  'bottomwear',
+  'legwear',
+  'footwear',
+  'tail',
+  'wings',
+  'objects',
+] as const;
+
+export const HEAD_TAGS = [
+  'headwear',
+  'face',
+  'irides',
+  'eyebrow',
+  'eyewhite',
+  'eyelash',
+  'eyewear',
+  'ears',
+  'earwear',
+  'nose',
+  'mouth',
+] as const;
+
+export type BaseTag = (typeof BODY_TAGS)[number] | (typeof HEAD_TAGS)[number];
+
+/** The tags upstream splits into `-r` / `-l` halves. */
+export const SPLIT_TAGS = ['handwear', 'eyewhite', 'irides', 'eyelash', 'eyebrow', 'ears'] as const;
+
+export type SplitTag = (typeof SPLIT_TAGS)[number];
+export type Side = 'r' | 'l';
+
+/** Every v3 tag, in the order upstream lists them. */
+export const V3_TAGS: readonly BaseTag[] = [...BODY_TAGS, ...HEAD_TAGS];
+
+export interface TagReading {
+  /** The name as the layer carries it: `eyebrow-l`, `front hair`. */
+  name: string;
+  base: BaseTag;
+  /** `null` for an unsplit tag or an unsplit form of a split tag. */
+  side: Side | null;
+  group: 'body' | 'head';
+}
+
+/**
+ * Read a layer name as a v3 tag, or `null` when it is not one.
+ *
+ * Accepted: any of the 24 base tags, and `<tag>-r` / `<tag>-l` for the six
+ * split tags. A suffix on a tag upstream never splits (`topwear-l`) is not a
+ * tag — upstream cannot have produced it, so accepting it would be accepting a
+ * layer somebody renamed.
+ */
+export function readTag(name: string): TagReading | null {
+  const split = /^(.+)-([rl])$/.exec(name);
+  if (split !== null && (SPLIT_TAGS as readonly string[]).includes(split[1])) {
+    const base = split[1] as SplitTag;
+    return { name, base, side: split[2] as Side, group: groupOf(base) };
+  }
+  if ((V3_TAGS as readonly string[]).includes(name)) {
+    const base = name as BaseTag;
+    return { name, base, side: null, group: groupOf(base) };
+  }
+  return null;
+}
+
+function groupOf(tag: BaseTag): 'body' | 'head' {
+  return (HEAD_TAGS as readonly string[]).includes(tag) ? 'head' : 'body';
+}
+
+/** Every name `readTag` accepts, sorted — what a refusal quotes as "required". */
+export function acceptedTagNames(): string[] {
+  const names = new Set<string>(V3_TAGS);
+  for (const t of SPLIT_TAGS) {
+    names.add(`${t}-r`);
+    names.add(`${t}-l`);
+  }
+  return [...names].sort();
+}
+
+/** The mirror of a split layer name (`eyebrow-l` <-> `eyebrow-r`), or `null` for an unsided one. */
+export function pairOf(name: string): string | null {
+  const t = readTag(name);
+  if (t === null || t.side === null) return null;
+  return `${t.base}-${t.side === 'r' ? 'l' : 'r'}`;
+}

package/src/weights.ts

@@ -0,0 +1,124 @@
+/**
+ * Vertex weights by distance to bone SEGMENTS.
+ *
+ * Each mesh names its candidate segments in the config — a chain (every link,
+ * origin to the next link, the last to the chain's tip), a single bone (origin
+ * to its tip), or an explicit `[bone, [x0, y0], [x1, y1]]`. That list is the
+ * one authored decision about a layer: which bones may pull it. The weights
+ * then follow from the geometry and nothing else:
+ *
+ *     w = 1 / (d + r)^e          d = distance from the vertex to the segment
+ *
+ * per candidate, with `e` the mesh's declared `exponent` (issue #161) and 2 —
+ * {@link DISTANCE_EXPONENT}, the rule as it always was — where none is
+ * declared; a bone named by two segments keeps the larger; the top
+ * {@link MAX_INFLUENCES} are kept, normalised, any below {@link MIN_WEIGHT}
+ * dropped, the rest normalised again, rounded to 5 decimals, and the last
+ * weight written as `1 - sum(others)` so every vertex sums to exactly 1 after
+ * rounding. Ties in the sort keep the order the bones first appeared among the
+ * segments (Python's `sorted` is stable, and so is `Array.prototype.sort`).
+ *
+ * Distances are the reference's arithmetic, operation for operation — the
+ * projection `t = clip(((p - a) . ab) / |ab|^2, 0, 1)` and `sqrt(dx^2 + dy^2)`,
+ * not `Math.hypot`, whose last bit differs — because a weight rounded at the
+ * fifth decimal is where a one-ulp difference becomes a visible one.
+ *
+ * ⛔ **No invented segment.** The reference gave a single bone with no tip and
+ * no chain child the segment `(x, y) -> (x, y + 1)`: one pixel, straight down,
+ * a direction nothing in the config says. Here that is `RIG_SEGMENT_DEFINED`,
+ * naming the bone and the two fields that would define it. A chain link whose
+ * next point is its own origin is refused the same way (`RIG_CHAIN_POINTS`).
+ */
+import type { Point } from './config.ts';
+
+/** At most this many bones pull one vertex — Spine's usual budget and the reference's `[:4]`. */
+export const MAX_INFLUENCES = 4;
+
+/** A normalised weight under this is dropped before the final normalisation — the reference's `>= 0.03`. */
+export const MIN_WEIGHT = 0.03;
+
+/**
+ * The exponent of the distance rule where a mesh declares none: `1/(d + r)²`,
+ * the reference's rule. At this value the weight is computed as
+ * `(d + r) * (d + r)`, the reference's operations, and never through
+ * `Math.pow`, which the language does not promise to round as one multiply
+ * does — so a mesh that declares nothing, or declares 2, writes the bytes it
+ * always wrote.
+ */
+export const DISTANCE_EXPONENT = 2;
+
+export interface Segment {
+  bone: string;
+  a: Point;
+  b: Point;
+}
+
+/** Distance from `p` to the segment `a -> b`; a zero-length segment is its point. */
+export function segmentDistance(p: Point, a: Point, b: Point): number {
+  const abx = b[0] - a[0];
+  const aby = b[1] - a[1];
+  const len2 = abx * abx + aby * aby;
+  let t = 0;
+  if (len2 > 0) {
+    t = ((p[0] - a[0]) * abx + (p[1] - a[1]) * aby) / len2;
+    t = t < 0 ? 0 : t > 1 ? 1 : t;
+  }
+  const dx = p[0] - (a[0] + t * abx);
+  const dy = p[1] - (a[1] + t * aby);
+  return Math.sqrt(dx * dx + dy * dy);
+}
+
+export interface Influence {
+  bone: string;
+  /** Unrounded, normalised over the kept influences. */
+  weight: number;
+}
+
+/**
+ * The cap and the floor `influences()` applies. The lattice and the contour
+ * mode always run at {@link DEFAULT_LIMITS} (the reference's `[:4]` and
+ * `>= 0.03`); the automatic mode (`src/automesh.ts`, issue #126) passes the
+ * author's numbers instead, because rig-c's reduction is handed explicit
+ * influence limits on every weighted call and the 0.03 floor is not one the
+ * author wrote (P19). The arithmetic is the same either way, so with the
+ * defaults every byte the two older modes write is unchanged.
+ */
+export interface InfluenceLimits {
+  maxInfluences: number;
+  minWeight: number;
+}
+
+export const DEFAULT_LIMITS: InfluenceLimits = { maxInfluences: MAX_INFLUENCES, minWeight: MIN_WEIGHT };
+
+/**
+ * The influences on one vertex at `p` (rig pixels), before rounding, under
+ * `w = 1/(d + r)^exponent`. The rig stage passes every mesh's exponent
+ * explicitly; the default is for readers of today's rule (the tools, the
+ * selftest's older controls).
+ */
+export function influences(p: Point, segments: readonly Segment[], r: number, limits: InfluenceLimits = DEFAULT_LIMITS, exponent: number = DISTANCE_EXPONENT): Influence[] {
+  const agg = new Map<string, number>();
+  for (const s of segments) {
+    const d = segmentDistance(p, s.a, s.b);
+    // 2 is the reference's multiply, bit for bit (DISTANCE_EXPONENT); any other declared exponent is Math.pow.
+    const w = 1.0 / (exponent === DISTANCE_EXPONENT ? (d + r) * (d + r) : Math.pow(d + r, exponent));
+    const was = agg.get(s.bone);
+    agg.set(s.bone, was === undefined ? w : Math.max(was, w));
+  }
+  return capAndFloor([...agg.entries()], limits);
+}
+
+/**
+ * The cap and the floor, on raw per-bone values in first-appearance order: sorted (stable), the top
+ * `maxInfluences` normalised, those under `minWeight` dropped, the rest normalised again. The distance rule
+ * above and bone heat (`src/heat.ts`, issue #161) both end here, so the two rules share one cap and one floor.
+ */
+export function capAndFloor(raw: ReadonlyArray<readonly [string, number]>, limits: InfluenceLimits): Influence[] {
+  const top = [...raw].sort((x, y) => y[1] - x[1]).slice(0, limits.maxInfluences);
+  let s = 0;
+  for (const [, v] of top) s += v;
+  const kept = top.map(([bone, v]) => ({ bone, weight: v / s })).filter((e) => e.weight >= limits.minWeight);
+  let s2 = 0;
+  for (const e of kept) s2 += e.weight;
+  return kept.map((e) => ({ bone: e.bone, weight: e.weight / s2 }));
+}

package/workflows/seethrough.json

@@ -0,0 +1,68 @@
+{
+  "_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.",
+  "1": {
+    "class_type": "LoadImage",
+    "inputs": { "image": "%IMAGE%" }
+  },
+  "2": {
+    "class_type": "SeeThrough_LoadLayerDiffModel",
+    "inputs": {
+      "model": "layerdifforg/seethroughv0.0.2_layerdiff3d",
+      "vae_ckpt": "",
+      "unet_ckpt": "",
+      "quant_mode": "%QUANT%",
+      "cache_tag_embeds": true,
+      "group_offload": "%OFFLOAD%",
+      "auto_download": true
+    }
+  },
+  "3": {
+    "class_type": "SeeThrough_GenerateLayers",
+    "inputs": {
+      "image": ["1", 0],
+      "layerdiff_model": ["2", 0],
+      "seed": "%SEED%",
+      "resolution": "%RESOLUTION%",
+      "num_inference_steps": "%STEPS%"
+    }
+  },
+  "4": {
+    "class_type": "SeeThrough_LoadDepthModel",
+    "inputs": {
+      "model": "layerdifforg/seethroughv0.0.1_marigold",
+      "quant_mode": "%QUANT%",
+      "cache_tag_embeds": true,
+      "group_offload": "%OFFLOAD%",
+      "auto_download": true
+    }
+  },
+  "5": {
+    "class_type": "SeeThrough_GenerateDepth",
+    "inputs": {
+      "layers": ["3", 0],
+      "depth_model": ["4", 0],
+      "seed": "%SEED%",
+      "resolution_depth": -1
+    }
+  },
+  "6": {
+    "class_type": "SeeThrough_PostProcess",
+    "inputs": {
+      "layers_depth": ["5", 0],
+      "tblr_split": true,
+      "use_lama": "%LAMA%"
+    }
+  },
+  "7": {
+    "class_type": "SeeThrough_SavePSD",
+    "inputs": { "parts": ["6", 0], "filename_prefix": "%PREFIX%" }
+  },
+  "8": {
+    "class_type": "SaveImage",
+    "inputs": { "images": ["3", 1], "filename_prefix": "%PREFIX%_preview_layers" }
+  },
+  "9": {
+    "class_type": "SaveImage",
+    "inputs": { "images": ["6", 1], "filename_prefix": "%PREFIX%_preview_parts" }
+  }
+}