@bitbaum/geo-kit 0.1.1 → 0.2.0

package/dist/map/paint.js

@@ -0,0 +1,174 @@
+/**
+ * Painting the map on a canvas: the fills grouped so each colour is one path,
+ * and one frame drawn: atmosphere and lit sphere, graticule, land, borders,
+ * limb shade, the hover and selection outlines, then whatever the caller
+ * draws over it (sites, routes, figures). Every layer but the land and its
+ * borders is optional, so the same painter draws a lit globe of the world and
+ * a plain map of communes where the data is the picture.
+ */
+import { geoGraticule10, geoPath } from "d3-geo";
+import { centreOf, horizonOf, visible } from "./cull.js";
+import { basisOf, pack, traceLine, traceRing } from "./trace.js";
+const FULL = Math.PI * 2;
+/**
+ * Any CSS colour at an alpha, for gradients that fade without greying. The
+ * canvas normalises the colour first: a build may minify `#000000` to `#000`,
+ * and a token could as well be `rgb()`.
+ */
+export function fade(colour, a) {
+    const probe = document.createElement("canvas").getContext("2d");
+    if (!probe)
+        return colour;
+    probe.fillStyle = "#000";
+    probe.fillStyle = colour;
+    const norm = String(probe.fillStyle);
+    const hex = /^#([0-9a-f]{6})$/i.exec(norm);
+    if (hex?.[1]) {
+        const n = parseInt(hex[1], 16);
+        return `rgba(${n >> 16},${(n >> 8) & 255},${n & 255},${a})`;
+    }
+    const rgba = /^rgba?\(([^,]+),([^,]+),([^,)]+)/.exec(norm.replace(/\s/g, ""));
+    return rgba ? `rgba(${rgba[1]},${rgba[2]},${rgba[3]},${a})` : colour;
+}
+/**
+ * The fills as one entry per colour, in the order the caller's map first
+ * names each colour, then the features with no fill: a path per colour, not
+ * per feature. As indexes, so the full and the coarse shapes share it.
+ */
+export function groupFills(features, fills, land) {
+    const groups = new Map();
+    for (const fill of fills.values())
+        if (!groups.has(fill))
+            groups.set(fill, []);
+    groups.set(land, groups.get(land) ?? []);
+    features.forEach((f, i) => groups.get(fills.get(f.id) ?? land).push(i));
+    // The plain land first, so a coloured feature's edge is never painted over.
+    const plain = groups.get(land);
+    groups.delete(land);
+    return [[land, plain], ...groups.entries()].filter(([, members]) => members.length > 0);
+}
+const GRATICULE = geoGraticule10().coordinates.map(pack);
+function blit(ctx, layer) {
+    ctx.save();
+    ctx.setTransform(1, 0, 0, 1, 0, 0);
+    ctx.drawImage(layer, 0, 0);
+    ctx.restore();
+}
+/**
+ * Atmosphere and sphere (under the land) and the limb shade (over it) do not
+ * turn with the Earth: render them once per disc and blit them, instead of
+ * full-disc gradients every frame.
+ */
+function backdrop(paint, target, cx, cy, r, size) {
+    const key = [target.width, target.height, cx, cy, r].map((n) => n.toFixed(1)).join();
+    if (paint.backdrop?.key === key)
+        return paint.backdrop;
+    const { palette } = paint;
+    const scale = target.width / size.w;
+    const layer = (draw) => {
+        const canvas = document.createElement("canvas");
+        canvas.width = target.width;
+        canvas.height = target.height;
+        const c = canvas.getContext("2d");
+        if (c) {
+            c.setTransform(scale, 0, 0, scale, 0, 0);
+            draw(c);
+        }
+        return canvas;
+    };
+    const disc = (c, radius, fill) => {
+        c.fillStyle = fill;
+        c.beginPath();
+        c.arc(cx, cy, radius, 0, FULL);
+        c.fill();
+    };
+    const under = layer((c) => {
+        if (palette.glow && r < Math.hypot(size.w, size.h)) {
+            const glow = c.createRadialGradient(cx, cy, r * 0.97, cx, cy, r * 1.12);
+            glow.addColorStop(0, palette.glow[0]);
+            glow.addColorStop(1, palette.glow[1]);
+            disc(c, r * 1.12, glow);
+        }
+        if (palette.sphereLight) {
+            // The sphere, lit from the upper left.
+            const sea = c.createRadialGradient(cx - r * 0.4, cy - r * 0.45, r * 0.05, cx, cy, r);
+            sea.addColorStop(0, palette.sphereLight);
+            sea.addColorStop(1, palette.sphere);
+            disc(c, r, sea);
+        }
+        else
+            disc(c, r, palette.sphere);
+    });
+    const over = layer((c) => {
+        if (!palette.limb)
+            return;
+        const limb = c.createRadialGradient(cx, cy, r * 0.55, cx, cy, r);
+        limb.addColorStop(0, palette.limb[0]);
+        limb.addColorStop(1, palette.limb[1]);
+        disc(c, r, limb);
+    });
+    paint.backdrop = { key, under, over };
+    return paint.backdrop;
+}
+/** One frame, in CSS pixels (the caller has set the device-pixel transform). */
+export function paintMap(ctx, size, proj, shapes, paint, marks = {}, over) {
+    const { palette, groups } = paint;
+    const [cx, cy] = proj.translate();
+    const r = proj.scale();
+    ctx.clearRect(0, 0, size.w, size.h);
+    const { under, over: shade } = backdrop(paint, ctx.canvas, cx, cy, r, size);
+    blit(ctx, under);
+    const centre = centreOf(proj);
+    const horizon = horizonOf(proj, size);
+    const basis = basisOf(centre, cx, cy, r);
+    if (palette.graticule) {
+        ctx.beginPath();
+        for (const line of GRATICULE)
+            traceLine(ctx, line, basis);
+        ctx.strokeStyle = palette.graticule;
+        ctx.lineWidth = 0.5;
+        ctx.stroke();
+    }
+    for (const [fill, members] of groups) {
+        ctx.beginPath();
+        for (const i of members)
+            if (visible(shapes.caps[i], centre, horizon))
+                for (const ring of shapes.rings[i])
+                    traceRing(ctx, ring, basis);
+        ctx.fillStyle = fill;
+        ctx.fill("evenodd");
+    }
+    ctx.beginPath();
+    shapes.lines.forEach((line, i) => {
+        if (visible(shapes.lineCaps[i], centre, horizon))
+            traceLine(ctx, line, basis);
+    });
+    ctx.strokeStyle = palette.border;
+    ctx.lineWidth = palette.borderWidth ?? 0.6;
+    ctx.lineJoin = "round";
+    ctx.stroke();
+    blit(ctx, shade);
+    const path = geoPath(proj, ctx);
+    const outline = (f, width, colour) => {
+        if (!f)
+            return;
+        const feature = { type: "Feature", geometry: f.geometry, properties: null };
+        ctx.beginPath();
+        path(feature);
+        ctx.strokeStyle = colour;
+        ctx.lineWidth = width;
+        ctx.stroke();
+        // Too small to see at this zoom: ring it.
+        const [[x0, y0], [x1, y1]] = path.bounds(feature);
+        if (Number.isFinite(x0) && Math.max(x1 - x0, y1 - y0) < 10) {
+            ctx.beginPath();
+            ctx.arc((x0 + x1) / 2, (y0 + y1) / 2, 11, 0, FULL);
+            ctx.lineWidth = 1.5;
+            ctx.stroke();
+        }
+    };
+    if (marks.hover !== marks.selected)
+        outline(marks.hover, 1.25, palette.hover);
+    outline(marks.selected, 2, palette.selected);
+    over?.(ctx, basis, proj);
+}

