@algorisys/tinyfly 0.77.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.
- package/README.md +9 -5
- package/lib/addons/characters.js +1139 -793
- package/lib/addons/maps.js +442 -0
- package/lib/browser/tinyfly-maps.iife.js +1 -0
- package/lib/browser/tinyfly.iife.js +4 -4
- package/lib/browser/tinyfly.js +2235 -1889
- package/lib/browser/tinyfly.umd.js +4 -4
- package/lib/types/characters/character.d.ts +19 -0
- package/lib/types/characters/hand.d.ts +57 -4
- package/lib/types/characters/hands/draw-cartoon-hand.d.ts +39 -0
- package/lib/types/characters/hands/hand-rig.d.ts +116 -0
- package/lib/types/characters/hands/index.d.ts +3 -0
- package/lib/types/characters/index.d.ts +1 -0
- package/lib/types/maps/cities.d.ts +13 -0
- package/lib/types/maps/index.d.ts +12 -0
- package/lib/types/maps/map-target.d.ts +125 -0
- package/lib/types/maps/projection.d.ts +66 -0
- package/lib/types/maps/tiles.d.ts +67 -0
- package/lib/types/maps/world-110m.d.ts +13 -0
- package/lib/types/maps/world.d.ts +53 -0
- package/package.json +6 -2
|
@@ -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
|
|
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
|
|
56
|
-
*
|
|
57
|
-
*
|
|
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;
|
|
@@ -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';
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Major world cities, for picking places without looking up coordinates.
|
|
3
|
+
* Longitude and latitude in degrees (city centres, to about 1 km).
|
|
4
|
+
*/
|
|
5
|
+
export interface City {
|
|
6
|
+
name: string;
|
|
7
|
+
country: string;
|
|
8
|
+
lon: number;
|
|
9
|
+
lat: number;
|
|
10
|
+
}
|
|
11
|
+
export declare const WORLD_CITIES: City[];
|
|
12
|
+
/** A city by name (case-insensitive). */
|
|
13
|
+
export declare function findCity(name: string): City | undefined;
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `@algorisys/tinyfly/maps`: animated maps for canvas scenes (browser or
|
|
3
|
+
* headless video). Web Mercator projection and camera helpers, an offline
|
|
4
|
+
* world outline (Natural Earth, public domain), raster tiles (OpenStreetMap or
|
|
5
|
+
* any {z}/{x}/{y} server), and a map target with places and routes whose view,
|
|
6
|
+
* pins and route drawing are timeline tracks.
|
|
7
|
+
*/
|
|
8
|
+
export * from './projection';
|
|
9
|
+
export * from './world';
|
|
10
|
+
export * from './tiles';
|
|
11
|
+
export * from './map-target';
|
|
12
|
+
export * from './cities';
|
|
@@ -0,0 +1,125 @@
|
|
|
1
|
+
import type { CustomTarget } from '../adapters/canvas';
|
|
2
|
+
import type { FrameInfo } from '../headless/video-scene';
|
|
3
|
+
import type { EasingType, Track } from '../engine/types';
|
|
4
|
+
import { type Point, type SketchStyle } from '../adapters/canvas/sketch';
|
|
5
|
+
import { type LonLat, type MapView } from './projection';
|
|
6
|
+
import { type WorldStyle } from './world';
|
|
7
|
+
import { type TileCache, type TileSource } from './tiles';
|
|
8
|
+
/**
|
|
9
|
+
* A map as a canvas target: a base map (the offline world outline, or raster
|
|
10
|
+
* tiles) with places and routes on it. Everything that moves is a number the
|
|
11
|
+
* timeline can animate:
|
|
12
|
+
*
|
|
13
|
+
* - `view.lon`, `view.lat`, `view.zoom`: the view (fly the camera with these).
|
|
14
|
+
* Named with a dot so they never clash with a CSS property (`zoom` is one)
|
|
15
|
+
* - `<place>.show`: 0..1, a pin drops in and its label fades up (default 1)
|
|
16
|
+
* - `<route>.draw`: 0..1, how much of a route is drawn (default 1)
|
|
17
|
+
* - `<route>.marker`: 0..1, where a marker travelling the route is; below 0 hides it (default -1)
|
|
18
|
+
*
|
|
19
|
+
* Places and routes are drawn through the same view as the base map, so they
|
|
20
|
+
* stay put on it as the view pans and zooms.
|
|
21
|
+
*/
|
|
22
|
+
export interface MapPlace {
|
|
23
|
+
id: string;
|
|
24
|
+
lon: number;
|
|
25
|
+
lat: number;
|
|
26
|
+
/** Text beside the pin (default none) */
|
|
27
|
+
label?: string;
|
|
28
|
+
/** Pin colour (default red) */
|
|
29
|
+
color?: string;
|
|
30
|
+
}
|
|
31
|
+
export interface MapRoute {
|
|
32
|
+
id: string;
|
|
33
|
+
/** Stops: place ids, or [lon, lat] points */
|
|
34
|
+
through: Array<string | LonLat>;
|
|
35
|
+
/**
|
|
36
|
+
* `arc` (default): a flight-path bow between stops; `great-circle`: the
|
|
37
|
+
* shortest way over the globe; `straight`: straight on the map
|
|
38
|
+
*/
|
|
39
|
+
shape?: 'arc' | 'great-circle' | 'straight';
|
|
40
|
+
/** Line colour and width (default dark red, 3 px) */
|
|
41
|
+
color?: string;
|
|
42
|
+
width?: number;
|
|
43
|
+
/** Dashed line (default false) */
|
|
44
|
+
dashed?: boolean;
|
|
45
|
+
/** The travelling marker: a dot, or an arrow that points along the route (default arrow) */
|
|
46
|
+
marker?: 'dot' | 'arrow';
|
|
47
|
+
}
|
|
48
|
+
export interface MapOptions {
|
|
49
|
+
/** Size of the map's box, px */
|
|
50
|
+
width: number;
|
|
51
|
+
height: number;
|
|
52
|
+
/** The view at the start; `lon`/`lat`/`zoom` tracks animate it */
|
|
53
|
+
view: {
|
|
54
|
+
lon: number;
|
|
55
|
+
lat: number;
|
|
56
|
+
zoom: number;
|
|
57
|
+
};
|
|
58
|
+
/** `outline` (default): the offline world map. `tiles`: raster tiles (needs `tiles` and `tileCache`) */
|
|
59
|
+
base?: 'outline' | 'tiles';
|
|
60
|
+
tiles?: TileSource;
|
|
61
|
+
tileCache?: TileCache;
|
|
62
|
+
/** The outline map's colours (and pencil borders) */
|
|
63
|
+
style?: WorldStyle;
|
|
64
|
+
places?: MapPlace[];
|
|
65
|
+
routes?: MapRoute[];
|
|
66
|
+
/** Draw routes in hand-drawn pencil strokes that boil (the outline borders follow `style.sketch`) */
|
|
67
|
+
sketch?: SketchStyle;
|
|
68
|
+
/** Label font (default 600 14px sans-serif) */
|
|
69
|
+
font?: string;
|
|
70
|
+
}
|
|
71
|
+
/** The props a map starts with: its view, every place shown, every route drawn, no markers. */
|
|
72
|
+
export declare function mapProps(options: MapOptions): Record<string, number>;
|
|
73
|
+
/** The view a map shows for these props. */
|
|
74
|
+
export declare function mapView(options: MapOptions, props: Record<string, number>): MapView;
|
|
75
|
+
/** A route's line in the map's box, through its stops, shaped as asked. */
|
|
76
|
+
export declare function routeLine(options: MapOptions, route: MapRoute, view: MapView): Point[];
|
|
77
|
+
/** Draw a map into the box (0, 0)–(width, height) for a set of props; `time` picks pencil boil frames. */
|
|
78
|
+
export declare function drawMap(ctx: CanvasRenderingContext2D, options: MapOptions, props: Record<string, number>, time?: number): void;
|
|
79
|
+
/** A `custom` target made by {@link mapTarget}. */
|
|
80
|
+
export interface MapTarget extends CustomTarget {
|
|
81
|
+
readonly map: MapOptions;
|
|
82
|
+
}
|
|
83
|
+
/**
|
|
84
|
+
* A `custom` canvas target that draws a map in the box at (x, y). Its props
|
|
85
|
+
* are the view (`view.lon`, `view.lat`, `view.zoom`) and each place's `.show`, each route's
|
|
86
|
+
* `.draw` and `.marker`, so timeline tracks fly the camera, drop pins and draw
|
|
87
|
+
* routes on.
|
|
88
|
+
*/
|
|
89
|
+
export declare function mapTarget(options: MapOptions & {
|
|
90
|
+
x: number;
|
|
91
|
+
y: number;
|
|
92
|
+
}): MapTarget;
|
|
93
|
+
/**
|
|
94
|
+
* A map target's view in a frame, and where a place is in the scene then:
|
|
95
|
+
* for immediate-mode drawing that stays on the map (a caption by a city).
|
|
96
|
+
* `id` is the target's key in the scene's `targets`.
|
|
97
|
+
*/
|
|
98
|
+
export declare function mapAt(target: CustomTarget, frame: Pick<FrameInfo, 'state'>, id: string): {
|
|
99
|
+
view: MapView;
|
|
100
|
+
point: (lon: number, lat: number) => Point;
|
|
101
|
+
};
|
|
102
|
+
/**
|
|
103
|
+
* How far along a route (0..1 of its drawn length) each of its stops is, so a
|
|
104
|
+
* pin can drop as the line reaches it. The same at any zoom.
|
|
105
|
+
*/
|
|
106
|
+
export declare function routeStops(options: MapOptions, routeId: string): number[];
|
|
107
|
+
/**
|
|
108
|
+
* Keyframe tracks for `view.lon`, `view.lat` and `view.zoom` that fly a map target's view
|
|
109
|
+
* from one place to another between `start` and `end` ms, pulling out in the
|
|
110
|
+
* middle when they are far apart (see `flyView`). The flight is sampled into
|
|
111
|
+
* `samples` keys, so the JSON is plain keyframes.
|
|
112
|
+
*/
|
|
113
|
+
export declare function mapFlyTracks(target: string, from: {
|
|
114
|
+
lon: number;
|
|
115
|
+
lat: number;
|
|
116
|
+
zoom: number;
|
|
117
|
+
}, to: {
|
|
118
|
+
lon: number;
|
|
119
|
+
lat: number;
|
|
120
|
+
zoom: number;
|
|
121
|
+
}, start: number, end: number, options?: {
|
|
122
|
+
samples?: number;
|
|
123
|
+
width?: number;
|
|
124
|
+
easing?: EasingType;
|
|
125
|
+
}): Track[];
|
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
import type { Point } from '../adapters/canvas/sketch';
|
|
2
|
+
/**
|
|
3
|
+
* Web Mercator, the projection web maps use (OpenStreetMap, Google, Mapbox):
|
|
4
|
+
* longitude and latitude to flat coordinates, so routes, pins and tiles line
|
|
5
|
+
* up. Pure arithmetic, so it runs anywhere and always gives the same numbers.
|
|
6
|
+
*
|
|
7
|
+
* World coordinates run 0..1 from the antimeridian eastward (x) and from the
|
|
8
|
+
* north edge of the map southward (y). At zoom z the world is 256 × 2^z px
|
|
9
|
+
* across, as in the standard tile scheme.
|
|
10
|
+
*/
|
|
11
|
+
/** Tile size in px, and the world's size at zoom 0. */
|
|
12
|
+
export declare const TILE_SIZE = 256;
|
|
13
|
+
/** Latitudes beyond this do not fit a square Mercator map. */
|
|
14
|
+
export declare const MAX_LATITUDE = 85.05112878;
|
|
15
|
+
export type LonLat = [lon: number, lat: number];
|
|
16
|
+
/** A view of the map: what is at the centre, the zoom, and the size of the window onto it (px). */
|
|
17
|
+
export interface MapView {
|
|
18
|
+
lon: number;
|
|
19
|
+
lat: number;
|
|
20
|
+
zoom: number;
|
|
21
|
+
width: number;
|
|
22
|
+
height: number;
|
|
23
|
+
}
|
|
24
|
+
/** Longitude and latitude (degrees) to world coordinates (0..1). */
|
|
25
|
+
export declare function lonLatToWorld(lon: number, lat: number): Point;
|
|
26
|
+
/** World coordinates (0..1) back to longitude and latitude. */
|
|
27
|
+
export declare function worldToLonLat(x: number, y: number): LonLat;
|
|
28
|
+
/** The world's width in px at a zoom. */
|
|
29
|
+
export declare const worldSize: (zoom: number) => number;
|
|
30
|
+
/** Where a place is in a view, px from the view's top-left corner. */
|
|
31
|
+
export declare function project(view: MapView, lon: number, lat: number): Point;
|
|
32
|
+
/** The place at a point in a view (px from its top-left corner). */
|
|
33
|
+
export declare function unproject(view: MapView, x: number, y: number): LonLat;
|
|
34
|
+
/**
|
|
35
|
+
* The centre and zoom that fit `places` in a window `width` × `height` px,
|
|
36
|
+
* with `padding` px to spare on every side. One place is shown at `maxZoom`.
|
|
37
|
+
*/
|
|
38
|
+
export declare function fitView(places: LonLat[], width: number, height: number, padding?: number, maxZoom?: number): {
|
|
39
|
+
lon: number;
|
|
40
|
+
lat: number;
|
|
41
|
+
zoom: number;
|
|
42
|
+
};
|
|
43
|
+
/**
|
|
44
|
+
* A view part way (`t` 0..1) along a flight from `from` to `to`: the centre
|
|
45
|
+
* slides across the world while the zoom eases between the two, pulling out
|
|
46
|
+
* in the middle far enough to keep both ends in sight when they are far
|
|
47
|
+
* apart (as map apps fly between places).
|
|
48
|
+
*/
|
|
49
|
+
export declare function flyView(from: {
|
|
50
|
+
lon: number;
|
|
51
|
+
lat: number;
|
|
52
|
+
zoom: number;
|
|
53
|
+
}, to: {
|
|
54
|
+
lon: number;
|
|
55
|
+
lat: number;
|
|
56
|
+
zoom: number;
|
|
57
|
+
}, t: number, width?: number): {
|
|
58
|
+
lon: number;
|
|
59
|
+
lat: number;
|
|
60
|
+
zoom: number;
|
|
61
|
+
};
|
|
62
|
+
/**
|
|
63
|
+
* Points along the great circle from one place to another (the shortest
|
|
64
|
+
* route over the globe, which a flight follows): curved on a flat map.
|
|
65
|
+
*/
|
|
66
|
+
export declare function greatCircle(from: LonLat, to: LonLat, samples?: number): LonLat[];
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
import { type MapView } from './projection';
|
|
2
|
+
/**
|
|
3
|
+
* Raster map tiles (OpenStreetMap, or any server using the standard
|
|
4
|
+
* {z}/{x}/{y} scheme) for a view.
|
|
5
|
+
*
|
|
6
|
+
* Loading images is the one part of the maps module that is not pure: tiles
|
|
7
|
+
* arrive over the network, later or not at all. Drawing never waits: a tile
|
|
8
|
+
* not loaded yet is drawn from a loaded parent tile (blurrier, but in place),
|
|
9
|
+
* or left as the background. To render frames that must be complete (video,
|
|
10
|
+
* stills), call `preloadTiles` for every view first.
|
|
11
|
+
*/
|
|
12
|
+
export interface TileSource {
|
|
13
|
+
/** URL template with {z}, {x}, {y} and optionally {s} (a subdomain) */
|
|
14
|
+
url: string;
|
|
15
|
+
/** Credit line drawn on the map; required by most tile servers' terms */
|
|
16
|
+
attribution: string;
|
|
17
|
+
/** Deepest zoom the server has (default 19) */
|
|
18
|
+
maxZoom?: number;
|
|
19
|
+
/** Values for {s} (default none) */
|
|
20
|
+
subdomains?: string[];
|
|
21
|
+
}
|
|
22
|
+
/**
|
|
23
|
+
* OpenStreetMap's standard tiles. Their use policy allows light use with
|
|
24
|
+
* attribution and forbids heavy use: for anything busy, point `url` at your
|
|
25
|
+
* own tile server or a commercial provider.
|
|
26
|
+
*/
|
|
27
|
+
export declare const OSM_TILES: TileSource;
|
|
28
|
+
/** Loads one tile image; return a promise of anything `drawImage` accepts. */
|
|
29
|
+
export type TileLoader = (url: string) => Promise<CanvasImageSource>;
|
|
30
|
+
/** A tile loader for browsers: an <img> with CORS on, so canvases stay exportable. */
|
|
31
|
+
export declare function browserTileLoader(): TileLoader;
|
|
32
|
+
/** Loaded tiles by URL, loading on first ask; the oldest are forgotten past `limit`. */
|
|
33
|
+
export declare class TileCache {
|
|
34
|
+
private readonly tiles;
|
|
35
|
+
/** Loads in flight, so a tile asked for twice is fetched once */
|
|
36
|
+
private readonly pending;
|
|
37
|
+
private readonly load;
|
|
38
|
+
private readonly limit;
|
|
39
|
+
constructor(load: TileLoader, limit?: number);
|
|
40
|
+
/** The tile if it has loaded; otherwise starts loading it and returns undefined. */
|
|
41
|
+
get(url: string): CanvasImageSource | undefined;
|
|
42
|
+
/** The tile if it has loaded, without starting a load. */
|
|
43
|
+
peek(url: string): CanvasImageSource | undefined;
|
|
44
|
+
/** Load every URL; resolves when all have arrived or failed. */
|
|
45
|
+
ready(urls: string[]): Promise<void>;
|
|
46
|
+
private fetch;
|
|
47
|
+
}
|
|
48
|
+
export interface TilePlacement {
|
|
49
|
+
url: string;
|
|
50
|
+
z: number;
|
|
51
|
+
x: number;
|
|
52
|
+
y: number;
|
|
53
|
+
/** Where the tile goes in the view, px */
|
|
54
|
+
left: number;
|
|
55
|
+
top: number;
|
|
56
|
+
size: number;
|
|
57
|
+
}
|
|
58
|
+
export declare function tileUrl(source: TileSource, z: number, x: number, y: number): string;
|
|
59
|
+
/** The tiles that cover a view, and where each one goes. */
|
|
60
|
+
export declare function tilesForView(view: MapView, source: TileSource): TilePlacement[];
|
|
61
|
+
/** Load every tile the views need (for rendering frames that must be complete). */
|
|
62
|
+
export declare function preloadTiles(cache: TileCache, source: TileSource, views: MapView[]): Promise<void>;
|
|
63
|
+
/**
|
|
64
|
+
* Draw the tiles for a view into the box (0, 0)–(width, height). Returns
|
|
65
|
+
* whether every tile was loaded (false while some are still arriving).
|
|
66
|
+
*/
|
|
67
|
+
export declare function drawTiles(ctx: CanvasRenderingContext2D, view: MapView, source: TileSource, cache: TileCache): boolean;
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* World country outlines, from Natural Earth 1:110m admin-0 countries (public
|
|
3
|
+
* domain, naturalearthdata.com). Generated by scripts/build-world-map.mjs; do
|
|
4
|
+
* not edit by hand.
|
|
5
|
+
*
|
|
6
|
+
* Each country is [name, ISO 3166-1 alpha-3 code, Natural Earth colour index
|
|
7
|
+
* 1..7 (neighbours differ), rings]. A ring is a flat list of longitude and
|
|
8
|
+
* latitude differences in hundredths of a degree, each from the previous point
|
|
9
|
+
* (the first from 0, 0). Rings are outer edges and holes; fill them even-odd.
|
|
10
|
+
*/
|
|
11
|
+
export type WorldCountryRecord = [name: string, iso: string, color: number, rings: number[][]];
|
|
12
|
+
export declare const WORLD_110M_SCALE = 100;
|
|
13
|
+
export declare const WORLD_110M: WorldCountryRecord[];
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
import type { Point } from '../adapters/canvas/sketch';
|
|
2
|
+
import { type SketchStyle } from '../adapters/canvas/sketch';
|
|
3
|
+
import { type LonLat, type MapView } from './projection';
|
|
4
|
+
/**
|
|
5
|
+
* The offline world map: country outlines from Natural Earth (public domain),
|
|
6
|
+
* drawn as vector shapes. It needs no network and no images, so it works the
|
|
7
|
+
* same in a browser, a Worker and headless video, and it can be drawn in pencil.
|
|
8
|
+
*/
|
|
9
|
+
export interface WorldCountry {
|
|
10
|
+
name: string;
|
|
11
|
+
/** ISO 3166-1 alpha-3 code ('IND', 'NPL', 'FRA'…) */
|
|
12
|
+
iso: string;
|
|
13
|
+
/** Natural Earth colour index 1..7: neighbouring countries differ */
|
|
14
|
+
color: number;
|
|
15
|
+
/** Outer edges and holes, as longitude/latitude points */
|
|
16
|
+
rings: LonLat[][];
|
|
17
|
+
/** Each ring in world coordinates (0..1), and its bounds, for quick drawing */
|
|
18
|
+
world: Array<{
|
|
19
|
+
points: Point[];
|
|
20
|
+
minX: number;
|
|
21
|
+
maxX: number;
|
|
22
|
+
minY: number;
|
|
23
|
+
maxY: number;
|
|
24
|
+
}>;
|
|
25
|
+
}
|
|
26
|
+
/** Every country of the offline world map (decoded once). */
|
|
27
|
+
export declare function worldCountries(): WorldCountry[];
|
|
28
|
+
/** A country by its ISO alpha-3 code or its name. */
|
|
29
|
+
export declare function findCountry(code: string): WorldCountry | undefined;
|
|
30
|
+
export interface WorldStyle {
|
|
31
|
+
/** Sea colour (default pale blue) */
|
|
32
|
+
sea?: string;
|
|
33
|
+
/** Land colour, or one colour per Natural Earth colour index 1..7 (default a soft cream) */
|
|
34
|
+
land?: string | string[];
|
|
35
|
+
/** Border colour and width (default a soft brown, 1 px) */
|
|
36
|
+
border?: string;
|
|
37
|
+
borderWidth?: number;
|
|
38
|
+
/** Countries to fill in their own colour, by ISO code or name */
|
|
39
|
+
highlight?: Record<string, string>;
|
|
40
|
+
/** Draw the borders in hand-drawn pencil strokes that boil */
|
|
41
|
+
sketch?: SketchStyle;
|
|
42
|
+
}
|
|
43
|
+
export declare const WORLD_STYLE_DEFAULTS: {
|
|
44
|
+
readonly sea: "#cfe6f2";
|
|
45
|
+
readonly land: "#f3ecd9";
|
|
46
|
+
readonly border: "#9c8a74";
|
|
47
|
+
readonly borderWidth: 1;
|
|
48
|
+
};
|
|
49
|
+
/**
|
|
50
|
+
* Draw the world outline for a view, into the box (0, 0)–(width, height).
|
|
51
|
+
* `time` picks the boil frame of a sketched border.
|
|
52
|
+
*/
|
|
53
|
+
export declare function drawWorld(ctx: CanvasRenderingContext2D, view: MapView, style?: WorldStyle, time?: number): void;
|