@reearth/ezu 0.12.0 → 0.13.0

package/README.md

@@ -103,12 +103,17 @@ bytes a browser may download, so for now the choice is explicit.
 
 ```ts
 function simdEnabled(): boolean;
+// How many node ops the module registered, and their names.
+function opCount(): number;
+function opNames(): string[];
 
 class Renderer {
   constructor(styleJson: string);
 
   setStyle(styleJson: string): number;            // → new node count
   readonly tileSize: number;
+  readonly renderTileSize: number;  // what renders use: setTileSize's, or tileSize
+  readonly warnings: string[];  // what building the style's graph warned about
 
   // Bind tile bytes under a `sources.<name>` entry from the style.
   // The renderer dispatches on the source's declared `type`:
@@ -136,16 +141,25 @@ class Renderer {
     indexUrl?: string;          // a sprite index that is a URL, not inline
   }>;
 
-  // Cap the resident glyph bytes per fontstack. 0xFFFFFFFF lifts the cap
-  // (and reads back as `Infinity` from `memoryUsage().glyphBudget`).
+  // Cap the resident glyph bytes per fontstack. clearGlyphBudget() lifts
+  // the cap, as does 0xFFFFFFFF (it reads back as `Infinity` from
+  // `memoryUsage().glyphBudget`).
   setGlyphBudget(bytes: number): void;
+  clearGlyphBudget(): void;
+
+  // Let the render cache hold `bytes` of pixels instead of its default
+  // (8 MiB); clearCacheBudget() goes back. Kept through setStyle.
+  setCacheBudget(bytes: number): void;
+  clearCacheBudget(): void;
 
   // Single unified render. `opts.format` picks the encoder; `tileSize`
-  // / `pad` override the canvas for hi-DPI / preview.
+  // / `pad` override the canvas (in style pixels); `pixelRatio` renders
+  // the same tile at a higher density for hi-DPI screens.
   renderTile(z: number, x: number, y: number, opts?: {
     format?: "png" | "webp" | "rgba";      // default "png"
     tileSize?: number;
     pad?: number;
+    pixelRatio?: number;                   // 1 to 4, default 1
     // Render-time overrides for the style's declared `params`, validated
     // against the declarations (type, min/max) — an unknown name or an
     // out-of-range value throws. Names left out keep their default. One
@@ -154,10 +168,141 @@ class Renderer {
     png?: { compression?: "fast" | "default" | "best" };
   }): Uint8Array;
 
+  // Decode a tile-scoped payload (mvt, pmtiles, dem, raster, remote
+  // geojson) once, to sit in the set of every render that reads it.
+  loadSource(name: string, bytes: Uint8Array): SourceData;
+
+  // renderTile, from a set of loaded data instead of what is bound. Does
+  // not trim glyphs to the budget; call trimGlyphs() after a batch.
+  renderTileWith(z: number, x: number, y: number, set: SourceSet,
+                 opts?: object /* renderTile's opts */): Uint8Array;
+
+  // renderTileWith, also handing back what the named features nodes held:
+  // one { node, extent, geojson } per node, geojson being a GeoJSON
+  // FeatureCollection as text in tile units (0..extent). Pass
+  // { nodes, coords: "lonlat" | "px" } for WGS84 or the tile's pixels.
+  renderTileWithFeatures(z: number, x: number, y: number, set: SourceSet,
+                         nodes: string[] | { nodes: string[];
+                                             coords?: "tile" | "lonlat" | "px" },
+                         opts?: object): TileWithFeatures;
+
+  // neededCodepoints / neededGlyphRanges for the features in a set.
+  neededCodepointsIn(set: SourceSet): Record<string, number[]>;
+  neededGlyphRangesIn(set: SourceSet): Record<string, number[]>;
+
+  // Bring the glyph banks back under setGlyphBudget's budget.
+  trimGlyphs(): void;
+
+  // Render every tile at `size` px instead of the style's tile-size,
+  // without editing the style, until `clearTileSize()` or `setStyle`.
+  setTileSize(size: number): void;
+  clearTileSize(): void;
+
+  // Print frames — see "A page at a print scale" below.
+  computeFrame(req: FrameRequest): Frame;
+  renderFrame(
+    frame: Frame,
+    sources: ((tile: { z: number; x: number; y: number },
+               binder: FrameBinder) => SourceSet | Promise<SourceSet>)
+      | null | undefined,
+    opts?: { pad?: number; params?: Record<string, number | boolean | string> },
+  ): Promise<Uint8Array>;                    // straight RGBA, width × height
+  // renderFrame, also gathering features nodes over the page: each node's
+  // page as the GeoJSON text `ezu frame --features` writes.
+  renderFrameWithFeatures(
+    frame: Frame, sources: /* as renderFrame */ any,
+    request: { nodes: { node: string; key?: string[] }[];
+               coords?: "lonlat" | "px" },
+    opts?: { pad?: number; params?: Record<string, number | boolean | string> },
+  ): Promise<{ image: Uint8Array; features: { node: string; geojson: string }[] }>;
+
+  free(): void;
+}
+
+// One decoded tile. Sets that hold it keep it alive.
+class SourceData {
+  readonly source: string;                   // the sources.<name> it is for
   free(): void;
 }
+
+// The tile data one render reads, each at its place in the 3×3.
+class SourceSet {
+  constructor();
+  bind(data: SourceData,
+       opts?: { coord?: [number, number]; sourceZoom?: number }): void;
+  contains(source: string): boolean;
+  isEmpty(): boolean;
+  clone(): SourceSet;                        // shares the data
+  free(): void;
+}
+
+// Handed to renderFrame's sources: bindSource into the renderer (glyphs,
+// fonts, sprites — not tile data, which goes in the set) for that tile
+// only, until its sources returns or settles (then it throws StaleBinder).
+class FrameBinder {
+  bindSource(name: string, bytes: Uint8Array,
+             opts?: { coord?: [number, number]; sourceZoom?: number }): void;
+}
+
+interface FrameRequest {
+  centerLon: number; centerLat: number;      // degrees, WGS84
+  scale: number;                             // 1000 for 1:1000
+  dpi: number;
+  width: number; height: number;             // output pixels
+  zoom?: number;                             // the CLI's --zoom
+  styleTileSize?: number;                    // default: the style's
+}
+
+interface Frame {
+  zoom: number; tileSize: number;            // what the tiles render at
+  scale: number;                             // the denominator met
+  width: number; height: number;
+  left: number; top: number;                 // corner, in world pixels
+  shift: [number, number];                   // rounding, within ±0.5 px
+  tilesX: [number, number];                  // start inclusive, end exclusive
+  tilesY: [number, number];
+}
+```
+
+## A page at a print scale
+
+A printed page is asked for as "1:1000 at 200 dpi, 245 × 174 mm, centred
+here", not as a zoom. `computeFrame` picks the zoom and tile size that
+meet the scale and the tiles the page covers; `renderFrame` renders them,
+calling you back for the `SourceSet` each one renders from, and crops them
+into one RGBA page — the same page `ezu frame` writes, pixel for pixel:
+
+```js
+const mm = (length, dpi) => Math.round(length / 25.4 * dpi);
+const f = renderer.computeFrame({
+  centerLon: 139.70, centerLat: 35.68,
+  scale: 1000, dpi: 200,
+  width: mm(245, 200), height: mm(174, 200),   // 1929 × 1370
+});
+const loaded = new Map();                      // each fetched tile, decoded once
+const rgba = await renderer.renderFrame(f, async ({ z, x, y }, binder) => {
+  const key = `${z}/${x}/${y}`;
+  if (!loaded.has(key)) {
+    loaded.set(key, renderer.loadSource("basemap", await fetchMvt(z, x, y)));
+  }
+  const set = new SourceSet();
+  set.bind(loaded.get(key));                   // and the neighbours, at their coord
+  return set;
+});
 ```
 