package/dist/map/pick.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Which feature is under a pixel of the map: invert the projection, then test
+ * the few features whose lon/lat box holds the point.
+ */
+import { type GeoProjection } from "d3-geo";
+import type { MapFeature } from "./shapes.ts";
+export interface Pickable<P = Record<string, unknown>> {
+    feature: MapFeature<P>;
+    /** lon/lat box; west > east when it crosses the antimeridian. */
+    box: [[number, number], [number, number]];
+}
+export declare function pickIndex<P>(features: readonly MapFeature<P>[]): Pickable<P>[];
+/**
+ * The feature under a canvas pixel, or null for sea and the space around the
+ * globe. `invert` is the projection's; off the disc it has no answer.
+ */
+export declare function pickAt<P>(index: readonly Pickable<P>[], projection: GeoProjection, x: number, y: number): MapFeature<P> | null;

package/dist/map/pick.js

@@ -0,0 +1,34 @@
+/**
+ * Which feature is under a pixel of the map: invert the projection, then test
+ * the few features whose lon/lat box holds the point.
+ */
+import { geoBounds, geoContains } from "d3-geo";
+export function pickIndex(features) {
+    return features.map((feature) => ({
+        feature,
+        box: geoBounds({ type: "Feature", geometry: feature.geometry, properties: null }),
+    }));
+}
+function inBox([[w, s], [e, n]], [lon, lat]) {
+    if (lat < s || lat > n)
+        return false;
+    return w <= e ? lon >= w && lon <= e : lon >= w || lon <= e;
+}
+/**
+ * The feature under a canvas pixel, or null for sea and the space around the
+ * globe. `invert` is the projection's; off the disc it has no answer.
+ */
+export function pickAt(index, projection, x, y) {
+    const [cx, cy] = projection.translate();
+    const r = projection.scale();
+    if ((x - cx) ** 2 + (y - cy) ** 2 > r * r)
+        return null;
+    const at = projection.invert?.([x, y]);
+    if (!at || !Number.isFinite(at[0]) || !Number.isFinite(at[1]))
+        return null;
+    const point = [at[0], at[1]];
+    for (const p of index)
+        if (inBox(p.box, point) && geoContains({ type: "Feature", geometry: p.feature.geometry, properties: null }, point))
+            return p.feature;
+    return null;
+}

