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

package/dist/index.d.ts

@@ -2559,19 +2559,407 @@ type BackgroundLayerSpecification = {
   };
 };
 type LayerSpecification = FillLayerSpecification | LineLayerSpecification | SymbolLayerSpecification | CircleLayerSpecification | HeatmapLayerSpecification | FillExtrusionLayerSpecification | RasterLayerSpecification | HillshadeLayerSpecification | ColorReliefLayerSpecification | BackgroundLayerSpecification;
+//#endregion
+//#region src/expression/types/color_spaces.d.ts
+/**
+ * @param r Red component 0..1
+ * @param g Green component 0..1
+ * @param b Blue component 0..1
+ * @param alpha Alpha component 0..1
+ */
+type RGBColor = [r: number, g: number, b: number, alpha: number];
+/**
+ * @param h Hue as degrees 0..360
+ * @param c Chroma 0..~230
+ * @param l Lightness as percentage 0..100
+ * @param alpha Alpha component 0..1
+ */
+type HCLColor = [h: number, c: number, l: number, alpha: number];
+/**
+ * @param l Lightness as percentage 0..100
+ * @param a A axis value -125..125
+ * @param b B axis value -125..125
+ * @param alpha Alpha component 0..1
+ */
+type LABColor = [l: number, a: number, b: number, alpha: number];
+//#endregion
+//#region src/expression/types/color.d.ts
+type InterpolationColorSpace = 'rgb' | 'hcl' | 'lab';
+/**
+ * Color representation used by WebGL.
+ * Defined in sRGB color space and pre-blended with alpha.
+ * @private
+ */
+declare class Color {
+  readonly r: number;
+  readonly g: number;
+  readonly b: number;
+  readonly a: number;
+  /**
+   * @param r Red component premultiplied by `alpha` 0..1
+   * @param g Green component premultiplied by `alpha` 0..1
+   * @param b Blue component premultiplied by `alpha` 0..1
+   * @param [alpha=1] Alpha component 0..1
+   * @param [premultiplied=true] Whether the `r`, `g` and `b` values have already
+   * been multiplied by alpha. If `true` nothing happens if `false` then they will
+   * be multiplied automatically.
+   */
+  constructor(r: number, g: number, b: number, alpha?: number, premultiplied?: boolean);
+  static black: Color;
+  static white: Color;
+  static transparent: Color;
+  static red: Color;
+  /**
+   * Parses CSS color strings and converts colors to sRGB color space if needed.
+   * Officially supported color formats:
+   * - keyword, e.g. 'aquamarine' or 'steelblue'
+   * - hex (with 3, 4, 6 or 8 digits), e.g. '#f0f' or '#e9bebea9'
+   * - rgb and rgba, e.g. 'rgb(0,240,120)' or 'rgba(0%,94%,47%,0.1)' or 'rgb(0 240 120 / .3)'
+   * - hsl and hsla, e.g. 'hsl(0,0%,83%)' or 'hsla(0,0%,83%,.5)' or 'hsl(0 0% 83% / 20%)'
+   *
+   * @param input CSS color string to parse.
+   * @returns A `Color` instance, or `undefined` if the input is not a valid color string.
+   */
+  static parse(input: Color | string | undefined | null): Color | undefined;
+  /**
+   * Used in color interpolation and by 'to-rgba' expression.
+   *
+   * @returns Gien color, with reversed alpha blending, in sRGB color space.
+   */
+  get rgb(): RGBColor;
+  /**
+   * Used in color interpolation.
+   *
+   * @returns Gien color, with reversed alpha blending, in HCL color space.
+   */
+  get hcl(): HCLColor;
+  /**
+   * Used in color interpolation.
+   *
+   * @returns Gien color, with reversed alpha blending, in LAB color space.
+   */
+  get lab(): LABColor;
+  /**
+   * Lazy getter pattern. When getter is called for the first time lazy value
+   * is calculated and then overwrites getter function in given object instance.
+   *
+   * @example:
+   * const redColor = Color.parse('red');
+   * let x = redColor.hcl; // this will invoke `get hcl()`, which will calculate
+   * // the value of red in HCL space and invoke this `overwriteGetter` function
+   * // which in turn will set a field with a key 'hcl' in the `redColor` object.
+   * // In other words it will override `get hcl()` from its `Color` prototype
+   * // with its own property: hcl = [calculated red value in hcl].
+   * let y = redColor.hcl; // next call will no longer invoke getter but simply
+   * // return the previously calculated value
+   * x === y; // true - `x` is exactly the same object as `y`
+   *
+   * @param getterKey Getter key
+   * @param lazyValue Lazily calculated value to be memoized by current instance
+   * @private
+   */
+  private overwriteGetter;
+  /**
+   * Used by 'to-string' expression.
+   *
+   * @returns Serialized color in format `rgba(r,g,b,a)`
+   * where r,g,b are numbers within 0..255 and alpha is number within 1..0
+   *
+   * @example
+   * var purple = new Color.parse('purple');
+   * purple.toString; // = "rgba(128,0,128,1)"
+   * var translucentGreen = new Color.parse('rgba(26, 207, 26, .73)');
+   * translucentGreen.toString(); // = "rgba(26,207,26,0.73)"
+   */
+  toString(): string;
+  static interpolate(from: Color, to: Color, t: number, spaceKey?: InterpolationColorSpace): Color;
+}
+//#endregion
+//#region src/point2d.d.ts
+interface Point2D$1 {
+  x: number;
+  y: number;
+}
+//#endregion
+//#region src/expression/index.d.ts
+type Feature$1 = {
+  readonly type: 0 | 1 | 2 | 3 | 'Unknown' | 'Point' | 'MultiPoint' | 'LineString' | 'MultiLineString' | 'Polygon' | 'MultiPolygon';
+  readonly id?: any;
+  readonly properties: {
+    [_: string]: any;
+  };
+  readonly patterns?: {
+    [_: string]: {
+      min: string;
+      mid: string;
+      max: string;
+    };
+  };
+  readonly dashes?: {
+    [_: string]: {
+      min: string;
+      mid: string;
+      max: string;
+    };
+  };
+  readonly geometry?: Array<Array<Point2D$1>>;
+};
+
+type Properties = Record<string, unknown>;
+type Patterns = Record<string, {
+    min: string;
+    mid: string;
+    max: string;
+}>;
+type Geometry = Point2D[][];
+type Bbox = [number, number, number, number];
+declare class Point2D implements Point2D$1 {
+    x: number;
+    y: number;
+    constructor(x: number, y: number);
+    isZero(): boolean;
+    scale(factor: number): this;
+    translate(offset: Point2D): this;
+    getProject2Pixel(): Point2D;
+}
+declare class Feature implements Feature$1 {
+    #private;
+    readonly type: 'LineString' | 'Point' | 'Polygon';
+    readonly id: unknown;
+    readonly properties: Properties;
+    readonly patterns?: Patterns;
+    readonly geometry: Geometry;
+    /**
+     * The boundary of a polygon for the fill-antialias outline, as open polylines — when it
+     * differs from the polygon's rings, i.e. when the polygon was clipped to its tile: the
+     * clipped edges along the tile border are not part of the outline.
+     */
+    readonly outline?: Geometry;
+    constructor(opt: {
+        type: 'LineString' | 'Point' | 'Polygon';
+        id?: unknown;
+        properties: Properties;
+        patterns?: Patterns;
+        geometry: Geometry;
+        outline?: Geometry;
+    });
+    getBbox(): Bbox;
+    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;
+}
 
