@mailwoman/map-tui 9.1.0

package/renderer.ts

@@ -0,0 +1,297 @@
+/**
+ * @copyright Sister Software.
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+
+/**
+ * Viewport-to-braille-frame renderer for map-tui's debug view.
+ *
+ * `MapRenderer.renderFrame` is the package's single public entry point: given a `Viewport` (center lon/lat, zoom, cell
+ * columns/rows), it fetches the covering tiles from a `TileSource`, rasterizes styled geometry (./style.ts,
+ * ./raster.ts) into a subpixel RGBA grid, converts that grid to braille cells (./frame.ts), then overlays collected
+ * labels and marker/ring annotations on top. Draw order is fill → line → label per the layer style table, with overlays
+ * (ring, labels, markers) layered afterward in that order — markers deliberately skip the label collision bitmap so a
+ * requested marker always wins the cell.
+ */
+
+import { type MapFrame, overlayText, rasterizeToFrame, rgbToPacked } from "./frame.ts"
+import { lonLatToWorldPx, metersPerPixel, TILE_SIZE } from "./mercator.ts"
+import type { DecodedFeature } from "./mvt.ts"
+import { drawCircle, drawPolyline, fillPolygon, RGBAGrid } from "./raster.ts"
+import { type LayerStyle, type RGB, stylesFor } from "./style.ts"
+import type { DecodedTile, TileSource } from "./tile-source.ts"
+
+export interface Viewport {
+	centerLon: number
+	centerLat: number
+	zoom: number
+	columns: number
+	rows: number
+}
+
+export interface MarkerSpec {
+	lon: number
+	lat: number
+	char?: string
+	color?: RGB
+}
+
+export interface RingSpec {
+	lon: number
+	lat: number
+	radiusMeters: number
+}
+
+const DEFAULT_MARKER_CHAR = "●"
+const DEFAULT_MARKER_COLOR: RGB = [255, 80, 80]
+
+/**
+ * Subpixel dimensions per braille cell: 2 columns wide, 4 rows tall.
+ */
+const SUBPIXEL_COLUMNS_PER_CELL = 2
+const SUBPIXEL_ROWS_PER_CELL = 4
+
+/**
+ * Minimum ring radius (in device pixels) worth drawing — smaller than this, the midpoint circle algorithm degenerates
+ * to a single point or nothing useful.
+ */
+const MIN_RING_RADIUS_PX = 2
+
+interface ProjectedPoint {
+	x: number
+	y: number
+}
+
+interface PendingLabel {
+	text: string
+	column: number
+	row: number
+	color: number
+}
+
+/**
+ * Origin of the render's subpixel grid, in world (Mercator) pixels — everything projected onto the grid is offset by
+ * this pair.
+ */
+interface GridOrigin {
+	x: number
+	y: number
+}
+
+/**
+ * Everything a point projection needs, bundled so the per-feature rasterizers below take one parameter instead of four
+ * — that's what keeps `rasterizeFeature` under `max-params` (8) once `style`, `renderZoom`, and `pendingLabels` join
+ * it. Threaded through as a value rather than closed over so those rasterizers stay free functions (no nesting inside
+ * `renderFrame` deep enough to trip `max-depth`).
+ */
+interface TileProjection {
+	tileX: number
+	tileY: number
+	scale: number
+	origin: GridOrigin
+}
+
+function clamp(value: number, min: number, max: number): number {
+	return Math.min(Math.max(value, min), max)
+}
+
+function projectPoint(projection: TileProjection, gx: number, gy: number): ProjectedPoint {
+	return {
+		x: projection.tileX * TILE_SIZE + gx * projection.scale - projection.origin.x,
+		y: projection.tileY * TILE_SIZE + gy * projection.scale - projection.origin.y,
+	}
+}
+
+function rasterizeFill(grid: RGBAGrid, feature: DecodedFeature, projection: TileProjection, color: RGB): void {
+	const rings = feature.geometry.map((ring) => ring.map((point) => projectPoint(projection, point.x, point.y)))
+
+	fillPolygon(grid, rings, color)
+}
+
+function rasterizeLine(
+	grid: RGBAGrid,
+	feature: DecodedFeature,
+	projection: TileProjection,
+	color: RGB,
+	width: number
+): void {
+	for (const part of feature.geometry) {
+		const points = part.map((point) => projectPoint(projection, point.x, point.y))
+
+		drawPolyline(grid, points, color, width)
+	}
+}
+
+function collectLabels(
+	feature: DecodedFeature,
+	property: string,
+	color: RGB,
+	projection: TileProjection,
+	pendingLabels: PendingLabel[]
+): void {
+	const text = String(feature.properties[property] ?? "")
+
+	if (!text.length) return
+
+	const packedColor = rgbToPacked(color)
+
+	for (const part of feature.geometry) {
+		for (const point of part) {
+			const projected = projectPoint(projection, point.x, point.y)
+
+			pendingLabels.push({
+				text,
+				column: Math.floor(projected.x / SUBPIXEL_COLUMNS_PER_CELL),
+				row: Math.floor(projected.y / SUBPIXEL_ROWS_PER_CELL),
+				color: packedColor,
+			})
+		}
+	}
+}
+
+/**
+ * Rasterizes (or, for labels, collects) one feature under one style. The `style.kind` dispatch is the only branching
+ * here — the actual per-kind work lives in {@link rasterizeFill}/{@link rasterizeLine}/{@link collectLabels} so this
+ * stays a flat one-level `if`/`else` regardless of how deeply its caller is already nested.
+ */
+function rasterizeFeature(
+	grid: RGBAGrid,
+	feature: DecodedFeature,
+	style: LayerStyle,
+	renderZoom: number,
+	projection: TileProjection,
+	pendingLabels: PendingLabel[]
+): void {
+	if (style.kind === "fill") {
+		rasterizeFill(grid, feature, projection, style.color)
+	} else if (style.kind === "line") {
+		rasterizeLine(grid, feature, projection, style.color, style.width(renderZoom))
+	} else {
+		collectLabels(feature, style.property, style.color, projection, pendingLabels)
+	}
+}
+
+/**
+ * Rasterizes every layer/style/feature in one tile matching `kind`. Pulled out of {@link MapRenderer.renderFrame} so
+ * that method's own tile loop doesn't accumulate this function's three nested loops on top of its own.
+ */
+function rasterizeTileForKind(
+	grid: RGBAGrid,
+	tile: DecodedTile,
+	tileX: number,
+	tileY: number,
+	kind: LayerStyle["kind"],
+	renderZoom: number,
+	origin: GridOrigin,
+	pendingLabels: PendingLabel[]
+): void {
+	for (const layer of tile.layers) {
+		const styles = stylesFor(layer.name, renderZoom).filter((style) => style.kind === kind)
+
+		if (!styles.length) continue
+
+		const projection: TileProjection = { tileX, tileY, scale: TILE_SIZE / layer.extent, origin }
+
+		for (const style of styles) {
+			for (const feature of layer.features) {
+				rasterizeFeature(grid, feature, style, renderZoom, projection, pendingLabels)
+			}
+		}
+	}
+}
+
+/**
+ * Walks a viewport's rendering pipeline: tile fetch, style-ordered rasterization, braille conversion, then overlay
+ * annotations (ring, labels, markers). One `MapRenderer` can render any number of viewports against the same
+ * `TileSource` — it holds no per-frame state itself.
+ */
+export class MapRenderer {
+	private readonly source: TileSource
+
+	constructor(source: TileSource) {
+		this.source = source
+	}
+
+	async renderFrame(viewport: Viewport, overlays?: { markers?: MarkerSpec[]; ring?: RingSpec }): Promise<MapFrame> {
+		const { centerLon, centerLat, columns, rows } = viewport
+
+		const subpixelW = columns * SUBPIXEL_COLUMNS_PER_CELL
+		const subpixelH = rows * SUBPIXEL_ROWS_PER_CELL
+
+		const renderZoom = clamp(Math.round(viewport.zoom), this.source.minZoom, this.source.maxZoom)
+		const center = lonLatToWorldPx(centerLon, centerLat, renderZoom)
+		const origin: GridOrigin = { x: center.x - subpixelW / 2, y: center.y - subpixelH / 2 }
+
+		const zoomTileCount = 2 ** renderZoom
+		const minTileX = clamp(Math.floor(origin.x / TILE_SIZE), 0, zoomTileCount - 1)
+		const maxTileX = clamp(Math.floor((origin.x + subpixelW) / TILE_SIZE), 0, zoomTileCount - 1)
+		const minTileY = clamp(Math.floor(origin.y / TILE_SIZE), 0, zoomTileCount - 1)
+		const maxTileY = clamp(Math.floor((origin.y + subpixelH) / TILE_SIZE), 0, zoomTileCount - 1)
+
+		const tileCoords: Array<{ x: number; y: number }> = []
+
+		for (let tileY = minTileY; tileY <= maxTileY; tileY++) {
+			for (let tileX = minTileX; tileX <= maxTileX; tileX++) {
+				tileCoords.push({ x: tileX, y: tileY })
+			}
+		}
+
+		const tiles = await Promise.all(tileCoords.map((coord) => this.source.getTile(renderZoom, coord.x, coord.y)))
+
+		const grid = new RGBAGrid(subpixelW, subpixelH)
+		const pendingLabels: PendingLabel[] = []
+
+		for (const kind of ["fill", "line", "label"] as const) {
+			for (let i = 0; i < tileCoords.length; i++) {
+				const tile = tiles[i]
+
+				if (!tile) continue
+
+				const { x: tileX, y: tileY } = tileCoords[i]!
+
+				rasterizeTileForKind(grid, tile, tileX, tileY, kind, renderZoom, origin, pendingLabels)
+			}
+		}
+
+		if (overlays?.ring) {
+			const { lon, lat, radiusMeters } = overlays.ring
+			const radiusPx = radiusMeters / metersPerPixel(lat, renderZoom)
+
+			if (radiusPx >= MIN_RING_RADIUS_PX) {
+				const ringCenterWorld = lonLatToWorldPx(lon, lat, renderZoom)
+				const ringColor: RGB = [255, 255, 255]
+
+				drawCircle(grid, ringCenterWorld.x - origin.x, ringCenterWorld.y - origin.y, radiusPx, ringColor)
+			}
+		}
+
+		const frame = rasterizeToFrame(grid, columns, rows, this.source.attribution)
+
+		const occupied = new Uint8Array(columns * rows)
+
+		for (const label of pendingLabels) {
+			overlayText(frame, label.column, label.row, label.text, label.color, occupied)
+		}
+
+		if (overlays?.markers) {
+			for (const marker of overlays.markers) {
+				const markerWorld = lonLatToWorldPx(marker.lon, marker.lat, renderZoom)
+				const px = markerWorld.x - origin.x
+				const py = markerWorld.y - origin.y
+				const column = Math.floor(px / SUBPIXEL_COLUMNS_PER_CELL)
+				const row = Math.floor(py / SUBPIXEL_ROWS_PER_CELL)
+
+				overlayText(
+					frame,
+					column,
+					row,
+					marker.char ?? DEFAULT_MARKER_CHAR,
+					rgbToPacked(marker.color ?? DEFAULT_MARKER_COLOR)
+				)
+			}
+		}
+
+		return frame
+	}
+}

