@versatiles/png-renderer 2.2.0 → 2.3.0

package/dist/index.d.ts

@@ -2741,6 +2741,12 @@ declare class Feature implements Feature$1 {
      * clipped edges along the tile border are not part of the outline.
      */
     readonly outline?: Geometry;
+    /**
+     * For each line of the geometry, how far along the line in its tile it starts, in pixels
+     * — where the line was clipped to its tile, which cut off its start. A dash pattern
+     * starts where the line in the tile does.
+     */
+    readonly lineStarts?: number[];
     constructor(opt: {
         type: 'LineString' | 'Point' | 'Polygon';
         id?: unknown;
@@ -2748,6 +2754,7 @@ declare class Feature implements Feature$1 {
         patterns?: Patterns;
         geometry: Geometry;
         outline?: Geometry;
+        lineStarts?: number[];
     });
     getBbox(): Bbox;
     doesOverlap(bbox: Bbox): boolean;
@@ -2774,6 +2781,18 @@ interface Padding {
     left?: number;
 }
 
+/**
+ * The dashes of a line with `line-dasharray`, shared by every backend, as MapLibre GL JS
+ * draws them (`line_sdf.vertex.glsl`, `LineAtlas`).
+ */
+/** A dash pattern in pixels. */
+interface LineDash {
+    /** The lengths of dashes and gaps in turn, starting with a dash: an even number of them. */
+    lengths: number[];
+    /** How far into the pattern a line starts. */
+    offset: number;
+}
+
 /**
  * A drawing surface the render pipeline paints a map onto. It only describes *how* to
  * draw; how the result is handed back is up to the backend, because those differ in
@@ -2890,14 +2909,15 @@ interface LineStyle {
     blur: number;
     cap: 'butt' | 'round' | 'square';
     color: Color;
-    dasharray?: number[];
+    /** `line-dasharray`, in pixels (see `dashPattern`). */
+    dash?: LineDash;
     join: 'bevel' | 'miter' | 'round';
     miterLimit: number;
     offset: number;
     opacity: number;
     translate: [number, number];
     width: number;
-    /** `line-pattern`: drawn instead of `color` and `dasharray`. */
+    /** `line-pattern`: drawn instead of `color` and `dash`. */
     pattern?: LinePattern;
 }
 /**

package/dist/index.js

@@ -119,6 +119,12 @@ class Feature {
      * clipped edges along the tile border are not part of the outline.
      */
     outline;
+    /**
+     * For each line of the geometry, how far along the line in its tile it starts, in pixels
+     * — where the line was clipped to its tile, which cut off its start. A dash pattern
+     * starts where the line in the tile does.
+     */
+    lineStarts;
     #bbox;
     constructor(opt) {
         this.type = opt.type;
@@ -127,6 +133,7 @@ class Feature {
         this.patterns = opt.patterns;
         this.geometry = opt.geometry;
         this.outline = opt.outline;
+        this.lineStarts = opt.lineStarts;
     }
     getBbox() {
         if (this.#bbox)
@@ -2133,32 +2140,49 @@ function clipPolygonOutline(rings, min, max) {
 }
 /** Clips a polyline to the square [min, max]², returning the parts inside of it. */
 function clipLine(line, min, max) {
+    return clipLineMeasured(line, min, max).map(({ points }) => points);
+}
+/**
+ * Clips a polyline to the square [min, max]², like `clipLine`, and measures where each part
+ * starts: its distance from the polyline's start, which is where MapLibre starts a dash
+ * pattern. MapLibre stores that distance in a few bits and starts again from zero at a
+ * vertex further along than `resetAfter` (`LineBucket.addCurrentVertex`).
+ */
+function clipLineMeasured(line, min, max, resetAfter = Infinity) {
     const parts = [];
     let current = [];
+    let start = 0;
+    let distance = 0;
+    const flush = () => {
+        if (current.length > 1)
+            parts.push({ points: current, start });
+        current = [];
+    };
     for (let i = 0; i + 1 < line.length; i++) {
-        const segment = clipSegment(line[i], line[i + 1], min, max);
-        if (!segment) {
-            if (current.length > 1)
-                parts.push(current);
-            current = [];
-            continue;
-        }
-        const [a, b] = segment;
-        const last = current[current.length - 1];
-        if (last?.x !== a.x || last.y !== a.y) {
-            if (current.length > 1)
-                parts.push(current);
-            current = [a];
+        const from = line[i];
+        const to = line[i + 1];
+        const segment = clipSegment(from, to, min, max);
+        if (segment) {
+            const [a, b] = segment;
+            const last = current[current.length - 1];
+            if (last?.x !== a.x || last.y !== a.y) {
+                flush();
+                current = [a];
+                start = distance + Math.hypot(a.x - from.x, a.y - from.y);
+            }
+            current.push(b);
+            // The segment left the square: the line continues elsewhere.
+            if (b !== to)
+                flush();
         }
-        current.push(b);
-        // The segment left the square: the line continues elsewhere.
-        if (b !== line[i + 1]) {
-            parts.push(current);
-            current = [];
+        else {
+            flush();
         }
+        distance += Math.hypot(to.x - from.x, to.y - from.y);
+        if (distance > resetAfter)
+            distance = 0;
     }
-    if (current.length > 1)
-        parts.push(current);
+    flush();
     return parts;
 }
 /** Liang–Barsky: the part of the segment a→b inside the square, or undefined. */
@@ -2218,6 +2242,11 @@ function lerpAtY(a, b, y) {
 }
 
 const TILE_EXTENT = 4096;
+/**
+ * How far along a line MapLibre measures before it starts again from zero: two tiles
+ * (`MAX_LINE_DISTANCE / 2` in its `line_bucket.ts`, for its tile extent of 8192).
+ */
+const MAX_LINE_DISTANCE = 2 * TILE_EXTENT;
 const VTFeatureType = { Unknown: 0, Point: 1, LineString: 2, Polygon: 3 };
 async function loadVectorSource(source, job, layerFeatures, loadTile = getTile) {
     const tiles = source.tiles;
@@ -2236,7 +2265,7 @@ async function loadVectorSource(source, job, layerFeatures, loadTile = getTile)
     });
 }
 /** Decodes one vector tile and adds its features, projected to the screen. */
-function addTileFeatures(buffer, { project, clipToTile }, layerFeatures, width, height) {
+function addTileFeatures(buffer, { project, clipToTile, pixelsPerUnit }, layerFeatures, width, height) {
     const vectorTile = new VectorTile(new PbfReader(buffer));
     for (const [name, layer] of Object.entries(vectorTile.layers)) {
         let features = layerFeatures.get(name);
@@ -2266,6 +2295,7 @@ function addTileFeatures(buffer, { project, clipToTile }, layerFeatures, width,
             }
             let rings = featureSrc.loadGeometry();
             let outline;
+            let lineStarts;
             // Clip polygons and lines to the tile, like MapLibre's stencil clipping: otherwise
             // the parts in the tile buffer are drawn twice, which shows when translucent.
             if (clipToTile && type !== 'Point' && exceedsSquare(rings, 0, TILE_EXTENT)) {
@@ -2274,7 +2304,11 @@ function addTileFeatures(buffer, { project, clipToTile }, layerFeatures, width,
                     rings = clipPolygon(rings, 0, TILE_EXTENT);
                 }
                 else {
-                    rings = rings.flatMap((line) => clipLine(line, 0, TILE_EXTENT));
+                    const parts = rings.flatMap((line) => clipLineMeasured(line, 0, TILE_EXTENT, MAX_LINE_DISTANCE));
+                    rings = parts.map(({ points }) => points);
+                    if (pixelsPerUnit !== undefined) {
+                        lineStarts = parts.map(({ start }) => start * pixelsPerUnit);
+                    }
                 }
             }
             const geometry = project(type, rings);
@@ -2298,6 +2332,7 @@ function addTileFeatures(buffer, { project, clipToTile }, layerFeatures, width,
                     type,
                     geometry,
                     outline,
+                    lineStarts,
                     id: featureSrc.id,
                     properties: featureSrc.properties,
                 });
@@ -2352,6 +2387,7 @@ function getTileProjections(source, job) {
             y,
             z: zoomLevel,
             clipToTile: true,
+            pixelsPerUnit: scale,
             project: (_type, rings) => rings.map((ring) => ring.map((point) => {
                 const p = new Point2D(point.x, point.y).scale(scale).translate(offset);
                 return moved ? moved.fromNorthUp(p.x, p.y) : p;
@@ -11749,6 +11785,55 @@ function stretchZonesToCuts(zones, fixedSize, stretchSize) {
     return cuts;
 }
 
+/**
+ * The dashes of a line with `line-dasharray`, shared by every backend, as MapLibre GL JS
+ * draws them (`line_sdf.vertex.glsl`, `LineAtlas`).
+ */
+/**
+ * The dash pattern of `dasharray`, or undefined for a line without dashes.
+ *
+ * MapLibre measures a dash array in line widths, but not in the width the line is drawn
+ * with: in its width at the zoom level's integer part (`floorWidth`), scaled with the map
+ * from that integer zoom level up to `zoom`, as its tiles are. And where a dash array has
+ * an odd number of lengths, it is not repeated to an even one, as SVG and the canvas do: its
+ * last and first dash are joined to one.
+ */
+function dashPattern(dasharray, floorWidth, zoom) {
+    if (!dasharray || dasharray.length === 0)
+        return undefined;
+    const unit = floorWidth * 2 ** (zoom - Math.floor(zoom));
+    if (!(unit > 0))
+        return undefined;
+    const lengths = dasharray.map((length) => Math.max(length, 0) * unit);
+    let offset = 0;
+    if (lengths.length % 2 === 1) {
+        // A single length is a dash without a gap.
+        if (lengths.length === 1)
+            return undefined;
+        // The last dash goes before the first: the pattern starts that far into their sum.
+        offset = lengths.pop();
+        lengths[0] += offset;
+    }
+    // Without a gap, the line is solid.
+    const hasGap = lengths.some((length, i) => i % 2 === 1 && length > 0);
+    return hasGap ? { lengths, offset } : undefined;
+}
+/** `offset` within one period of `dash`, for a line that starts `start` pixels in. */
+function dashOffset(dash, start) {
+    const period = dash.lengths.reduce((sum, length) => sum + length, 0);
+    const offset = (dash.offset + start) % period;
+    return offset < 0 ? offset + period : offset;
+}
+/**
+ * How far along a ring its first vertex is: MapLibre measures a ring from its last vertex,
+ * so by the length of its closing segment (`LineBucket.addLine`).
+ */
+function closingLength(ring) {
+    const first = ring[0];
+    const last = ring[ring.length - 1];
+    return first && last ? Math.hypot(first.x - last.x, first.y - last.y) : 0;
+}
+
 /**
  * Geometry for drawing a line with `line-pattern`, shared by every backend: the sprite image
  * repeated along the line, its height across the line's width, as MapLibre GL JS draws it
@@ -12219,9 +12304,10 @@ async function renderLineLayer(layer) {
     if (lineStringFeatures.length === 0)
         return;
     const { getPaint, getLayout } = evaluateLayer(layer);
-    // A pattern is scaled to the line's width at the zoom level's integer part, as in MapLibre.
+    // A pattern and the dashes are scaled to the line's width at the zoom level's integer
+    // part, as in MapLibre.
     const { zoom } = layer.job.view;
-    const atFloorZoom = layer.layerStyle.usesPattern
+    const atFloorZoom = layer.layerStyle.usesPattern || getPaint('line-dasharray') !== undefined
         ? evaluateLayer(layer, Math.floor(zoom))
         : undefined;
     const sorted = sortByKey(lineStringFeatures, (feature) => getLayout('line-sort-key', feature));
@@ -12230,21 +12316,26 @@ async function renderLineLayer(layer) {
         // A pattern whose image is not in the sprite draws nothing, as in MapLibre.
         if (found === null)
             return [];
+        const width = getPaint('line-width', feature);
+        const floorWidth = atFloorZoom?.getPaint('line-width', feature) ?? width;
+        const dash = dashPattern(getPaint('line-dasharray', feature), floorWidth, zoom);
+        const cap = getLayout('line-cap', feature);
         const style = {
             blur: getPaint('line-blur', feature),
             color: getPaint('line-color', feature),
             translate: screenTranslate(layer.job, getPaint('line-translate', feature), getPaint('line-translate-anchor', feature)),
-            cap: getLayout('line-cap', feature),
-            dasharray: getPaint('line-dasharray', feature),
+            // MapLibre's dashes end flat unless the caps are round: with square caps, an SVG or
+            // a canvas would lengthen every dash. (That leaves out the caps at the line's ends.)
+            cap: dash && cap === 'square' ? 'butt' : cap,
+            dash,
             join: getLayout('line-join', feature),
             miterLimit: getLayout('line-miter-limit', feature),
             offset: getPaint('line-offset', feature),
             opacity: getPaint('line-opacity', feature),
-            width: getPaint('line-width', feature),
+            width,
         };
         if (found) {
             const { sprite } = found;
-            const floorWidth = atFloorZoom?.getPaint('line-width', feature) ?? style.width;
             style.pattern = {
                 name: found.name,
                 sprite,
@@ -14045,6 +14136,10 @@ function strokeAttr(color, width) {
 function formatScaled(v) {
     return formatNum(Math.round(v * 10));
 }
+/** How far into its dash pattern a line starts, in hundredths of a pixel. */
+function formatDash(v) {
+    return (Math.round(v * 100) / 100).toString();
+}
 function formatUnit(v) {
     return (Math.round(v * 100000) / 100000).toString();
 }
@@ -14690,9 +14785,9 @@ class SVGRenderer {
                 ? ''
                 : ` transform="translate(${formatPoint(style.translate)})"`;
             const roundedWidth = formatScaled(style.width);
-            const dasharrayStr = style.dasharray
-                ? style.dasharray.map((v) => formatScaled(v * style.width)).join(',')
-                : '';
+            const { dash } = style;
+            // The lengths are written precisely: what is rounded off adds up along the line.
+            const dasharrayStr = dash ? dash.lengths.map(formatUnit).join(',') : '';
             // MapLibre's line-blur fades the line as the blur approaches its width
             // (the feather eats into the opaque core). A Gaussian conserves total ink,
             // so approximate that fade with an extra opacity factor; it tends to 1 for
@@ -14715,33 +14810,55 @@ class SVGRenderer {
                 filterAttr,
             ].join('\0');
             const translucent = effectiveOpacity < 1 || color.alpha < 255;
-            if (translucent || key !== currentKey) {
-                const attrs = [
-                    'fill="none"',
-                    strokeAttr(color, roundedWidth),
-                    `stroke-linecap="${style.cap}"`,
-                    `stroke-linejoin="${style.join}"`,
-                    `stroke-miterlimit="${String(style.miterLimit)}"`,
-                ];
-                if (dasharrayStr)
-                    attrs.push(`stroke-dasharray="${dasharrayStr}"`);
-                groups.push({
-                    segments: [],
-                    rings: [],
-                    attrs: attrs.join(' ') + translate + opacityAttr + filterAttr,
-                    separate: translucent,
+            // The group of paths with these attributes; `dashOffsetStr` is how far into the dash
+            // pattern they start.
+            const groupFor = (dashOffsetStr) => {
+                const groupKey = key + '\0' + dashOffsetStr;
+                if (translucent || groupKey !== currentKey) {
+                    const attrs = [
+                        'fill="none"',
+                        strokeAttr(color, roundedWidth),
+                        `stroke-linecap="${style.cap}"`,
+                        `stroke-linejoin="${style.join}"`,
+                        `stroke-miterlimit="${String(style.miterLimit)}"`,
+                    ];
+                    if (dasharrayStr)
+                        attrs.push(`stroke-dasharray="${dasharrayStr}"`);
+                    if (dashOffsetStr !== '0')
+                        attrs.push(`stroke-dashoffset="${dashOffsetStr}"`);
+                    groups.push({
+                        segments: [],
+                        rings: [],
+                        attrs: attrs.join(' ') + translate + opacityAttr + filterAttr,
+                        separate: translucent,
+                        dashed: dash !== undefined,
+                    });
+                    currentKey = translucent ? undefined : groupKey;
+                }
+                return groups[groups.length - 1];
+            };
+            const { open, closed } = strokeLines(feature.geometry, feature.type === 'Polygon', style.offset);
+            if (dash) {
+                // Every part has its dashes where MapLibre draws them: from the start of the line
+                // in its tile, and a ring from the start of its closing segment.
+                open.forEach((line, i) => {
+                    const offset = formatDash(dashOffset(dash, feature.lineStarts?.[i] ?? 0));
+                    groupFor(offset).segments.push(line.map((p) => roundXY(p.x, p.y)));
                 });
-                currentKey = translucent ? undefined : key;
+                for (const ring of closed) {
+                    const offset = formatDash(dashOffset(dash, closingLength(ring)));
+                    groupFor(offset).rings.push(ring.map((p) => roundXY(p.x, p.y)));
+                }
+                return;
             }
-            const group = groups[groups.length - 1];
-            const { open, closed } = strokeLines(feature.geometry, feature.type === 'Polygon', style.offset);
+            const group = groupFor('0');
             for (const line of open)
                 group.segments.push(line.map((p) => roundXY(p.x, p.y)));
             for (const ring of closed)
                 group.rings.push(ring.map((p) => roundXY(p.x, p.y)));
         });
         this.#svg.push(`<g id="${escapeXml(id)}">`);
-        for (const { segments, rings, attrs, separate, patterned } of groups) {
+        for (const { segments, rings, attrs, separate, dashed, patterned } of groups) {
             if (patterned) {
                 this.#svg.push(patterned);
                 continue;
@@ -14755,7 +14872,7 @@ class SVGRenderer {
                 }
                 continue;
             }
-            const chains = chainSegments(segments);
+            const chains = dashed ? segments : chainSegments(segments);
             const d = segmentsToPath(chains) + segmentsToPath(rings, true);
             this.#svg.push(`<path d="${d}" ${attrs} />`);
         }
@@ -16087,8 +16204,23 @@ class CanvasRenderer {
                 ctx.lineCap = style.cap;
                 ctx.lineJoin = style.join;
                 ctx.miterLimit = style.miterLimit;
-                if (style.dasharray)
-                    ctx.setLineDash(style.dasharray.map((v) => v * style.width));
+                const { dash } = style;
+                if (dash) {
+                    // Every part has its dashes where MapLibre draws them: from the start of the
+                    // line in its tile, and a ring from the start of its closing segment.
+                    ctx.setLineDash(dash.lengths);
+                    segments.forEach((segment, i) => {
+                        ctx.lineDashOffset = dashOffset(dash, feature.lineStarts?.[i] ?? 0);
+                        this.#trace(ctx, [segment], false);
+                        ctx.stroke();
+                    });
+                    lines.closed.forEach((ring, i) => {
+                        ctx.lineDashOffset = dashOffset(dash, closingLength(ring));
+                        this.#trace(ctx, [rings[i]], true);
+                        ctx.stroke();
+                    });
+                    return;
+                }
                 if (translucent) {
                     for (const segment of segments) {
                         this.#trace(ctx, [segment], false);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@versatiles/png-renderer",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "Renders MapLibre styles as PNG (and SVG) in Node.js.",
   "keywords": [
     "png",
@@ -41,7 +41,7 @@
     "node": ">= 22"
   },
   "dependencies": {
-    "@napi-rs/canvas": "^1.0.9",
+    "@napi-rs/canvas": "^1.0.10",
     "@types/geojson": "^7946.0.16"
   }
 }