@versatiles/png-renderer 2.1.0 → 2.2.0

package/README.md

@@ -77,7 +77,9 @@ const map = new PNGMapRenderer({ style, fetch: cachedFetch });
 
 ### Labels in the style's own 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.
+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.
+
+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.
 
 ```typescript
 const png = await renderToPNG({
@@ -85,7 +87,7 @@ const png = await renderToPNG({
 	lon: 13.4,
 	lat: 52.5,
 	zoom: 14,
-	renderLabels: true,
+	labels: 'text',
 	fonts: {
 		noto_sans_regular: 'fonts/NotoSans-Regular.ttf',
 		noto_sans_bold: 'fonts/NotoSans-Bold.ttf',
@@ -99,16 +101,18 @@ The VersaTiles styles use Noto Sans. One source is `npm install @fontsource/noto
 
 ### `renderToPNG(options): Promise<Uint8Array>`
 
-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:
+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:
 
-| Option  | Type                     | Default | Description                                                                                          |
-| ------- | ------------------------ | ------- | ---------------------------------------------------------------------------------------------------- |
-| `scale` | `number`                 | `1`     | Pixel density: the image is `width × scale` by `height × scale` pixels. Use `2` for sharp output.    |
-| `fonts` | `Record<string, string>` | —       | Font files for labels, by the `text-font` name the style uses: `{ noto_sans_regular: 'path.woff2' }` |
+| Option  | Type                     | Default | Description                                                                                                                |
+| ------- | ------------------------ | ------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `scale` | `number`                 | `1`     | Pixel density: the image is `width × scale` by `height × scale` pixels. Use `2` for sharp output.                          |
+| `fonts` | `Record<string, string>` | —       | Font files for labels with `labels: 'text'`, by the `text-font` name the style uses: `{ noto_sans_regular: 'path.woff2' }` |
 
 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.
 
-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).
+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.
+
+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).
 
 ### `new PNGMapRenderer(options)`
 

package/dist/index.d.ts

@@ -2708,6 +2708,9 @@ type Feature$1 = {
   readonly geometry?: Array<Array<Point2D$1>>;
 };
 
+/** Values of the style's global state, by name, as read by `global-state` expressions. */
+type GlobalState = Record<string, unknown>;
+
 type Properties = Record<string, unknown>;
 type Patterns = Record<string, {
     min: string;
@@ -2750,44 +2753,26 @@ declare class Feature implements Feature$1 {
     doesOverlap(bbox: Bbox): boolean;
 }
 
-/**
- * The part of a `Response` the renderer uses. A real `Response` has all of it; the type
- * is spelled out so that using this package needs neither the DOM nor Node's type
- * definitions.
- */
-interface FetchResponse {
-    readonly ok: boolean;
-    readonly status: number;
-    readonly headers: {
-        get(name: string): string | null;
-    };
-    arrayBuffer(): Promise<ArrayBuffer>;
-    json(): Promise<unknown>;
-}
-/**
- * Loads a URL, like `fetch`: the renderer loads tiles and sprites through it. It is called
- * with the URL only, and should resolve to a `Response`.
- */
-type FetchFunction = (url: string) => Promise<FetchResponse>;
-
-interface SpriteEntry {
-    width: number;
-    height: number;
-    x: number;
-    y: number;
-    pixelRatio: number;
-    sdf: boolean;
-    sheetDataUri: string;
-    sheetWidth: number;
-    sheetHeight: number;
-}
-type SpriteAtlas = Map<string, SpriteEntry>;
-
 interface ClipCircle {
     x: number;
     y: number;
     radius: number;
 }
+type Triangle = [[number, number], [number, number], [number, number]];
+/** A triangle of a raster tile's mesh on the globe, drawn with its own affine transform. */
+interface RasterTriangle {
+    /** Corners of the triangle within the tile image, in tile units (0..1). */
+    source: Triangle;
+    /** The same corners on screen, in pixels. */
+    target: Triangle;
+}
+/** Space around the map's center, as MapLibre's `padding`, in pixels. */
+interface Padding {
+    top?: number;
+    right?: number;
+    bottom?: number;
+    left?: number;
+}
 
 /**
  * A drawing surface the render pipeline paints a map onto. It only describes *how* to
@@ -2798,10 +2783,19 @@ interface ClipCircle {
 interface Renderer {
     readonly width: number;
     readonly height: number;
-    drawBackgroundFill(style: BackgroundStyle): void;
-    drawPolygons(id: string, features: [Feature, FillStyle][]): void;
-    drawLineStrings(id: string, features: [Feature, LineStyle][]): void;
+    /**
+     * These two may be asynchronous, like {@link Renderer.drawIcons}: a pattern is a sprite
+     * image, which a raster backend has to decode first.
+     */
+    drawBackgroundFill(style: BackgroundStyle): void | Promise<void>;
+    drawPolygons(id: string, features: [Feature, FillStyle][]): void | Promise<void>;
+    /** May be asynchronous, as a line pattern is a sprite image (see `drawPolygons`). */
+    drawLineStrings(id: string, features: [Feature, LineStyle][]): void | Promise<void>;
     drawCircles(id: string, features: [Feature, CircleStyle][]): void;
+    /**
+     * Draws text labels, and (below) icons. Each feature is a single point: the pipeline
+     * has already placed the symbol, one per point, line or polygon.
+     */
     drawLabels(id: string, features: [Feature, SymbolStyle][]): void;
     /**
      * These two may be asynchronous. Their images arrive as data URIs, which a raster
@@ -2819,13 +2813,65 @@ interface Renderer {
      */
     finish?(): void;
 }