package/dist/map/shapes.d.ts

@@ -0,0 +1,59 @@
+import type { Feature, GeoJsonProperties, Geometry, MultiLineString, Position } from "geojson";
+import type { Topology } from "topojson-specification";
+import { type Cap } from "./cull.ts";
+import { type Packed } from "./trace.ts";
+/** A feature as the map holds it: its id, its geometry and the caller's properties. */
+export interface MapFeature<P = Record<string, unknown>> {
+    id: string;
+    geometry: Geometry;
+    properties: P;
+}
+export interface Shapes<P = Record<string, unknown>> {
+    features: MapFeature<P>[];
+    /** Where each id sits in `features`, `caps` and `rings`. */
+    index: Map<string, number>;
+    /** Every border and coast once. */
+    borders: MultiLineString;
+    caps: Cap[];
+    lineCaps: Cap[];
+    rings: Packed[][];
+    lines: Packed[];
+}
+/** The full detail and the coarse copy painted in motion. */
+export interface MapShapes<P = Record<string, unknown>> extends Shapes<P> {
+    coarse: Shapes<P>;
+}
+type Ring = Position[];
+export declare function polygonsOf(g: Geometry): Ring[][];
+/**
+ * d3-geo is spherical: a ring wound the "wrong" way encloses the rest of the
+ * globe, so one bad polygon floods the ocean with that feature's colour.
+ * Simplification leaves a few such rings, and planar data (most national
+ * boundary files) is wound the other way throughout; a polygon covering more
+ * than a hemisphere is one of them, and reversing its rings puts it right.
+ */
+export declare function rewound(g: Geometry): Geometry;
+/** Prepare features and their shared borders for painting. */
+export declare function shapesOf<P>(features: readonly MapFeature<P>[], borders: MultiLineString): Shapes<P>;
+/**
+ * Every `every`-th vertex of each arc, ends kept. Thinning the topology's arcs
+ * rather than each feature's rings keeps a shared border shared: neighbours
+ * still meet exactly, with no slivers between them.
+ */
+export declare function coarsened<T extends Topology>(topo: T, every: number): T;
+export interface TopologyOptions<P extends GeoJsonProperties> {
+    /** The object in `topo.objects` to draw. */
+    object: string;
+    /** The id each feature is known by; null leaves the feature out. */
+    idOf: (feature: Feature<Geometry, P>) => string | null;
+    /** Keep every n-th vertex for the copy painted in motion (default 3; 1 keeps all). */
+    coarseEvery?: number;
+}
+/** Shapes from one object of a TopoJSON topology, with its coarse copy. */
+export declare function shapesFromTopology<P extends GeoJsonProperties>(topo: Topology, options: TopologyOptions<P>): MapShapes<P>;
+/**
+ * Shapes from GeoJSON features, whose borders are their rings (a feature
+ * collection carries no shared arcs). Painted in motion as they are.
+ */
+export declare function shapesFromFeatures<P>(features: readonly MapFeature<P>[]): MapShapes<P>;
+export {};

