@ikijs/editor 0.17.0 → 0.19.0

package/README.md

@@ -40,19 +40,19 @@ 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`, `partIdsOfRole`, `createLayerSetMeasurer`, `TurnTargets`, `DEFAULT_TURN_TARGETS`, `TurnSolveReport`, `RigStyle`, `LayerGeometryError` |
-| 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`, `armGeometry`, `ArmGeometry`, `TurnTargets`, `DEFAULT_TURN_TARGETS`, `TurnSolveReport`, `RigStyle`, `LayerGeometryError` |
+| Bindings           | `captureBindingEndpoint`                                                                                                                                                                                          |
 
 ## Auto-rig
 
@@ -82,9 +82,9 @@ it), the ears lag the face, the far one narrowing. AngleZ rolls the head 14° ab
 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`.
+shoulder at the top, hang from it too: each becomes an elbow cap, 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

@@ -855,6 +855,92 @@ interface GenerateOptions {
     };
 }
 
+/**
+ * The arms. Each `arm_L` / `arm_R` layer is one drawing of the whole arm,
+ * hanging, its shoulder at the top. It becomes three parts on two nested
+ * matrix deformers hung from the body warp:
+ * - the upper arm (the role's own id) on `armDeformer_X`, which turns about
+ *   the shoulder, the deltoid cap's centre;
+ * - the forearm (`forearm_X`) on `forearmDeformer_X`, a child of the arm's,
+ *   which turns about the elbow;
+ * - the elbow cap (`elbow_X`), also on `forearmDeformer_X`, drawn behind the
+ *   upper arm.
+ * The shoulder pivot rides an all-weight-1 cell of the body warp (`body.ts`),
+ * so the arm breathes and turns with the chest rigidly, never sheared.
+ *
+ * All three parts are cut from the one crop: they share its box, transform
+ * and texture rect. The upper arm is the band above the seam, the elbow
+ * pivot's row; the forearm is the band below it. Iki has no glue between
+ * meshes, and two bands hinged at a seam open a wedge as wide as the arm on a
+ * bend. The cap fills it: a half-disc fan centred on the elbow pivot turns
+ * about its own centre, so it rotates into itself and keeps the joint covered
+ * at any bend.
+ *
+ * Behind the upper arm, the cap shows only where the forearm's bend uncovers
+ * it, so it must lie inside the paint at rest, or its edge would show past
+ * the arm's. Its boundary is therefore the arm's own contour, not a circle:
+ * `armGeometry` walks each of the fan's 13 rays out from the elbow to the
+ * contour (`capRays`). A ring at the boundary, `CAP_RIM` wide, takes the UVs
+ * of the seam row's edge cross-section swept round the arc, so the exposed
+ * wedge carries the painted line, fading out in the antialias column as the
+ * painted edge does; the fan inside it is the crop's own pixels.
+ *
+ * Draw order: hair_back < body < elbow_L, arm_L, forearm_L, elbow_R, arm_R,
+ * forearm_R < face … < hair_front. The forearm draws over the upper arm,
+ * which draws over the cap.
+ *
+ * Signs: ParamArmX + raises the arm outward on either side, in degrees 1:1.
+ * A rotation is CCW-positive, so an arm whose shoulder lies right of the
+ * body's axis (+x, the character's left) turns CCW for +, and one at −x turns
+ * CW. ParamElbowX + bends the forearm toward the body, the opposite turn to
+ * the shoulder's +: it turns CW on the +x side, CCW on the −x side.
+ */
+
+type Point = {
+    x: number;
+    y: number;
+};
+interface ArmGeometry {
+    /** The shoulder pivot, model space: the deltoid cap's centre. */
+    shoulder: Point;
+    /** r_u: the upper arm's half-width under the cap, px. */
+    shoulderRadius: number;
+    /** The elbow pivot, model space. Its y is the seam the two meshes meet on. */
+    elbow: Point;
+    /** The elbow cap's largest radius, px. */
+    capRadius: number;
+    /** The cap's radius on each of its `CAP_SEGMENTS + 1` rays, from the elbow
+     *  at angles 0..π, px: the walk out to the contour, less `capInset`, at
+     *  most `capRadius`. */
+    capRays: number[];
+    /** The seam row's widest run, crop columns [start, end). */
+    seamRun: [number, number];
+    /** +1 for a shoulder right of the body's axis (+ turns CCW), −1 left of it
+     *  (+ turns CW). */
+    side: 1 | -1;
+}
+/**
+ * The arm's pivots, read off the widest opaque run of each crop row
+ * (`rowRuns`); a row without one, or a layer without runs, reads as the
+ * crop:
+ * - r_u is half the median width over the `CAP_ROWS` rows;
+ * - the shoulder pivot lies r_u under the first painted row's centre, at the
+ *   run centre of the row it lands in;
+ * - the elbow is the centre of the row `ELBOW_AT` of the way from there to
+ *   the last painted row, at its run centre;
+ * - the cap radius is half the elbow's run + 1 px, kept inside the crop;
+ * - each cap ray walks 1 px at a time from the elbow until it leaves the
+ *   widest run of the crop row it is in (strictly inside: `start < x < end`,
+ *   on canvas columns, the row the floor of the canvas y), then stops
+ *   `capInset(i)` short of that exit (none on the two seam-end rays, 2 px on
+ *   the next, `CAP_INSET` on the rest), and at `capRadius`.
+ * Pivots are on the 0.01 grid, as the written model is. `bodyAxisX` is the
+ * body's axis, model x: the shoulder's side of it sets the sign. An arm too
+ * short for its width to put the elbow under the shoulder would rig
+ * inverted, so it throws `LayerGeometryError`.
+ */
+declare function armGeometry(layer: LayerInput, bodyAxisX: number): ArmGeometry;
+
 /** 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[];
@@ -875,8 +961,8 @@ declare function parseLayerRoles(fileNames: string[]): {
  * (`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
