@ikijs/editor 0.4.0 → 0.5.0

package/README.md

@@ -49,7 +49,7 @@ leaves the document untouched.
 | Grid keyforms      | `computeGridOffsets`, `interpolateGridOffsets`, `upsertGridKeyform`                                                                                               |
 | Factories          | `createDefaultPart`, `createDefaultMatrixDeformer`, `createDefaultWarpDeformer`, `createGridMesh`                                                                 |
 | Pixels             | `detectAlphaBbox`, `ALPHA_BBOX_THRESHOLD`, `AlphaBbox`                                                                                                            |
-| Auto-rig           | `generateIkiFromLayerSet`, `parseLayerRoles`                                                                                                                      |
+| Auto-rig           | `generateIkiFromLayerSet`, `parseLayerRoles`, `TurnTargets`, `DEFAULT_TURN_TARGETS`, `TurnSolveReport`                                                            |
 | Bindings           | `captureBindingEndpoint`                                                                                                                                          |
 
 ## Auto-rig
@@ -60,6 +60,35 @@ leaves the document untouched.
 torso that follows and breathes, and emotes with its brows — including a
 hair-sway physics rig when a `hair_front` layer is present.
 
+On the turn the head's outline holds still — the bangs that draw it pin their
+own silhouette — while everything inside it slides: the face plate, its
+features, and the bangs' own inner strands. That slide is the plate's own ask, a
+quarter of its half-width, capped to what the held outline has room for when
+`turnTargets.headHalfWidth` was measured and uncut when it was not. That turn is
+**fitted, not tuned**: on a layer set with a `nose`, the cylinder's radius and
+each feature's own depth on top of that slide are solved from
+`options.turnTargets` — the cues a 30° reference measures (how far the eye pair
+slides, how much the far eye foreshortens, whether the silhouette holds),
+defaulting to `DEFAULT_TURN_TARGETS`. The features' slide is bounded by the art:
+every feature has to stay on the face plate, because past its contour the far
+eye is drawn over the side hair, which still bends with the plate inside that
+held outline and swallows it. A target you passed that this layer set cannot
+reach **throws**, naming the field and the range it could have had; a target
+that came from the defaults is a style prior, not a measurement of this
+character, so it is **clamped** to what the layer set can do and the rig is
+built. Pass `options.onTurnSolved` to see what the turn settled on and which
+targets were clamped.
+
+`turnTargets.headHalfWidth` is what the shift targets are fractions of, when a
+caller has measured the actual head (the face plate stands in otherwise).
+Alongside it, `options.headEdges` names, per side, every layer with an opaque
+pixel at the eye row and its own rest x there — a companion to a measured
+`headHalfWidth`, absent otherwise — so the solver can land each candidate
+through its OWN part's deformation (the bangs move with their hold, the back
+hair holds still, a face-plate or body edge slide) rather than assume the head
+is centred on the face plate or that whichever part drew furthest out at rest
+is still the furthest out after it turns.
+
 It takes **already-decoded** layer geometry (`LayerInput`), never pixels, which
 is what keeps this package free of any image dependency: the editor app
 decodes with canvas, `@ikijs/mcp` decodes with `sharp`, and both feed the same

package/dist/index.d.mts

@@ -891,6 +891,92 @@ declare function parseLayerRoles(fileNames: string[]): {
     role: string;
     fileName: string;
 }[];
