@algorisys/tinyfly 0.78.0 → 0.79.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.
@@ -6,6 +6,7 @@ import type { BodyPlan, Pose, Vec3 } from './rig/body-plan';
6
6
  import { type SolvedHead } from './rig/skeleton';
7
7
  import { type Look, type Pen, type PencilOptions } from './look/pen';
8
8
  import { type HumanPoseName } from './species/human';
9
+ import { type HandPose } from './hands/hand-rig';
9
10
  /**
10
11
  * Characters (v2): any body plan, posed by numbers, turned in 3D, drawn flat
11
12
  * in a look (clean, pencil, silhouette) and a figure style (fluid, stick).
@@ -59,6 +60,15 @@ export interface CharacterOptions {
59
60
  layers?: CharacterLayers;
60
61
  /** 'ground' (default) rests the lowest contact point on the ground; 'none' leaves the figure where its pose puts it */
61
62
  contact?: 'ground' | 'none';
63
+ /**
64
+ * Hands on the fluid figure: `dot` (default) a round end to each arm,
65
+ * `cartoon` posed cartoon hands (gloved in `skin`), shaped by the pose's
66
+ * `hand.left.*` / `hand.right.*` fields (any field of a hand pose, e.g.
67
+ * `hand.right.index.curl`; see {@link characterHandPose})
68
+ */
69
+ hands?: 'dot' | 'cartoon';
70
+ /** Cartoon hand length, wrist to fingertip, fraction of the height (default 0.17: a cartoon glove) */
71
+ handSize?: number;
62
72
  }
63
73
  /** A character, with every option resolved. Plain data plus its plan. */