+ * upper arm, a forearm and an elbow cap 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
@@ -1281,4 +1367,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, 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 };
+export { ALPHA_BBOX_THRESHOLD, ALPHA_OPAQUE, ATLAS_PADDING, AddDeformer, AddPart, AddPhysicsRig, type AlphaBbox, type ApplyAtlasInput, type ArmGeometry, 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, armGeometry, 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

@@ -855,6 +855,92 @@ interface GenerateOptions {
     };
 }
 
+/**
+ * The arms. Each `arm_L` / `arm_R` layer is one drawing of the whole arm,
+ * hanging, its shoulder at the top. It becomes three parts on two nested
+ * matrix deformers hung from the body warp:
+ * - the upper arm (the role's own id) on `armDeformer_X`, which turns about
+ *   the shoulder, the deltoid cap's centre;
+ * - the forearm (`forearm_X`) on `forearmDeformer_X`, a child of the arm's,
+ *   which turns about the elbow;
+ * - the elbow cap (`elbow_X`), also on `forearmDeformer_X`, drawn behind the
+ *   upper arm.
+ * The shoulder pivot rides an all-weight-1 cell of the body warp (`body.ts`),
+ * so the arm breathes and turns with the chest rigidly, never sheared.
+ *
+ * All three parts are cut from the one crop: they share its box, transform
+ * and texture rect. The upper arm is the band above the seam, the elbow
+ * pivot's row; the forearm is the band below it. Iki has no glue between
+ * meshes, and two bands hinged at a seam open a wedge as wide as the arm on a
+ * bend. The cap fills it: a half-disc fan centred on the elbow pivot turns
+ * about its own centre, so it rotates into itself and keeps the joint covered
+ * at any bend.
+ *
+ * Behind the upper arm, the cap shows only where the forearm's bend uncovers
+ * it, so it must lie inside the paint at rest, or its edge would show past
+ * the arm's. Its boundary is therefore the arm's own contour, not a circle:
+ * `armGeometry` walks each of the fan's 13 rays out from the elbow to the
+ * contour (`capRays`). A ring at the boundary, `CAP_RIM` wide, takes the UVs
+ * of the seam row's edge cross-section swept round the arc, so the exposed
+ * wedge carries the painted line, fading out in the antialias column as the
+ * painted edge does; the fan inside it is the crop's own pixels.
+ *
+ * Draw order: hair_back < body < elbow_L, arm_L, forearm_L, elbow_R, arm_R,
+ * forearm_R < face … < hair_front. The forearm draws over the upper arm,
+ * which draws over the cap.
+ *
+ * Signs: ParamArmX + raises the arm outward on either side, in degrees 1:1.
+ * A rotation is CCW-positive, so an arm whose shoulder lies right of the
+ * body's axis (+x, the character's left) turns CCW for +, and one at −x turns
+ * CW. ParamElbowX + bends the forearm toward the body, the opposite turn to
+ * the shoulder's +: it turns CW on the +x side, CCW on the −x side.
+ */
+
+type Point = {
+    x: number;
+    y: number;
+};
+interface ArmGeometry {
+    /** The shoulder pivot, model space: the deltoid cap's centre. */
+    shoulder: Point;
+    /** r_u: the upper arm's half-width under the cap, px. */
+    shoulderRadius: number;
+    /** The elbow pivot, model space. Its y is the seam the two meshes meet on. */
+    elbow: Point;
+    /** The elbow cap's largest radius, px. */
+    capRadius: number;
+    /** The cap's radius on each of its `CAP_SEGMENTS + 1` rays, from the elbow
+     *  at angles 0..π, px: the walk out to the contour, less `capInset`, at
+     *  most `capRadius`. */
+    capRays: number[];
+    /** The seam row's widest run, crop columns [start, end). */
+    seamRun: [number, number];
+    /** +1 for a shoulder right of the body's axis (+ turns CCW), −1 left of it
+     *  (+ turns CW). */
+    side: 1 | -1;
+}
+/**
+ * The arm's pivots, read off the widest opaque run of each crop row
+ * (`rowRuns`); a row without one, or a layer without runs, reads as the
+ * crop:
+ * - r_u is half the median width over the `CAP_ROWS` rows;
+ * - the shoulder pivot lies r_u under the first painted row's centre, at the
+ *   run centre of the row it lands in;
+ * - the elbow is the centre of the row `ELBOW_AT` of the way from there to
+ *   the last painted row, at its run centre;
+ * - the cap radius is half the elbow's run + 1 px, kept inside the crop;
+ * - each cap ray walks 1 px at a time from the elbow until it leaves the
+ *   widest run of the crop row it is in (strictly inside: `start < x < end`,
+ *   on canvas columns, the row the floor of the canvas y), then stops
+ *   `capInset(i)` short of that exit (none on the two seam-end rays, 2 px on
+ *   the next, `CAP_INSET` on the rest), and at `capRadius`.
+ * Pivots are on the 0.01 grid, as the written model is. `bodyAxisX` is the
+ * body's axis, model x: the shoulder's side of it sets the sign. An arm too
+ * short for its width to put the elbow under the shoulder would rig
+ * inverted, so it throws `LayerGeometryError`.
+ */
+declare function armGeometry(layer: LayerInput, bodyAxisX: number): ArmGeometry;
+
 /** 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[];
@@ -875,8 +961,8 @@ declare function parseLayerRoles(fileNames: string[]): {
  * (`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
+ * upper arm, a forearm and an elbow cap 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
@@ -1281,4 +1367,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, 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 };
+export { ALPHA_BBOX_THRESHOLD, ALPHA_OPAQUE, ATLAS_PADDING, AddDeformer, AddPart, AddPhysicsRig, type AlphaBbox, type ApplyAtlasInput, type ArmGeometry, 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, armGeometry, captureBindingEndpoint, computeGridOffsets, createDefaultMatrixDeformer, createDefaultPart, createDefaultWarpDeformer, createGridMesh, createLayerSetMeasurer, denseCoreOf, detectAlphaBbox, foregroundSpan, generateIkiFromLayerSet, headHalfOf, interpolateGridOffsets, isSpeckCore, packAtlas, parseLayerRoles, partIdsOfRole, upsertGridKeyform, uvRectFor, validateDeformerDelete, validateDeformerReparent, validatePartAttach };