@bitbaum/geo-kit 0.1.2 → 0.2.0

package/dist/map/cull.d.ts

@@ -0,0 +1,28 @@
+/**
+ * What is on the far side of the globe need not be drawn. Each country and
+ * each border line carries a cap — the smallest circle on the sphere, around
+ * its centre, that holds every vertex — and a frame streams only the ones
+ * whose cap reaches over the horizon. Half the world is skipped at rest, far
+ * more when zoomed in. Pure, so the horizon maths is tested.
+ */
+import { type GeoPermissibleObjects, type GeoProjection } from "d3-geo";
+export interface Cap {
+    center: [number, number];
+    /** Degrees from the centre to the farthest vertex. */
+    reach: number;
+}
+export declare function capOf(shape: GeoPermissibleObjects & {
+    coordinates: unknown;
+}): Cap;
+/**
+ * How far from the centre of view, in degrees, anything can still be seen on
+ * this canvas: the hemisphere when the whole disc fits, less when the globe
+ * is zoomed past the canvas edges.
+ */
+export declare function horizonOf(proj: GeoProjection, size: {
+    w: number;
+    h: number;
+}): number;
+/** The point of the Earth at the centre of an orthographic projection. */
+export declare function centreOf(proj: GeoProjection): [number, number];
+export declare function visible(cap: Cap, centre: [number, number], horizon: number): boolean;

package/dist/map/cull.js

@@ -0,0 +1,46 @@
+/**
+ * What is on the far side of the globe need not be drawn. Each country and
+ * each border line carries a cap — the smallest circle on the sphere, around
+ * its centre, that holds every vertex — and a frame streams only the ones
+ * whose cap reaches over the horizon. Half the world is skipped at rest, far
+ * more when zoomed in. Pure, so the horizon maths is tested.
+ */
+import { geoCentroid, geoDistance } from "d3-geo";
+const DEG = 180 / Math.PI;
+function eachPosition(coords, fn) {
+    if (!Array.isArray(coords))
+        return;
+    if (typeof coords[0] === "number")
+        return fn(coords);
+    for (const c of coords)
+        eachPosition(c, fn);
+}
+export function capOf(shape) {
+    const [lon, lat] = geoCentroid(shape);
+    const center = Number.isFinite(lon) ? [lon, lat] : [0, 0];
+    let reach = 0;
+    eachPosition(shape.coordinates, (p) => {
+        reach = Math.max(reach, geoDistance(center, [p[0] ?? 0, p[1] ?? 0]));
+    });
+    // A shape whose centroid is meaningless (a ring around a pole) is never culled.
+    return { center, reach: Number.isFinite(lon) ? reach * DEG : 180 };
+}
+/**
+ * How far from the centre of view, in degrees, anything can still be seen on
+ * this canvas: the hemisphere when the whole disc fits, less when the globe
+ * is zoomed past the canvas edges.
+ */
+export function horizonOf(proj, size) {
+    const [cx, cy] = proj.translate();
+    const r = proj.scale();
+    const far = Math.max(Math.hypot(cx, cy), Math.hypot(size.w - cx, cy), Math.hypot(cx, size.h - cy), Math.hypot(size.w - cx, size.h - cy));
+    return far >= r ? 90 : Math.asin(far / r) * DEG;
+}
+/** The point of the Earth at the centre of an orthographic projection. */
+export function centreOf(proj) {
+    const [l, p] = proj.rotate();
+    return [-l, -p];
+}
+export function visible(cap, centre, horizon) {
+    return geoDistance(centre, cap.center) * DEG - cap.reach < horizon + 1;
+}

package/dist/map/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `@bitbaum/geo-kit/map`: the renderer for the geography the main entry
+ * delivers. An orthographic globe on Canvas 2D (d3-geo), which zoomed in is a
+ * flat map of the place in front of the reader, so the world and a commune are
+ * one projection. Framework-free: `createMap` takes a canvas; the pure parts
+ * (camera, motion, culling, picking, the fast projection) are exported for
+ * tests and overlays. Needs the optional peers `d3-geo` and, for TopoJSON,
+ * `topojson-client`.
+ */
+export { WORLD_LIMITS, cameraFor, cameraForBounds, clampTilt, clampZoom, disc, focusOf, mainland, projectionFor, rotationOf, wrapLon, zoomFor, type Camera, type Focus, type Limits, type View, } from "./camera.ts";
+export { createMap, type FrameInfo, type MapController, type MapOptions } from "./controller.ts";
+export { capOf, centreOf, horizonOf, visible, type Cap } from "./cull.ts";
+export { coast, dragged, flight, type Flight, type Spin } from "./motion.ts";
+export { fade, groupFills, paintMap, type DrawOver, type Fill, type Marks, type Paint, type Palette } from "./paint.ts";
+export { pickAt, pickIndex, type Pickable } from "./pick.ts";
+export { coarsened, polygonsOf, rewound, shapesFromFeatures, shapesFromTopology, shapesOf, type MapFeature, type MapShapes, type Shapes, type TopologyOptions, } from "./shapes.ts";
+export { basisOf, pack, project, traceLine, traceRing, type Basis, type Packed } from "./trace.ts";

