@rig-c/parts 1.61.0 → 1.62.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/src/config.ts CHANGED
@@ -93,6 +93,7 @@ import { CLOTH_TARGETS, type ClothRecipes, RECIPE_STRENGTH, RIGC_DEFAULT_DAMPING
93
93
  import { GRID, MAX_SIDE } from './contour.ts';
94
94
  import { type Problem, refuseIfAny } from './errors.ts';
95
95
  import { edgeLength } from './length.ts';
96
+ import { setFocusProblems } from './setfocus.ts';
96
97
  import { isSkeletonName, KEYPOINT_NAMES, type KeypointName, type PosePoints, scaledPoints, SKELETON_NAMES, type SkeletonName } from './skeleton.ts';
97
98
  import { acceptedTagNames, AUTHOR_LABEL_RULE, AUTHOR_PREFIX, readLayerTag } from './tags.ts';
98
99
  import { EAR_DEPTH_RANGE, FACE_DEFORM_FRACTIONS, FACE_DEFORM_RANGES, type FaceDeformKey, FACE_RATED_PITCH_BAND, FACE_RATED_YAW_BAND, TURN_BONE, type TurnSpec, turnNearest } from './turn.ts';
@@ -264,6 +265,8 @@ export interface Cut {
264
265
 
265
266
  export interface AlternateSetConfig {
266
267
  name: string;
268
+ /** Authored point on this painting, x right/y down; omitted means no focus. */
269
+ focus?: Point;
267
270
  source?: string;
268
271
  full?: string;
269
272
  head?: string;
@@ -346,7 +349,7 @@ export type Segment = string | [string, Point, Point];
346
349
  * locally refined by rig-c's `reduceMesh` under the author's declared
347
350
  * bounds (`src/automesh.ts`).
348
351
  */
349
- export type MeshSpec = (LatticeMeshSpec | ContourMeshSpec | AutoMeshSpec | InfluenceMeshSpec) & { gather?: false };
352
+ export type MeshSpec = (LatticeMeshSpec | ContourMeshSpec | AutoMeshSpec | InfluenceMeshSpec | ExplicitMeshSpec) & { gather?: false };
350
353
 
351
354
  /**
352
355
  * One mesh in the influence mode (issue #378): rig-c's `segments` lattice over the part at `cell` px, every vertex
@@ -357,6 +360,24 @@ export type MeshSpec = (LatticeMeshSpec | ContourMeshSpec | AutoMeshSpec | Influ
357
360
  * `hold_tip: true` (issue #615, optional, written by `propose --cloth` from the recipe's `split.hold_tip`) smooths the
358
361
  * pulled shares by the lattice's held-fork passes, capped at `max`; absent, the shares are rig-c's as pulled.
359
362
  */
363
+ /** An accepted mesh transferred without regenerating topology or bone-local bind positions (issue #658). */
364
+ export interface ExplicitMeshSpec {
365
+ /** Direct bone names: the first is the slot bone; all weighted bones must be declared here. No segment geometry is regenerated. */
366
+ segments: Segment[];
367
+ explicit: {
368
+ /** SHA-256 over the unpadded part's decoded RGBA bytes. */
369
+ image_sha256: string;
370
+ /** SHA-256 of JSON.stringify([rig width, rig height, x, y, w, h]). */
371
+ region_sha256: string;
372
+ /** Normalized UVs over the ordinary PAD-padded rig image, as rig-c reads them. */
373
+ uvs: number[];
374
+ triangles: number[];
375
+ hull: number;
376
+ /** rig-c by-name weights, in bone-local Spine pixels, copied without rounding. */
377
+ weights: Array<Array<{ bone: string; x: number; y: number; weight: number }>>;
378
+ };
379
+ }
380
+
360
381
  export interface InfluenceMeshSpec {
361
382
  influence: { cell: number; radius: number; across: boolean; max: number; shape: 'linear' | 'smooth'; hold_tip?: true };
362
383
  segments: Segment[];
@@ -742,6 +763,10 @@ export function partBoundBones(b: PartBinding): Map<string, string[]> {
742
763
  out.set(part, list);
743
764
  };
744
765
  for (const [part, m] of Object.entries(b.meshes)) {
766
+ if ('explicit' in m) {
767
+ for (const row of m.explicit.weights) for (const w of row) bind(part, w.bone);
768
+ continue;
769
+ }
745
770
  for (const sg of m.segments) {
746
771
  if (typeof sg !== 'string') bind(part, sg[0]);
747
772
  else for (const l of chains.get(sg) ?? [sg]) bind(part, l);
@@ -1594,7 +1619,7 @@ function parseConfigFrom(raw: Json, base: string | null): { config: CharacterCon
1594
1619
  if (isPlainObject(t.assemble) && 'alternates' in t.assemble) {
1595
1620
  checkAlternates(c, t.assemble.alternates, { parts, patches, cuts }, limbs, names.bones, names.chains, t.regions, t.meshes);
1596
1621
  }
1597
- if ('meshes' in t) checkMeshes(c, t.meshes, names.bones, names.chains);
1622
+ if ('meshes' in t) checkMeshes(c, t.meshes, names.bones, names.chains, t.stops);
1598
1623
  if ('regions' in t) checkRegions(c, t.regions, names.bones);
1599
1624
  if ('meshes' in t && 'regions' in t && 'assemble' in t) checkCoverage(c, [...parts, ...cuts], patches, t.meshes, t.regions, limbs);
1600
1625
  if ('motion' in t) checkMotion(c, t.motion, names.bones, names.chains, 'regions' in t ? t.regions : undefined);
@@ -1841,7 +1866,7 @@ export function parseProposalSections(raw: Json): SkeletonSections & { limbs?: R
1841
1866
  : [];
1842
1867
  checkLimbs(c, top.limbs, { parts: [...new Set(taken)], patches: [], cuts: [] }, names, false);
1843
1868
  }
1844
- if ('meshes' in top) checkMeshes(c, top.meshes, names.bones, names.chains);
1869
+ if ('meshes' in top) checkMeshes(c, top.meshes, names.bones, names.chains, top.stops);
1845
1870
  if ('regions' in top) checkRegions(c, top.regions, names.bones);
1846
1871
  if ('motion' in top) checkMotion(c, top.motion, names.bones, names.chains, 'regions' in top ? top.regions : undefined);
1847
1872
  if ('constraints' in top) checkConstraints(c, top.constraints, names.bones, names.parents);
@@ -2173,7 +2198,7 @@ function checkAlternates(
2173
2198
  const seenNames = new Map<string, number>();
2174
2199
  (v as Json[]).forEach((entry, i) => {
2175
2200
  const at = `${p}[${i}]`;
2176
- const e = c.object(at, entry, ['name'], ['source', 'full', 'head', 'parts', 'hides', 'head_box', 'cuts', 'skeleton', 'anchor', 'drawn', 'tips', 'front', 'layers']);
2201
+ const e = c.object(at, entry, ['name'], ['source', 'full', 'head', 'parts', 'hides', 'head_box', 'cuts', 'skeleton', 'anchor', 'drawn', 'tips', 'front', 'layers', 'focus']);
2177
2202
  if (e === null) return;
2178
2203
  if ('name' in e && c.string(`${at}.name`, e.name)) {
2179
2204
  if (!partNameOk(e.name)) c.fail('CONFIG_PART_NAME', `${at}.name`, `names the set ${show(e.name)}; a set name is a file prefix, so it may not be empty, start with "." or hold a slash`);
@@ -2183,6 +2208,7 @@ function checkAlternates(
2183
2208
  for (const k of ['source', 'full', 'head', 'skeleton'] as const) {
2184
2209
  if (k in e) c.string(`${at}.${k}`, e[k]);
2185
2210
  }
2211
+ if ('focus' in e) c.problems.push(...setFocusProblems(e.focus, `${at} (set ${show(e.name)}).focus`));
2186
2212
  if ('anchor' in e) {
2187
2213
  if (!('skeleton' in e)) c.fail('CONFIG_FIELD_PRESENT', `${at}.skeleton`, 'is absent; anchor registers a skeleton set and requires its skeleton file');
2188
2214
  const a = e.anchor;
@@ -2519,7 +2545,21 @@ function checkBones(c: Check, v: Json): { bones: Set<string>; chains: Map<string
2519
2545
  return { bones, chains, parents };
2520
2546
  }
2521
2547
 
2522
- function checkMeshes(c: Check, v: Json, bones: Set<string>, chains: Map<string, number>): void {
2548
+ /** Only drawn names generated by the declared, valid stopped links are additional explicit bindings. */
2549
+ export function explicitBoneNames(bones: ReadonlySet<string>, chains: ReadonlyMap<string, number>, stops: unknown): Set<string> {
2550
+ const out = new Set(bones);
2551
+ if (!Array.isArray(stops)) return out;
2552
+ for (const stop of stops) {
2553
+ if (!isPlainObject(stop) || typeof stop.chain !== 'string') continue;
2554
+ const count = chains.get(stop.chain);
2555
+ if (count === undefined) continue;
2556
+ const links = Array.from({ length: count }, (_, i) => `${stop.chain}${i}`);
2557
+ for (const link of Array.isArray(stop.links) ? stop.links : links) if (typeof link === 'string' && links.includes(link)) out.add(`${link}_d`);
2558
+ }
2559
+ return out;
2560
+ }
2561
+
2562
+ function checkMeshes(c: Check, v: Json, bones: Set<string>, chains: Map<string, number>, stops: Json): void {
2523
2563
  if (typeof v !== 'object' || v === null || Array.isArray(v)) {
2524
2564
  c.fail('CONFIG_FIELD_TYPE', 'config.meshes', `is ${show(v)}; an object of part name -> mesh is required`);
2525
2565
  return;
@@ -2528,9 +2568,13 @@ function checkMeshes(c: Check, v: Json, bones: Set<string>, chains: Map<string,
2528
2568
  const at = `config.meshes.${part}`;
2529
2569
  // The known keys keep their old order (grid, r, segments) with contour after them, and `r` and `segments` are
2530
2570
  // required in the place and words the object check uses, so a lattice mesh's refusals read as they did.
2531
- const m = c.object(at, spec, [], ['grid', 'r', 'segments', 'contour', 'auto', 'exponent', 'rule', 'ribs', 'influences', 'stray', 'influence', 'gather']);
2571
+ const m = c.object(at, spec, [], ['grid', 'r', 'segments', 'contour', 'auto', 'exponent', 'rule', 'ribs', 'influences', 'stray', 'influence', 'gather', 'explicit']);
2532
2572
  if (m === null) continue;
2533
2573
  checkGather(c, at, m);
2574
+ if ('explicit' in m) {
2575
+ checkExplicit(c, at, m, explicitBoneNames(bones, chains, stops));
2576
+ continue;
2577
+ }
2534
2578
  // issue #378: the influence mode weights by rig-c's own pull, so `r` (the distance rule's softening) is not one of its
2535
2579
  // fields — it is refused there below, and required in every other mode as it always was.
2536
2580
  for (const key of 'influence' in m ? ['segments'] : ['r', 'segments']) if (!(key in m)) c.fail('CONFIG_FIELD_PRESENT', `${at}.${key}`, 'is absent and required');
@@ -2581,6 +2625,51 @@ function checkMeshes(c: Check, v: Json, bones: Set<string>, chains: Map<string,
2581
2625
  }
2582
2626
  }
2583
2627
 
2628
+ /** The loader checks the payload's shape and names; rig-c's mandatory gate owns mesh validity. */
2629
+ function checkExplicit(c: Check, at: string, m: Record<string, Json>, bones: Set<string>): void {
2630
+ for (const k of ['grid', 'r', 'contour', 'auto', 'exponent', 'rule', 'ribs', 'influences', 'stray', 'influence']) {
2631
+ if (k in m) c.fail('CONFIG_EXPLICIT_MODE', `${at}.${k}`, 'is declared beside explicit, which transfers an accepted payload without generation; remove the generator field');
2632
+ }
2633
+ if (!('segments' in m)) c.fail('CONFIG_FIELD_PRESENT', `${at}.segments`, 'is absent and required: direct bone names, first the slot bone');
2634
+ else if (c.array(`${at}.segments`, m.segments, true)) m.segments.forEach((bone, i) => {
2635
+ if (c.string(`${at}.segments[${i}]`, bone) && !bones.has(bone)) c.fail('CONFIG_NAME_RESOLVES', `${at}.segments[${i}]`, `names "${bone}", which is not a bone; explicit segments name bones directly, not chains`);
2636
+ });
2637
+ const where = `${at}.explicit`;
2638
+ const o = c.object(where, m.explicit, ['image_sha256', 'region_sha256', 'uvs', 'triangles', 'hull', 'weights'], []);
2639
+ if (o === null) return;
2640
+ for (const k of ['image_sha256', 'region_sha256']) if (k in o && !(typeof o[k] === 'string' && /^[0-9a-f]{64}$/.test(o[k] as string))) {
2641
+ c.fail('CONFIG_EXPLICIT_HASH', `${where}.${k}`, 'requires exactly 64 lowercase hexadecimal SHA-256 digits; derive it from the accepted part image and region');
2642
+ }
2643
+ const uvs = Array.isArray(o.uvs) ? o.uvs : [];
2644
+ if ('uvs' in o && c.array(`${where}.uvs`, o.uvs, true)) {
2645
+ uvs.forEach((v, i) => c.number(`${where}.uvs[${i}]`, v));
2646
+ if (uvs.length % 2 !== 0) c.fail('CONFIG_EXPLICIT_SHAPE', `${where}.uvs`, `has ${uvs.length} numbers; x/y pairs are required`);
2647
+ }
2648
+ if ('triangles' in o && c.array(`${where}.triangles`, o.triangles, true)) {
2649
+ o.triangles.forEach((v, i) => {
2650
+ if (c.int(`${where}.triangles[${i}]`, v, 0) && v >= uvs.length / 2) c.fail('CONFIG_EXPLICIT_SHAPE', `${where}.triangles[${i}]`, `is ${v}; the payload has ${uvs.length / 2} vertices`);
2651
+ });
2652
+ if (o.triangles.length % 3 !== 0) c.fail('CONFIG_EXPLICIT_SHAPE', `${where}.triangles`, `has ${o.triangles.length} indices; triples are required`);
2653
+ }
2654
+ if ('hull' in o && c.int(`${where}.hull`, o.hull, 1) && o.hull > uvs.length / 2) c.fail('CONFIG_EXPLICIT_SHAPE', `${where}.hull`, `is ${o.hull}; the payload has ${uvs.length / 2} vertices`);
2655
+ if ('weights' in o && c.array(`${where}.weights`, o.weights, true)) {
2656
+ if (o.weights.length !== uvs.length / 2) c.fail('CONFIG_EXPLICIT_SHAPE', `${where}.weights`, `has ${o.weights.length} rows for ${uvs.length / 2} vertices; one row per vertex is required`);
2657
+ o.weights.forEach((row, i) => {
2658
+ const atRow = `${where}.weights[${i}]`;
2659
+ if (!c.array(atRow, row, true)) return;
2660
+ row.forEach((v, j) => {
2661
+ const atWeight = `${atRow}[${j}]`, w = c.object(atWeight, v, ['bone', 'x', 'y', 'weight'], []);
2662
+ if (w === null) return;
2663
+ if ('bone' in w && c.string(`${atWeight}.bone`, w.bone)) {
2664
+ if (!bones.has(w.bone)) c.fail('CONFIG_NAME_RESOLVES', `${atWeight}.bone`, `names "${w.bone}", which is not a bone`);
2665
+ else if (Array.isArray(m.segments) && !m.segments.includes(w.bone)) c.fail('CONFIG_NAME_RESOLVES', `${atWeight}.bone`, `names "${w.bone}", which this explicit mesh's segments do not declare`);
2666
+ }
2667
+ for (const k of ['x', 'y', 'weight']) if (k in w) c.number(`${atWeight}.${k}`, w[k]);
2668
+ });
2669
+ });
2670
+ }
2671
+ }
2672
+
2584
2673
  /** The fields of the distance rule and of the other modes, which an influence mesh does not read (issue #378). */
2585
2674
  export const INFLUENCE_FOREIGN_FIELDS = ['r', 'exponent', 'rule', 'influences', 'stray', 'ribs'] as const;
2586
2675
 
package/src/coords.ts CHANGED
@@ -22,5 +22,17 @@
22
22
  * `flattenRig` goes back through `toWorld`. No rotation matrix is written out
23
23
  * by hand in this package.
24
24
  */
25
+ import { cropToSpineY } from 'rig-c/src/transform.ts';
26
+
27
+ /** A painting point on the accepted integer rig canvas, in setup-world coordinates. */
28
+ export function paintingToSetupPoint(point: readonly number[], sourceSize: readonly number[], rigSize: readonly number[]): [number, number] {
29
+ return [point[0] * (rigSize[0] / sourceSize[0]) - rigSize[0] / 2, cropToSpineY(point[1] * (rigSize[1] / sourceSize[1]), rigSize[1])];
30
+ }
31
+
32
+ /** Inverse of paintingToSetupPoint; cropToSpineY is its own inverse. */
33
+ export function setupToPaintingPoint(point: readonly number[], sourceSize: readonly number[], rigSize: readonly number[]): [number, number] {
34
+ return [(point[0] + rigSize[0] / 2) / (rigSize[0] / sourceSize[0]), cropToSpineY(point[1], rigSize[1]) / (rigSize[1] / sourceSize[1])];
35
+ }
36
+
25
37
  export { computeExactFrameTransforms, computeWorldTransforms, cropToSpineY, normaliseDegrees, toBoneLocal, toBoneLocalVector, toWorld } from 'rig-c/src/transform.ts';
26
38
  export type { BoneTransform } from 'rig-c/src/transform.ts';
@@ -206,6 +206,7 @@ export function legChainChoice(P: PartSet, spec: { bones: readonly BoneEntry[];
206
206
  if (!hasSourceBinding && P.recs.some((p) => p.name === part)) sources.add(part);
207
207
  };
208
208
  for (const [part, mesh] of Object.entries(spec.meshes)) {
209
+ if ('explicit' in mesh) { if (mesh.explicit.weights.some(row => row.some(w => links.has(w.bone)))) bound(part); continue; }
209
210
  if (mesh.segments.some((s) => typeof s === 'string' ? s === entry.chain || links.has(s) : links.has(s[0]))) bound(part);
210
211
  }
211
212
  for (const [part, bone] of Object.entries(spec.regions ?? {})) if (links.has(regionBone(bone))) bound(part);
@@ -0,0 +1,53 @@
1
+ /** Immutable accepted-mesh transfer (issue #658). No generator or topology repair runs here. */
2
+ import { createHash } from 'node:crypto';
3
+ import type { ExplicitMeshSpec } from './config.ts';
4
+ import type { Problem } from './errors.ts';
5
+ import { ART_ALPHA, artCoverage } from './mesh.ts';
6
+ import type { PartRecord } from './parts.ts';
7
+ import { alphaAbove, pad } from './raster/index.ts';
8
+ import type { Raster } from './raster/types.ts';
9
+ import { PAD, type MeshAttachment } from './rig.ts';
10
+ import { pyRound } from './round.ts';
11
+
12
+ /** SHA-256 over unpadded decoded RGBA, with its size bound by explicitRegionHash. */
13
+ export function explicitImageHash(image: Raster): string {
14
+ return createHash('sha256').update(image.data).digest('hex');
15
+ }
16
+
17
+ /** The canvas and placed unpadded part rectangle, in the parts reader's field order. */
18
+ export function explicitRegionHash(size: readonly number[], part: Pick<PartRecord, 'x' | 'y' | 'w' | 'h'>): string {
19
+ return createHash('sha256').update(JSON.stringify([size[0], size[1], part.x, part.y, part.w, part.h])).digest('hex');
20
+ }
21
+
22
+ export interface ExplicitMeshReport {
23
+ part: string;
24
+ vertices: number;
25
+ triangles: number;
26
+ hull: number;
27
+ bones: string[];
28
+ max_influences: number;
29
+ mean_influences: number;
30
+ art_coverage: number;
31
+ mode: 'explicit';
32
+ image_sha256: string;
33
+ region_sha256: string;
34
+ }
35
+
36
+ /** Guard before constructing output; clone only named payload fields, retaining every supplied number. */
37
+ export function explicitAttachment(part: PartRecord, image: Raster, size: readonly number[], spec: ExplicitMeshSpec): { attachment: MeshAttachment; report: ExplicitMeshReport } | Problem[] {
38
+ const input = spec.explicit, problems: Problem[] = [];
39
+ const hashes = { image_sha256: explicitImageHash(image), region_sha256: explicitRegionHash(size, part) };
40
+ for (const [field, code] of [['image_sha256', 'RIG_EXPLICIT_IMAGE_HASH'], ['region_sha256', 'RIG_EXPLICIT_REGION_HASH']] as const) {
41
+ if (input[field] !== hashes[field]) problems.push({ code, object: `config.meshes.${part.name}.explicit.${field}`, detail: `declares ${input[field]}; the current part has ${hashes[field]} — restore the accepted part image and region, or supply its matching accepted payload; nothing is written` });
42
+ }
43
+ if (problems.length > 0) return problems;
44
+ const padded = pad(image, PAD, PAD, PAD, PAD, [0, 0, 0, 0]);
45
+ const weights = input.weights.map(row => row.map(w => ({ bone: w.bone, x: w.x, y: w.y, weight: w.weight })));
46
+ const attachment: MeshAttachment = { type: 'mesh', image: `${part.name}.png`, width: padded.width, height: padded.height, uvs: [...input.uvs], triangles: [...input.triangles], hull: input.hull, weights };
47
+ const vertices: Array<[number, number]> = [];
48
+ for (let i = 0; i < input.uvs.length; i += 2) vertices.push([input.uvs[i] * padded.width, input.uvs[i + 1] * padded.height]);
49
+ return { attachment, report: { part: part.name, vertices: weights.length, triangles: input.triangles.length / 3, hull: input.hull,
50
+ bones: [...new Set(weights.flatMap(row => row.map(w => w.bone)))].sort(), max_influences: weights.reduce((n, row) => Math.max(n, row.length), 0),
51
+ mean_influences: pyRound(weights.reduce((n, row) => n + row.length, 0) / weights.length, 2),
52
+ art_coverage: pyRound(artCoverage({ vertices, triangles: input.triangles }, alphaAbove(padded, ART_ALPHA)), 5), mode: 'explicit', ...hashes } };
53
+ }
package/src/meshdraft.ts CHANGED
@@ -133,7 +133,7 @@ export const NOT_COMPARED_SENTENCE = 'mesh-draft drafts lattice entries only, so
133
133
  /** A config entry `mesh-draft` did not draft because it is not a lattice (issue #307), in config order. */
134
134
  export interface NotCompared {
135
135
  part: string;
136
- mode: 'contour' | 'auto' | 'influence';
136
+ mode: 'contour' | 'auto' | 'influence' | 'explicit';
137
137
  note: string;
138
138
  }
139
139
 
@@ -142,7 +142,7 @@ export function notCompared(meshes: CharacterConfig['meshes']): NotCompared[] {
142
142
  const out: NotCompared[] = [];
143
143
  for (const [part, spec] of Object.entries(meshes)) {
144
144
  if ('grid' in spec) continue;
145
- const mode = 'auto' in spec ? 'auto' : 'influence' in spec ? 'influence' : 'contour';
145
+ const mode = 'explicit' in spec ? 'explicit' : 'auto' in spec ? 'auto' : 'influence' in spec ? 'influence' : 'contour';
146
146
  out.push({ part, mode, note: `its entry is "${mode}", not a lattice: ${NOT_COMPARED_SENTENCE}` });
147
147
  }
148
148
  return out;
package/src/meshstats.ts CHANGED
@@ -16,7 +16,7 @@ import { buildRig, DEFAULT_IDLE_KEYS, type MeshReport } from './rig.ts';
16
16
  /** One mesh's counts, as the rig stage's `mesh_report.json` row holds them; `mode` is `lattice` for a `grid` entry, whose row carries no mode. */
17
17
  export interface MeshStatsRow {
18
18
  part: string;
19
- mode: 'lattice' | 'contour' | 'auto' | 'influence';
19
+ mode: 'lattice' | 'contour' | 'auto' | 'influence' | 'explicit';
20
20
  vertices: number;
21
21
  triangles: number;
22
22
  }
package/src/parts.ts CHANGED
@@ -89,6 +89,7 @@ import { existsSync, readFileSync, writeFileSync } from 'node:fs';
89
89
  import { type Problem, refuseIfAny } from './errors.ts';
90
90
  import { KEYPOINT_NAMES, type PosePoints } from './skeleton.ts';
91
91
  import { readLayerTag } from './tags.ts';
92
+ import { recordedFocusProblems } from './setfocus.ts';
92
93
 
93
94
  export interface PartRecord {
94
95
  name: string;
@@ -283,6 +284,8 @@ export interface RecompositeRecord {
283
284
  }
284
285
 
285
286
  export interface AlternateSetMap {
287
+ /** Authored point in setup-world coordinates, only when supplied (issue #719). */
288
+ focus?: [number, number];
286
289
  slots: Record<string, string>;
287
290
  hides?: string[];
288
291
  drawn?: Record<string, number>;
@@ -301,6 +304,9 @@ export const FRONT_SUFFIX = '_front';
301
304
 
302
305
  export interface AlternatePartsRecord {
303
306
  name: string;
307
+ /** Original authored painting point and its source size, only when supplied. */
308
+ focus?: [number, number];
309
+ focus_source_size?: [number, number];
304
310
  parts?: string[];
305
311
  hides?: string[];
306
312
  /**
@@ -472,6 +478,8 @@ export function serializeParts(file: PartsFile): string {
472
478
  ...(a.single_run_pad === undefined ? {} : { single_run_pad: Object.fromEntries(SINGLE_RUN_PAD_KEYS.map((k) => [k, (a.single_run_pad as SingleRunPad)[k]])) }),
473
479
  ...(a.skeleton === undefined ? {} : { skeleton: Object.fromEntries(KEYPOINT_NAMES.map((k) => [k, (a.skeleton as PosePoints)[k]])) }),
474
480
  ...(a.drawn === undefined ? {} : { drawn: a.drawn }),
481
+ ...(a.focus === undefined ? {} : { focus: a.focus }),
482
+ ...(a.focus_source_size === undefined ? {} : { focus_source_size: a.focus_source_size }),
475
483
  ...(a.tips_source_size === undefined ? {} : { tips_source_size: a.tips_source_size }),
476
484
  ...(a.tips === undefined ? {} : { tips: Object.fromEntries(Object.keys(a.tips).sort().map((bone) => [bone, (a.tips as Record<string, [number, number]>)[bone]])) }),
477
485
  ...(a.drawnLength === undefined ? {} : { drawnLength: a.drawnLength }),
@@ -692,6 +700,7 @@ function checkParts(raw: unknown, path: string): PartsFile {
692
700
  if (typeof a !== 'object' || a === null || Array.isArray(a)) return;
693
701
  const set = a as Record<string, unknown>;
694
702
  const at = `${path} alternates[${i}]${typeof set.name === 'string' ? ` (set "${set.name}")` : ''}`;
703
+ if (sizeOk && typeof scale === 'number') problems.push(...recordedFocusProblems(set, `${at}.focus`, size as number[], scale));
695
704
  if ('tips' in set || 'tips_source_size' in set) {
696
705
  const sourceSize = set.tips_source_size;
697
706
  if (!('tips' in set) || !Array.isArray(sourceSize) || sourceSize.length !== 2 || !sourceSize.every((n) => typeof n === 'number' && Number.isInteger(n) && n > 0)) {
package/src/propose.ts CHANGED
@@ -4908,6 +4908,7 @@ export function lint(
4908
4908
  unknownMeshes.push(mname);
4909
4909
  continue;
4910
4910
  }
4911
+ if ('explicit' in m) continue;
4911
4912
  const mask = dilate(P.alpha(part), 31);
4912
4913
  const names: string[] = [];
4913
4914
  for (const sp of m.segments) {
@@ -4932,7 +4933,7 @@ export function lint(
4932
4933
  return part !== undefined && splitFrom(part.from)[0] === 'head' && splitFrom(part.from)[1] === 'front hair';
4933
4934
  });
4934
4935
  const lockChains = lockMeshes.flatMap(([mname, m]) =>
4935
- m.segments.flatMap((sp) => {
4936
+ ('explicit' in m ? [] : m.segments).flatMap((sp) => {
4936
4937
  if (typeof sp !== 'string') return [];
4937
4938
  const e = spec.bones.find((b) => 'chain' in b && b.chain === sp);
4938
4939
  return e !== undefined && 'chain' in e && e.parent === 'head' ? [{ mesh: mname, entry: e }] : [];
@@ -5426,6 +5427,10 @@ function lintCoverage(
5426
5427
  const single: string[] = [];
5427
5428
  const partless: string[] = [];
5428
5429
  for (const [mname, m] of Object.entries(spec.meshes)) {
5430
+ if ('explicit' in m) {
5431
+ if (m.explicit.weights.some(row => row.some(w => w.bone === bone))) why.push(`bound by meshes.${mname}.explicit.weights: the segment-origin checks do not read an accepted payload`);
5432
+ continue;
5433
+ }
5429
5434
  m.segments.forEach((sp, i) => {
5430
5435
  const at = `meshes.${mname}.segments[${i}]`;
5431
5436
  if (typeof sp !== 'string') {
package/src/rig.ts CHANGED
@@ -1,4 +1,5 @@
1
- import { regionBone } from './config.ts';
1
+ import { explicitBoneNames, regionBone } from './config.ts';
2
+ import { explicitAttachment, type ExplicitMeshReport } from './explicitmesh.ts';
2
3
  /**
3
4
  * The rig stage: a character config and its assembled parts in, a rig spec
4
5
  * and a motion spec in rig-c's format out.
@@ -135,8 +136,9 @@ import { regionBone } from './config.ts';
135
136
  * order the objects are built in, and every number is rounded by `pyRound`).
136
137
  */
137
138
  import { type AutoSpec, type BoneEntry, type InfluenceMeshSpec, type WeightRule, type CharacterConfig, type ConfigConstraint, type ConfigStop, CONSTRAINT_FOLLOWS, constraintForRig, contourRegionsOf, type ContourSpec, DEFAULT_BUST_BONE_L, DEFAULT_BUST_BONE_R, type Point, type RibsSpec, ROOT_BONE, stopForRig, turnRidersByBone, weightsABone } from './config.ts';
138
- import { type BoneTransform, computeExactFrameTransforms, cropToSpineY, normaliseDegrees, toBoneLocal, toWorld } from './coords.ts';
139
+ import { type BoneTransform, computeExactFrameTransforms, cropToSpineY, normaliseDegrees, paintingToSetupPoint, toBoneLocal, toWorld } from './coords.ts';
139
140
  import { type Problem, refuseIfAny } from './errors.ts';
141
+ import { recordedFocusProblems } from './setfocus.ts';
140
142
  import { eyeLineDegrees } from './headframe.ts';
141
143
  import type { RigBoneInherit, RigStop } from 'rig-c/src/rig.ts';
142
144
  import { f32 } from 'rig-c/compile';
@@ -795,7 +797,7 @@ export function meshBoundBones(att: Pick<MeshAttachment, 'weights'>): string[] {
795
797
  }
796
798
 
797
799
  /** One row of `mesh_report.json`: a lattice mesh's row is as it always was; a contour mesh's says so. */
798
- export type MeshReport = LatticeMeshReport | ContourMeshReport | AutoMeshReport | InfluenceMeshReport;
800
+ export type MeshReport = LatticeMeshReport | ContourMeshReport | AutoMeshReport | InfluenceMeshReport | ExplicitMeshReport;
799
801
 
800
802
  /**
801
803
  * An influence mesh's row (issue #378): the lattice's counts and coverage as every row has them, the block as declared,
@@ -1253,6 +1255,18 @@ export function buildRig(
1253
1255
  const CX = W / 2;
1254
1256
  const byPart = new Map(parts.parts.map((p) => [p.name, p]));
1255
1257
 
1258
+ for (const a of parts.alternates ?? []) {
1259
+ problems.push(...recordedFocusProblems(a, `parts.json alternate set "${a.name}".focus`, parts.rig_size, parts.scale_rig_per_source));
1260
+ }
1261
+ for (const a of cfg.assemble.alternates ?? cfg.alternates ?? []) {
1262
+ const record = parts.alternates?.find((p) => p.name === a.name);
1263
+ if ((a.focus !== undefined || record?.focus !== undefined)
1264
+ && JSON.stringify(a.focus) !== JSON.stringify(record?.focus)) {
1265
+ fail('CONFIG_SET_FOCUS', `config.assemble alternate set "${a.name}".focus`, 'does not match the assembled painting point; re-run assemble after changing or removing focus');
1266
+ }
1267
+ }
1268
+ refuseIfAny(problems);
1269
+
1256
1270
  // Standalone rig checks source-bound normalization, never reconstructing
1257
1271
  // original dimensions from nominal scale or treating source points as rig points.
1258
1272
  for (const a of parts.alternates ?? []) {
@@ -1364,7 +1378,14 @@ export function buildRig(
1364
1378
  // issue #378: which `segments` entry each resolved segment came from — rig-c's `bones` entries, which an influence
1365
1379
  // mesh's `across: false` keeps apart. Every mode resolves them; only the influence mode reads this.
1366
1380
  const meshSegmentEntries = new Map<string, number[]>();
1381
+ const explicitNames = explicitBoneNames(new Set(B.keys()), new Map([...chains].map(([k, v]) => [k, v.length])), cfg.stops);
1367
1382
  for (const [part, m] of Object.entries(cfg.meshes)) {
1383
+ if ('explicit' in m) {
1384
+ for (const bone of [...m.segments.map(s => typeof s === 'string' ? s : s[0]), ...m.explicit.weights.flatMap(row => row.map(w => w.bone))]) {
1385
+ if (!explicitNames.has(bone)) fail('RIG_NAME_RESOLVES', `config.meshes.${part}.explicit`, `names the bone "${bone}", which config.bones does not declare`);
1386
+ }
1387
+ continue;
1388
+ }
1368
1389
  if ('contour' in m) {
1369
1390
  (m.contour.regions ?? []).forEach((rg, i) => {
1370
1391
  if (!B.has(rg.bone)) fail('RIG_NAME_RESOLVES', `config.meshes.${part}.contour.regions[${i}].bone`, `names the bone "${rg.bone}", which config.bones does not declare`);
@@ -1499,6 +1520,11 @@ export function buildRig(
1499
1520
  // to its control under `ctl` as theirs do. A config with no contour region adds nothing here.
1500
1521
  for (const m of Object.values(cfg.meshes)) if ('contour' in m) for (const rg of contourRegionsOf(m.contour)) meshBones.add(rg.bone);
1501
1522
  for (const m of Object.values(cfg.meshes)) if ('auto' in m) for (const rg of m.auto.regions ?? []) if (weightsABone(rg)) meshBones.add(rg.bone);
1523
+ for (const m of Object.values(cfg.meshes)) if ('explicit' in m) for (const row of m.explicit.weights) for (const w of row) meshBones.add(w.bone);
1524
+ // Accepted final bindings may already name a stop's drawn link. Its source link still needs the idle control.
1525
+ for (const stop of cfg.stops ?? []) for (const link of stop.links ?? chains.get(stop.chain) ?? []) {
1526
+ if (meshBones.has(`${link}_d`)) meshBones.add(link);
1527
+ }
1502
1528
  const meshKeyed = controlledBones(motion, meshBones);
1503
1529
  const controls = idleKeys === 'ctl' ? meshKeyed : [];
1504
1530
  for (const k of controls) {
@@ -2289,6 +2315,14 @@ export function buildRig(
2289
2315
  addSlots(p.name, { name: p.name, bone: bone.name, attachment: p.name });
2290
2316
  continue;
2291
2317
  }
2318
+ if ('explicit' in mesh) {
2319
+ const row = explicitAttachment(p, images.get(p.name) as Raster, parts.rig_size, mesh);
2320
+ if (Array.isArray(row)) { problems.push(...row); continue; }
2321
+ skin[p.name] = { [p.name]: row.attachment };
2322
+ addSlots(p.name, { name: p.name, bone: mesh.segments[0] as string, attachment: p.name });
2323
+ meshReport.push(row.report);
2324
+ continue;
2325
+ }
2292
2326
  const segs = meshSegments.get(p.name) as Segment[];
2293
2327
  if ('auto' in mesh) {
2294
2328
  const row = autoAttachment(p, img, file, mesh.auto, mesh.r, mesh.exponent, segs, mesh.rule ?? 'distance', mesh, problems);
@@ -2469,6 +2503,7 @@ export function buildRig(
2469
2503
  for (const s of meshSegments.get(pName) ?? []) coveredBones.add(s.bone);
2470
2504
  const m = cfg.meshes[pName];
2471
2505
  if (m !== undefined) {
2506
+ if ('explicit' in m) for (const row of m.explicit.weights) for (const w of row) coveredBones.add(w.bone);
2472
2507
  if ('contour' in m) for (const rg of contourRegionsOf(m.contour)) coveredBones.add(rg.bone);
2473
2508
  if ('auto' in m) for (const rg of m.auto.regions ?? []) if (weightsABone(rg)) coveredBones.add(rg.bone);
2474
2509
  }
@@ -2534,6 +2569,10 @@ export function buildRig(
2534
2569
  skin[skinSlot][attName] = altRegion(file, bone.name, p.x + p.w / 2, p.y + p.h / 2);
2535
2570
  continue;
2536
2571
  }
2572
+ if ('explicit' in mesh) {
2573
+ fail('RIG_EXPLICIT_ALTERNATE', `config.meshes.${p.name}.explicit`, `set "${alt.name}" replaces this part; an accepted payload is bound to one image and region, not alternate artwork or bind poses — use a generated mesh for this alternate part`);
2574
+ continue;
2575
+ }
2537
2576
  const fullSegs = meshSegments.get(p.name) as Segment[];
2538
2577
  const explicitSegments = new Map(fullSegs.map((s, k) => [s, typeof mesh.segments[(meshSegmentEntries.get(p.name) as number[])[k]] !== 'string']));
2539
2578
  const baseAtt = skin[p.name]?.[p.name];
@@ -2661,6 +2700,7 @@ export function buildRig(
2661
2700
  const coversFace = Object.hasOwn(slotMap, 'face');
2662
2701
  setEntries[alt.name] = {
2663
2702
  slots: slotMap,
2703
+ ...(alt.focus === undefined ? {} : { focus: paintingToSetupPoint(alt.focus, alt.focus_source_size as [number, number], parts.rig_size) }),
2664
2704
  ...(hideList.length > 0 ? { hides: hideList } : {}),
2665
2705
  ...(drawn === undefined ? {} : { drawn }),
2666
2706
  ...(alt.drawnLength === undefined ? {} : { drawnLength: { ...alt.drawnLength } }),
@@ -2682,8 +2722,13 @@ export function buildRig(
2682
2722
  ...Object.entries(cfg.meshes).filter(([, spec]) => spec.gather === false).map(([part]) => ({ part, object: `config.meshes.${part}.gather`, slots: slotFamilies.get(part) ?? [part] })),
2683
2723
  ...Object.entries(cfg.regions).filter(([, spec]) => typeof spec !== 'string' && spec.gather === false).map(([part]) => ({ part, object: `config.regions.${part}.gather`, slots: slotFamilies.get(part) ?? [part] })),
2684
2724
  ];
2685
- const limbLayout = coalesceLimbSlots(cfg.limbs, bones, slots, skin, ungathered);
2686
- const explicitLayout = placeLimbLayouts(cfg.limbs, bones, limbLayout, skin, slotFamilies);
2725
+ // Accepted explicit weights already name drawn stop links. Resolve only the
2726
+ // declared aliases for ownership before applyStops, without rebinding them
2727
+ // or adding these lookup-only entries to the emitted bone graph.
2728
+ const ownershipBones = cfg.stops === undefined ? bones : [...bones, ...cfg.stops.flatMap(s =>
2729
+ (s.links ?? chains.get(s.chain) ?? []).map(link => ({ name: `${link}_d`, parent: link, x: 0, y: 0 })))];
2730
+ const limbLayout = coalesceLimbSlots(cfg.limbs, ownershipBones, slots, skin, ungathered);
2731
+ const explicitLayout = placeLimbLayouts(cfg.limbs, ownershipBones, limbLayout, skin, slotFamilies);
2687
2732
  // ---- leg stops (issue #404) --------------------------------------------
2688
2733
  // Only when the config has `stops`: each link after the first (and any bone hanging from a stopped link) hangs
2689
2734
  // from the drawn link `<link>_d` above it, and slots and weights on a stopped link bind `<link>_d`.
@@ -2701,6 +2746,13 @@ export function buildRig(
2701
2746
  if (att !== undefined && 'type' in att) row.bones = meshBoundBones(att);
2702
2747
  }
2703
2748
 
2749
+ for (const [part, mesh] of Object.entries(cfg.meshes)) if ('explicit' in mesh) {
2750
+ const att = skin[part]?.[part];
2751
+ if (att !== undefined && 'type' in att && JSON.stringify(att.weights) !== JSON.stringify(mesh.explicit.weights.map(row => row.map(w => ({ bone: w.bone, x: w.x, y: w.y, weight: w.weight }))))) {
2752
+ fail('RIG_EXPLICIT_BINDING', `config.meshes.${part}.explicit.weights`, 'the declared stops or turn would change these accepted bindings; supply the accepted final emitted bone names and bind coordinates, or use a generated mesh; no payload is normalized');
2753
+ }
2754
+ }
2755
+ refuseIfAny(problems);
2704
2756
  const name = `${cfg.key}_painting`;
2705
2757
  const rig: RigSpec = {
2706
2758
  spec: 'rigc-rig/1',
@@ -0,0 +1,21 @@
1
+ /** Issue #719: authored painting points, never inferred from geometry. */
2
+ import type { Problem } from './errors.ts';
3
+
4
+ export function setFocusProblems(value: unknown, object: string, size?: readonly number[]): Problem[] {
5
+ if (!Array.isArray(value) || value.length !== 2 || !value.every((n) => typeof n === 'number' && Number.isFinite(n))
6
+ || value.some((n) => n < 0) || (size !== undefined && value.some((n, i) => n > size[i]))) {
7
+ return [{ code: 'CONFIG_SET_FOCUS', object, detail: `is ${Array.isArray(value) ? '[' + value.map((n) => typeof n === 'number' ? String(n) : JSON.stringify(n)).join(', ') + ']' : String(JSON.stringify(value))}; exactly two finite painting-pixel coordinates [x, y]${size === undefined ? ', both non-negative' : ` inside the ${size[0]}x${size[1]} painting (edges included)`} are required; author the point or omit focus` }];
8
+ }
9
+ return [];
10
+ }
11
+
12
+ /** The conditional parts record retains the actual painting size, not a size guessed from rig_scale. */
13
+ export function recordedFocusProblems(record: { focus?: unknown; focus_source_size?: unknown }, object: string, rigSize: readonly number[], scale: number): Problem[] {
14
+ if (!('focus' in record) && !('focus_source_size' in record)) return [];
15
+ const size = record.focus_source_size;
16
+ if (!('focus' in record) || !Array.isArray(size) || size.length !== 2 || !size.every((n) => typeof n === 'number' && Number.isInteger(n) && n > 0)
17
+ || size.some((n, i) => Math.trunc(n * scale) !== rigSize[i])) {
18
+ return [{ code: 'CONFIG_SET_FOCUS', object, detail: 'requires focus with its original positive integer focus_source_size [width, height] producing rig_size at scale_rig_per_source; re-run assemble' }];
19
+ }
20
+ return setFocusProblems(record.focus, object, size);
21
+ }
package/src/squeeze.ts CHANGED
@@ -182,6 +182,7 @@ export function chainSqueezes(
182
182
  const times = frameTimes(motion.duration);
183
183
 
184
184
  for (const [mname, m] of Object.entries(spec.meshes)) {
185
+ if ('explicit' in m) { unread.push(`mesh ${JSON.stringify(mname)} is an explicit payload; the lattice squeeze is not read`); continue; }
185
186
  const keyed = m.segments.filter((s): s is string => typeof s === 'string' && chains.has(s) && tracks.has(s));
186
187
  if (keyed.length < 2) continue;
187
188
  const pairs: Array<[string, string]> = [];
@@ -318,7 +319,7 @@ export function branchSqueezes(
318
319
  }
319
320
 
320
321
  for (const [mname, m] of Object.entries(spec.meshes)) {
321
- if ('contour' in m || 'auto' in m || 'influence' in m || m.rule === 'heat' || m.r >= m.grid) continue;
322
+ if ('explicit' in m || 'contour' in m || 'auto' in m || 'influence' in m || m.rule === 'heat' || m.r >= m.grid) continue;
322
323
  const byFork = new Map<string, string[]>();
323
324
  for (const sp of m.segments) {
324
325
  if (typeof sp !== 'string') continue;
package/src/structure.ts CHANGED
@@ -179,6 +179,10 @@ export function configRoles(s: SkeletonSections & { constraints?: readonly Confi
179
179
  }
180
180
  const bound = new Map<string, string[]>();
181
181
  for (const [part, m] of Object.entries(s.meshes)) {
182
+ if ('explicit' in m) {
183
+ for (const row of m.explicit.weights) for (const w of row) push(bound, w.bone, `meshes.${part}.explicit.weights`);
184
+ continue;
185
+ }
182
186
  m.segments.forEach((sp, i) => {
183
187
  const at = `meshes.${part}.segments[${i}]`;
184
188
  if (typeof sp === 'string') for (const b of chains.get(sp) ?? [sp]) push(bound, b, at);