package/dist/map/shapes.js

@@ -0,0 +1,105 @@
+/**
+ * What a map draws, prepared once: each feature keyed by its id, wound the
+ * way d3's spherical geometry needs, its far-side cap (cull.ts) and its rings
+ * as unit vectors (trace.ts); every shared border once, so the outline is one
+ * stroke, not one per feature. A coarse copy, the same features in the same
+ * order, is painted while the map moves so a drag stays inside a phone's
+ * frame budget; the frame after it stops is full detail again.
+ *
+ * Country-neutral: the features are whatever the caller loaded (countries,
+ * cantons, communes), keyed by whatever id the caller's data uses.
+ */
+import { geoArea } from "d3-geo";
+import { feature as topoFeature, mesh } from "topojson-client";
+import { capOf } from "./cull.js";
+import { pack } from "./trace.js";
+export function polygonsOf(g) {
+    if (g.type === "Polygon")
+        return [g.coordinates];
+    if (g.type === "MultiPolygon")
+        return g.coordinates;
+    return [];
+}
+/**
+ * d3-geo is spherical: a ring wound the "wrong" way encloses the rest of the
+ * globe, so one bad polygon floods the ocean with that feature's colour.
+ * Simplification leaves a few such rings, and planar data (most national
+ * boundary files) is wound the other way throughout; a polygon covering more
+ * than a hemisphere is one of them, and reversing its rings puts it right.
+ */
+export function rewound(g) {
+    const fix = (rings) => {
+        const area = geoArea({ type: "Polygon", coordinates: rings });
+        return area > 2 * Math.PI ? rings.map((ring) => [...ring].reverse()) : rings;
+    };
+    if (g.type === "Polygon")
+        return { ...g, coordinates: fix(g.coordinates) };
+    if (g.type === "MultiPolygon")
+        return { ...g, coordinates: g.coordinates.map(fix) };
+    return g;
+}
+/** Prepare features and their shared borders for painting. */
+export function shapesOf(features, borders) {
+    const kept = features.map((f) => ({ ...f, geometry: rewound(f.geometry) }));
+    return {
+        features: kept,
+        index: new Map(kept.map((f, i) => [f.id, i])),
+        borders,
+        caps: kept.map((f) => capOf(f.geometry)),
+        lineCaps: borders.coordinates.map((line) => capOf({ type: "LineString", coordinates: line })),
+        rings: kept.map((f) => polygonsOf(f.geometry).flat().map(pack)),
+        lines: borders.coordinates.map(pack),
+    };
+}
+/**
+ * Every `every`-th vertex of each arc, ends kept. Thinning the topology's arcs
+ * rather than each feature's rings keeps a shared border shared: neighbours
+ * still meet exactly, with no slivers between them.
+ */
+export function coarsened(topo, every) {
+    const t = topo.transform;
+    const arcs = topo.arcs.map((arc) => {
+        let x = 0;
+        let y = 0;
+        const absolute = t
+            ? arc.map(([dx = 0, dy = 0]) => {
+                x += dx;
+                y += dy;
+                return [x * t.scale[0] + t.translate[0], y * t.scale[1] + t.translate[1]];
+            })
+            : arc;
+        return absolute.filter((_, i) => i % every === 0 || i === absolute.length - 1);
+    });
+    return { ...topo, transform: undefined, arcs };
+}
+function fromTopology(topo, options) {
+    const object = topo.objects[options.object];
+    if (!object)
+        throw new Error(`topology has no object "${options.object}"`);
+    const collection = topoFeature(topo, object);
+    const features = collection.features.flatMap((f) => {
+        const id = options.idOf(f);
+        return id === null || !f.geometry ? [] : [{ id, geometry: f.geometry, properties: f.properties }];
+    });
+    return shapesOf(features, mesh(topo, object));
+}
+/** Shapes from one object of a TopoJSON topology, with its coarse copy. */
+export function shapesFromTopology(topo, options) {
+    const every = options.coarseEvery ?? 3;
+    return {
+        ...fromTopology(topo, options),
+        coarse: fromTopology(every > 1 ? coarsened(topo, every) : topo, options),
+    };
+}
+/**
+ * Shapes from GeoJSON features, whose borders are their rings (a feature
+ * collection carries no shared arcs). Painted in motion as they are.
+ */
+export function shapesFromFeatures(features) {
+    const borders = {
+        type: "MultiLineString",
+        coordinates: features.flatMap((f) => polygonsOf(f.geometry).flat()),
+    };
+    const shapes = shapesOf(features, borders);
+    return { ...shapes, coarse: shapes };
+}