+A page's tiles border each other, so a `SourceData` kept for the tiles
+around it is decoded once however many of them read it. Until the promise
+settles the renderer is the frame's: glyphs a set needs are bound through
+the `binder` you are handed, which works only for its own tile and only
+until that call returns or settles. Calls that would change the renderer —
+`bindSource`, `clearSources`, `renderTile`, `trimGlyphs`, another
+`renderFrame`, `setStyle`, `setTileSize`, `clearTileSize`,
+`setGlyphBudget`, `clearGlyphBudget` — throw `FrameInProgress` meanwhile, so another request
+cannot change the frame's tiles under it. `loadSource`, `renderTileWith`
+and queries that only read, such as `sourceTile` and `neededCodepointsIn`,
+still work.
+
 ## Output formats
 
 - **`format: "png"`** (default) returns PNG bytes — feed to `<img>`
@@ -195,6 +340,8 @@ discriminates the kind:
 | `RenderFailed` | A node `eval` failed (e.g. missing brush, downcast mismatch) |
 | `PngEncode`    | PNG encoding failed |
 | `WebpEncode`   | WebP encoding failed |
+| `FrameInProgress` | A call would change a renderer that a `renderFrame` holds until its promise settles |
+| `StaleBinder`  | A frame's `binder` was used after its tile's `sources` returned or settled |
 
 ```js
 try {