@versatiles/svg-renderer 2.5.0 → 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.
Files changed (4) hide show
  1. package/README.md +38 -22
  2. package/dist/index.d.ts +49 -1
  3. package/dist/index.js +966 -778
  4. 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.
package/dist/index.d.ts CHANGED
@@ -2279,6 +2279,15 @@ type RasterLayerSpecification = {
2279
2279
  */
2280
2280
  "raster-opacity"?: PropertyValueSpecification<number>;
2281
2281
  "raster-opacity-transition"?: TransitionSpecification;
2282
+ /**
2283
+ * Controls how the layer is composited with the content already rendered beneath it. Unlike [`raster-opacity`](#raster-opacity), which only fades the layer, this property determines how its colors interact with the existing map contents.
2284
+ *
2285
+ * @default
2286
+ * ```json
2287
+ * "normal"
2288
+ * ```
2289
+ */
2290
+ "raster-layer-blend"?: "normal" | "multiply" | "color" | "luminosity" | "plus-lighter" | "screen" | "overlay";
2282
2291
  /**
2283
2292
  * Rotates hues around the color wheel.
2284
2293
  */
@@ -3164,6 +3173,32 @@ interface FetchRequestInit {
3164
3173
  */
3165
3174
  type FetchFunction = (url: string, init?: FetchRequestInit) => Promise<FetchResponse>;
3166
3175
 
3176
+ /**
3177
+ * An image that the style uses besides those of its sprite, as MapLibre GL JS takes it with
3178
+ * `map.addImage(id, { width, height, data }, { pixelRatio, sdf })`.
3179
+ */
3180
+ interface StyleImage {
3181
+ /** The name that the style uses, e.g. in `icon-image` or `fill-pattern`. No sprite id is put before it. */
3182
+ id: string;
3183
+ /** Width in pixels. */
3184
+ width: number;
3185
+ /** Height in pixels. */
3186
+ height: number;
3187
+ /** The pixels as RGBA, row by row, not premultiplied: `width * height * 4` bytes. */
3188
+ data: Uint8Array | Uint8ClampedArray;
3189
+ /**
3190
+ * Image pixels per pixel of the map, e.g. `2` for an image drawn at half its size.
3191
+ * @defaultValue `1`
3192
+ */
3193
+ pixelRatio?: number;
3194
+ /**
3195
+ * Whether the image is a signed distance field, as a sprite image can be: only its alpha
3196
+ * channel counts, and `icon-color` and the icon halo color it.
3197
+ * @defaultValue `false`
3198
+ */
3199
+ sdf?: boolean;
3200
+ }
3201
+
3167
3202
  /** Options for {@link SVGMapRenderer}: what stays the same for every view of the map. */
3168
3203
  interface SVGMapRendererOptions {
3169
3204
  /**
@@ -3250,6 +3285,19 @@ interface SVGMapRendererOptions {
3250
3285
  * @defaultValue the defaults of the style's `state`
3251
3286
  */
3252
3287
  globalState?: GlobalState;
3288
+ /**
3289
+ * Images that the style uses besides those of its sprite, like `map.addImage(id, image,
3290
+ * { pixelRatio, sdf })` in MapLibre GL JS: for `icon-image`, `fill-pattern`, `line-pattern`
3291
+ * and `background-pattern`, by their `id`, which no sprite id is put before. An SDF image is
3292
+ * colored by `icon-color` and its halo, like one of the sprite.
3293
+ *
3294
+ * As in MapLibre GL JS, where `addImage` fails for an id that exists, an image of the sprite
3295
+ * with the same id is drawn instead, reported through
3296
+ * {@link SVGMapRendererOptions.onWarning}. In an SVG, each image is a data URI of a PNG file
3297
+ * without compression.
3298
+ * @defaultValue none
3299
+ */
3300
+ images?: readonly StyleImage[];
3253
3301
  }
3254
3302
  /** The view to render: size, centre and zoom. */
3255
3303
  interface ViewOptions {
@@ -3425,4 +3473,4 @@ interface RenderToSVGOptions extends Omit<SVGMapRendererOptions, 'tileCacheSize'
3425
3473
  declare function renderToSVG(options: RenderToSVGOptions): Promise<string>;
3426
3474
 
3427
3475
  export { SVGMapRenderer, renderToSVG };
3428
- export type { FetchFunction, FetchRequestInit, FetchResponse, GlobalState, RenderToSVGOptions, SVGMapRendererOptions, ViewOptions };
3476
+ export type { FetchFunction, FetchRequestInit, FetchResponse, GlobalState, RenderToSVGOptions, SVGMapRendererOptions, StyleImage, ViewOptions };