-/** Options for {@link renderToSVG}. */
-interface RenderToSVGOptions {
+/**
+ * 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
+ * kind: the SVG backend serializes to a string ({@link StringRenderer}), while a raster
+ * backend produces an encoded image buffer.
+ */
+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;
+    drawCircles(id: string, features: [Feature, CircleStyle][]): void;
+    drawLabels(id: string, features: [Feature, SymbolStyle][]): void;
+    /**
+     * These two may be asynchronous. Their images arrive as data URIs, which a raster
+     * backend has to decode before it can paint them, while the SVG backend simply embeds
+     * the URI and stays synchronous. The pipeline awaits both, so layers keep their order
+     * either way.
+     */
+    drawIcons(id: string, features: [Feature, IconStyle][], spriteAtlas: SpriteAtlas): void | Promise<void>;
+    drawRasterTiles(id: string, tiles: RasterTile[], style: RasterStyle): void | Promise<void>;
+    /** Restricts all drawing to a circle (the silhouette of the globe). */
+    setClipCircle?(circle: ClipCircle): void;
+    /**
+     * Called once the map is complete: undoes any state set up for drawing it (such as the
+     * clip circle), so that whoever gets the result can keep drawing on it.
+     */
+    finish?(): void;
+}
+interface BackgroundStyle {
+    color: Color;
+    opacity: number;
+}
+interface FillStyle {
+    color: Color;
+    opacity: number;
+    translate: [number, number];
+    /**
+     * fill-outline-color. When omitted the fill `color` is used (MapLibre's
+     * default: the antialias outline is drawn in the fill color).
+     */
+    outlineColor?: Color;
+    /**
+     * fill-antialias. When truthy, a ~1px edge outline in `outlineColor` is drawn
+     * over all fills of the layer (a separate pass) so a lower feature's border
+     * composites on top of later overlapping fills — matching MapLibre for
+     * choropleths and stacked polygons.
+     */
+    antialias?: boolean;
+}
+interface LineStyle {
+    blur: number;
+    cap: 'butt' | 'round' | 'square';
+    color: Color;
+    dasharray?: number[];
+    join: 'bevel' | 'miter' | 'round';
+    miterLimit: number;
+    offset: number;
+    opacity: number;
+    translate: [number, number];
+    width: number;
+}
+interface CircleStyle {
+    color: Color;
+    opacity: number;
+    radius: number;
+    translate: [number, number];
+    strokeWidth: number;
+    strokeColor: Color;
+}
+interface RasterStyle {
+    opacity: number;
+    hueRotate: number;
+    brightnessMin: number;
+    brightnessMax: number;
+    saturation: number;
+    contrast: number;
+    resampling: 'linear' | 'nearest';
+}
+interface SymbolStyle {
+    text: string;
+    size: number;
+    font: string[];
+    anchor: string;
+    offset: [number, number];
+    rotate: number;
+    color: Color;
+    opacity: number;
+    haloColor: Color;
+    haloWidth: number;
+}
+interface IconStyle {
+    image: string;
+    size: number;
+    anchor: string;
+    offset: [number, number];
+    rotate: number;
+    opacity: number;
+    sdf: boolean;
+    color: Color;
+    haloColor: Color;
+    haloWidth: number;
+}
+interface RasterTile {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    dataUri: string;
+    /**
+     * On the globe a tile cannot be drawn as a rectangle. Instead it is split into a mesh of
+     * triangles, each drawn with its own affine transform.
+     */
+    triangles?: RasterTriangle[];
+}
+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;
+}
+
+/** 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. Styles
-     * built with `@versatiles/style` come in that form, so pass them through its
-     * `inlineSources()` first — see the examples on {@link renderToSVG}.
+     * **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.
      */
     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`.
+     * @defaultValue `false`
+     */
+    renderLabels?: boolean;
+    /**
+     * How much memory the fetched tiles may take, in bytes. Tiles are kept so that
+     * rendering an overlapping view does not fetch them again; beyond this size, the least
+     * recently used ones are dropped. `0` keeps none.
+     *
+     * Tiles are kept for the lifetime of the instance, regardless of the HTTP caching
+     * headers they were served with; see {@link SVGMapRenderer.clearCache}.
+     * @defaultValue `134217728` (128 MB)
+     */
+    tileCacheSize?: number;
+    /**
+     * Loads tiles and sprites, 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
+     * server has no such tile, which is remembered (see {@link SVGMapRendererOptions.tileCacheSize}); any other
+     * error status, or a rejected promise, counts as failed, and the next render tries
+     * again.
+     * @defaultValue the global `fetch`
+     */
+    fetch?: FetchFunction;
+}
+/** The view to render: size, centre and zoom. */
+interface ViewOptions {
     /**
      * Width of the image in pixels.
      * @defaultValue `1024`
@@ -2598,20 +2986,100 @@ interface RenderToSVGOptions {
      * @defaultValue `2`
      */
     zoom?: number;
+}
+/**
+ * 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
+ * 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.
+ *
+ * The style is read when the instance is created and is expected not to change
+ * afterwards; to render a changed style, create a new instance. Renders may run
+ * concurrently.
+ *
+ * @example Render several views of one style
+ * ```ts
+ * import { SVGMapRenderer } from '@versatiles/svg-renderer';
+ *
+ * const map = new SVGMapRenderer({ style });
+ *
+ * const berlin = await map.renderSVG({ lon: 13.4, lat: 52.52, zoom: 12 });
+ * const potsdam = await map.renderSVG({ lon: 13.06, lat: 52.4, zoom: 12 });
+ * ```
+ */
+declare class SVGMapRenderer {
+    #private;
     /**
-     * Draw the style's symbol layers: text labels and icons.
+     * @param options - The style, whether to draw labels, the tile cache size, and how to
+     *   load tiles and sprites.
+     * @throws If `tileCacheSize` is negative or not a number.
+     */
+    constructor(options: SVGMapRendererOptions);
+    /**
+     * Renders one view of the map as SVG. The result is a single self-contained SVG
+     * document, as described on {@link renderToSVG}.
      *
-     * 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.
+     * @param view - Size, centre and zoom. All optional.
+     * @returns The SVG document, as a string beginning with `<svg`.
+     * @throws If `width` or `height` is not positive.
+     */
+    renderSVG(view?: ViewOptions): Promise<string>;
+    /**
+     * Forgets the fetched tiles and sprite, so the next render fetches them again, e.g.
+     * after they were updated on the server, or to free their memory.
+     */
+    clearCache(): void;
+    /** Draws `view` onto `renderer`, which must already have the view's size. */
+    protected draw<R extends Renderer>(renderer: R, view: ViewOptions): Promise<R>;
+    /**
+     * Where a coordinate lands in the image of `view`: its position in the units of
+     * `width` and `height`, the same in the SVG and on the canvas of `renderCanvas`. Use
+     * it to place your own drawing on the map.
      *
-     * 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`.
-     * @defaultValue `false`
+     * On the globe, a coordinate on its far side is hidden; then this returns `undefined`.
+     * A position outside the image is returned as is, so it can lie beyond `width` and
+     * `height`, or be negative. The map ends at about ±85.05° latitude, as in MapLibre: a
+     * latitude beyond that, up to the poles, gives the position of the map's edge.
+     *
+     * @example Mark a place on a rendered canvas
+     * ```ts
+     * const view = { lon: 13.4, lat: 52.52, zoom: 12 };
+     * const canvas = await map.renderCanvas(view);
+     * const [x, y] = map.project(view, [13.3777, 52.5163])!; // Brandenburg Gate
+     * const ctx = canvas.getContext('2d');
+     * ctx.beginPath();
+     * ctx.arc(x, y, 6, 0, 2 * Math.PI);
+     * ctx.fill();
+     * ```
+     *
+     * @param view - The view the image was rendered with.
+     * @param lonLat - Longitude and latitude, in degrees.
+     * @returns `[x, y]`, or `undefined` for a point hidden on the globe, and for a
+     *   longitude or latitude that is not a finite number.
+     * @throws If `width` or `height` is not positive.
      */
