@algorisys/tinyfly 0.76.0 → 0.78.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.
@@ -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;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@algorisys/tinyfly",
3
- "version": "0.76.0",
3
+ "version": "0.78.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",
@@ -101,6 +101,10 @@
101
101
  "types": "./lib/types/characters/index.d.ts",
102
102
  "import": "./lib/addons/characters.js"
103
103
  },
104
+ "./maps": {
105
+ "types": "./lib/types/maps/index.d.ts",
106
+ "import": "./lib/addons/maps.js"
107
+ },
104
108
  "./headless": {
105
109
  "types": "./lib/types/headless/index.d.ts",
106
110
  "import": "./lib/headless/headless.js"
@@ -133,7 +137,7 @@
133
137
  "test": "vitest",
134
138
  "test:run": "vitest run",
135
139
  "build:addons": "vite build --config vite.config.addons.ts",
136
- "build:browser": "vite build --config vite.config.browser.ts",
140
+ "build:browser": "vite build --config vite.config.browser.ts && vite build --config vite.config.browser-maps.ts",
137
141
  "prepublishOnly": "npm run test:run && npm run build:libs",
138
142
  "e2e": "node e2e/run.mjs",
139
143
  "release:oss": "./scripts/publish-oss.sh --push",