package/style.ts

@@ -0,0 +1,62 @@
+/**
+ * @copyright Sister Software.
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+
+/**
+ * Protomaps-basemap style table for the map-tui debug view.
+ *
+ * Defines fill, line, and label styles for each of the nine protomaps-basemap layers, gated by zoom level. Color
+ * palette calibrated for dark-terminal rendering: dim fills (read as stipple density via dithering), bright lines and
+ * labels.
+ */
+
+export type RGB = readonly [red: number, green: number, blue: number]
+
+export interface FillStyle {
+	kind: "fill"
+	color: RGB
+	minZoom: number
+}
+
+export interface LineStyle {
+	kind: "line"
+	color: RGB
+	minZoom: number
+	width: (zoom: number) => number
+}
+
+export interface LabelStyle {
+	kind: "label"
+	color: RGB
+	minZoom: number
+	property: string
+}
+
+export type LayerStyle = FillStyle | LineStyle | LabelStyle
+
+// Zoom level at which roads render with 2px width instead of 1px.
+const ROAD_WIDTH_THRESHOLD = 14
+
+const STYLE_TABLE: Record<string, LayerStyle[]> = {
+	earth: [{ kind: "fill", color: [40, 44, 36], minZoom: 0 }],
+	landcover: [{ kind: "fill", color: [36, 52, 32], minZoom: 4 }],
+	landuse: [{ kind: "fill", color: [48, 48, 40], minZoom: 10 }],
+	water: [{ kind: "fill", color: [24, 48, 90], minZoom: 0 }],
+	buildings: [{ kind: "fill", color: [70, 66, 60], minZoom: 13 }],
+	boundaries: [{ kind: "line", color: [140, 110, 160], minZoom: 0, width: () => 1 }],
+	roads: [
+		{ kind: "line", color: [170, 170, 150], minZoom: 6, width: (zoom) => (zoom >= ROAD_WIDTH_THRESHOLD ? 2 : 1) },
+	],
+	places: [{ kind: "label", color: [235, 235, 220], minZoom: 2, property: "name" }],
+	pois: [{ kind: "label", color: [180, 200, 160], minZoom: 14, property: "name" }],
+}
+
+/**
+ * Styles applying to a protomaps-basemap layer at a zoom, draw-ordered (fills < lines < labels). Empty for
+ * unstyled/gated layers.
+ */
+export function stylesFor(layerName: string, zoom: number): LayerStyle[] {
+	return (STYLE_TABLE[layerName] ?? []).filter((style) => zoom >= style.minZoom)
+}