package/dist/map/trace.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The map's fast path. d3's projection stream spends several sin/cos per
+ * vertex per frame (rotate, clip, project); on a phone that is the frame
+ * budget. Here every vertex is turned into a unit vector once, at load, and a
+ * frame is three dot products per vertex against the view's basis — the same
+ * orthographic projection d3 draws (tested against it), without the trig.
+ *
+ * Behind the globe a polygon's vertices are pulled onto the limb, so a
+ * country crossing the horizon fills up to the edge; a line breaks there.
+ * Picking and one-off outlines still use d3 (pick.ts, paint.ts).
+ */
+import type { Position } from "geojson";
+/** x, y, z triples of unit vectors. */
+export type Packed = Float64Array;
+export declare function pack(coords: Position[]): Packed;
+/** The view's basis: east and north on screen, forward toward the reader. */
+export interface Basis {
+    e: [number, number, number];
+    n: [number, number, number];
+    f: [number, number, number];
+    cx: number;
+    cy: number;
+    r: number;
+}
+export declare function basisOf(center: [number, number], cx: number, cy: number, r: number): Basis;
+/** [x, y, depth]: depth < 0 is behind the globe. For tests and markers. */
+export declare function project(b: Basis, lon: number, lat: number): [number, number, number];
+interface Pen {
+    moveTo(x: number, y: number): void;
+    lineTo(x: number, y: number): void;
+    closePath(): void;
+}
+/** A closed ring; vertices behind the globe are pulled onto the limb. */
+export declare function traceRing(pen: Pen, ring: Packed, b: Basis): void;
+/** An open line; it breaks where it passes behind the globe. */
+export declare function traceLine(pen: Pen, line: Packed, b: Basis): void;
+export {};

package/dist/map/trace.js