-    renderLabels?: boolean;
+    project(view: ViewOptions, lonLat: [number, number]): [number, number] | undefined;
+    /**
+     * The opposite of {@link SVGMapRenderer.project}: the coordinate shown at a position in
+     * the image of `view`, e.g. where a user clicked on it.
+     *
+     * Where the image shows no map — next to the globe, or beyond the poles of the mercator
+     * map (about ±85°) — this returns `undefined`. The longitude is between -180 and 180.
+     *
+     * @param view - The view the image was rendered with.
+     * @param xy - A position in the units of `width` and `height`.
+     * @returns `[lon, lat]` in degrees, or `undefined` where there is no map, and for a
+     *   position that is not a finite number.
+     * @throws If `width` or `height` is not positive.
+     */
+    unproject(view: ViewOptions, xy: [number, number]): [number, number] | undefined;
+}
+
+/** Options for {@link renderToSVG}: the style and the view, in one object. */
+interface RenderToSVGOptions extends Omit<SVGMapRendererOptions, 'tileCacheSize'>, ViewOptions {
 }
 /**
  * Renders a MapLibre style to an SVG image.
@@ -2625,38 +3093,18 @@ interface RenderToSVGOptions {
  * `@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);
- * ```
+ * Each call starts from scratch: it parses the style and fetches the tiles and the
+ * sprite again. To render many views of one style, use {@link SVGMapRenderer}, which
+ * keeps them between renders.
  *
- * @example Render a hosted style in the browser
+ * @example Render a map
  * ```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());
+ * const url = 'https://tiles.versatiles.org/assets/styles/colorful/style.json';
+ * const style = await (await fetch(url)).json();
  *
- * document.body.innerHTML = await renderToSVG({ style, width: 800, height: 600, zoom: 3 });
+ * const svg = await renderToSVG({ style, lon: 13.4, lat: 52.52, zoom: 12 });
  * ```
  *
  * @example Include labels and icons
@@ -2670,5 +3118,5 @@ interface RenderToSVGOptions {
  */
 declare function renderToSVG(options: RenderToSVGOptions): Promise<string>;
 
-export { renderToSVG };
-export type { RenderToSVGOptions };
+export { SVGMapRenderer, renderToSVG };
+export type { FetchFunction, FetchResponse, RenderToSVGOptions, SVGMapRendererOptions, ViewOptions };