@versatiles/svg-renderer 1.2.0 → 2.0.0

package/dist/index.js

@@ -8014,6 +8014,10 @@ class Color {
     get rgb() {
         return `#${d2h(this.values[0])}${d2h(this.values[1])}${d2h(this.values[2])}`;
     }
+    /** The red, green and blue components as bytes, for painting pixels directly. */
+    get rgbBytes() {
+        return [this.values[0], this.values[1], this.values[2]];
+    }
     get opacity() {
         return this.values[3] / 255;
     }
@@ -8232,6 +8236,133 @@ function formatNum(tenths) {
     return (negative ? '-' : '') + String(whole) + '.' + String(frac);
 }
 
+/**
+ * Where a symbol sits relative to its point, shared by every backend so the two cannot
+ * drift apart. The text vocabulary is SVG's (`text-anchor` / `dominant-baseline`); the
+ * canvas backend translates it to `textAlign` / `textBaseline`.
+ */
+function mapTextAnchor(anchor) {
+    switch (anchor) {
+        case 'left':
+            return ['start', 'central'];
+        case 'right':
+            return ['end', 'central'];
+        case 'top':
+            return ['middle', 'text-before-edge'];
+        case 'bottom':
+            return ['middle', 'text-after-edge'];
+        case 'top-left':
+            return ['start', 'text-before-edge'];
+        case 'top-right':
+            return ['end', 'text-before-edge'];
+        case 'bottom-left':
+            return ['start', 'text-after-edge'];
+        case 'bottom-right':
+            return ['end', 'text-after-edge'];
+        default:
+            return ['middle', 'central'];
+    }
+}
+function mapIconAnchor(anchor, w, h) {
+    switch (anchor) {
+        case 'left':
+            return [0, -h / 2];
+        case 'right':
+            return [-w, -h / 2];
+        case 'top':
+            return [-w / 2, 0];
+        case 'bottom':
+            return [-w / 2, -h];
+        case 'top-left':
+            return [0, 0];
+        case 'top-right':
+            return [-w, 0];
+        case 'bottom-left':
+            return [0, -h];
+        case 'bottom-right':
+            return [-w, -h];
+        default:
+            return [-w / 2, -h / 2];
+    }
+}
+
+/** Size of a raster tile image in user units, when drawn as a mesh of triangles on the globe. */
+const RASTER_TILE_UNITS = 256;
+/** How far (pixels) a raster tile image reaches beyond the tile border in the seam underlay. */
+const RASTER_TILE_BLEED_PX = 1;
+/** How far (pixels) each raster triangle is grown beyond its edges to overlap its neighbours. */
+const RASTER_TRIANGLE_OVERLAP_PX = 0.5;
+/**
+ * The affine transform [a, b, c, d, e, f] mapping the source triangle (in tile units 0..1,
+ * scaled to RASTER_TILE_UNITS) exactly onto the target triangle, or undefined if either is
+ * degenerate.
+ */
+function affineFromTriangles(source, target) {
+    const k = RASTER_TILE_UNITS;
+    const [[u0, v0], [u1, v1], [u2, v2]] = source.map(([u, v]) => [u * k, v * k]);
+    const [[x0, y0], [x1, y1], [x2, y2]] = target;
+    const du1 = u1 - u0;
+    const dv1 = v1 - v0;
+    const du2 = u2 - u0;
+    const dv2 = v2 - v0;
+    const det = du1 * dv2 - du2 * dv1;
+    if (Math.abs(det) < 1e-12)
+        return undefined;
+    const dx1 = x1 - x0;
+    const dx2 = x2 - x0;
+    const dy1 = y1 - y0;
+    const dy2 = y2 - y0;
+    // Screen area below a hundredth of a pixel: nothing to draw.
+    if (Math.abs(dx1 * dy2 - dx2 * dy1) < 0.02)
+        return undefined;
+    const a = (dx1 * dv2 - dx2 * dv1) / det;
+    const c = (du1 * dx2 - du2 * dx1) / det;
+    const b = (dy1 * dv2 - dy2 * dv1) / det;
+    const d = (du1 * dy2 - du2 * dy1) / det;
+    return [a, b, c, d, x0 - a * u0 - c * v0, y0 - b * u0 - d * v0];
+}
+function isOnTileBorder(source) {
+    return source.some(([u, v]) => u === 0 || u === 1 || v === 0 || v === 1);
+}
+/**
+ * Moves the source corners of a triangle that lie on the tile border inwards, by the
+ * equivalent of RASTER_TILE_BLEED_PX on screen, so that the image edge lies beyond the border.
+ * (Used for the underlay that closes the seams between tiles, see `#drawRasterMeshes`.)
+ */
+function bleedAtTileBorder(source, target) {
+    const [[u0, v0], [u1, v1], [u2, v2]] = source;
+    const [[x0, y0], [x1, y1], [x2, y2]] = target;
+    const sourceArea = Math.abs((u1 - u0) * (v2 - v0) - (u2 - u0) * (v1 - v0));
+    const targetArea = Math.abs((x1 - x0) * (y2 - y0) - (x2 - x0) * (y1 - y0));
+    if (sourceArea === 0 || targetArea === 0)
+        return source;
+    // Pixels per tile unit, and the bleed in tile units, kept within the triangle.
+    const scale = Math.sqrt(targetArea / sourceArea);
+    const size = Math.max(Math.abs(u1 - u0), Math.abs(u2 - u0), Math.abs(v1 - v0), Math.abs(v2 - v0));
+    const bleed = Math.min(RASTER_TILE_BLEED_PX / scale, size / 4);
+    const inset = (t) => (t === 0 ? bleed : t === 1 ? 1 - bleed : t);
+    return source.map(([u, v]) => [inset(u), inset(v)]);
+}
+/**
+ * Moves every edge of a triangle outwards by `distance`, by scaling it around its incenter.
+ * Growth is limited for very thin triangles, whose corners would otherwise shoot far out.
+ */
+function growTriangle(triangle, distance) {
+    const [[x0, y0], [x1, y1], [x2, y2]] = triangle;
+    const a = Math.hypot(x2 - x1, y2 - y1);
+    const b = Math.hypot(x2 - x0, y2 - y0);
+    const c = Math.hypot(x1 - x0, y1 - y0);
+    const perimeter = a + b + c;
+    const area = Math.abs((x1 - x0) * (y2 - y0) - (x2 - x0) * (y1 - y0)) / 2;
+    if (perimeter === 0 || area === 0)
+        return triangle;
+    const inradius = (2 * area) / perimeter;
+    const cx = (a * x0 + b * x1 + c * x2) / perimeter;
+    const cy = (a * y0 + b * y1 + c * y2) / perimeter;
+    const scale = 1 + distance / Math.max(inradius, 2 * distance);
+    return triangle.map(([x, y]) => [cx + (x - cx) * scale, cy + (y - cy) * scale]);
+}
+
 // line-blur approximates MapLibre's edge-feather blur, which keeps an opaque core
 // and feathers over ~`blur` px with a hard cutoff. feGaussianBlur alone conserves
 // total ink and leaves soft, infinite tails, so we combine three corrections,
@@ -8805,82 +8936,6 @@ function strokeAttr(color, width) {
 function formatScaled(v) {
     return formatNum(Math.round(v * 10));
 }
-/** Size of a raster tile image in user units, when drawn as a mesh of triangles on the globe. */
-const RASTER_TILE_UNITS = 256;
-/** How far (pixels) a raster tile image reaches beyond the tile border in the seam underlay. */
-const RASTER_TILE_BLEED_PX = 1;
-/** How far (pixels) each raster triangle is grown beyond its edges to overlap its neighbours. */
-const RASTER_TRIANGLE_OVERLAP_PX = 0.5;
-/**
- * The affine transform [a, b, c, d, e, f] mapping the source triangle (in tile units 0..1,
- * scaled to RASTER_TILE_UNITS) exactly onto the target triangle, or undefined if either is
- * degenerate.
- */
-function affineFromTriangles(source, target) {
-    const k = RASTER_TILE_UNITS;
-    const [[u0, v0], [u1, v1], [u2, v2]] = source.map(([u, v]) => [u * k, v * k]);
-    const [[x0, y0], [x1, y1], [x2, y2]] = target;
-    const du1 = u1 - u0;
-    const dv1 = v1 - v0;
-    const du2 = u2 - u0;
-    const dv2 = v2 - v0;
-    const det = du1 * dv2 - du2 * dv1;
-    if (Math.abs(det) < 1e-12)
-        return undefined;
-    const dx1 = x1 - x0;
-    const dx2 = x2 - x0;
-    const dy1 = y1 - y0;
-    const dy2 = y2 - y0;
-    // Screen area below a hundredth of a pixel: nothing to draw.
-    if (Math.abs(dx1 * dy2 - dx2 * dy1) < 0.02)
-        return undefined;
-    const a = (dx1 * dv2 - dx2 * dv1) / det;
-    const c = (du1 * dx2 - du2 * dx1) / det;
-    const b = (dy1 * dv2 - dy2 * dv1) / det;
-    const d = (du1 * dy2 - du2 * dy1) / det;
-    return [a, b, c, d, x0 - a * u0 - c * v0, y0 - b * u0 - d * v0];
-}
-function isOnTileBorder(source) {
-    return source.some(([u, v]) => u === 0 || u === 1 || v === 0 || v === 1);
-}
-/**
- * Moves the source corners of a triangle that lie on the tile border inwards, by the
- * equivalent of RASTER_TILE_BLEED_PX on screen, so that the image edge lies beyond the border.
- * (Used for the underlay that closes the seams between tiles, see `#drawRasterMeshes`.)
- */
-function bleedAtTileBorder(source, target) {
-    const [[u0, v0], [u1, v1], [u2, v2]] = source;
-    const [[x0, y0], [x1, y1], [x2, y2]] = target;
-    const sourceArea = Math.abs((u1 - u0) * (v2 - v0) - (u2 - u0) * (v1 - v0));
-    const targetArea = Math.abs((x1 - x0) * (y2 - y0) - (x2 - x0) * (y1 - y0));
-    if (sourceArea === 0 || targetArea === 0)
-        return source;
-    // Pixels per tile unit, and the bleed in tile units, kept within the triangle.
-    const scale = Math.sqrt(targetArea / sourceArea);
-    const size = Math.max(Math.abs(u1 - u0), Math.abs(u2 - u0), Math.abs(v1 - v0), Math.abs(v2 - v0));
-    const bleed = Math.min(RASTER_TILE_BLEED_PX / scale, size / 4);
-    const inset = (t) => (t === 0 ? bleed : t === 1 ? 1 - bleed : t);
-    return source.map(([u, v]) => [inset(u), inset(v)]);
-}
-/**
- * Moves every edge of a triangle outwards by `distance`, by scaling it around its incenter.
- * Growth is limited for very thin triangles, whose corners would otherwise shoot far out.
- */
-function growTriangle(triangle, distance) {
-    const [[x0, y0], [x1, y1], [x2, y2]] = triangle;
-    const a = Math.hypot(x2 - x1, y2 - y1);
-    const b = Math.hypot(x2 - x0, y2 - y0);
-    const c = Math.hypot(x1 - x0, y1 - y0);
-    const perimeter = a + b + c;
-    const area = Math.abs((x1 - x0) * (y2 - y0) - (x2 - x0) * (y1 - y0)) / 2;
-    if (perimeter === 0 || area === 0)
-        return triangle;
-    const inradius = (2 * area) / perimeter;
-    const cx = (a * x0 + b * x1 + c * x2) / perimeter;
-    const cy = (a * y0 + b * y1 + c * y2) / perimeter;
-    const scale = 1 + distance / Math.max(inradius, 2 * distance);
-    return triangle.map(([x, y]) => [cx + (x - cx) * scale, cy + (y - cy) * scale]);
-}
 function formatUnit(v) {
     return (Math.round(v * 100000) / 100000).toString();
 }
@@ -8894,50 +8949,6 @@ function formatPoint(p) {
     const [x, y] = roundXY(p[0], p[1]);
     return formatNum(x) + ',' + formatNum(y);
 }
-function mapTextAnchor(anchor) {
-    switch (anchor) {
-        case 'left':
-            return ['start', 'central'];
-        case 'right':
-            return ['end', 'central'];
-        case 'top':
-            return ['middle', 'text-before-edge'];
-        case 'bottom':
-            return ['middle', 'text-after-edge'];
-        case 'top-left':
-            return ['start', 'text-before-edge'];
-        case 'top-right':
-            return ['end', 'text-before-edge'];
-        case 'bottom-left':
-            return ['start', 'text-after-edge'];
-        case 'bottom-right':
-            return ['end', 'text-after-edge'];
-        default:
-            return ['middle', 'central'];
-    }
-}
-function mapIconAnchor(anchor, w, h) {
-    switch (anchor) {
-        case 'left':
-            return [0, -h / 2];
-        case 'right':
-            return [-w, -h / 2];
-        case 'top':
-            return [-w / 2, 0];
-        case 'bottom':
-            return [-w / 2, -h];
-        case 'top-left':
-            return [0, 0];
-        case 'top-right':
-            return [-w, 0];
-        case 'bottom-left':
-            return [0, -h];
-        case 'bottom-right':
-            return [-w, -h];
-        default:
-            return [-w / 2, -h / 2];
-    }
-}
 function escapeXml(s) {
     return s
         .replace(/&/g, '&amp;')
@@ -11358,7 +11369,13 @@ function resolveTokens(text, properties) {
         return '';
     });
 }
-async function renderMap(job) {
+/**
+ * Draws the map described by `job` onto its renderer and returns that renderer, so a
+ * caller can take the result in whatever form the backend provides (see
+ * {@link renderMap} for the SVG string, or `renderToPNG` in `@versatiles/png-renderer` for
+ * an image buffer).
+ */
+async function drawMap(job) {
     job.projection ??= Projection.fromStyle({
         width: job.renderer.width,
         height: job.renderer.height,
@@ -11370,7 +11387,10 @@ async function renderMap(job) {
     if (clipCircle)
         job.renderer.setClipCircle?.(clipCircle);
     await render(job);
-    return job.renderer.getString();
+    return job.renderer;
+}
+async function renderMap(job) {
+    return (await drawMap(job)).getString();
 }
 function getFeatures(layerFeatures, layerStyle) {
     return layerFeatures.get(layerStyle.sourceLayer) ?? layerFeatures.get(layerStyle.source);
@@ -11483,7 +11503,7 @@ async function render(job) {
             case 'raster':
                 {
                     const tiles = await getRasterTiles(job, layerStyle.source);
-                    renderer.drawRasterTiles(layerId, tiles, {
+                    await renderer.drawRasterTiles(layerId, tiles, {
                         opacity: getPaint('raster-opacity'),
                         hueRotate: getPaint('raster-hue-rotate'),
                         brightnessMin: getPaint('raster-brightness-min'),
@@ -11535,7 +11555,7 @@ async function render(job) {
                     if (symbolFeatures.length === 0)
                         continue;
                     // Render icons first (underneath text)
-                    renderer.drawIcons(`${layerId}-icons`, symbolFeatures.flatMap((feature) => {
+                    await renderer.drawIcons(`${layerId}-icons`, symbolFeatures.flatMap((feature) => {
                         const iconImage = getLayout('icon-image', feature);
                         const iconName = iconImage != null
                             ? resolveTokens(iconImage.toString(), feature.properties)
@@ -11599,6 +11619,61 @@ async function render(job) {
     }
 }
 
+/**
+ * Renders a MapLibre style to an SVG image.
+ *
+ * Fetches the vector and raster tiles the view needs, then draws every layer as SVG
+ * elements: fills and lines as paths, raster tiles and sprites as embedded images. The
+ * result is a single self-contained SVG document — it references no external files, so
+ * it can be saved, inlined into HTML or opened in a vector editor as is.
+ *
+ * Works in Node.js (22 or later) and in the browser. The same function is exported by
+ * `@versatiles/svg-renderer`, `@versatiles/png-renderer` and
+ * `@versatiles/maplibre-svg-export`; the examples import it from the first.
+ *
+ * @example Render a map in Node.js
+ * ```ts
+ * import { renderToSVG } from '@versatiles/svg-renderer';
+ * 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,
+ *   width: 800,
+ *   height: 600,
+ *   lon: 13.4, // Berlin
+ *   lat: 52.52,
+ *   zoom: 12,
+ * });
+ *
+ * await writeFile('berlin.svg', svg);
+ * ```
+ *
+ * @example Render a hosted style in the browser
+ * ```ts
+ * import { renderToSVG } from '@versatiles/svg-renderer';
+ *
+ * // This hosted style already lists its tile URLs, so it can be used directly.
+ * const style = await fetch(
+ *   'https://tiles.versatiles.org/assets/styles/colorful/style.json',
+ * ).then((response) => response.json());
+ *
+ * document.body.innerHTML = await renderToSVG({ style, width: 800, height: 600, zoom: 3 });
+ * ```
+ *
+ * @example Include labels and icons
+ * ```ts
+ * const svg = await renderToSVG({ style, lon: 13.4, lat: 52.52, zoom: 14, renderLabels: true });
+ * ```
+ *
+ * @param options - What to render and how large. Only `style` is required.
+ * @returns The SVG document, as a string beginning with `<svg`.
+ * @throws If `width` or `height` is not positive.
+ */
 async function renderToSVG(options) {
     const width = options.width ?? 1024;
     const height = options.height ?? 1024;

package/package.json

@@ -1,118 +1,41 @@
 {
   "name": "@versatiles/svg-renderer",
-  "version": "1.2.0",
-  "description": "Renders vector maps as SVG.",
+  "version": "2.0.0",
+  "description": "Renders MapLibre styles as SVG, in Node.js or the browser.",
   "keywords": [
     "svg",
     "map",
-    "renderer",
+    "maplibre",
     "vector-tiles",
+    "renderer",
+    "export",
     "versatiles"
   ],
-  "homepage": "https://github.com/versatiles-org/versatiles-svg-renderer",
+  "homepage": "https://github.com/versatiles-org/versatiles-svg-renderer/tree/main/packages/svg-renderer",
   "bugs": "https://github.com/versatiles-org/versatiles-svg-renderer/issues",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/versatiles-org/versatiles-svg-renderer.git"
+    "url": "git+https://github.com/versatiles-org/versatiles-svg-renderer.git",
+    "directory": "packages/svg-renderer"
   },
-  "main": "dist/index.cjs",
-  "module": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "unpkg": "dist/maplibre-svg-export.umd.js",
-  "jsdelivr": "dist/maplibre-svg-export.umd.js",
+  "author": "Michael Kreil <versatiles@michael-kreil.de>",
+  "license": "MIT",
+  "type": "module",
   "exports": {
     ".": {
-      "import": {
-        "types": "./dist/index.d.ts",
-        "default": "./dist/index.js"
-      },
-      "require": {
-        "types": "./dist/index.d.ts",
-        "default": "./dist/index.cjs"
-      }
-    },
-    "./maplibre": {
-      "script": "./dist/maplibre-svg-export.umd.js",
-      "import": {
-        "types": "./dist/maplibre-svg-export.d.ts",
-        "default": "./dist/maplibre-svg-export.js"
-      }
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
     }
   },
   "files": [
     "dist",
     "!dist/**/*.map"
   ],
-  "scripts": {
-    "build": "rm -rf dist && rollup -c rollup.config.ts --configPlugin @rollup/plugin-typescript && rm -rf dist/types",
-    "build-analyze": "npm run build && tsx scripts/analyze-bundle.ts",
-    "check": "npm run format && npm run lint && npm run typecheck && npm run build && npm run test && npm run test:e2e",
-    "demo": "tsx src/demo.ts",
-    "dev": "tsx dev/serve.ts",
-    "dev:render-comparison": "tsx dev/render-comparison.ts",
-    "doc:graph": "vrt deps-graph | vrt doc-insert README.md '## Dependency Graph'",
-    "doc:typescript": "npx vrt doc-typescript -f html -o ./doc-typescript",
-    "format": "prettier --write --log-level warn .",
-    "lint": "eslint --color .",
-    "prepack": "npm run doc:graph && npm run build",
-    "release": "npx vrt release-npm",
-    "start": "tsx src/index.ts",
-    "test": "vitest run",
-    "test:coverage": "vitest run --coverage",
-    "test:e2e:maplibre": "tsx e2e/maplibre-control.ts",
-    "test:e2e:screenshots": "tsx e2e/screenshots.ts",
-    "test:e2e": "vitest run --config vitest.e2e.config.ts && npm run test:e2e:maplibre && npm run test:e2e:screenshots",
-    "typecheck": "tsc --noEmit && tsc --noEmit -p e2e/tsconfig.json && tsc --noEmit -p dev/tsconfig.json",
-    "upgrade": "vrt deps-upgrade"
-  },
   "sideEffects": false,
-  "type": "module",
-  "author": "Michael Kreil <versatiles@michael-kreil.de>",
-  "license": "MIT",
   "engines": {
     "node": ">= 22"
   },
-  "peerDependencies": {
-    "maplibre-gl": ">=3.0.0"
-  },
-  "peerDependenciesMeta": {
-    "maplibre-gl": {
-      "optional": true
-    }
-  },
-  "devDependencies": {
-    "@eslint/js": "^10.0.1",
-    "@mapbox/vector-tile": "^3.0.0",
-    "@maplibre/maplibre-gl-style-spec": "^26.4.4",
-    "@rollup/plugin-node-resolve": "^16.0.3",
-    "@rollup/plugin-typescript": "^12.3.0",
-    "@types/node": "^26.6.2",
-    "@types/pbf": "^3.0.5",
-    "@types/pngjs": "^6.0.5",
-    "@versatiles/release-tool": "^2.15.0",
-    "@versatiles/style": "^6.0.0",
-    "@vitest/coverage-v8": "^5.0.1",
-    "eslint": "^10.11.0",
-    "geojson": "^0.5.0",
-    "jsdom": "^30.1.0",
-    "maplibre-gl": "^6.10.0",
-    "npm-check-updates": "^23.1.0",
-    "pbf": "^5.1.2",
-    "pixelmatch": "^7.2.0",
-    "playwright": "^1.63.0",
-    "pngjs": "^7.0.0",
-    "prettier": "^3.9.8",
-    "rollup": "^4.63.4",
-    "rollup-plugin-dts": "^6.5.1",
-    "rollup-plugin-visualizer": "^7.1.1",
-    "tslib": "^2.8.1",
-    "tsx": "^4.23.13",
-    "typescript": "^6.0.3",
-    "typescript-eslint": "^8.70.0",
-    "vitest": "^5.0.1"
-  },
-  "allowScripts": {
-    "esbuild": true,
-    "fsevents": true
+  "dependencies": {
+    "@types/geojson": "^7946.0.16"
   }
 }