package/tile-source.ts

@@ -0,0 +1,130 @@
+/**
+ * @copyright Sister Software.
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+
+/**
+ * PMTiles archive reader for map-tui.
+ *
+ * TileSource wraps a local `.pmtiles` file (node:fs/promises FileHandle) behind the pmtiles `Source` interface, decodes
+ * each requested tile's MVT payload via ./mvt.ts, and keeps a small LRU cache of decoded tiles so repeated draws of the
+ * same viewport don't re-decode.
+ */
+
+import { type FileHandle, open } from "node:fs/promises"
+
+import { PMTiles, type RangeResponse, type Source } from "pmtiles"
+
+import { type DecodedLayer, decodeMVT } from "./mvt.ts"
+
+export interface DecodedTile {
+	layers: DecodedLayer[]
+}
+
+class FilePMTilesSource implements Source {
+	private readonly path: string
+	private readonly handle: FileHandle
+
+	constructor(path: string, handle: FileHandle) {
+		this.path = path
+		this.handle = handle
+	}
+
+	getKey(): string {
+		return this.path
+	}
+
+	async getBytes(offset: number, length: number): Promise<RangeResponse> {
+		const buffer = Buffer.alloc(length)
+		const { bytesRead } = await this.handle.read(buffer, 0, length, offset)
+
+		return { data: buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + bytesRead) }
+	}
+}
+
+const TILE_CACHE_LIMIT = 64
+
+/**
+ * A single LRU cache slot. Wrapping the decoded tile in an object lets `getTile` tell "cached and known absent" (`{
+ * tile: null }`) apart from "not yet cached" (no entry in the Map) using plain presence, with no comparison against
+ * `undefined` needed.
+ */
+interface CacheEntry {
+	tile: DecodedTile | null
+}
+
+export class TileSource {
+	readonly minZoom: number
+	readonly maxZoom: number
+
+	/**
+	 * Plain-text attribution from archive metadata (HTML tags stripped); empty string when absent.
+	 */
+	readonly attribution: string
+
+	private readonly handle: FileHandle
+	private readonly pmtiles: PMTiles
+	private readonly cache = new Map<string, CacheEntry>()
+
+	private constructor(handle: FileHandle, pmtiles: PMTiles, minZoom: number, maxZoom: number, attribution: string) {
+		this.handle = handle
+		this.pmtiles = pmtiles
+		this.minZoom = minZoom
+		this.maxZoom = maxZoom
+		this.attribution = attribution
+	}
+
+	static async open(path: string): Promise<TileSource> {
+		const handle = await open(path, "r")
+		const pmtiles = new PMTiles(new FilePMTilesSource(path, handle))
+
+		const [header, metadata] = await Promise.all([pmtiles.getHeader(), pmtiles.getMetadata()])
+
+		const attribution =
+			typeof metadata === "object" &&
+			metadata !== null &&
+			"attribution" in metadata &&
+			typeof (metadata as { attribution: unknown }).attribution === "string"
+				? (metadata as { attribution: string }).attribution.replaceAll(/<[^>]+>/gu, "").trim()
+				: ""
+
+		return new TileSource(handle, pmtiles, header.minZoom, header.maxZoom, attribution)
+	}
+
+	/**
+	 * Decoded tile, LRU-cached (64 entries). null = tile absent from the archive.
+	 */
+	async getTile(z: number, x: number, y: number): Promise<DecodedTile | null> {
+		const key = `${z}/${x}/${y}`
+		const cached = this.cache.get(key)
+
+		if (cached != null) {
+			// Refresh recency by re-inserting at the end of iteration order.
+			this.cache.delete(key)
+			this.cache.set(key, cached)
+
+			return cached.tile
+		}
+
+		const response = await this.pmtiles.getZxy(z, x, y)
+
+		const tile: DecodedTile | null = response != null ? { layers: decodeMVT(new Uint8Array(response.data)) } : null
+
+		this.cache.set(key, { tile })
+
+		if (this.cache.size > TILE_CACHE_LIMIT) {
+			const oldestKey = this.cache.keys().next().value
+
+			if (typeof oldestKey === "string") {
+				this.cache.delete(oldestKey)
+			}
+		}
+
+		return tile
+	}
+
+	async close(): Promise<void> {
+		await this.handle.close()
+	}
+}