@versatiles/png-renderer 2.0.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 +72 -28
  2. package/dist/index.d.ts +597 -64
  3. package/dist/index.js +5135 -4600
  4. package/package.json +4 -1
package/README.md CHANGED
@@ -25,45 +25,61 @@ 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
+
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();
60
66
 
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.
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
+ 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.
81
+
82
+ ```typescript
67
83
  const png = await renderToPNG({
68
84
  style,
69
85
  lon: 13.4,
@@ -71,17 +87,19 @@ const png = await renderToPNG({
71
87
  zoom: 14,
72
88
  renderLabels: true,
73
89
  fonts: {
74
- noto_sans_regular: `${files}/noto-sans-latin-400-normal.woff2`,
75
- noto_sans_bold: `${files}/noto-sans-latin-700-normal.woff2`,
90
+ noto_sans_regular: 'fonts/NotoSans-Regular.ttf',
91
+ noto_sans_bold: 'fonts/NotoSans-Bold.ttf',
76
92
  },
77
93
  });
78
94
  ```
79
95
 
96
+ 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`.
97
+
80
98
  ## API
81
99
 
82
100
  ### `renderToPNG(options): Promise<Uint8Array>`
83
101
 
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:
102
+ 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`, `fetch`), plus:
85
103
 
86
104
  | Option | Type | Default | Description |
87
105
  | ------- | ------------------------ | ------- | ---------------------------------------------------------------------------------------------------- |
@@ -92,9 +110,29 @@ The result is typed as a `Uint8Array` so the package does not require Node's typ
92
110
 
93
111
  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).
94
112
 
95
- ### `renderToSVG(options): Promise<string>`
113
+ ### `new PNGMapRenderer(options)`
114
+
115
+ 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.
116
+
117
+ - **`renderPNG(view?): Promise<Uint8Array>`** renders one view as PNG. `view` takes `width`, `height`, `lon`, `lat`, `zoom` and `scale`, with the same defaults as `renderToPNG`.
118
+ - **`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).
119
+ - **`renderSVG(view?): Promise<string>`** renders one view as SVG, sharing the tiles and the sprite with the PNG renders.
120
+ - **`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).
121
+ - **`clearCache()`** forgets the fetched tiles and sprite, and the decoded images.
122
+
123
+ A font that cannot be loaded is reported by `renderPNG`, and the next `renderPNG` tries again.
96
124
 
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).
125
+ ### `renderToCanvas(options): Promise<Canvas>`
126
+
127
+ Takes the options of `renderToPNG` and returns the canvas instead of the PNG file, like `renderCanvas`.
128
+
129
+ ### TypeScript
130
+
131
+ 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`.
132
+
133
+ ### `renderToSVG(options): Promise<string>` and `new SVGMapRenderer(options)`
134
+
135
+ The same as in [`@versatiles/svg-renderer`](https://github.com/versatiles-org/versatiles-svg-renderer/blob/main/packages/svg-renderer/README.md#api).
98
136
 
99
137
  ## Platforms
100
138
 
@@ -114,6 +152,12 @@ This error means the binary for the platform was not installed. It names the pla
114
152
 
115
153
  `renderToSVG` keeps working in either case, because the binary is only loaded when a PNG is rendered.
116
154
 
155
+ ## Dependency Graph
156
+
157
+ <!--- This chapter is generated automatically --->
158
+
159
+ [![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)
160
+
117
161
  ## License
118
162
 
119
163
  MIT. Part of [VersaTiles](https://github.com/versatiles-org/versatiles-svg-renderer): source code, issues and the changelog are on GitHub.