@versatiles/svg-renderer 1.1.0 → 2.0.0-rc.0

package/README.md

@@ -1,36 +1,47 @@
-[![NPM version](https://img.shields.io/npm/v/%40versatiles%2Fsvg-renderer)](https://www.npmjs.com/package/@versatiles/svg-renderer)
-[![NPM downloads](https://img.shields.io/npm/dt/%40versatiles%2Fsvg-renderer)](https://www.npmjs.com/package/@versatiles/svg-renderer)
-[![Code coverage](https://codecov.io/gh/versatiles-org/versatiles-svg-renderer/branch/main/graph/badge.svg)](https://codecov.io/gh/versatiles-org/versatiles-svg-renderer)
+[![npm](https://img.shields.io/npm/v/%40versatiles%2Fsvg-renderer)](https://www.npmjs.com/package/@versatiles/svg-renderer)
 [![CI status](https://img.shields.io/github/actions/workflow/status/versatiles-org/versatiles-svg-renderer/ci.yml)](https://github.com/versatiles-org/versatiles-svg-renderer/actions/workflows/ci.yml)
-[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+[![License](https://img.shields.io/badge/license-MIT-green)](https://github.com/versatiles-org/versatiles-svg-renderer/blob/main/LICENSE)
 
-# VersaTiles SVG Renderer
+# @versatiles/svg-renderer
 
-Renders vector maps as SVG.
+Renders MapLibre styles as SVG, in Node.js or the browser.
 
-![Example: rendered map view](docs/demo.svg)
+The result is a single self-contained SVG document: vector layers become paths, raster tiles and icons are embedded, and nothing refers to external files. It can be saved, inlined into HTML or edited in a vector editor.
 
-[Download SVG](docs/demo.svg)
+![Example: rendered map view](https://raw.githubusercontent.com/versatiles-org/versatiles-svg-renderer/main/docs/demo.svg)
 
 Supported layer types: background, fill, line, circle, symbol, and raster.
 
+**[API documentation](https://versatiles.org/versatiles-svg-renderer/doc-typescript/)** · **[Visual comparison with MapLibre](https://versatiles.org/versatiles-svg-renderer/e2e/report.html)**
+
+> [!TIP]
+> **Need PNG output?** Use [`@versatiles/png-renderer`](https://www.npmjs.com/package/@versatiles/png-renderer). It renders PNG in Node.js and includes this package's `renderToSVG` as well.
+>
+> **Want an "export as SVG" button on a MapLibre map?** Use [`@versatiles/maplibre-svg-export`](https://www.npmjs.com/package/@versatiles/maplibre-svg-export).
+
 ## Installation
 
 ```bash
 npm install @versatiles/svg-renderer
 ```
 
+No native code. The only dependency is `@types/geojson` (types only). The package is ESM; Node.js 22 or later, or any modern bundler.
+
 ## Usage
 
 ### Node.js
 
 ```typescript
 import { renderToSVG } from '@versatiles/svg-renderer';
-import { styles } from '@versatiles/style';
-import { writeFileSync } from 'node:fs';
+import { inlineSources, osm } from '@versatiles/style';
+import { writeFile } from 'node:fs/promises';
+
+// inlineSources() resolves the style's TileJSON sources into tile URLs, which the
+// renderer needs. Without it, the map comes out empty.
+const style = await inlineSources(osm({ theme: 'colorful' }));
 
 const svg = await renderToSVG({
-	style: styles.colorful(),
+	style,
 	width: 800,
 	height: 600,
 	lon: 13.4,
@@ -38,74 +49,29 @@ const svg = await renderToSVG({
 	zoom: 10,
 });
 
-writeFileSync('map.svg', svg);
+await writeFile('map.svg', svg);
 ```
 
+> [!IMPORTANT]
+> 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.
+
 ### Browser
 
 ```typescript
 import { renderToSVG } from '@versatiles/svg-renderer';
 
-const svg = await renderToSVG({
-	style: await fetch('https://tiles.versatiles.org/assets/styles/colorful/style.json').then((r) =>
-		r.json(),
-	),
+const style = await fetch('https://tiles.versatiles.org/assets/styles/colorful/style.json').then(
+	(r) => r.json(),
+);
+
+document.body.innerHTML = await renderToSVG({
+	style,
 	width: 800,
 	height: 600,
 	lon: 13.4,
 	lat: 52.5,
 	zoom: 10,
 });
-
-document.body.innerHTML = svg;
-```
-
-### MapLibre Plugin
-
-The package includes an `SVGExportControl` that adds an export button to any MapLibre GL JS map.
-
-With a bundler, import it from the `/maplibre` subpath:
-
-```typescript
-import { SVGExportControl } from '@versatiles/svg-renderer/maplibre';
-
-map.addControl(new SVGExportControl(), 'top-right');
-```
-
-Or load it directly in the browser via the UMD bundle, which exposes a `VersaTilesSVG` global:
-
-```html
-<!DOCTYPE html>
-<html>
-	<head>
-		<link rel="stylesheet" href="https://unpkg.com/maplibre-gl@5/dist/maplibre-gl.css" />
-		<script src="https://unpkg.com/maplibre-gl@5/dist/maplibre-gl.js"></script>
-		<script src="https://unpkg.com/@versatiles/svg-renderer/dist/maplibre-svg-export.umd.js"></script>
-	</head>
-	<body>
-		<div id="map"></div>
-		<script>
-			const map = new maplibregl.Map({
-				container: 'map',
-				style: 'https://tiles.versatiles.org/assets/styles/colorful/style.json',
-				center: [13.4, 52.5],
-				zoom: 10,
-			});
-			map.addControl(new VersaTilesSVG.SVGExportControl(), 'top-right');
-		</script>
-	</body>
-</html>
-```
-
-The control opens a panel where the user can set width and height, preview the SVG, download it, or open it in a new tab. Map interactions are disabled while the panel is open.
-
-Options:
-
-```typescript
-new SVGExportControl({
-	defaultWidth: 1024, // default: 1024
-	defaultHeight: 1024, // default: 1024
-});
 ```
 
 ## API
@@ -114,7 +80,7 @@ new SVGExportControl({
 
 | Option         | Type                 | Default      | Description                               |
 | -------------- | -------------------- | ------------ | ----------------------------------------- |
-| `style`        | `StyleSpecification` | *(required)* | MapLibre style specification              |
+| `style`        | `StyleSpecification` | _(required)_ | MapLibre style specification              |
 | `width`        | `number`             | `1024`       | Output width in pixels                    |
 | `height`       | `number`             | `1024`       | Output height in pixels                   |
 | `lon`          | `number`             | `0`          | Center longitude                          |
@@ -126,82 +92,18 @@ new SVGExportControl({
 
 When `renderLabels` is set to `true`, symbol layers are rendered, including text labels and sprite-based icons. By default, this option is disabled.
 
+The SVG names each label's font (`text-font`) and leaves resolving it to whatever displays the SVG, so labels use the intended typeface only where that font is installed or provided with `@font-face`.
+
 > [!WARNING]
 > The rendering of labels and icons is experimental and may produce imperfect results. Since we cannot use the original layouting engine of MapLibre GL JS, there are known limitations:
 >
 > - **No collision detection:** Text labels are rendered without collision detection, so labels may overlap.
 > - **Simplified text placement:** Labels can not be positioned along lines.
 
-## E2E Visual Comparison
-
-A visual comparison report between the SVG renderer and MapLibre GL JS is published to GitHub Pages:
-
-[View Report](https://versatiles-org.github.io/versatiles-svg-renderer/report.html)
-
-## Dependency Graph
-
-<!--- This chapter is generated automatically --->
-
-```mermaid
----
-config:
-  layout: elk
----
-flowchart TB
-
-subgraph 0["src"]
-1["demo.ts"]
-2["index.ts"]
-subgraph 3["pipeline"]
-4["render.ts"]
-E["style_layer.ts"]
-end
-subgraph 5["sources"]
-6["index.ts"]
-7["geojson.ts"]
-9["raster.ts"]
-A["base64.ts"]
-B["tiles.ts"]
-C["sprite.ts"]
-D["vector.ts"]
-end
-8["geometry.ts"]
-subgraph F["renderer"]
-G["svg.ts"]
-H["color.ts"]
-I["svg_path.ts"]
-N["types.ts"]
-end
-subgraph J["maplibre"]
-K["control.ts"]
-L["panel_css.ts"]
-M["index.ts"]
-end
-end
-1-->2
-2-->4
-2-->G
-4-->6
-4-->C
-4-->E
-6-->7
-6-->9
-6-->C
-6-->D
-7-->8
-9-->A
-9-->B
-B-->8
-C-->A
-D-->8
-D-->B
-G-->H
-G-->I
-K-->2
-K-->L
-M-->2
-M-->K
-
-class 0,3,5,F,J subgraphs;
-classDef subgraphs fill-opacity:0.1, fill:#888, color:#888, stroke:#888;
-```
+### Projections
+
+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.
+
+## License
+
+MIT. Part of [VersaTiles](https://github.com/versatiles-org/versatiles-svg-renderer): source code, issues and the changelog are on GitHub.