package/dist/map/index.js

@@ -0,0 +1,17 @@
+/**
+ * `@bitbaum/geo-kit/map`: the renderer for the geography the main entry
+ * delivers. An orthographic globe on Canvas 2D (d3-geo), which zoomed in is a
+ * flat map of the place in front of the reader, so the world and a commune are
+ * one projection. Framework-free: `createMap` takes a canvas; the pure parts
+ * (camera, motion, culling, picking, the fast projection) are exported for
+ * tests and overlays. Needs the optional peers `d3-geo` and, for TopoJSON,
+ * `topojson-client`.
+ */
+export { WORLD_LIMITS, cameraFor, cameraForBounds, clampTilt, clampZoom, disc, focusOf, mainland, projectionFor, rotationOf, wrapLon, zoomFor, } from "./camera.js";
+export { createMap } from "./controller.js";
+export { capOf, centreOf, horizonOf, visible } from "./cull.js";
+export { coast, dragged, flight } from "./motion.js";
+export { fade, groupFills, paintMap } from "./paint.js";
+export { pickAt, pickIndex } from "./pick.js";
+export { coarsened, polygonsOf, rewound, shapesFromFeatures, shapesFromTopology, shapesOf, } from "./shapes.js";
+export { basisOf, pack, project, traceLine, traceRing } from "./trace.js";

package/dist/map/motion.d.ts

@@ -0,0 +1,29 @@
+import { type Camera, type Limits } from "./camera.ts";
+/**
+ * Turning the globe by a drag of (dx, dy) pixels: the land under the finger
+ * follows it at the centre of the disc, whatever the zoom. North stays up.
+ */
+export declare function dragged(camera: Camera, dx: number, dy: number, radius: number, limits?: Limits): Camera;
+export interface Flight {
+    at: (t: number) => Camera;
+    /** Milliseconds: longer the farther it turns, never a slog. */
+    duration: number;
+}
+/**
+ * From one view to another along the great circle (the short way round, so
+ * Fiji to Samoa crosses the date line instead of circling the globe), pulling
+ * back mid-way on a long turn so the reader sees where they are going. The
+ * zoom moves on a log scale, so a flight from the world to a commune does not
+ * spend its first half barely zooming.
+ */
+export declare function flight(from: Camera, to: Camera, limits?: Limits): Flight;
+/** A flick: px/ms along each axis, carried on after the finger lifts. */
+export interface Spin {
+    vx: number;
+    vy: number;
+}
+/** One frame of coasting: turn by the velocity, then let it decay. */
+export declare function coast(camera: Camera, spin: Spin, dt: number, radius: number, limits?: Limits): {
+    camera: Camera;
+    spin?: Spin;
+};

package/dist/map/motion.js