@@ -0,0 +1,73 @@
+const RAD = Math.PI / 180;
+export function pack(coords) {
+    const out = new Float64Array(coords.length * 3);
+    coords.forEach(([lon = 0, lat = 0], i) => {
+        const l = lon * RAD;
+        const p = lat * RAD;
+        out[i * 3] = Math.cos(p) * Math.cos(l);
+        out[i * 3 + 1] = Math.cos(p) * Math.sin(l);
+        out[i * 3 + 2] = Math.sin(p);
+    });
+    return out;
+}
+export function basisOf(center, cx, cy, r) {
+    const l = center[0] * RAD;
+    const p = center[1] * RAD;
+    return {
+        e: [-Math.sin(l), Math.cos(l), 0],
+        n: [-Math.sin(p) * Math.cos(l), -Math.sin(p) * Math.sin(l), Math.cos(p)],
+        f: [Math.cos(p) * Math.cos(l), Math.cos(p) * Math.sin(l), Math.sin(p)],
+        cx,
+        cy,
+        r,
+    };
+}
+/** [x, y, depth]: depth < 0 is behind the globe. For tests and markers. */
+export function project(b, lon, lat) {
+    const [x = 0, y = 0, z = 0] = pack([[lon, lat]]);
+    const u = b.e[0] * x + b.e[1] * y + b.e[2] * z;
+    const v = b.n[0] * x + b.n[1] * y + b.n[2] * z;
+    return [b.cx + b.r * u, b.cy - b.r * v, b.f[0] * x + b.f[1] * y + b.f[2] * z];
+}
+/** A closed ring; vertices behind the globe are pulled onto the limb. */
+export function traceRing(pen, ring, b) {
+    const { e, n, f, cx, cy, r } = b;
+    for (let i = 0; i < ring.length; i += 3) {
+        const x = ring[i];
+        const y = ring[i + 1];
+        const z = ring[i + 2];
+        let u = e[0] * x + e[1] * y + e[2] * z;
+        let v = n[0] * x + n[1] * y + n[2] * z;
+        if (f[0] * x + f[1] * y + f[2] * z < 0) {
+            const m = Math.hypot(u, v) || 1;
+            u /= m;
+            v /= m;
+        }
+        if (i === 0)
+            pen.moveTo(cx + r * u, cy - r * v);
+        else
+            pen.lineTo(cx + r * u, cy - r * v);
+    }
+    pen.closePath();
+}
+/** An open line; it breaks where it passes behind the globe. */
+export function traceLine(pen, line, b) {
+    const { e, n, f, cx, cy, r } = b;
+    let down = false;
+    for (let i = 0; i < line.length; i += 3) {
+        const x = line[i];
+        const y = line[i + 1];
+        const z = line[i + 2];
+        if (f[0] * x + f[1] * y + f[2] * z < 0) {
+            down = false;
+            continue;
+        }
+        const px = cx + r * (e[0] * x + e[1] * y + e[2] * z);
+        const py = cy - r * (n[0] * x + n[1] * y + n[2] * z);
+        if (down)
+            pen.lineTo(px, py);
+        else
+            pen.moveTo(px, py);
+        down = true;
+    }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@bitbaum/geo-kit",
-  "version": "0.1.1",
-  "description": "Versioned, on-demand geography resources and sourced boundary assertions for web applications.",
+  "version": "0.2.0",
+  "description": "Versioned, on-demand geography resources and sourced boundary assertions for web applications, and a Canvas 2D renderer for them (globe or map).",
   "author": "BitBaum",
   "homepage": "https://github.com/bitbaum/geo-kit#readme",
   "repository": {
@@ -14,7 +14,9 @@
   "license": "MIT",
   "type": "module",
   "packageManager": "pnpm@11.25.0",
-  "engines": { "node": ">=20" },
+  "engines": {
+    "node": ">=20"
+  },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
@@ -22,10 +24,22 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "default": "./dist/index.js"
+    },
+    "./map": {
+      "types": "./dist/map/index.d.ts",
+      "import": "./dist/map/index.js",
+      "default": "./dist/map/index.js"
     }
   },
-  "files": ["dist", "README.md", "LICENSE"],
-  "publishConfig": { "access": "public", "provenance": true },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
   "sideEffects": false,
   "scripts": {
     "typecheck": "tsc --noEmit -p tsconfig.json",
@@ -34,8 +48,27 @@
     "pack:check": "node scripts/check-pack.mjs",
     "verify": "pnpm run typecheck && pnpm run test && pnpm run build && pnpm run pack:check"
   },
+  "peerDependencies": {
+    "d3-geo": "^3.1.0",
+    "topojson-client": "^3.1.0"
+  },
+  "peerDependenciesMeta": {
+    "d3-geo": {
+      "optional": true
+    },
+    "topojson-client": {
+      "optional": true
+    }
+  },
   "devDependencies": {
+    "@types/d3-geo": "^3.1.1",
+    "@types/geojson": "^7946.0.16",
     "@types/node": "^22.0.0",
-    "typescript": "^5.8.0"
+    "@types/topojson-client": "^3.1.5",
+    "@types/topojson-specification": "^1.0.5",
+    "d3-geo": "3.1.1",
+    "topojson-client": "3.1.0",
+    "typescript": "^5.8.0",
+    "world-atlas": "2.0.2"
   }
 }