@versatiles/svg-renderer 2.0.0-rc.0 → 2.1.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.
Files changed (4) hide show
  1. package/README.md +60 -40
  2. package/dist/index.d.ts +492 -44
  3. package/dist/index.js +11803 -11371
  4. package/package.json +8 -4
package/README.md CHANGED
@@ -29,64 +29,78 @@ No native code. The only dependency is `@types/geojson` (types only). The packag
29
29
 
30
30
  ## Usage
31
31
 
32
- ### Node.js
33
-
34
32
  ```typescript
35
33
  import { renderToSVG } from '@versatiles/svg-renderer';
36
- import { inlineSources, osm } from '@versatiles/style';
37
- import { writeFile } from 'node:fs/promises';
38
-
39
- // inlineSources() resolves the style's TileJSON sources into tile URLs, which the
40
- // renderer needs. Without it, the map comes out empty.
41
- const style = await inlineSources(osm({ theme: 'colorful' }));
42
34
 
43
- const svg = await renderToSVG({
44
- style,
45
- width: 800,
46
- height: 600,
47
- lon: 13.4,
48
- lat: 52.5,
49
- zoom: 10,
50
- });
35
+ const url = 'https://tiles.versatiles.org/assets/styles/colorful/style.json';
36
+ const style = await (await fetch(url)).json();
51
37
 
52
- await writeFile('map.svg', svg);
38
+ const svg = await renderToSVG({ style, lon: 13.4, lat: 52.5, zoom: 10 });
53
39
  ```
54
40
 
41
+ The result is an SVG document as a string: write it to a file, or put it into a web page. This works the same in Node.js and in the browser. Without `width` and `height`, the image is 1024 × 1024 pixels.
42
+
55
43
  > [!IMPORTANT]
56
- > The style's sources must list their tile URLs directly (`"tiles": [...]`). A source that only points at a TileJSON document (`"url": ".../tiles.json"`) is **not fetched, and the map comes out empty without an error**. Styles built with `@versatiles/style` are in that form, so pass them through its `inlineSources()` as above. Hosted style files usually list their tiles already.
44
+ > The style's sources must list their tile URLs (`"tiles": [...]`). A source that only points at a TileJSON document (`"url": "…/tiles.json"`) renders as an **empty map, without an error**. Hosted styles like the one above list their tiles; a style built with `@versatiles/style` needs its `inlineSources()` first.
45
+
46
+ ### Many views of one style
57
47
 
58
- ### Browser
48
+ `renderToSVG` starts from scratch on every call. To render many views of one style, create an `SVGMapRenderer` once: it parses the style once and keeps the tiles it has fetched.
59
49
 
60
50
  ```typescript
61
- import { renderToSVG } from '@versatiles/svg-renderer';
51
+ import { SVGMapRenderer } from '@versatiles/svg-renderer';
62
52
 
63
- const style = await fetch('https://tiles.versatiles.org/assets/styles/colorful/style.json').then(
64
- (r) => r.json(),
65
- );
53
+ const map = new SVGMapRenderer({ style });
66
54
 
67
- document.body.innerHTML = await renderToSVG({
68
- style,
69
- width: 800,
70
- height: 600,
71
- lon: 13.4,
72
- lat: 52.5,
73
- zoom: 10,
74
- });
55
+ const berlin = await map.renderSVG({ lon: 13.4, lat: 52.52, zoom: 12 });
56
+ const potsdam = await map.renderSVG({ lon: 13.06, lat: 52.4, zoom: 12 });
75
57
  ```
76
58
 
77
59
  ## API
78
60
 
79
61
  ### `renderToSVG(options): Promise<string>`
80
62
 