@@ -0,0 +1,58 @@
+/**
+ * How the map moves, pure so it can be tested: a drag turns it, a flight
+ * carries it from one view to another the short way round, and a flick keeps
+ * it turning for a moment after release.
+ */
+import { geoDistance, geoInterpolate } from "d3-geo";
+import { WORLD_LIMITS, clampTilt, wrapLon } from "./camera.js";
+/**
+ * Turning the globe by a drag of (dx, dy) pixels: the land under the finger
+ * follows it at the centre of the disc, whatever the zoom. North stays up.
+ */
+export function dragged(camera, dx, dy, radius, limits = WORLD_LIMITS) {
+    const perPixel = 180 / (Math.PI * radius * camera.k);
+    // Near the poles a pixel is more longitude; ease it so a drag there does not whip.
+    const lonScale = 1 / Math.max(Math.cos((camera.center[1] * Math.PI) / 180), 0.35);
+    return {
+        center: [
+            wrapLon(camera.center[0] - dx * perPixel * Math.min(lonScale, 2)),
+            clampTilt(camera.center[1] + dy * perPixel, limits),
+        ],
+        k: camera.k,
+    };
+}
+const ease = (t) => (t < 0.5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2);
+/**
+ * From one view to another along the great circle (the short way round, so
+ * Fiji to Samoa crosses the date line instead of circling the globe), pulling
+ * back mid-way on a long turn so the reader sees where they are going. The
+ * zoom moves on a log scale, so a flight from the world to a commune does not
+ * spend its first half barely zooming.
+ */
+export function flight(from, to, limits = WORLD_LIMITS) {
+    const arc = (geoDistance(from.center, to.center) * 180) / Math.PI;
+    const along = geoInterpolate(from.center, to.center);
+    const pull = Math.min(Math.max((arc - 30) / 150, 0), 0.45);
+    const lk0 = Math.log(from.k);
+    const lk1 = Math.log(to.k);
+    return {
+        duration: Math.round(450 + Math.min(arc, 180) * 4 + Math.min(Math.abs(lk1 - lk0), 6) * 60),
+        at(t) {
+            const e = ease(Math.min(Math.max(t, 0), 1));
+            const [lon = 0, lat = 0] = along(e);
+            const k = Math.exp(lk0 + (lk1 - lk0) * e);
+            const dip = 1 - pull * Math.sin(Math.PI * e);
+            return {
+                center: [wrapLon(lon), clampTilt(lat, limits)],
+                k: Math.max(k * dip, limits.minZoom),
+            };
+        },
+    };
+}
+/** One frame of coasting: turn by the velocity, then let it decay. */
+export function coast(camera, spin, dt, radius, limits = WORLD_LIMITS) {
+    const next = dragged(camera, spin.vx * dt, spin.vy * dt, radius, limits);
+    const decay = Math.exp(-dt / 325);
+    const left = { vx: spin.vx * decay, vy: spin.vy * decay };
+    return { camera: next, spin: Math.hypot(left.vx, left.vy) < 0.01 ? undefined : left };
+}

package/dist/map/paint.d.ts

@@ -0,0 +1,66 @@
+/**
+ * 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 { type GeoProjection } from "d3-geo";
+import type { MapFeature, Shapes } from "./shapes.ts";
+import { type Basis } from "./trace.ts";
+export type Fill = string | CanvasPattern;
+export interface Palette {
+    /** The sea, or the page under a map with no base. */
+    sphere: string;
+    /** The sphere's lit side; absent paints it flat. */
+    sphereLight?: string;
+    /** Absent draws no graticule. */
+    graticule?: string;
+    /** A feature with no fill of its own. */
+    land: string;
+    border: string;
+    hover: string;
+    selected: string;
+    /** A glow past the limb, [inner, outer]; absent draws none. */
+    glow?: [string, string];
+    /** Shade toward the limb, [inner, outer]; absent draws none. */
+    limb?: [string, string];
+    /** Border width in CSS pixels (default 0.6). */
+    borderWidth?: number;
+}
+/**
+ * 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 declare function fade(colour: string, a: number): string;
+/**
+ * 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 declare function groupFills(features: readonly MapFeature<unknown>[], fills: ReadonlyMap<string, Fill>, land: Fill): [Fill, number[]][];
+interface Backdrop {
+    key: string;
+    under: HTMLCanvasElement;
+    over: HTMLCanvasElement;
+}
+/** What a frame needs that outlives it: the palette, the fill groups, the cached backdrop. */
+export interface Paint {
+    palette: Palette;
+    groups: [Fill, number[]][];
+    backdrop?: Backdrop;
+}
+export interface Marks<P = Record<string, unknown>> {
+    hover?: MapFeature<P>;
+    selected?: MapFeature<P>;
+}
+/** What the caller draws over the map, in CSS pixels, with the frame's basis. */
+export type DrawOver = (ctx: CanvasRenderingContext2D, basis: Basis, projection: GeoProjection) => void;
+/** One frame, in CSS pixels (the caller has set the device-pixel transform). */
+export declare function paintMap<P>(ctx: CanvasRenderingContext2D, size: {
+    w: number;
+    h: number;
+}, proj: GeoProjection, shapes: Shapes<P>, paint: Paint, marks?: Marks<P>, over?: DrawOver): void;
+export {};

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 };
+}