+/**
+ * What a head does at full turn, as the cues `measure_turn_reference` reads off
+ * a front/turned reference pair. The turn is fitted to these — the cylinder's
+ * radius and the features' depths are solved from them, not tuned.
+ *
+ * Every field is optional: `DEFAULT_TURN_TARGETS` supplies the three a
+ * reference measures, and the nose and the mouth derive from the eyes when they
+ * are not given.
+ *
+ * What happens when the layer set cannot reach a target depends on where the
+ * target came from. A number the CALLER passed is a measurement, so an
+ * unreachable one throws, naming the field and what was on offer. A number this
+ * module filled in — a default, or a nose/mouth derived from the eyes — is a
+ * style prior, not a promise about this character: it is CLAMPED to what the
+ * layer set can do and the rig is built. The alternative is a generator that
+ * refuses its own defaults, which would leave a perfectly good layer set with
+ * no model at all. `solveTurnModel` reports which fields it clamped.
+ */
+interface TurnTargets {
+    /** How far the eye pair's centre slides toward the far side at full turn, as
+     *  a fraction of the head's half-width. The sign is ignored: which way is
+     *  the turn's own business. */
+    eyeShift?: number;
+    /** The far eye's width over the near eye's at full turn, divided by the same
+     *  ratio at rest. 1 is no foreshortening; 0 is an edge-on far eye. */
+    farEyeRatio?: number;
+    /** The head's half-width at full turn over its half-width at rest, as a
+     *  RENDER measures it — the outermost opaque edge on each side, whichever
+     *  part owns it. 1 holds the silhouette; below 1 narrows it. The hold that
+     *  produces it is fitted to it, so a measured one is met or refused, never
+     *  quietly rendered as something else. */
+    silhouetteRatio?: number;
+    /** `eyeShift` for the nose. Derived from `eyeShift` when absent. */
+    noseShift?: number;
+    /** `eyeShift` for the mouth. Derived from `eyeShift` when absent. */
+    mouthShift?: number;
+    /** The head's own half-width at the eye row, in canvas px: what the shift
+     *  fractions are fractions OF, and the rest distance the silhouette hold
+     *  pivots on. Without it both fall back to the face plate's half-width, which
+     *  is narrower than the head the hair draws, so the shifts land short — an
+     *  approximation for callers that have no pixels, not a default to prefer. */
+    headHalfWidth?: number;
+}
+/**
+ * A `turnTargets` field this generator will not build a rig from: not a number,
+ * outside its range, unreachable on this layer set, or a measured head narrower
+ * than the face plate it is drawn around. Every one of them carries a number
+ * the CALLER passed, so a host can tell them apart from the invariant breaks the
+ * rest of the generator throws and report them as bad input instead of failing.
+ */
+declare class TurnTargetError extends Error {
+    constructor(message: string);
+}
+/**
+ * The reference the turn is fitted to when the caller measured none of its own:
+ * a 3/4 portrait, which `measure_turn_reference` reads as 0.671 / −0.224 /
+ * 1.012 (its raw turned far/near iris ratio is 0.71 — 0.67 is that ratio
+ * normalised by the same ratio at rest, which is what the field means).
+ * The silhouette is held exactly: a 1 % change is inside that tool's own noise.
+ */
+declare const DEFAULT_TURN_TARGETS: Readonly<Required<Pick<TurnTargets, "eyeShift" | "farEyeRatio" | "silhouetteRatio">>>;
+/** The turn depth of each feature family: the share of the pinned bulk slide
+ *  (`headTurnParallaxUnit`) it gets back at full turn. Solved, never tuned. */
+interface TurnDepths {
+    eye: number;
+    nose: number;
+    mouth: number;
+}
+/** What the turn solve settled on, for a caller that wants to see it — the
+ *  cues it reached and the targets it had to cut down to reach them. */
+interface TurnSolveReport {
+    /** Cylinder radius the face-warp bake and the parallax unit were built on. */
+    radius: number;
+    /** Rest distance from the face centre the silhouette hold pivots on. */
+    holdBase: number;
+    depths: TurnDepths;
+    /** What the rig actually reaches, in the targets' own units. */
+    achieved: {
+        eyeShift: number;
+        farEyeRatio: number;
+        silhouetteRatio: number;
+    };
+    /** Defaulted fields the layer set could not reach, cut down to what it can.
+     *  Empty when every target was met. */
+    clamped: (keyof TurnTargets)[];
+}
 /**
  * Auto-rig: given decoded layer inputs and the shared canvas size, produce a
  * valid IkiModel ready for parseIkiModel.
@@ -900,7 +986,8 @@ declare function parseLayerRoles(fileNames: string[]): {
  *   - Emit the standard parameters (same ids/ranges as sample-model.ts), plus a
  *     conditional HairSwayX descriptor + hair-sway physics rig when a hair_front
  *     layer is present.
- *   - Build headDeformer (matrix, neck pivot, AngleX+Breath bindings),
+ *   - Build headDeformer (matrix, neck pivot, nod/tilt/breath bindings — the
+ *     turn translates nothing rigidly; its travel is in the face warp),
  *     bodyDeformer when a body layer is present (matrix, torso-base pivot,
  *     AngleX follow + Breath follow), and faceWarp (warp, FACE_GRID_CELLS²,
  *     baked cylinder warp center-relative on faceCenterX).
@@ -910,10 +997,36 @@ declare function parseLayerRoles(fileNames: string[]): {
  *   - Part ids equal the role string (deterministic, no crypto.randomUUID).
  *   - Return parseIkiModel(structuredClone(model)) — every caller gets a
  *     validated model; bad assembly fails loudly.
+ *
+ * `options.turnTargets` is what the head turn is fitted to: the cues a 30°
+ * reference measures, defaulting to DEFAULT_TURN_TARGETS. A target the CALLER
+ * passed that this layer set cannot reach throws; one that came from the
+ * defaults is clamped to what it can do — see TurnTargets for why the two
+ * differ, and pass `options.onTurnSolved` to see which ones were clamped and
+ * what the turn ended up reaching.
  */
 declare function generateIkiFromLayerSet(layers: LayerInput[], canvas: {
     width: number;
     height: number;
+}, options?: {
+    turnTargets?: TurnTargets;
+    /** Called once, after a turn is solved, with what it settled on. Not called
+     *  for a layer set without a nose, which solves no turn at all. */
+    onTurnSolved?: (report: TurnSolveReport) => void;
+    /** Every role with an opaque pixel in the eye-row band, per side, when
+     *  `turnTargets.headHalfWidth` was measured off that same union — a
+     *  companion to it, not a turn target itself (the caller-facing contract
+     *  stays the three cues). See `TurnSolveContext.headEdges`. */
+    headEdges?: {
+        left: {
+            role: string;
+            x: number;
+        }[];
+        right: {
+            role: string;
+            x: number;
+        }[];
+    };
 }): IkiModel;
 
