@ikijs/editor 0.16.1 → 0.17.0

package/README.md

@@ -40,26 +40,27 @@ leaves the document untouched.
 
 ## API
 
-| Area               | Exports                                                                                                                                                                  |
-| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Document           | `EditorDocument`, `EditCommand`                                                                                                                                          |
-| Part edits         | `AddPart`, `DeletePart`, `SetPartColor`, `SetPartWidth`, `SetPartHeight`, `SetPartOrder`, `SetPartTransform`, `SetPartBindings`, `SetPartMesh`, `SetPartDeformer`        |
-| Deformer edits     | `AddDeformer`, `DeleteDeformer`, `SetDeformerParent`, `SetDeformerTransform`, `SetDeformerBindings`, `SetDeformerPivot` (+ `X`/`Y`), `CaptureGridKeyform`                |
-| Physics edits      | `AddPhysicsRig`, `SetPhysicsRig`, `DeletePhysicsRig`                                                                                                                     |
-| Referential guards | `validateDeformerReparent`, `validateDeformerDelete`, `validatePartAttach`                                                                                               |
-| Atlas              | `packAtlas`, `uvRectFor`, `ATLAS_PADDING`, `UV_INSET_PX`                                                                                                                 |
-| Grid keyforms      | `computeGridOffsets`, `interpolateGridOffsets`, `upsertGridKeyform`                                                                                                      |
-| Factories          | `createDefaultPart`, `createDefaultMatrixDeformer`, `createDefaultWarpDeformer`, `createGridMesh`                                                                        |
-| Pixels             | `detectAlphaBbox`, `ALPHA_BBOX_THRESHOLD`, `AlphaBbox`, `ALPHA_OPAQUE`, `HEAD_BAND`, `SPECK_CORE_FRACTION`, `denseCoreOf`, `isSpeckCore`, `foregroundSpan`, `headHalfOf` |
-| Auto-rig           | `generateIkiFromLayerSet`, `parseLayerRoles`, `createLayerSetMeasurer`, `TurnTargets`, `DEFAULT_TURN_TARGETS`, `TurnSolveReport`, `RigStyle`                             |
-| Bindings           | `captureBindingEndpoint`                                                                                                                                                 |
+| Area               | Exports                                                                                                                                                                             |
+| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Document           | `EditorDocument`, `EditCommand`                                                                                                                                                     |
+| Part edits         | `AddPart`, `DeletePart`, `SetPartColor`, `SetPartWidth`, `SetPartHeight`, `SetPartOrder`, `SetPartTransform`, `SetPartBindings`, `SetPartMesh`, `SetPartDeformer`                   |
+| Deformer edits     | `AddDeformer`, `DeleteDeformer`, `SetDeformerParent`, `SetDeformerTransform`, `SetDeformerBindings`, `SetDeformerPivot` (+ `X`/`Y`), `CaptureGridKeyform`                           |
+| Physics edits      | `AddPhysicsRig`, `SetPhysicsRig`, `DeletePhysicsRig`                                                                                                                                |
+| Referential guards | `validateDeformerReparent`, `validateDeformerDelete`, `validatePartAttach`                                                                                                          |
+| Atlas              | `packAtlas`, `uvRectFor`, `ATLAS_PADDING`, `UV_INSET_PX`                                                                                                                            |
+| Grid keyforms      | `computeGridOffsets`, `interpolateGridOffsets`, `upsertGridKeyform`                                                                                                                 |
+| Factories          | `createDefaultPart`, `createDefaultMatrixDeformer`, `createDefaultWarpDeformer`, `createGridMesh`                                                                                   |
+| Pixels             | `detectAlphaBbox`, `ALPHA_BBOX_THRESHOLD`, `AlphaBbox`, `ALPHA_OPAQUE`, `HEAD_BAND`, `SPECK_CORE_FRACTION`, `denseCoreOf`, `isSpeckCore`, `foregroundSpan`, `headHalfOf`            |
+| Auto-rig           | `generateIkiFromLayerSet`, `parseLayerRoles`, `partIdsOfRole`, `createLayerSetMeasurer`, `TurnTargets`, `DEFAULT_TURN_TARGETS`, `TurnSolveReport`, `RigStyle`, `LayerGeometryError` |
+| Bindings           | `captureBindingEndpoint`                                                                                                                                                            |
 
 ## Auto-rig
 
 `generateIkiFromLayerSet` turns role-named layers (`face`, `eye_L`, `eye_R`,
 `mouth`, plus optional `iris_*`, `brow_*`, `lash_*`, `lash_lower_*`, `hair_front`, `hair_back`,
-…) into a rigged model that blinks, gazes, opens its mouth, turns its head over
-a torso that breathes, and emotes with its brows — including a
+`body`, `arm_*`, …) into a rigged model that blinks, gazes, opens its mouth, turns its head over
+a body warp that breathes, follows the head a little and turns on
+`ParamBodyAngleX/Y/Z`, and emotes with its brows — including a
 hair-sway physics rig when a `hair_front` layer is present. With a `blush_*`
 layer it declares `ParamCheek`, which fades the blush from faint at rest to
 as drawn. Every rigged model also declares the head motions Nod, Shake and