81
- | Option | Type | Default | Description |
82
- | -------------- | -------------------- | ------------ | ----------------------------------------- |
83
- | `style` | `StyleSpecification` | _(required)_ | MapLibre style specification |
84
- | `width` | `number` | `1024` | Output width in pixels |
85
- | `height` | `number` | `1024` | Output height in pixels |
86
- | `lon` | `number` | `0` | Center longitude |
87
- | `lat` | `number` | `0` | Center latitude |
88
- | `zoom` | `number` | `2` | Zoom level |
89
- | `renderLabels` | `boolean` | `false` | Enable rendering of text labels and icons |
63
+ | Option | Type | Default | Description |
64
+ | -------------- | -------------------- | -------------- | -------------------------------------------------------------------------------------- |
65
+ | `style` | `StyleSpecification` | _(required)_ | MapLibre style specification |
66
+ | `width` | `number` | `1024` | Output width in pixels |
67
+ | `height` | `number` | `1024` | Output height in pixels |
68
+ | `lon` | `number` | `0` | Center longitude |
69
+ | `lat` | `number` | `0` | Center latitude |
70
+ | `zoom` | `number` | `2` | Zoom level |
71
+ | `renderLabels` | `boolean` | `false` | Enable rendering of text labels and icons |
72
+ | `fetch` | `FetchFunction` | global `fetch` | Loads tiles and sprites; see [Loading tiles your own way](#loading-tiles-your-own-way) |
73
+
74
+ ### `new SVGMapRenderer(options)`
75
+
76
+ Renders many views of one style. The options stay the same for every view:
77
+
78
+ | Option | Type | Default | Description |
79
+ | --------------- | -------------------- | -------------------- | ----------------------------------------------------------------------------------------- |
80
+ | `style` | `StyleSpecification` | _(required)_ | MapLibre style specification. Read once: to render a changed style, create a new instance |
81
+ | `renderLabels` | `boolean` | `false` | Enable rendering of text labels and icons |
82
+ | `tileCacheSize` | `number` | `134217728` (128 MB) | How much memory fetched tiles may take, in bytes. `0` keeps none |
83
+ | `fetch` | `FetchFunction` | global `fetch` | Loads tiles and sprites; see [Loading tiles your own way](#loading-tiles-your-own-way) |
84
+
85
+ - **`renderSVG(view?): Promise<string>`** renders one view. `view` takes `width`, `height`, `lon`, `lat` and `zoom`, with the same defaults as `renderToSVG`. Renders may run concurrently.
86
+ - **`project(view, [lon, lat]): [x, y] | undefined`** tells where a coordinate lands in the image of `view`, in the units of `width` and `height`, to place your own drawing on the map. On the globe, a point on the far side gives `undefined`.
87
+ - **`unproject(view, [x, y]): [lon, lat] | undefined`** is the opposite: the coordinate shown at a position in the image, e.g. where a user clicked. It gives `undefined` where the image shows no map: next to the globe, or beyond the poles of the mercator map (about ±85°).
88
+ - **`clearCache()`** forgets the fetched tiles and sprite, e.g. after they were updated on the server.
89
+
90
+ Tiles are kept for the lifetime of the instance, regardless of their HTTP caching headers; beyond `tileCacheSize`, the least recently used ones are dropped. A tile the server does not have (404) is remembered as missing; a failed request (network error, server error) is not, so the next render tries again.
91
+
92
+ ### Loading tiles your own way
93
+
94
+ Tiles and sprites are loaded with the global `fetch`, unless you pass your own function as `fetch`: `(url: string) => Promise<Response>`. Use it to send headers (an API key, say), go through a proxy, or keep tiles on disk between runs — see [Caching tiles on disk](https://github.com/versatiles-org/versatiles-svg-renderer/blob/main/packages/png-renderer/README.md#caching-tiles-on-disk) for an example in Node.js.
95
+
96
+ ```typescript
97
+ const map = new SVGMapRenderer({
98
+ style,
99
+ fetch: (url) => fetch(url, { headers: { Authorization: `Bearer ${token}` } }),
100
+ });
101
+ ```
102
+
103
+ It must return a real `Response`, and the status counts: a 404 or 204 means the server has no such tile, and the renderer remembers that; any other error status, or a rejected promise, counts as failed, so the next render tries again. The renderer only asks for tiles and sprites: a style's TileJSON sources are resolved beforehand, e.g. by `inlineSources()` of `@versatiles/style`, which uses its own requests.
90
104
 
91
105
  ### About `renderLabels`
92
106
 
@@ -104,6 +118,12 @@ The SVG names each label's font (`text-font`) and leaves resolving it to whateve
104
118
 
105
119
  The renderer follows the style's [`projection`](https://maplibre.org/maplibre-style-spec/projection/): `mercator` (the default), `vertical-perspective` and `globe`, which — like in MapLibre GL JS — shows the globe up to zoom 11 and blends into mercator between zoom 11 and 12. Zoom-dependent `step`/`interpolate` expressions are supported as well. On the globe, geometry is clipped at the horizon and the map is clipped to the globe's outline; everything outside of it stays transparent. Raster tiles are drawn as a mesh of small triangles, each mapped exactly onto the globe by its own affine transform.
106
120
 
121
+ ## Dependency Graph
122
+
123
+ <!--- This chapter is generated automatically --->
124
+
125
+ [![Dependency graph](https://raw.githubusercontent.com/versatiles-org/versatiles-svg-renderer/main/packages/svg-renderer/docs/dependency-graph.svg)](https://raw.githubusercontent.com/versatiles-org/versatiles-svg-renderer/main/packages/svg-renderer/docs/dependency-graph.svg)
126
+
107
127
  ## License
108
128
 
109
129
  MIT. Part of [VersaTiles](https://github.com/versatiles-org/versatiles-svg-renderer): source code, issues and the changelog are on GitHub.