-export { ALPHA_BBOX_THRESHOLD, ATLAS_PADDING, AddDeformer, AddPart, AddPhysicsRig, type AlphaBbox, type ApplyAtlasInput, type AtlasAssignment, type AtlasLayout, type AtlasPlacement, type AtlasSource, CaptureGridKeyform, type DeformerTransformChannel, DeleteDeformer, DeletePart, DeletePhysicsRig, type EditCommand, type EditTransformChannel, EditorDocument, type LayerInput, SetDeformerBindings, SetDeformerParent, SetDeformerPivot, SetDeformerPivotX, SetDeformerPivotY, SetDeformerTransform, SetPartBindings, SetPartColor, SetPartDeformer, SetPartHeight, SetPartMesh, SetPartOrder, SetPartTransform, SetPartWidth, SetPhysicsRig, UV_INSET_PX, captureBindingEndpoint, computeGridOffsets, createDefaultMatrixDeformer, createDefaultPart, createDefaultWarpDeformer, createGridMesh, detectAlphaBbox, generateIkiFromLayerSet, interpolateGridOffsets, packAtlas, parseLayerRoles, upsertGridKeyform, uvRectFor, validateDeformerDelete, validateDeformerReparent, validatePartAttach };
+export { ALPHA_BBOX_THRESHOLD, ATLAS_PADDING, AddDeformer, AddPart, AddPhysicsRig, type AlphaBbox, type ApplyAtlasInput, type AtlasAssignment, type AtlasLayout, type AtlasPlacement, type AtlasSource, CaptureGridKeyform, DEFAULT_TURN_TARGETS, type DeformerTransformChannel, DeleteDeformer, DeletePart, DeletePhysicsRig, type EditCommand, type EditTransformChannel, EditorDocument, type LayerInput, SetDeformerBindings, SetDeformerParent, SetDeformerPivot, SetDeformerPivotX, SetDeformerPivotY, SetDeformerTransform, SetPartBindings, SetPartColor, SetPartDeformer, SetPartHeight, SetPartMesh, SetPartOrder, SetPartTransform, SetPartWidth, SetPhysicsRig, type TurnDepths, type TurnSolveReport, TurnTargetError, type TurnTargets, UV_INSET_PX, captureBindingEndpoint, computeGridOffsets, createDefaultMatrixDeformer, createDefaultPart, createDefaultWarpDeformer, createGridMesh, detectAlphaBbox, generateIkiFromLayerSet, interpolateGridOffsets, packAtlas, parseLayerRoles, upsertGridKeyform, uvRectFor, validateDeformerDelete, validateDeformerReparent, validatePartAttach };

package/dist/index.d.ts

@@ -891,6 +891,92 @@ declare function parseLayerRoles(fileNames: string[]): {
     role: string;
     fileName: string;
 }[];