@@ -77,8 +78,13 @@ edge further outside the back hair painted behind it than the nod alone does —
 and the back hair stays behind; the neck and the
 ears the face layer paints are cut off into islands of the plate's own mesh,
 drawn behind the head — the neck stays (only the chin's shade slides across
-it), the ears lag the face, the far one narrowing. AngleZ rolls the head 14° about the chin; the torso only
-breathes.
+it), the ears lag the face, the far one narrowing. AngleZ rolls the head 14° about the chin.
+A `body` rides a body warp that breathes, follows the head's turn and tilt a
+little and turns on `ParamBodyAngleX/Y/Z`, its legs planted, and the head
+hangs from it. `arm_L` / `arm_R`, each a whole arm drawn hanging with its
+shoulder at the top, hang from it too: each becomes an upper arm and a
+forearm cut from the one crop, turning about the shoulder and the elbow on
+`ParamArmL/R` and `ParamElbowL/R`. An arm needs a `body`.
 
 On a layer set with a `nose`, `options.turnTargets` — the cues a 30° reference
 measures (how far the eye pair slides, how much the far eye foreshortens,

package/dist/index.d.mts

@@ -696,7 +696,8 @@ interface RigStyle {
 
 /** One role layer, as a host measured it off its decoded pixels. */
 interface LayerInput {
-    /** Canonical role (see `parseLayerRoles`); becomes the part id. */
+    /** Canonical role (see `parseLayerRoles`); becomes the part ids
+     *  `partIdsOfRole` lists. */
     role: string;
     fileName: string;
     canvasW: number;
@@ -712,12 +713,14 @@ interface LayerInput {
     cropH: number;
     /** Face only: half the opaque span of each crop row, canvas px (0 = none). */
     rowHalfWidths?: number[];
-    /** `face` / `hair_front` / `hair_back` only: per crop row, its opaque (alpha ≥ 128)
-     *  runs as a flat list of canvas columns `[start0, end0, start1, end1, …]`,
-     *  each end exclusive (`[]` for a row with none). The actual pixels, so a
-     *  gap in the hair is a gap here: the turn and the nod read off it where
-     *  back hair is painted behind the front hair, and the crown's turn reads the
-     *  face's so it never bares skin. */
+    /** `face` / `hair_front` / `hair_back` / `body` / `arm_L` / `arm_R` only:
+     *  per crop row, its opaque (alpha ≥ 128) runs as a flat list of canvas
+     *  columns `[start0, end0, start1, end1, …]`, each end exclusive (`[]` for a
+     *  row with none). The actual pixels, so a gap in the hair is a gap here:
+     *  the turn and the nod read off it where back hair is painted behind the
+     *  front hair, and the crown's turn reads the face's so it never bares skin.
+     *  The body's place the hips (where it splits into legs), and an arm's place
+     *  its shoulder and elbow pivots. */
     rowRuns?: number[][];
     /** Nose only: the tight box of its alpha ≥ 128 pixels, canvas px. */
     denseCore?: {
@@ -763,6 +766,14 @@ interface TurnTargets {
 declare class TurnTargetError extends Error {
     constructor(message: string);
 }
+/**
+ * Art geometry the rig cannot build on — today a body whose hips leave no row
+ * line under its pivots, or too little room for its motion (`body.ts`). A fact about the layers, not a bug, so a
+ * host reports it as an input error.
+ */
+declare class LayerGeometryError extends Error {
+    constructor(message: string);
+}
 /**
  * The profile's own turn (`profile.ts`), in the cues' units — what a rig with
  * no `turnTargets` renders on a head whose silhouette at the eye row is back
@@ -844,9 +855,13 @@ interface GenerateOptions {
     };
 }
 
+/** The part ids a `role`'s layer becomes, back to front: every one of them
+ *  takes its texture from the layer's crop. Throws on an unknown role. */
+declare function partIdsOfRole(role: string): readonly string[];
 /**
- * Map file names to roles. Throws on an unknown role, a role named twice, or
- * a required role (`face`, `eye_L`, `eye_R`, `mouth`) missing.
+ * Map file names to roles. Throws on an unknown role, a role named twice, a
+ * required role (`face`, `eye_L`, `eye_R`, `mouth`) missing, or an arm
+ * without a body.
  */
 declare function parseLayerRoles(fileNames: string[]): {
     role: string;
@@ -856,13 +871,17 @@ declare function parseLayerRoles(fileNames: string[]): {
 /**
  * `generateIkiFromLayerSet`: role layers in, a rigged `.iki` out.
  *
- * The rig's shape is a 2D head rig's usual one (`profile.ts`): a torso that
- * only breathes; a head deformer that rolls about the chin and breathes; one
- * small warp grid per feature (each eye, each brow, the nose, the mouth),
- * translating and foreshortening it by its own lead over the plate; and the
- * plate, the hair and the blush moved by per-vertex keyforms of their own —
- * the plate as up to four islands of one drawing: a head that slides, a neck
- * that stays and two ears that lag. Blink, gaze, brows, mouth, breath and
+ * The rig's shape is a 2D head rig's usual one (`profile.ts`): a body warp
+ * (`body.ts`) that breathes, follows the head's turn and tilt a little and
+ * turns on BodyAngleX/Y/Z, its legs planted; a head deformer hung from it
+ * that rolls about the chin and breathes; each arm hung from it too, as an
+ * upper arm and a forearm turning about the shoulder and the elbow
+ * (`arms.ts`); one small warp grid per feature
+ * (each eye, each brow, the nose, the mouth), translating and foreshortening
+ * it by its own lead over the plate; and the plate, the hair and the blush
+ * moved by per-vertex keyforms of their own — the plate as up to four
+ * islands of one drawing: a head that slides, a neck that stays on the torso
+ * and two ears that lag. Blink, gaze, brows, mouth, breath and
  * hair sway are part warps and bindings under those. The model also declares
  * the default expressions and the Nod, Shake and Tilt motions
  * (`animations.ts`).
@@ -1004,7 +1023,8 @@ interface LayerSetMeasurer {
      * it: only the set's opaque union, this layer's per-row opaque extent and
      * the `LayerInput` it returns outlive the call, so the host may drop `rgba`
      * as soon as it returns. Returns the layer's `LayerInput` — its crop
-     * box, the face's `rowHalfWidths`, the face's and hair layers' `rowRuns`, the nose's
+     * box, the face's `rowHalfWidths`, the face's, hair layers', body's and
+     * arms' `rowRuns`, the nose's
      * `denseCore` unless that is a speck of its crop (`isSpeckCore`) — or
      * `null` for an empty layer, one with no pixel at or above
      * `ALPHA_BBOX_THRESHOLD`, which it records nothing for: the host reports
@@ -1261,4 +1281,4 @@ declare function createGridMesh(cols: number, rows: number): IkiMesh;
  */
 declare function createDefaultWarpDeformer(model: IkiModel): IkiWarpDeformer;
 
-export { ALPHA_BBOX_THRESHOLD, ALPHA_OPAQUE, 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, HEAD_BAND, type IrisStrand, type LayerInput, type LayerSetMeasurement, type LayerSetMeasurer, type RgbaLayer, type RigStyle, SPECK_CORE_FRACTION, SetDeformerBindings, SetDeformerParent, SetDeformerPivot, SetDeformerPivotX, SetDeformerPivotY, SetDeformerTransform, SetPartBindings, SetPartColor, SetPartDeformer, SetPartHeight, SetPartMesh, SetPartOrder, SetPartTransform, SetPartWidth, SetPhysicsRig, type StrandOverlap, type TurnDepths, type TurnSolveReport, TurnTargetError, type TurnTargets, UV_INSET_PX, captureBindingEndpoint, computeGridOffsets, createDefaultMatrixDeformer, createDefaultPart, createDefaultWarpDeformer, createGridMesh, createLayerSetMeasurer, denseCoreOf, detectAlphaBbox, foregroundSpan, generateIkiFromLayerSet, headHalfOf, interpolateGridOffsets, isSpeckCore, packAtlas, parseLayerRoles, upsertGridKeyform, uvRectFor, validateDeformerDelete, validateDeformerReparent, validatePartAttach };
+export { ALPHA_BBOX_THRESHOLD, ALPHA_OPAQUE, 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, HEAD_BAND, type IrisStrand, LayerGeometryError, type LayerInput, type LayerSetMeasurement, type LayerSetMeasurer, type RgbaLayer, type RigStyle, SPECK_CORE_FRACTION, SetDeformerBindings, SetDeformerParent, SetDeformerPivot, SetDeformerPivotX, SetDeformerPivotY, SetDeformerTransform, SetPartBindings, SetPartColor, SetPartDeformer, SetPartHeight, SetPartMesh, SetPartOrder, SetPartTransform, SetPartWidth, SetPhysicsRig, type StrandOverlap, type TurnDepths, type TurnSolveReport, TurnTargetError, type TurnTargets, UV_INSET_PX, captureBindingEndpoint, computeGridOffsets, createDefaultMatrixDeformer, createDefaultPart, createDefaultWarpDeformer, createGridMesh, createLayerSetMeasurer, denseCoreOf, detectAlphaBbox, foregroundSpan, generateIkiFromLayerSet, headHalfOf, interpolateGridOffsets, isSpeckCore, packAtlas, parseLayerRoles, partIdsOfRole, upsertGridKeyform, uvRectFor, validateDeformerDelete, validateDeformerReparent, validatePartAttach };

package/dist/index.d.ts

@@ -696,7 +696,8 @@ interface RigStyle {
 
 /** One role layer, as a host measured it off its decoded pixels. */
 interface LayerInput {
-    /** Canonical role (see `parseLayerRoles`); becomes the part id. */
+    /** Canonical role (see `parseLayerRoles`); becomes the part ids
+     *  `partIdsOfRole` lists. */
     role: string;
     fileName: string;
     canvasW: number;
@@ -712,12 +713,14 @@ interface LayerInput {
     cropH: number;
     /** Face only: half the opaque span of each crop row, canvas px (0 = none). */
     rowHalfWidths?: number[];
-    /** `face` / `hair_front` / `hair_back` only: per crop row, its opaque (alpha ≥ 128)
-     *  runs as a flat list of canvas columns `[start0, end0, start1, end1, …]`,
-     *  each end exclusive (`[]` for a row with none). The actual pixels, so a
-     *  gap in the hair is a gap here: the turn and the nod read off it where
-     *  back hair is painted behind the front hair, and the crown's turn reads the
-     *  face's so it never bares skin. */
+    /** `face` / `hair_front` / `hair_back` / `body` / `arm_L` / `arm_R` only:
+     *  per crop row, its opaque (alpha ≥ 128) runs as a flat list of canvas
+     *  columns `[start0, end0, start1, end1, …]`, each end exclusive (`[]` for a
+     *  row with none). The actual pixels, so a gap in the hair is a gap here:
+     *  the turn and the nod read off it where back hair is painted behind the
+     *  front hair, and the crown's turn reads the face's so it never bares skin.
+     *  The body's place the hips (where it splits into legs), and an arm's place
+     *  its shoulder and elbow pivots. */
     rowRuns?: number[][];
     /** Nose only: the tight box of its alpha ≥ 128 pixels, canvas px. */
     denseCore?: {
@@ -763,6 +766,14 @@ interface TurnTargets {
 declare class TurnTargetError extends Error {
     constructor(message: string);
 }
+/**
+ * Art geometry the rig cannot build on — today a body whose hips leave no row
+ * line under its pivots, or too little room for its motion (`body.ts`). A fact about the layers, not a bug, so a
+ * host reports it as an input error.
+ */
+declare class LayerGeometryError extends Error {
+    constructor(message: string);
+}
 /**
  * The profile's own turn (`profile.ts`), in the cues' units — what a rig with
  * no `turnTargets` renders on a head whose silhouette at the eye row is back
@@ -844,9 +855,13 @@ interface GenerateOptions {
     };
 }
 
+/** The part ids a `role`'s layer becomes, back to front: every one of them
+ *  takes its texture from the layer's crop. Throws on an unknown role. */
+declare function partIdsOfRole(role: string): readonly string[];
 /**
- * Map file names to roles. Throws on an unknown role, a role named twice, or
- * a required role (`face`, `eye_L`, `eye_R`, `mouth`) missing.
+ * Map file names to roles. Throws on an unknown role, a role named twice, a
+ * required role (`face`, `eye_L`, `eye_R`, `mouth`) missing, or an arm
+ * without a body.
  */
 declare function parseLayerRoles(fileNames: string[]): {
     role: string;
@@ -856,13 +871,17 @@ declare function parseLayerRoles(fileNames: string[]): {
 /**
  * `generateIkiFromLayerSet`: role layers in, a rigged `.iki` out.
  *
- * The rig's shape is a 2D head rig's usual one (`profile.ts`): a torso that
- * only breathes; a head deformer that rolls about the chin and breathes; one
- * small warp grid per feature (each eye, each brow, the nose, the mouth),
- * translating and foreshortening it by its own lead over the plate; and the
- * plate, the hair and the blush moved by per-vertex keyforms of their own —
- * the plate as up to four islands of one drawing: a head that slides, a neck
- * that stays and two ears that lag. Blink, gaze, brows, mouth, breath and
+ * The rig's shape is a 2D head rig's usual one (`profile.ts`): a body warp
+ * (`body.ts`) that breathes, follows the head's turn and tilt a little and
+ * turns on BodyAngleX/Y/Z, its legs planted; a head deformer hung from it
+ * that rolls about the chin and breathes; each arm hung from it too, as an
+ * upper arm and a forearm turning about the shoulder and the elbow
+ * (`arms.ts`); one small warp grid per feature
+ * (each eye, each brow, the nose, the mouth), translating and foreshortening
+ * it by its own lead over the plate; and the plate, the hair and the blush
+ * moved by per-vertex keyforms of their own — the plate as up to four
+ * islands of one drawing: a head that slides, a neck that stays on the torso
+ * and two ears that lag. Blink, gaze, brows, mouth, breath and
  * hair sway are part warps and bindings under those. The model also declares
  * the default expressions and the Nod, Shake and Tilt motions
  * (`animations.ts`).
@@ -1004,7 +1023,8 @@ interface LayerSetMeasurer {
      * it: only the set's opaque union, this layer's per-row opaque extent and
      * the `LayerInput` it returns outlive the call, so the host may drop `rgba`
      * as soon as it returns. Returns the layer's `LayerInput` — its crop
-     * box, the face's `rowHalfWidths`, the face's and hair layers' `rowRuns`, the nose's
+     * box, the face's `rowHalfWidths`, the face's, hair layers', body's and
+     * arms' `rowRuns`, the nose's
      * `denseCore` unless that is a speck of its crop (`isSpeckCore`) — or
      * `null` for an empty layer, one with no pixel at or above
      * `ALPHA_BBOX_THRESHOLD`, which it records nothing for: the host reports
@@ -1261,4 +1281,4 @@ declare function createGridMesh(cols: number, rows: number): IkiMesh;
  */
 declare function createDefaultWarpDeformer(model: IkiModel): IkiWarpDeformer;
 
-export { ALPHA_BBOX_THRESHOLD, ALPHA_OPAQUE, 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, HEAD_BAND, type IrisStrand, type LayerInput, type LayerSetMeasurement, type LayerSetMeasurer, type RgbaLayer, type RigStyle, SPECK_CORE_FRACTION, SetDeformerBindings, SetDeformerParent, SetDeformerPivot, SetDeformerPivotX, SetDeformerPivotY, SetDeformerTransform, SetPartBindings, SetPartColor, SetPartDeformer, SetPartHeight, SetPartMesh, SetPartOrder, SetPartTransform, SetPartWidth, SetPhysicsRig, type StrandOverlap, type TurnDepths, type TurnSolveReport, TurnTargetError, type TurnTargets, UV_INSET_PX, captureBindingEndpoint, computeGridOffsets, createDefaultMatrixDeformer, createDefaultPart, createDefaultWarpDeformer, createGridMesh, createLayerSetMeasurer, denseCoreOf, detectAlphaBbox, foregroundSpan, generateIkiFromLayerSet, headHalfOf, interpolateGridOffsets, isSpeckCore, packAtlas, parseLayerRoles, upsertGridKeyform, uvRectFor, validateDeformerDelete, validateDeformerReparent, validatePartAttach };
+export { ALPHA_BBOX_THRESHOLD, ALPHA_OPAQUE, 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, HEAD_BAND, type IrisStrand, LayerGeometryError, type LayerInput, type LayerSetMeasurement, type LayerSetMeasurer, type RgbaLayer, type RigStyle, SPECK_CORE_FRACTION, SetDeformerBindings, SetDeformerParent, SetDeformerPivot, SetDeformerPivotX, SetDeformerPivotY, SetDeformerTransform, SetPartBindings, SetPartColor, SetPartDeformer, SetPartHeight, SetPartMesh, SetPartOrder, SetPartTransform, SetPartWidth, SetPhysicsRig, type StrandOverlap, type TurnDepths, type TurnSolveReport, TurnTargetError, type TurnTargets, UV_INSET_PX, captureBindingEndpoint, computeGridOffsets, createDefaultMatrixDeformer, createDefaultPart, createDefaultWarpDeformer, createGridMesh, createLayerSetMeasurer, denseCoreOf, detectAlphaBbox, foregroundSpan, generateIkiFromLayerSet, headHalfOf, interpolateGridOffsets, isSpeckCore, packAtlas, parseLayerRoles, partIdsOfRole, upsertGridKeyform, uvRectFor, validateDeformerDelete, validateDeformerReparent, validatePartAttach };