64
74
  export interface Character {
@@ -73,6 +83,8 @@ export interface Character {
73
83
  pencil: PencilOptions;
74
84
  layers: CharacterLayers;
75
85
  contact: 'ground' | 'none';
86
+ hands: 'dot' | 'cartoon';
87
+ handSize: number;
76
88
  }
77
89
  export declare function character(options?: CharacterOptions): Character;
78
90
  /** Where every part of a character is, as drawn, in its drawing space (feet at 0, 0; up is -y). */
@@ -103,6 +115,13 @@ export declare function pointOnHead(head: SolvedHead, x: number, y: number, z: n
103
115
  };
104
116
  /** Where every part of a character is for a pose, as `drawCharacter` would draw it. */
105
117
  export declare function characterJoints(character: Character, pose: Pose): CharacterJoints;
118
+ /**
119
+ * The hand pose a character's pose gives one of its hands: its `hand.<side>.*`
120
+ * fields over a relaxed hand. The wrist turn starts from how a hand hangs at
121
+ * the side (thumb forward), seen from the character's view, so `hand.right.turn`
122
+ * 0 is a natural hand and 1 turns it a quarter further.
123
+ */
124
+ export declare function characterHandPose(pose: Pose, side: 'left' | 'right'): HandPose;
106
125
  /**
107
126
  * Draw a character in a pose with its feet at (0, 0). `time` (ms) picks the
108
127
  * pencil's boil frame and is passed to layer hooks.
@@ -42,7 +42,7 @@ export interface HandStyle {
42
42
  tool?: 'pencil' | 'eraser';
43
43
  /** Lean of the tool, degrees (default -30) */
44
44
  angle?: number;
45
- /** Size, 1 is a pencil 240 px long (default 1) */
45
+ /** Size, 1 is a pencil 190 px long (default 1) */
46
46
  scale?: number;
47
47
  /** Skin colour */
48
48
  skin?: string;
@@ -50,13 +50,66 @@ export interface HandStyle {
50
50
  sleeve?: string;
51
51
  /** Outline colour (default graphite) */
52
52
  outline?: string;
53
+ /**
54
+ * Length of the forearm shown past the wrist, px before scaling (default 300).
55
+ * The sleeve fades out toward its end, so the arm never needs to reach the
56
+ * edge of the frame.
57
+ */
58
+ arm?: number;
59
+ /**
60
+ * 0 the tip is on the paper, 1 lifted: the hand rises off the page and a soft
61
+ * shadow marks the point below it (see {@link handAt}).
62
+ */
63
+ lift?: number;
53
64
  }
54
65
  /**
55
- * A hand holding a pencil or an eraser with the tool's tip at `at`, its arm
56
- * reaching in from off screen. Pass a pen to sketch it: the tools are outlined
57
- * in pencil strokes and the hand shifts with the boil.
66
+ * A right hand holding a pencil or an eraser with the tool's tip at `at`: the
67
+ * cartoon hand rig (`drawCartoonHand`) in its `pencilGrip` shape, the tool
68
+ * held between the thumb and fingers, and the forearm leaving toward the
69
+ * lower right with its sleeve fading out. Pass a pen to sketch the tool's
70
+ * outline; the hand shifts with the boil.
58
71
  */
59
72
  export declare function drawHand(ctx: CanvasRenderingContext2D, at: Point, style?: HandStyle, pen?: SketchPen): void;
73
+ /** One stroke the hand draws (or rubs out), timed in ms, for {@link handAt}. */
74
+ export interface HandStroke {
75
+ /** When the tip starts along the path, ms */
76
+ start: number;
77
+ /** When it reaches the end, ms */
78
+ end: number;
79
+ /** The stroke, in scene coordinates */
80
+ path: Point[];
81
+ /** What the hand holds for this stroke (default pencil) */
82
+ tool?: 'pencil' | 'eraser';
83
+ }
84
+ export interface HandMotionOptions {
85
+ /** Where the hand waits off the page, scene coordinates (default far lower right: 2000, 1400) */
86
+ offstage?: Point;
87
+ /** Time to come in from offstage before the first stroke of a run, ms (default 450) */
88
+ enter?: number;
89
+ /** Time to leave after the last stroke of a run, ms (default 450) */
90
+ exit?: number;
91
+ /** Strokes closer together than this (ms) are one run: the hand moves between them instead of leaving (default 1500) */
92
+ linger?: number;
93
+ }
94
+ /** Where the hand is at a moment: see {@link handAt}. */
95
+ export interface HandPosition {
96
+ /** The tool's tip, scene coordinates */
97
+ at: Point;
98
+ tool: 'pencil' | 'eraser';
99
+ /** 0 on the paper (drawing), 1 lifted (travelling); pass it to {@link drawHand} as `lift` */
100
+ lift: number;
101
+ /** Whether the tip is drawing a stroke right now */
102
+ drawing: boolean;
103
+ }
104
+ /**
105
+ * Where the animator's hand is at `time` (ms), given the strokes it draws.
106
+ * During a stroke the tip follows it. Between strokes of a run it lifts and
107
+ * glides from where one ended to where the next begins, eased in and out; it
108
+ * comes in from `offstage` before a run and goes back after one. Returns null
109
+ * while the hand is off the page. Pure: the same strokes and time always give
110
+ * the same answer, so a scene can be scrubbed.
111
+ */
112
+ export declare function handAt(strokes: HandStroke[], time: number, options?: HandMotionOptions): HandPosition | null;
60
113
  /** A circle as points, starting at the top and running a little past a full turn, to draw on. */
61
114
  export declare function circlePath(cx: number, cy: number, r: number, overshoot?: number, segments?: number): Point[];
62
115
  export interface DrawnPathOptions {
@@ -0,0 +1,39 @@
1
+ import type { Point } from '../../adapters/canvas/sketch';
2
+ import { type Look, type Pen, type PencilOptions } from '../look/pen';
3
+ import { type HandJoints, type HandPose, type HandRigStyle } from './hand-rig';
4
+ /**
5
+ * Drawing a posed hand: the palm and each finger are parts, drawn far to near
6
+ * through a {@link Pen}, so a hand matches any look (clean, pencil,
7
+ * silhouette) and boils with a pencil figure.
8
+ */
9
+ export interface CartoonHandStyle extends HandRigStyle {
10
+ /** Skin fill (default a warm tan); a glove is just another colour */
11
+ skin?: string;
12
+ /** Outline colour (default graphite) */
13
+ ink?: string;
14
+ /** Outline width, px (default 3.5% of the size) */
15
+ lineWidth?: number;
16
+ /** Look, when no `pen` is given (default clean) */
17
+ look?: Look;
18
+ /** Pencil wobble seed (default 1) */
19
+ seed?: number;
20
+ pencil?: PencilOptions;
21
+ /** Draw with this pen instead of making one: share a character's pen so the hand matches it */
22
+ pen?: Pen;
23
+ /** Nails on fingertips that face the viewer (default true) */
24
+ nails?: boolean;
25
+ /**
26
+ * Something held, drawn among the hand's parts at `depth` (px toward the
27
+ * viewer, the palm being about 0): a pencil between the thumb and fingers,
28
+ * a cup behind them. Drawn in the same space as the hand.
29
+ */
30
+ prop?: {
31
+ depth: number;
32
+ draw: (pen: Pen) => void;
33
+ };
34
+ }
35
+ /**
36
+ * Draw a hand in a pose with its wrist at `at`. `time` (ms) picks the
37
+ * pencil's boil frame. Returns the joints as drawn, for attaching props.
38
+ */
39
+ export declare function drawCartoonHand(ctx: CanvasRenderingContext2D, at: Point, pose: HandPose, style?: CartoonHandStyle, time?: number): HandJoints;
@@ -0,0 +1,116 @@
1
+ import type { Point } from '../../adapters/canvas/sketch';
2
+ import type { Vec3 } from '../rig/body-plan';
3
+ /**
4
+ * Cartoon hands: a palm and five fingers built in the hand's own 3D space,
5
+ * posed by a flat record of numbers, turned and drawn flat. Because the hand
6
+ * is 3D, turning the wrist (back, side, palm toward us) needs no extra
7
+ * drawing code, and fingers behind the palm are drawn behind it.
8
+ *
9
+ * Hand space, for a right hand, in units of the hand's length (wrist to the
10
+ * tip of the middle finger):
11
+ * - **+y** runs from the wrist toward the fingers,
12
+ * - **+x** toward the little finger (the thumb is on the -x side),
13
+ * - **+z** out of the back of the hand (the palm faces -z).
14
+ *
15
+ * At `turn` 0 the back of the hand faces the viewer with the fingers up; a
16
+ * left hand is the right hand mirrored on screen. Pure: the same pose and
17
+ * style always give the same points.
18
+ */
19
+ export type FingerName = 'thumb' | 'index' | 'middle' | 'ring' | 'pinky';
20
+ export declare const FINGERS: readonly FingerName[];
21
+ /**
22
+ * A hand pose: every field a number, so poses blend and each field can be a
23
+ * timeline track.
24
+ *
25
+ * | Field | Meaning |
26
+ * |---|---|
27
+ * | `index.curl` … `pinky.curl` | 0 straight, 1 curled into the palm |
28
+ * | `thumb.curl` | 0 straight, 1 bent at both knuckles |
29
+ * | `thumb.across` | 0 out to the side, 1 across the palm |
30
+ * | `spread` | 0 fingers together, 1 fanned wide |
31
+ * | `turn` | Wrist turn: 0 back of the hand toward the viewer, 1 thumb side, 2 palm, -1 little-finger side |
32
+ * | `bend` | Wrist bend, degrees: + toward the palm |
33
+ * | `tilt` | Wrist tilt, degrees: + toward the little finger |
34
+ * | `roll` | The whole hand turned in the picture, degrees clockwise (a left hand turns the mirror way) |
35
+ */
36
+ export type HandPose = Record<string, number>;
37
+ export declare const HAND_REST: HandPose;
38
+ /** A full hand pose from the fields that differ from rest. */
39
+ export declare function handPose(changes?: Partial<HandPose>): HandPose;
40
+ /** Ready-made hand shapes. Blend between them with {@link mixHandPoses}, or change single fields. */
41
+ export declare const HAND_SHAPES: {
42
+ relaxed: HandPose;
43
+ open: HandPose;
44
+ spread: HandPose;
45
+ flat: HandPose;
46
+ fist: HandPose;
47
+ point: HandPose;
48
+ /** The fist on its side, knuckles toward the viewer, the thumb up */
49
+ thumbsUp: HandPose;
50
+ peace: HandPose;
51
+ ok: HandPose;
52
+ pinch: HandPose;
53
+ cupped: HandPose;
54
+ wave: HandPose;
55
+ /** Holding a pencil to write: thumb and middle finger pinch it, the index finger rests on top */
56
+ pencilGrip: HandPose;
57
+ /** Holding a handle, a cup or a bar: every finger wrapped round it */
58
+ hold: HandPose;
59
+ };
60
+ export type HandShapeName = keyof typeof HAND_SHAPES;
61
+ /** A blend of two hand poses: `t` 0 is `from`, 1 is `to`. */
62
+ export declare function mixHandPoses(from: HandPose, to: HandPose, t: number): HandPose;
63
+ export interface HandRigStyle {
64
+ /** Wrist to the tip of the middle finger, px (default 100) */
65
+ size?: number;
66
+ /** Which hand (default right) */
67
+ side?: 'right' | 'left';
68
+ /** Which way the fingers point on screen, degrees clockwise from straight up (default 0) */
69
+ angle?: number;
70
+ /** Four fingers (a thumb and three, the classic cartoon hand) or five (default 5) */
71
+ fingers?: 4 | 5;
72
+ /** Chunkiness: 1 is a natural hand (default); 1.5 is a fat cartoon glove, its fingers and palm wider */
73
+ plump?: number;
74
+ }
75
+ /** One finger as drawn: joints from the knuckle (the thumb: its base in the palm) to the tip. */
76
+ export interface FingerJoints {
77
+ points: Point[];
78
+ /** Each joint's depth toward the viewer, px */
79
+ depths: number[];
80
+ /** Width of the finger at each joint, px */
81
+ widths: number[];
82
+ /** How squarely the nail faces the viewer: 1 straight on, 0 edge on, negative hidden */
83
+ nail: number;
84
+ /** The direction the back of the fingertip faces, on screen (unit, or zero when it faces the viewer) */
85
+ back: Point;
86
+ }
87
+ /** Where every part of a hand is, as drawn. */
88
+ export interface HandJoints {
89
+ size: number;
90
+ side: 'right' | 'left';
91
+ wrist: Point;
92
+ /** Outline of the palm (the back of the hand and its edges), around */
93
+ palm: Point[];
94
+ /** The palm's depth toward the viewer, px */
95
+ palmDepth: number;
96
+ /** How squarely the inside of the palm faces the viewer: 1 straight on, negative when the back does */
97
+ palmFacing: number;
98
+ fingers: Partial<Record<FingerName, FingerJoints>>;
99
+ /** The hand's own axes on screen (unit vectors): toward the fingers, toward the little finger, out of the back */
100
+ axes: {
101
+ up: Point;
102
+ across: Point;
103
+ out: Point;
104
+ };
105
+ /** Each finger's curl, as posed (the thumb's included) */
106
+ curls: Partial<Record<FingerName, number>>;
107
+ }
108
+ /** Turn `v` about the unit `axis` by `angle` radians, right-handed (Rodrigues). */
109
+ export declare function rotateAbout(v: Vec3, axis: Vec3, angle: number): Vec3;
110
+ /**
111
+ * Solve a hand pose: every finger's joints on screen, with depths, for a
112
+ * hand whose wrist is at (0, 0). Move the result with {@link handJointsAt}.
113
+ */
114
+ export declare function handJoints(pose: HandPose, style?: HandRigStyle): HandJoints;
115
+ /** Hand joints moved so the wrist is at `at`. */
116
+ export declare function handJointsAt(joints: HandJoints, at: Point): HandJoints;
@@ -0,0 +1,3 @@
1
+ /** Cartoon hands: a small 3D hand rig, posed by numbers, drawn through a look's pen. */
2
+ export * from './hand-rig';
3
+ export * from './draw-cartoon-hand';
@@ -14,3 +14,4 @@ export { humanPlan, humanPose, humanFieldLabel, HUMAN_REST, HUMAN_POSES, HUMAN_E
14
14
  export type { BodyPlan, ChainSpec, BoneSpec, BoneAngles, ContactSpec, HeadSpec, Pose as CharacterPose, Vec3 } from './rig/body-plan';
15
15
  export { createPen, ellipsePoints, type Pen, type Look, type PencilOptions, type PenOptions } from './look/pen';
16
16
  export { basicOutfit, type BasicOutfitOptions } from './wardrobe/basic-outfit';
17
+ export * from './hands';
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@algorisys/tinyfly",
3
- "version": "0.78.0",
3
+ "version": "0.79.0",
4
4
  "type": "module",
5
5
  "description": "Lightweight, API-driven animation engine and editor. The engine is framework-agnostic and runs in browsers, Web Workers, and Node.",
6
6
  "license": "MIT",