+/**
+ * What a head does at full turn, as the cues `measure_turn_reference` reads off
+ * a front/turned reference pair. The turn is fitted to these — the cylinder's
+ * radius and the features' depths are solved from them, not tuned.
+ *
+ * Every field is optional: `DEFAULT_TURN_TARGETS` supplies the three a
+ * reference measures, and the nose and the mouth derive from the eyes when they
+ * are not given.
+ *
+ * What happens when the layer set cannot reach a target depends on where the
+ * target came from. A number the CALLER passed is a measurement, so an
+ * unreachable one throws, naming the field and what was on offer. A number this
+ * module filled in — a default, or a nose/mouth derived from the eyes — is a
+ * style prior, not a promise about this character: it is CLAMPED to what the
+ * layer set can do and the rig is built. The alternative is a generator that
+ * refuses its own defaults, which would leave a perfectly good layer set with
+ * no model at all. `solveTurnModel` reports which fields it clamped.
+ */
+interface TurnTargets {
+    /** How far the eye pair's centre slides toward the far side at full turn, as
+     *  a fraction of the head's half-width. The sign is ignored: which way is
+     *  the turn's own business. */
+    eyeShift?: number;
+    /** The far eye's width over the near eye's at full turn, divided by the same
+     *  ratio at rest. 1 is no foreshortening; 0 is an edge-on far eye. */
+    farEyeRatio?: number;
+    /** The head's half-width at full turn over its half-width at rest, as a
+     *  RENDER measures it — the outermost opaque edge on each side, whichever
+     *  part owns it. 1 holds the silhouette; below 1 narrows it. The hold that
+     *  produces it is fitted to it, so a measured one is met or refused, never
+     *  quietly rendered as something else. */
+    silhouetteRatio?: number;
+    /** `eyeShift` for the nose. Derived from `eyeShift` when absent. */
+    noseShift?: number;
+    /** `eyeShift` for the mouth. Derived from `eyeShift` when absent. */
+    mouthShift?: number;
+    /** The head's own half-width at the eye row, in canvas px: what the shift
+     *  fractions are fractions OF, and the rest distance the silhouette hold
+     *  pivots on. Without it both fall back to the face plate's half-width, which
+     *  is narrower than the head the hair draws, so the shifts land short — an
+     *  approximation for callers that have no pixels, not a default to prefer. */
+    headHalfWidth?: number;
+}
+/**
+ * A `turnTargets` field this generator will not build a rig from: not a number,
+ * outside its range, unreachable on this layer set, or a measured head narrower
+ * than the face plate it is drawn around. Every one of them carries a number
+ * the CALLER passed, so a host can tell them apart from the invariant breaks the
+ * rest of the generator throws and report them as bad input instead of failing.
+ */
+declare class TurnTargetError extends Error {
+    constructor(message: string);
+}
+/**
+ * The reference the turn is fitted to when the caller measured none of its own:
+ * a 3/4 portrait, which `measure_turn_reference` reads as 0.671 / −0.224 /
+ * 1.012 (its raw turned far/near iris ratio is 0.71 — 0.67 is that ratio
+ * normalised by the same ratio at rest, which is what the field means).
+ * The silhouette is held exactly: a 1 % change is inside that tool's own noise.
+ */
+declare const DEFAULT_TURN_TARGETS: Readonly<Required<Pick<TurnTargets, "eyeShift" | "farEyeRatio" | "silhouetteRatio">>>;
+/** The turn depth of each feature family: the share of the pinned bulk slide
+ *  (`headTurnParallaxUnit`) it gets back at full turn. Solved, never tuned. */
+interface TurnDepths {
+    eye: number;
+    nose: number;
+    mouth: number;
+}
+/** What the turn solve settled on, for a caller that wants to see it — the
+ *  cues it reached and the targets it had to cut down to reach them. */
+interface TurnSolveReport {
+    /** Cylinder radius the face-warp bake and the parallax unit were built on. */
+    radius: number;
+    /** Rest distance from the face centre the silhouette hold pivots on. */
+    holdBase: number;
+    depths: TurnDepths;
+    /** What the rig actually reaches, in the targets' own units. */
+    achieved: {
+        eyeShift: number;
+        farEyeRatio: number;
+        silhouetteRatio: number;
+    };
+    /** Defaulted fields the layer set could not reach, cut down to what it can.
+     *  Empty when every target was met. */
+    clamped: (keyof TurnTargets)[];
+}
 /**
  * Auto-rig: given decoded layer inputs and the shared canvas size, produce a
  * valid IkiModel ready for parseIkiModel.
@@ -900,7 +986,8 @@ declare function parseLayerRoles(fileNames: string[]): {
  *   - Emit the standard parameters (same ids/ranges as sample-model.ts), plus a
  *     conditional HairSwayX descriptor + hair-sway physics rig when a hair_front
  *     layer is present.
- *   - Build headDeformer (matrix, neck pivot, AngleX+Breath bindings),
+ *   - Build headDeformer (matrix, neck pivot, nod/tilt/breath bindings — the
+ *     turn translates nothing rigidly; its travel is in the face warp),
  *     bodyDeformer when a body layer is present (matrix, torso-base pivot,
  *     AngleX follow + Breath follow), and faceWarp (warp, FACE_GRID_CELLS²,
  *     baked cylinder warp center-relative on faceCenterX).
@@ -910,10 +997,36 @@ declare function parseLayerRoles(fileNames: string[]): {
  *   - Part ids equal the role string (deterministic, no crypto.randomUUID).
  *   - Return parseIkiModel(structuredClone(model)) — every caller gets a
  *     validated model; bad assembly fails loudly.
+ *
+ * `options.turnTargets` is what the head turn is fitted to: the cues a 30°
+ * reference measures, defaulting to DEFAULT_TURN_TARGETS. A target the CALLER
+ * passed that this layer set cannot reach throws; one that came from the
+ * defaults is clamped to what it can do — see TurnTargets for why the two
+ * differ, and pass `options.onTurnSolved` to see which ones were clamped and
+ * what the turn ended up reaching.
  */
 declare function generateIkiFromLayerSet(layers: LayerInput[], canvas: {
     width: number;
     height: number;
+}, options?: {
+    turnTargets?: TurnTargets;
+    /** Called once, after a turn is solved, with what it settled on. Not called
+     *  for a layer set without a nose, which solves no turn at all. */
+    onTurnSolved?: (report: TurnSolveReport) => void;
+    /** Every role with an opaque pixel in the eye-row band, per side, when
+     *  `turnTargets.headHalfWidth` was measured off that same union — a
+     *  companion to it, not a turn target itself (the caller-facing contract
+     *  stays the three cues). See `TurnSolveContext.headEdges`. */
+    headEdges?: {
+        left: {
+            role: string;
+            x: number;
+        }[];
+        right: {
+            role: string;
+            x: number;
+        }[];
+    };
 }): IkiModel;
 
