@versatiles/png-renderer 2.0.0 → 2.2.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 +82 -34
  2. package/dist/index.d.ts +796 -72
  3. package/dist/index.js +8192 -3756
  4. package/package.json +4 -1
package/README.md CHANGED
@@ -25,76 +25,118 @@ The package draws with [`@napi-rs/canvas`](https://www.npmjs.com/package/@napi-r
25
25
 
26
26
  ```typescript
27
27
  import { renderToPNG } from '@versatiles/png-renderer';
28
- import { inlineSources, osm } from '@versatiles/style';
29
28
  import { writeFile } from 'node:fs/promises';
30
29
 
31
- // inlineSources() resolves the style's TileJSON sources into tile URLs, which the
32
- // renderer needs. Without it, the map comes out empty.
33
- const style = await inlineSources(osm({ theme: 'colorful' }));
34
-
35
- const png = await renderToPNG({
36
- style,
37
- width: 800,
38
- height: 600,
39
- lon: 13.4,
40
- lat: 52.5,
41
- zoom: 10,
42
- scale: 2, // 1600 × 1200 pixels
43
- });
30
+ const url = 'https://tiles.versatiles.org/assets/styles/colorful/style.json';
31
+ const style = await (await fetch(url)).json();
44
32
 
33
+ const png = await renderToPNG({ style, lon: 13.4, lat: 52.5, zoom: 10 });
45
34
  await writeFile('map.png', png);
46
35
  ```
47
36
 
48
- The same style, view and options also work with `renderToSVG`, imported from this package:
37
+ Add `scale: 2` for twice the pixels, sharp on high-resolution screens. `renderToSVG` is exported by this package too and takes the same options. The style must list its tile URLs, as described for [`@versatiles/svg-renderer`](https://github.com/versatiles-org/versatiles-svg-renderer/blob/main/packages/svg-renderer/README.md#usage).
38
+
39
+ ### Many views of one style
40
+
41
+ `renderToPNG` starts from scratch on every call. To render many views of one style, create a `PNGMapRenderer` once: it parses the style once and keeps the tiles and images it has loaded — for PNG and SVG alike.
49
42
 
50
43
  ```typescript
51
- import { renderToSVG } from '@versatiles/png-renderer';
44
+ import { PNGMapRenderer } from '@versatiles/png-renderer';
45
+
46
+ const map = new PNGMapRenderer({ style });
52
47
 
53
- const svg = await renderToSVG({ style, width: 800, height: 600, lon: 13.4, lat: 52.5, zoom: 10 });
48
+ const berlin = await map.renderPNG({ lon: 13.4, lat: 52.52, zoom: 12 });
49
+ const potsdam = await map.renderPNG({ lon: 13.06, lat: 52.4, zoom: 12 });
50
+ const svg = await map.renderSVG({ lon: 13.4, lat: 52.52, zoom: 12 });
54
51
  ```
55
52
 
56
- > [!IMPORTANT]
57
- > 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.
53
+ ### Drawing on the map, or saving another format
58
54
 
59
- ### Labels in the style's own fonts
55
+ `renderCanvas` returns the canvas instead of a PNG file: a [`Canvas` of `@napi-rs/canvas`](https://github.com/Brooooooklyn/canvas). Draw on it, then encode it as WebP, JPEG, AVIF or PNG. `project` gives the position of a coordinate on it.
56
+
57
+ ```typescript
58
+ const view = { lon: 13.4, lat: 52.52, zoom: 12 };
59
+ const canvas = await map.renderCanvas(view);
60
60
 
61
- A style only _names_ its fonts (`"text-font": ["noto_sans_regular"]`). Map each name to a font file (TTF, OTF, WOFF or WOFF2) with `fonts`. A name left unmapped falls back to a font installed on the machine.
61
+ const [x, y] = map.project(view, [13.3777, 52.5163])!; // the Brandenburg Gate
62
+ const ctx = canvas.getContext('2d');
63
+ ctx.beginPath();
64
+ ctx.arc(x, y, 8, 0, 2 * Math.PI);
65
+ ctx.fill();
66
+
67
+ await writeFile('berlin.webp', await canvas.encode('webp'));
68
+ ```
69
+
70
+ ### Caching tiles on disk
71
+
72
+ To keep tiles between runs, pass a `fetch` that stores them on disk. [`examples/cached-fetch.ts`](https://github.com/versatiles-org/versatiles-svg-renderer/blob/main/packages/png-renderer/examples/cached-fetch.ts) is one, in about 25 lines:
62
73
 
63
74
  ```typescript
64
- // The VersaTiles styles use Noto Sans, e.g. from `npm install @fontsource/noto-sans`.
65
- const files = 'node_modules/@fontsource/noto-sans/files';
75
+ const map = new PNGMapRenderer({ style, fetch: cachedFetch });
76
+ ```
66
77
 
78
+ ### Labels in the style's own fonts
79
+
80
+ With `labels: 'glyphs'` (or `'glyphs-text'`), labels are drawn as the style's own glyphs, the letter shapes MapLibre GL JS draws, and need no font files.
81
+
82
+ With `labels: 'text'`, labels are drawn in fonts: a style only _names_ its fonts (`"text-font": ["noto_sans_regular"]`). Map each name to a font file (TTF, OTF, WOFF or WOFF2) with `fonts`; a name left unmapped falls back to a font installed on the machine.
83
+
84
+ ```typescript
67
85
  const png = await renderToPNG({
68
86
  style,
69
87
  lon: 13.4,
70
88
  lat: 52.5,
71
89
  zoom: 14,
72
- renderLabels: true,
90
+ labels: 'text',
73
91
  fonts: {
74
- noto_sans_regular: `${files}/noto-sans-latin-400-normal.woff2`,
75
- noto_sans_bold: `${files}/noto-sans-latin-700-normal.woff2`,
92
+ noto_sans_regular: 'fonts/NotoSans-Regular.ttf',
93
+ noto_sans_bold: 'fonts/NotoSans-Bold.ttf',
76
94
  },
77
95
  });
78
96
  ```
79
97
 
98
+ The VersaTiles styles use Noto Sans. One source is `npm install @fontsource/noto-sans`, whose font files are in `node_modules/@fontsource/noto-sans/files`.
99
+
80
100
  ## API
81
101
 
82
102
  ### `renderToPNG(options): Promise<Uint8Array>`
83
103
 
84
- Takes every option of [`renderToSVG`](https://github.com/versatiles-org/versatiles-svg-renderer/blob/main/packages/svg-renderer/README.md#api) (`style`, `width`, `height`, `lon`, `lat`, `zoom`, `renderLabels`), plus:
104
+ Takes every option of [`renderToSVG`](https://github.com/versatiles-org/versatiles-svg-renderer/blob/main/packages/svg-renderer/README.md#api) (`style`, `width`, `height`, `lon`, `lat`, `zoom`, `labels`, `fetch` and more), plus:
85
105
 
86
- | Option | Type | Default | Description |
87
- | ------- | ------------------------ | ------- | ---------------------------------------------------------------------------------------------------- |
88
- | `scale` | `number` | `1` | Pixel density: the image is `width × scale` by `height × scale` pixels. Use `2` for sharp output. |
89
- | `fonts` | `Record<string, string>` | — | Font files for labels, by the `text-font` name the style uses: `{ noto_sans_regular: 'path.woff2' }` |
106
+ | Option | Type | Default | Description |
107
+ | ------- | ------------------------ | ------- | -------------------------------------------------------------------------------------------------------------------------- |
108
+ | `scale` | `number` | `1` | Pixel density: the image is `width × scale` by `height × scale` pixels. Use `2` for sharp output. |
109
+ | `fonts` | `Record<string, string>` | — | Font files for labels with `labels: 'text'`, by the `text-font` name the style uses: `{ noto_sans_regular: 'path.woff2' }` |
90
110
 
91
111
  The result is typed as a `Uint8Array` so the package does not require Node's type definitions; at runtime it is a `Buffer` and can be written with `fs.writeFile` as is.
92
112
 
93
- Label rendering has the same limitations as in SVG output: [see `renderLabels`](https://github.com/versatiles-org/versatiles-svg-renderer/blob/main/packages/svg-renderer/README.md#about-renderlabels).
113
+ Label rendering has the same limitations as in SVG output: [see "About labels"](https://github.com/versatiles-org/versatiles-svg-renderer/blob/main/packages/svg-renderer/README.md#about-labels). With `'glyphs'`, PNG and SVG show the same letter shapes; `'glyphs-text'` draws as `'glyphs'`, since a PNG has no text.
114
+
115
+ Which MapLibre GL JS features are covered, and which are not yet: [MapLibre GL JS Coverage](https://github.com/versatiles-org/versatiles-svg-renderer#maplibre-gl-js-coverage).
116
+
117
+ ### `new PNGMapRenderer(options)`
118
+
119
+ An [`SVGMapRenderer`](https://github.com/versatiles-org/versatiles-svg-renderer/blob/main/packages/svg-renderer/README.md#new-svgmaprendereroptions) that can also render PNG. It takes the options of `SVGMapRenderer` (`style`, `renderLabels`, `tileCacheSize`, `fetch`), plus `fonts` as above.
120
+
121
+ - **`renderPNG(view?): Promise<Uint8Array>`** renders one view as PNG. `view` takes `width`, `height`, `lon`, `lat`, `zoom` and `scale`, with the same defaults as `renderToPNG`.
122
+ - **`renderCanvas(view?): Promise<Canvas>`** renders one view onto a canvas, to draw on or to encode in another format; see [above](#drawing-on-the-map-or-saving-another-format).
123
+ - **`renderSVG(view?): Promise<string>`** renders one view as SVG, sharing the tiles and the sprite with the PNG renders.
124
+ - **`project(view, [lon, lat])`** and **`unproject(view, [x, y])`** convert between coordinates and positions in the image of `view`, as on [`SVGMapRenderer`](https://github.com/versatiles-org/versatiles-svg-renderer/blob/main/packages/svg-renderer/README.md#new-svgmaprendereroptions).
125
+ - **`clearCache()`** forgets the fetched tiles and sprite, and the decoded images.
94
126
 
95
- ### `renderToSVG(options): Promise<string>`
127
+ A font that cannot be loaded is reported by `renderPNG`, and the next `renderPNG` tries again.
96
128
 
97
- The same function as in [`@versatiles/svg-renderer`](https://github.com/versatiles-org/versatiles-svg-renderer/blob/main/packages/svg-renderer/README.md#api).
129
+ ### `renderToCanvas(options): Promise<Canvas>`
130
+
131
+ Takes the options of `renderToPNG` and returns the canvas instead of the PNG file, like `renderCanvas`.
132
+
133
+ ### TypeScript
134
+
135
+ The types of `renderCanvas` and `renderToCanvas` are those of `@napi-rs/canvas`, which use Node's types (`Buffer`, for one). A TypeScript project using this package therefore needs `@types/node`, as most Node.js projects have anyway, or `skipLibCheck`.
136
+
137
+ ### `renderToSVG(options): Promise<string>` and `new SVGMapRenderer(options)`
138
+
139
+ The same as in [`@versatiles/svg-renderer`](https://github.com/versatiles-org/versatiles-svg-renderer/blob/main/packages/svg-renderer/README.md#api).
98
140
 
99
141
  ## Platforms
100
142
 
@@ -114,6 +156,12 @@ This error means the binary for the platform was not installed. It names the pla
114
156
 
115
157
  `renderToSVG` keeps working in either case, because the binary is only loaded when a PNG is rendered.
116
158
 
159
+ ## Dependency Graph
160
+
161
+ <!--- This chapter is generated automatically --->
162
+
163
+ [![Dependency graph](https://raw.githubusercontent.com/versatiles-org/versatiles-svg-renderer/main/packages/png-renderer/docs/dependency-graph.svg)](https://raw.githubusercontent.com/versatiles-org/versatiles-svg-renderer/main/packages/png-renderer/docs/dependency-graph.svg)
164
+
117
165
  ## License
118
166
 
119
167
  MIT. Part of [VersaTiles](https://github.com/versatiles-org/versatiles-svg-renderer): source code, issues and the changelog are on GitHub.