@versatiles/svg-renderer 2.4.2 → 2.6.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 +38 -22
- package/dist/index.d.ts +185 -62
- package/dist/index.js +1068 -820
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -59,33 +59,35 @@ const potsdam = await map.renderSVG({ lon: 13.06, lat: 52.4, zoom: 12 });
|
|
|
59
59
|
|
|
60
60
|
### `renderToSVG(options): Promise<string>`
|
|
61
61
|
|
|
62
|
-
| Option | Type | Default | Description
|
|
63
|
-
| ------------- | ----------------------------------------------- | --------------------------- |
|
|
64
|
-
| `style` | `StyleSpecification` | _(required)_ | MapLibre style specification
|
|
65
|
-
| `width` | `number` | `1024` | Output width in pixels
|
|
66
|
-
| `height` | `number` | `1024` | Output height in pixels
|
|
67
|
-
| `lon` | `number` | style's `center`, else `0` | Center longitude
|
|
68
|
-
| `lat` | `number` | style's `center`, else `0` | Center latitude
|
|
69
|
-
| `zoom` | `number` | style's `zoom`, else `2` | Zoom level
|
|
70
|
-
| `bearing` | `number` | style's `bearing`, else `0` | Compass direction that is up, in degrees (`90`: east is up)
|
|
71
|
-
| `padding` | `number \| Padding` | `0` | Space around the center, in pixels: it sits in the middle of the area inside
|
|
72
|
-
| `labels` | `'none' \| 'text' \| 'glyphs' \| 'glyphs-text'` | `'none'` | Whether and how to draw labels and icons; see [About labels](#about-labels)
|
|
73
|
-
| `fetch` | `FetchFunction` | global `fetch` | Loads tiles and sprites; see [Loading tiles your own way](#loading-tiles-your-own-way)
|
|
74
|
-
| `onWarning` | `(message) => void` | `console.warn` | Reports parts of the style that are not drawn; see [Warnings](#warnings)
|
|
75
|
-
| `globalState` | `GlobalState` | style's `state` | Values for `global-state` expressions, over the style's defaults
|
|
62
|
+
| Option | Type | Default | Description |
|
|
63
|
+
| ------------- | ----------------------------------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------- |
|
|
64
|
+
| `style` | `StyleSpecification` | _(required)_ | MapLibre style specification |
|
|
65
|
+
| `width` | `number` | `1024` | Output width in pixels |
|
|
66
|
+
| `height` | `number` | `1024` | Output height in pixels |
|
|
67
|
+
| `lon` | `number` | style's `center`, else `0` | Center longitude |
|
|
68
|
+
| `lat` | `number` | style's `center`, else `0` | Center latitude |
|
|
69
|
+
| `zoom` | `number` | style's `zoom`, else `2` | Zoom level |
|
|
70
|
+
| `bearing` | `number` | style's `bearing`, else `0` | Compass direction that is up, in degrees (`90`: east is up) |
|
|
71
|
+
| `padding` | `number \| Padding` | `0` | Space around the center, in pixels: it sits in the middle of the area inside |
|
|
72
|
+
| `labels` | `'none' \| 'text' \| 'glyphs' \| 'glyphs-text'` | `'none'` | Whether and how to draw labels and icons; see [About labels](#about-labels) |
|
|
73
|
+
| `fetch` | `FetchFunction` | global `fetch` | Loads tiles and sprites; see [Loading tiles your own way](#loading-tiles-your-own-way) |
|
|
74
|
+
| `onWarning` | `(message) => void` | `console.warn` | Reports parts of the style that are not drawn; see [Warnings](#warnings) |
|
|
75
|
+
| `globalState` | `GlobalState` | style's `state` | Values for `global-state` expressions, over the style's defaults |
|
|
76
|
+
| `images` | `StyleImage[]` | none | Images besides the sprite's, like `map.addImage`; see [Images besides the sprite](#images-besides-the-sprite) |
|
|
76
77
|
|
|
77
78
|
### `new SVGMapRenderer(options)`
|
|
78
79
|
|
|
79
80
|
Renders many views of one style. The options stay the same for every view:
|
|
80
81
|
|
|
81
|
-
| Option | Type | Default | Description
|
|
82
|
-
| --------------- | ----------------------------------------------- | -------------------- |
|
|
83
|
-
| `style` | `StyleSpecification` | _(required)_ | MapLibre style specification. Read once: to render a changed style, create a new instance
|
|
84
|
-
| `labels` | `'none' \| 'text' \| 'glyphs' \| 'glyphs-text'` | `'none'` | Whether and how to draw labels and icons; see [About labels](#about-labels)
|
|
85
|
-
| `tileCacheSize` | `number` | `134217728` (128 MB) | How much memory fetched tiles may take, in bytes. `0` keeps none
|
|
86
|
-
| `fetch` | `FetchFunction` | global `fetch` | Loads tiles and sprites; see [Loading tiles your own way](#loading-tiles-your-own-way)
|
|
87
|
-
| `onWarning` | `(message) => void` | `console.warn` | Reports parts of the style that are not drawn; see [Warnings](#warnings)
|
|
88
|
-
| `globalState` | `GlobalState` | style's `state` | Values for `global-state` expressions, over the style's defaults
|
|
82
|
+
| Option | Type | Default | Description |
|
|
83
|
+
| --------------- | ----------------------------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------- |
|
|
84
|
+
| `style` | `StyleSpecification` | _(required)_ | MapLibre style specification. Read once: to render a changed style, create a new instance |
|
|
85
|
+
| `labels` | `'none' \| 'text' \| 'glyphs' \| 'glyphs-text'` | `'none'` | Whether and how to draw labels and icons; see [About labels](#about-labels) |
|
|
86
|
+
| `tileCacheSize` | `number` | `134217728` (128 MB) | How much memory fetched tiles may take, in bytes. `0` keeps none |
|
|
87
|
+
| `fetch` | `FetchFunction` | global `fetch` | Loads tiles and sprites; see [Loading tiles your own way](#loading-tiles-your-own-way) |
|
|
88
|
+
| `onWarning` | `(message) => void` | `console.warn` | Reports parts of the style that are not drawn; see [Warnings](#warnings) |
|
|
89
|
+
| `globalState` | `GlobalState` | style's `state` | Values for `global-state` expressions, over the style's defaults |
|
|
90
|
+
| `images` | `StyleImage[]` | none | Images besides the sprite's, like `map.addImage`; see [Images besides the sprite](#images-besides-the-sprite) |
|
|
89
91
|
|
|
90
92
|
- **`renderSVG(view?): Promise<string>`** renders one view. `view` takes `width`, `height`, `lon`, `lat`, `zoom`, `bearing` and `padding`, with the same defaults as `renderToSVG`. Renders may run concurrently.
|
|
91
93
|
- **`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`.
|
|
@@ -94,6 +96,20 @@ Renders many views of one style. The options stay the same for every view:
|
|
|
94
96
|
|
|
95
97
|
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.
|
|
96
98
|
|
|
99
|
+
### Images besides the sprite
|
|
100
|
+
|
|
101
|
+
A style may use images that its sprite does not have, which a map in the browser gets with `map.addImage`. Give them to the renderer as `images`, an array of `{ id, width, height, data, pixelRatio, sdf }`, the arguments of `map.addImage(id, { width, height, data }, { pixelRatio, sdf })`:
|
|
102
|
+
|
|
103
|
+
```typescript
|
|
104
|
+
const svg = await renderToSVG({
|
|
105
|
+
style,
|
|
106
|
+
images: [{ id: 'dot', width: 16, height: 16, data: rgba, pixelRatio: 2, sdf: true }],
|
|
107
|
+
labels: 'text',
|
|
108
|
+
});
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
`data` holds the pixels as RGBA, row by row, not premultiplied: `width * height * 4` bytes. The style names an image by its `id`, without a sprite id before it, in `icon-image`, `fill-pattern`, `line-pattern` or `background-pattern`. An SDF image is colored by `icon-color` and its halo, like an SDF image of the sprite. As `map.addImage` fails for an id that exists, an image of the sprite with the same id is drawn instead, reported through `onWarning`. In the SVG, each image is a data URI of a PNG file without compression.
|
|
112
|
+
|
|
97
113
|
### Loading tiles your own way
|
|
98
114
|
|
|
99
115
|
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.
|