+/**
+ * How labels and icons are drawn: not at all, as `<text>`, as the style's glyphs traced
+ * into outlines, or as those with invisible text over them.
+ */
+type LabelMode = 'none' | 'text' | 'glyphs' | 'glyphs-text';
+/**
+ * A glyph's outline, in pixels at 24 per em (`GLYPH_EM`), as closed rings (to be filled
+ * even-odd): x from the middle of its advance, y from the middle of its line of text.
+ */
+interface GlyphOutline {
+    /** Identifies the outline, for renderers that define each once. */
+    key: string;
+    rings: [number, number][][];
+    /** The glyph's advance, in ems. */
+    advance: number;
+}
+/** A glyph of a label drawn as glyphs: its outline, its middle on screen, angle and scale. */
+interface PlacedGlyph {
+    outline: GlyphOutline;
+    /** Where the middle of the glyph's advance lies, in the middle of its line of text. */
+    x: number;
+    y: number;
+    /** Clockwise, in degrees. */
+    angle: number;
+    /** From the outline's units (24 per em) to pixels: the text size / 24. */
+    scale: number;
+}
 interface BackgroundStyle {
     color: Color;
     opacity: number;
+    /** `background-pattern`: drawn instead of `color`. */
+    pattern?: FillPattern;
+}
+/**
+ * A sprite image repeated over an area (`fill-pattern`, `background-pattern`), at its
+ * display size (`width / pixelRatio`) and anchored to the world, as in MapLibre.
+ */
+interface FillPattern {
+    /** The image's name in the sprite. */
+    name: string;
+    sprite: SpriteEntry;
+    /**
+     * A screen point where one copy of the image has its top-left corner: one aligned with
+     * the world's origin, so the pattern moves with the map.
+     */
+    origin: [number, number];
+    /** How far the pattern turns around `origin`, clockwise in degrees: with the map's bearing. */
+    angle?: number;
+    /**
+     * How much larger than its display size the image is drawn (1 if not given): MapLibre
+     * scales patterns with the map from the zoom level's integer part, as its tiles are.
+     */
+    scale?: number;
 }
 interface FillStyle {
     color: Color;
     opacity: number;
+    /** `fill-pattern`: drawn instead of `color`. */
+    pattern?: FillPattern;
     translate: [number, number];
     /**
      * fill-outline-color. When omitted the fill `color` is used (MapLibre's
@@ -2851,14 +2897,31 @@ interface LineStyle {
     opacity: number;
     translate: [number, number];
     width: number;
+    /** `line-pattern`: drawn instead of `color` and `dasharray`. */
+    pattern?: LinePattern;
+}
+/**
+ * A sprite image repeated along a line (`line-pattern`), spanning its width, as in MapLibre
+ * (see `line_pattern.ts`).
+ */
+interface LinePattern {
+    /** The image's name in the sprite. */
+    name: string;
+    sprite: SpriteEntry;
+    /** How far one copy of the image reaches along the line, in pixels. */
+    period: number;
 }
 interface CircleStyle {
     color: Color;
+    /** Opacity of the fill only; the stroke has its own, as in MapLibre. */
     opacity: number;
     radius: number;
     translate: [number, number];
     strokeWidth: number;
     strokeColor: Color;
+    strokeOpacity: number;
+    /** `circle-blur`: the share of the outer radius over which the circle fades out. */
+    blur?: number;
 }
 interface RasterStyle {
     opacity: number;
@@ -2869,7 +2932,41 @@ interface RasterStyle {
     contrast: number;
     resampling: 'linear' | 'nearest';
 }
+/** One character of a label along a line: its center, and its angle in degrees. */
+interface GlyphPlacement {
+    text: string;
+    x: number;
+    y: number;
+    angle: number;
+}
 interface SymbolStyle {
+    /**
+     * For a label along a line: where each of its characters goes. The label is drawn glyph
+     * by glyph there, centered on each position, instead of at the feature's point.
+     */
+    path?: GlyphPlacement[];
+    /**
+     * For a label drawn as the style's glyphs: each glyph's outline, where it goes and how
+     * large. Drawn instead of the text.
+     */
+    glyphs?: PlacedGlyph[];
+    /** With `glyphs`: also the text, invisible, so the label stays selectable and searchable. */
+    textOverlay?: boolean;
+    /**
+     * For a label of several lines: each line, and the point its alignment (`justify`)
+     * refers to, vertically at the middle of the line. The anchor and offset are applied
+     * already; `text` is all lines.
+     */
+    lines?: {
+        text: string;
+        x: number;
+        y: number;
+        width?: number;
+    }[];
+    /** How the `lines` align at their points (`text-justify`). */
+    justify?: 'left' | 'center' | 'right';
+    /** `text-letter-spacing`, in ems. */
+    letterSpacing?: number;
     text: string;
     size: number;
     font: string[];
@@ -2892,6 +2989,11 @@ interface IconStyle {
     color: Color;
     haloColor: Color;
     haloWidth: number;
+    /**
+     * Fitted to its label (`icon-text-fit`): the box the icon spans, `[left, top, right,
+     * bottom]` from its point, before `icon-size`; `anchor` and `offset` then do not apply.
+     */
+    fit?: [number, number, number, number];
 }
 interface RasterTile {
     x: number;
@@ -2904,38 +3006,96 @@ interface RasterTile {
      * triangles, each drawn with its own affine transform.
      */
     triangles?: RasterTriangle[];
+    /**
+     * An image on its own (an `image` source), with no neighbouring tiles to close seams
+     * with: its triangles are drawn without the underlay that reaches beyond its border.
+     */
+    standalone?: boolean;
 }
-type Triangle = [[number, number], [number, number], [number, number]];
-interface RasterTriangle {
-    /** Corners of the triangle within the tile image, in tile units (0..1). */
-    source: Triangle;
-    /** The same corners on screen, in pixels. */
-    target: Triangle;
+/** An image of the style's sprite: where it is on its sprite sheet, and how it stretches. */
+interface SpriteEntry {
+    width: number;
+    height: number;
+    x: number;
+    y: number;
+    pixelRatio: number;
+    sdf: boolean;
+    sheetDataUri: string;
+    sheetWidth: number;
+    sheetHeight: number;
+    /** The columns of the image that stretch with `icon-text-fit`, as `[from, to]` pixels. */
+    stretchX?: [number, number][];
+    /** The rows of the image that stretch with `icon-text-fit`, as `[from, to]` pixels. */
+    stretchY?: [number, number][];
+    /** The part of the image `icon-text-fit` fits to the label: `[left, top, right, bottom]` pixels. */
+    content?: [number, number, number, number];
+    /** Whether a fitted image keeps the content's aspect ratio, horizontally. */
+    textFitWidth?: TextFit;
+    /** Whether a fitted image keeps the content's aspect ratio, vertically. */
+    textFitHeight?: TextFit;
+}
+type TextFit = 'stretchOrShrink' | 'stretchOnly' | 'proportional';
+type SpriteAtlas = Map<string, SpriteEntry>;
+
+/**
+ * The part of a `Response` the renderer uses. A real `Response` has all of it; the type
+ * is spelled out so that using this package needs neither the DOM nor Node's type
+ * definitions.
+ */
+interface FetchResponse {
+    readonly ok: boolean;
+    readonly status: number;
+    readonly headers: {
+        get(name: string): string | null;
+    };
+    arrayBuffer(): Promise<ArrayBuffer>;
+    json(): Promise<unknown>;
 }
+/**
+ * Loads a URL, like `fetch`: the renderer loads tiles, sprites, TileJSON documents and GeoJSON data through it. It is called
+ * with the URL only, and should resolve to a `Response`.
+ */
+type FetchFunction = (url: string) => Promise<FetchResponse>;
 
 /** Options for {@link SVGMapRenderer}: what stays the same for every view of the map. */
 interface SVGMapRendererOptions {
     /**
      * The MapLibre style to render.
      *
-     * Its sources must list their tile URLs directly (`tiles: [...]`). A style whose
-     * sources only point at a TileJSON document (`url: '.../tiles.json'`) renders as an
-     * **empty map without any error**, because the renderer does not fetch TileJSON. Hosted
-     * styles such as those of VersaTiles list their tiles; a style built with
-     * `@versatiles/style` needs its `inlineSources()` first.
+     * A source may list its tile URLs (`tiles: [...]`) or point at a TileJSON document
+     * (`url: '.../tiles.json'`), which is fetched once, like the sprite, with
+     * {@link SVGMapRendererOptions.fetch}. As in MapLibre GL JS, `tiles`, `minzoom`,
+     * `maxzoom` and the like come from the document unless the style sets them, and
+     * relative tile URLs are resolved against the document's URL. A GeoJSON source's `data`
+     * may be a URL too. A source whose TileJSON or GeoJSON cannot be loaded is left out, and
+     * the next render tries again.
      */
     style: StyleSpecification;
     /**
-     * Draw the style's symbol layers: text labels and icons.
-     *
-     * Off by default, because labels are the least faithful part of the output. They are
-     * drawn as horizontal text at the middle of their feature: labels that MapLibre curves
-     * along a line (`symbol-placement: "line"`, typically street names) come out straight,
-     * and there is no collision detection, so crowded label layers can overlap.
-     *
-     * 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`.
+     * Whether and how to draw the style's symbol layers, its labels and icons:
+     *
+     * - `'none'`: neither labels nor icons.
+     * - `'text'`: labels as `<text>` naming the style's fonts (`text-font`), which whatever
+     *   displays the SVG resolves, so they show in the intended typeface only where that font
+     *   is installed. In PNG output, with the fonts given by `fonts`.
+     * - `'glyphs'`: labels as the style's own glyphs (`glyphs`), the letter shapes MapLibre
+     *   draws, traced into outlines: exact in every viewer and editor, but not text. Each
+     *   glyph is defined once and reused.
+     * - `'glyphs-text'`: as `'glyphs'`, with the text laid invisibly over the outlines, so labels
+     *   stay selectable and searchable. (In PNG output, the same as `'glyphs'`.)
+     *
+     * Labels are placed as in MapLibre: at points, inside each polygon at the point farthest
+     * from its edges, and along lines; labels and icons that would overlap one placed before
+     * are left out, from the top layer down. With glyphs, they are laid out with MapLibre's
+     * own metrics; as text, with the widths of Noto Sans. A style without `glyphs`, or glyphs
+     * that cannot be loaded, fall back to `'text'`, reported through `onWarning`.
+     * @defaultValue `'none'`, or as given by {@link SVGMapRendererOptions.renderLabels}
+     */
+    labels?: LabelMode;
+    /**
+     * Draw the style's labels and icons.
+     * @deprecated Use {@link SVGMapRendererOptions.labels}: `true` is `'glyphs-text'`, `false`
+     *   is `'none'`.
      * @defaultValue `false`
      */
     renderLabels?: boolean;
@@ -2950,7 +3110,7 @@ interface SVGMapRendererOptions {
      */
     tileCacheSize?: number;
     /**
-     * Loads tiles and sprites, like `fetch`, which is the default. Pass your own to send
+     * Loads tiles, sprites, TileJSON documents and GeoJSON data, like `fetch`, which is the default. Pass your own to send
      * headers, go through a proxy, or keep tiles in a cache on disk.
      *
      * It must return a real `Response`, and its status matters: a 404 or 204 means the
@@ -2960,6 +3120,24 @@ interface SVGMapRendererOptions {
      * @defaultValue the global `fetch`
      */
     fetch?: FetchFunction;
+    /**
+     * Called with a message for each part of the style the renderer does not draw: a layer
+     * type, a layer property, a source, or a TileJSON document that could not be loaded. Each
+     * message is reported once per instance. Pass `() => {}` to silence them.
+     *
+     * Properties that make no difference to a flat, north-up map (e.g. `*-pitch-alignment`)
+     * are not reported, nor are symbol layers unless {@link SVGMapRendererOptions.labels}
+     * is set.
+     * @defaultValue `console.warn`
+     */
+    onWarning?: (message: string) => void;
+    /**
+     * Values for the style's global state, read by `global-state` expressions, e.g. to
+     * switch the language or a theme of a style. They override the defaults in the style's
+     * `state`, like `map.setGlobalStateProperty(name, value)` in MapLibre GL JS.
+     * @defaultValue the defaults of the style's `state`
+     */
+    globalState?: GlobalState;
 }
 /** The view to render: size, centre and zoom. */
 interface ViewOptions {
@@ -2975,27 +3153,40 @@ interface ViewOptions {
     height?: number;
     /**
      * Longitude of the map centre, in degrees.
-     * @defaultValue `0`
+     * @defaultValue the longitude of the style's `center`, else `0`
      */
     lon?: number;
     /**
      * Latitude of the map centre, in degrees.
-     * @defaultValue `0`
+     * @defaultValue the latitude of the style's `center`, else `0`
      */
     lat?: number;
     /**
      * Zoom level, as in MapLibre: each step doubles the scale. Fractional values are
      * allowed.
-     * @defaultValue `2`
+     * @defaultValue the style's `zoom`, else `2`
      */
     zoom?: number;
+    /**
+     * The compass direction that is up, in degrees, as in MapLibre: `90` puts east at the
+     * top. The map turns around the image's center; labels stay upright.
+     * @defaultValue the style's `bearing`, else `0`
+     */
+    bearing?: number;
+    /**
+     * Space around the map's center, in pixels, as MapLibre's `padding`: the center (`lon`,
+     * `lat`) sits in the middle of the area inside it, e.g. to keep it clear of a panel laid
+     * over the image. A number applies to all sides.
+     * @defaultValue `0`
+     */
+    padding?: number | Padding;
 }
 /**
  * Renders many views of one MapLibre style as SVG.
  *
  * Does the work that depends only on the style once, when constructed or on the first
  * render, instead of on every call as {@link renderToSVG} does: the style is parsed once,
- * and the sprite (the icons, needed with `renderLabels`) is fetched once. Tiles are kept
+ * and the sprite (the icons, needed with `labels`) and the glyphs are fetched once. Tiles are kept
  * too (up to {@link SVGMapRendererOptions.tileCacheSize}), so overlapping views share
  * them. Use it to render a batch of views, e.g. thumbnails or a series of map sections.
  *
@@ -3016,8 +3207,8 @@ interface ViewOptions {
 declare class SVGMapRenderer {
     #private;
     /**
-     * @param options - The style, whether to draw labels, the tile cache size, and how to
-     *   load tiles and sprites.
+     * @param options - The style, whether to draw labels, the tile cache size, how to load
+     *   tiles and sprites, and where to report unsupported parts of the style.
      * @throws If `tileCacheSize` is negative or not a number.
      */
     constructor(options: SVGMapRendererOptions);
@@ -3031,7 +3222,7 @@ declare class SVGMapRenderer {
      */
     renderSVG(view?: ViewOptions): Promise<string>;
     /**
-     * Forgets the fetched tiles and sprite, so the next render fetches them again, e.g.
+     * Forgets the fetched tiles, sprite, TileJSON documents and GeoJSON data, so the next render fetches them again, e.g.
      * after they were updated on the server, or to free their memory.
      */
     clearCache(): void;
@@ -3112,7 +3303,7 @@ interface RenderToSVGOptions extends Omit<SVGMapRendererOptions, 'tileCacheSize'
  *
  * @example Include labels and icons
  * ```ts
- * const svg = await renderToSVG({ style, lon: 13.4, lat: 52.52, zoom: 14, renderLabels: true });
+ * const svg = await renderToSVG({ style, lon: 13.4, lat: 52.52, zoom: 14, labels: 'glyphs-text' });
  * ```
  *
  * @param options - What to render and how large. Only `style` is required.
@@ -3144,7 +3335,7 @@ interface RenderToPNGOptions extends RenderToSVGOptions {
      * installed on the machine, which is usually not the one the style asked for.
      *
      * Fonts are registered process-wide, so a name registered by one call stays available
-     * to every later call. Only matters when {@link RenderToSVGOptions.renderLabels} is on.
+     * to every later call. Only matters when {@link RenderToSVGOptions.labels} is `'text'`.
      */
     fonts?: Record<string, string>;
 }
@@ -3184,7 +3375,7 @@ interface RenderToPNGOptions extends RenderToSVGOptions {
  *   lon: 13.4,
  *   lat: 52.52,
  *   zoom: 14,
- *   renderLabels: true,
+ *   labels: 'text',
  *   fonts: { noto_sans_regular: 'fonts/NotoSans-Regular.ttf', noto_sans_bold: 'fonts/NotoSans-Bold.ttf' },
  * });
  * ```
@@ -3294,4 +3485,4 @@ declare class PNGMapRenderer extends SVGMapRenderer {
 }
 
 export { PNGMapRenderer, SVGMapRenderer, renderToCanvas, renderToPNG, renderToSVG };
-export type { FetchFunction, FetchResponse, PNGMapRendererOptions, PNGViewOptions, RenderToPNGOptions, RenderToSVGOptions, SVGMapRendererOptions, ViewOptions };
+export type { FetchFunction, FetchResponse, GlobalState, PNGMapRendererOptions, PNGViewOptions, RenderToPNGOptions, RenderToSVGOptions, SVGMapRendererOptions, ViewOptions };