-export { ALPHA_BBOX_THRESHOLD, ATLAS_PADDING, AddDeformer, AddPart, AddPhysicsRig, type AlphaBbox, type ApplyAtlasInput, type AtlasAssignment, type AtlasLayout, type AtlasPlacement, type AtlasSource, CaptureGridKeyform, type DeformerTransformChannel, DeleteDeformer, DeletePart, DeletePhysicsRig, type EditCommand, type EditTransformChannel, EditorDocument, type LayerInput, SetDeformerBindings, SetDeformerParent, SetDeformerPivot, SetDeformerPivotX, SetDeformerPivotY, SetDeformerTransform, SetPartBindings, SetPartColor, SetPartDeformer, SetPartHeight, SetPartMesh, SetPartOrder, SetPartTransform, SetPartWidth, SetPhysicsRig, UV_INSET_PX, captureBindingEndpoint, computeGridOffsets, createDefaultMatrixDeformer, createDefaultPart, createDefaultWarpDeformer, createGridMesh, detectAlphaBbox, generateIkiFromLayerSet, interpolateGridOffsets, packAtlas, parseLayerRoles, upsertGridKeyform, uvRectFor, validateDeformerDelete, validateDeformerReparent, validatePartAttach };
+export { ALPHA_BBOX_THRESHOLD, ATLAS_PADDING, AddDeformer, AddPart, AddPhysicsRig, type AlphaBbox, type ApplyAtlasInput, type AtlasAssignment, type AtlasLayout, type AtlasPlacement, type AtlasSource, CaptureGridKeyform, DEFAULT_TURN_TARGETS, type DeformerTransformChannel, DeleteDeformer, DeletePart, DeletePhysicsRig, type EditCommand, type EditTransformChannel, EditorDocument, type LayerInput, SetDeformerBindings, SetDeformerParent, SetDeformerPivot, SetDeformerPivotX, SetDeformerPivotY, SetDeformerTransform, SetPartBindings, SetPartColor, SetPartDeformer, SetPartHeight, SetPartMesh, SetPartOrder, SetPartTransform, SetPartWidth, SetPhysicsRig, type TurnDepths, type TurnSolveReport, TurnTargetError, type TurnTargets, UV_INSET_PX, captureBindingEndpoint, computeGridOffsets, createDefaultMatrixDeformer, createDefaultPart, createDefaultWarpDeformer, createGridMesh, detectAlphaBbox, generateIkiFromLayerSet, interpolateGridOffsets, packAtlas, parseLayerRoles, upsertGridKeyform, uvRectFor, validateDeformerDelete, validateDeformerReparent, validatePartAttach };