@motionscript/geography 0.1.0-alpha.7 → 0.1.0-alpha.9

package/src/border/registry.ts

@@ -0,0 +1,201 @@
+import { geoArea } from "d3-geo"
+
+import {
+    GEO_DATA_FORMAT,
+    type GeoFeature,
+    type GeoFileData,
+    type GeoIndex,
+    type GeoPolygon,
+    type GeoRingRef,
+} from "./format"
+import { ringBuckets } from "./simplify"
+
+/** Prefix every data key carries; bumped with the file format. */
+export const GEO_DATA_VERSION = `v${GEO_DATA_FORMAT}`
+
+/**
+ * Answers a data key — `v1/countries/FR`, `v1/states/US`, `v1/index` — with the
+ * parsed file, or `null` when this source does not have it. A throw means "could
+ * not tell" (offline, a 500) and is retried on the next load.
+ */
+export type GeoSource = (key: string) => Promise<unknown>
+
+type Position = readonly [number, number] | readonly number[]
+type GeoPolygonShape =
+    | { type: "Polygon"; coordinates: readonly (readonly Position[])[] }
+    | { type: "MultiPolygon"; coordinates: readonly (readonly (readonly Position[])[])[] }
+/** GeoJSON in lon/lat: a Polygon, a MultiPolygon, or a Feature holding one. */
+export type GeoShape = GeoPolygonShape | { type: "Feature"; geometry: GeoPolygonShape; properties?: { name?: string } | null }
+
+export interface GeoDefinition {
+    shape: GeoShape
+    name?: string
+    /** The country a subdivision code expands under, when it has one. */
+    parent?: string
+}
+
+/** Fetches `<base>/<key>.json`; `base` may instead map a key to its URL. */
+export function geoUrlSource(base: string | ((key: string) => string), init?: RequestInit): GeoSource {
+    return async (key) => {
+        const url = typeof base === "function" ? base(key) : `${base.replace(/\/+$/, "")}/${key}.json`
+        const response = await fetch(url, init)
+        // Some object stores answer a missing key with 400, not 404.
+        if (response.status === 404 || response.status === 400) return null
+        if (!response.ok) throw new Error(`${url} → HTTP ${response.status}`)
+        return response.json()
+    }
+}
+
+/** Wraps a function returning the file as text, bytes or parsed JSON (e.g. `fs.readFile`). */
+export function geoLoaderSource(
+    load: (key: string) => Promise<string | ArrayBuffer | Uint8Array | object | null | undefined>
+): GeoSource {
+    return async (key) => {
+        const value = await load(key)
+        if (value == null) return null
+        if (typeof value === "string") return JSON.parse(value)
+        if (value instanceof ArrayBuffer || value instanceof Uint8Array) {
+            return JSON.parse(new TextDecoder().decode(value))
+        }
+        return value
+    }
+}
+
+function definedFeature(code: string, definition: GeoDefinition, serial: number): GeoFeature {
+    const shape = definition.shape.type === "Feature" ? definition.shape.geometry : definition.shape
+    const feature = definition.shape.type === "Feature" ? definition.shape : null
+    const polygons: readonly (readonly (readonly Position[])[])[] =
+        shape.type === "Polygon" ? [shape.coordinates] : shape.coordinates
+    let arcIndex = 0
+
+    /**
+     * One ring, wound the way d3 reads it. d3 takes the *inside* of a ring to be
+     * the side its points go clockwise around, so an exterior must be small
+     * (`geoArea` under a hemisphere) and a hole its complement. GeoJSON (RFC 7946)
+     * writes the opposite way round, counter-clockwise exteriors, and a ring
+     * taken as written would fill the rest of the sphere; so a ring that reads
+     * the wrong way for its place is reversed.
+     */
+    const toRing = (ring: readonly Position[], exterior: boolean): GeoRingRef => {
+        const closed = ring.length > 0 && ring[0][0] === ring[ring.length - 1][0] && ring[0][1] === ring[ring.length - 1][1]
+        let coordinates = closed ? ring : [...ring, ring[0]]
+        const encloses = geoArea({ type: "Polygon", coordinates: [coordinates as [number, number][]] }) <= 2 * Math.PI
+        if (encloses !== exterior) coordinates = [...coordinates].reverse()
+        const points = new Float64Array(coordinates.length * 2)
+        coordinates.forEach(([lon, lat], i) => {
+            points[i * 2] = lon
+            points[i * 2 + 1] = lat
+        })
+        return { arc: { key: `define:${serial}:${code}:${arcIndex++}`, points, buckets: ringBuckets(points) }, reversed: false }
+    }
+
+    const measured: GeoPolygon[] = polygons.map((rings) => {
+        const resolved = rings.map((ring, i) => [toRing(ring, i === 0)])
+        const ringAreas = rings.map((ring) => {
+            const area = geoArea({ type: "Polygon", coordinates: [ring as [number, number][]] })
+            return area > 2 * Math.PI ? 4 * Math.PI - area : area
+        })
+        const area = Math.max(0, ringAreas[0] - ringAreas.slice(1).reduce((a, b) => a + b, 0))
+        return { rings: resolved, ringAreas, area, mainland: true }
+    })
+
+    const name = definition.name ?? feature?.properties?.name ?? code
+    return {
+        code,
+        name,
+        nameNl: name,
+        parent: definition.parent ?? (code.includes("-") ? code.slice(0, 2) : null),
+        first: true,
+        listed: false,
+        remote: false,
+        polygons: measured,
+    }
+}
+
+class GeoRegistry {
+    private _sources: GeoSource[] = []
+    private _defined = new Map<string, { serial: number; feature: GeoFeature }>()
+    private _generation = 0
+    private _serial = 0
+
+    /** Bumps whenever a source or a definition is added or removed. */
+    get generation(): number {
+        return this._generation
+    }
+
+    get hasSources(): boolean {
+        return this._sources.length > 0
+    }
+
+    /** Adds a source after every source already registered. Returns its removal. */
+    use(source: GeoSource): () => void {
+        this._sources.push(source)
+        this._generation++
+        return () => {
+            const i = this._sources.indexOf(source)
+            if (i < 0) return
+            this._sources.splice(i, 1)
+            this._generation++
+        }
+    }
+
+    /**
+     * Shapes (GeoJSON, lon/lat) under codes of your choosing, checked before any
+     * source. A definition replaces generated data for the same code.
+     */
+    define(shapes: Record<string, GeoShape | GeoDefinition>): () => void {
+        const serial = ++this._serial
+        const codes = Object.entries(shapes).map(([rawCode, value]) => {
+            const code = rawCode.trim().toUpperCase()
+            const definition = "shape" in value ? value : { shape: value }
+            this._defined.set(code, { serial, feature: definedFeature(code, definition, serial) })
+            return code
+        })
+        this._generation++
+        return () => {
+            for (const code of codes) {
+                if (this._defined.get(code)?.serial === serial) this._defined.delete(code)
+            }
+            this._generation++
+        }
+    }
+
+    defined(code: string): GeoFeature | undefined {
+        return this._defined.get(code)?.feature
+    }
+
+    /** Removes every source and definition — for tests. */
+    reset(): void {
+        this._sources = []
+        this._defined.clear()
+        this._generation++
+    }
+
+    /**
+     * Asks each source in registration order; the first non-null answer wins.
+     * Resolves `null` only when every source answered that it has no such file.
+     */
+    async resolve(key: string): Promise<GeoFileData | GeoIndex | null> {
+        if (this._sources.length === 0) {
+            throw new Error("No geo source registered — call geoRegistry.use(geoUrlSource(…)) before rendering GeoBorder")
+        }
+        let failure: unknown = null
+        for (const source of [...this._sources]) {
+            try {
+                const value = await source(key)
+                if (value != null) return value as GeoFileData | GeoIndex
+            } catch (error) {
+                failure ??= error
+            }
+        }
+        if (failure) throw failure
+        return null
+    }
+
+    /** Every listed region's code, names and parent, for a picker. */
+    async index(): Promise<GeoIndex | null> {
+        return (await this.resolve(`${GEO_DATA_VERSION}/index`)) as GeoIndex | null
+    }
+}
+
+export const geoRegistry = new GeoRegistry()

package/src/border/selection.ts

@@ -0,0 +1,95 @@
+import type { GeoFeature } from "./format"
+import { countryFileKey, geoFileEntry, statesFileKey } from "./loader"
+import { geoRegistry } from "./registry"
+
+export type GeoLevel = "country" | "state"
+export type GeoFrame = "mainland" | "all"
+
+const CODE = /^[A-Z]{2}(-[A-Z0-9]{1,3})?$/
+
+/** `"fr, de"`, `["FR", "de"]` → `["FR", "DE"]`; unique, in order, empties dropped. */
+export function normalizeIso(value: unknown): string[] {
+    const raw = Array.isArray(value) ? value : typeof value === "string" ? value.split(/[\s,;]+/) : []
+    const out: string[] = []
+    for (const item of raw) {
+        if (typeof item !== "string") continue
+        const code = item.trim().toUpperCase()
+        if (code && !out.includes(code)) out.push(code)
+    }
+    return out
+}
+
+function isSubdivision(code: string): boolean {
+    return code.includes("-")
+}
+
+/** Every data file a selection reads, for `declareAssets`. Depends on nothing but its arguments. */
+export function geoFilesFor(codes: readonly string[], level: GeoLevel): string[] {
+    const files = new Set<string>()
+    for (const code of codes) {
+        if (!CODE.test(code) || geoRegistry.defined(code)) continue
+        if (isSubdivision(code)) files.add(statesFileKey(code.slice(0, 2)))
+        else files.add(level === "state" ? statesFileKey(code) : countryFileKey(code))
+    }
+    return [...files]
+}
+
+export interface GeoSelection {
+    features: GeoFeature[]
+    /** A file this selection needs has not landed yet. */
+    pending: boolean
+    /** Codes whose file loaded without them. */
+    unknown: string[]
+}
+
+/**
+ * The features a selection draws. A bare country code at state level is its
+ * first-level subdivisions — minus the remote ones when framing the mainland —
+ * or the country itself when it has none.
+ */
+export function selectGeoFeatures(codes: readonly string[], level: GeoLevel, frame: GeoFrame): GeoSelection {
+    const features: GeoFeature[] = []
+    const seen = new Set<string>()
+    const unknown: string[] = []
+    let pending = false
+
+    const add = (feature: GeoFeature) => {
+        if (seen.has(feature.code)) return
+        seen.add(feature.code)
+        features.push(feature)
+    }
+
+    for (const code of codes) {
+        const defined = geoRegistry.defined(code)
+        if (defined) {
+            add(defined)
+            continue
+        }
+        if (!CODE.test(code)) {
+            unknown.push(code)
+            continue
+        }
+        const subdivision = isSubdivision(code)
+        const key = subdivision || level === "state" ? statesFileKey(code.slice(0, 2)) : countryFileKey(code)
+        const entry = geoFileEntry(key)
+        if (!entry || entry.status !== "ready") {
+            if (!entry) pending = true
+            continue
+        }
+        const file = entry.file.features
+        if (subdivision || level === "country") {
+            const feature = file.get(code)
+            if (feature) add(feature)
+            else unknown.push(code)
+            continue
+        }
+        const children = [...file.values()].filter(
+            (f) => f.parent === code && f.first && !(frame === "mainland" && f.remote)
+        )
+        if (children.length > 0) children.forEach(add)
+        else if (file.get(code)) add(file.get(code)!)
+        else unknown.push(code)
+    }
+
+    return { features, pending, unknown }
+}

package/src/border/simplify.ts

@@ -0,0 +1,110 @@
+/**
+ * Visvalingam–Whyatt weights for a hand-defined ring, in the same buckets the
+ * generated data carries (`-2·log2` of the effective area in steradians), so a
+ * shape passed to `geoRegistry.define` answers to `detail` like any other.
+ *
+ * Planar in degrees with longitude scaled by latitude: accurate enough for the
+ * handful of shapes an author defines, where the generated data uses the exact
+ * spherical area.
+ */
+export function ringBuckets(points: Float64Array): Uint8Array {
+    const n = points.length / 2
+    const buckets = new Uint8Array(n)
+    if (n < 3) return buckets
+
+    const radians = Math.PI / 180
+    const weight = new Float64Array(n)
+    const prev = new Int32Array(n)
+    const next = new Int32Array(n)
+    for (let i = 0; i < n; i++) {
+        prev[i] = i - 1
+        next[i] = i + 1
+    }
+
+    const area = (a: number, b: number, c: number): number => {
+        const cos = Math.cos(points[b * 2 + 1] * radians)
+        const ax = points[a * 2] * cos, ay = points[a * 2 + 1]
+        const bx = points[b * 2] * cos, by = points[b * 2 + 1]
+        const cx = points[c * 2] * cos, cy = points[c * 2 + 1]
+        return (Math.abs((bx - ax) * (cy - ay) - (cx - ax) * (by - ay)) / 2) * radians * radians
+    }
+
+    const heap: number[] = []
+    const position = new Int32Array(n).fill(-1)
+    const less = (i: number, j: number) => weight[heap[i]] < weight[heap[j]]
+    const swap = (i: number, j: number) => {
+        ;[heap[i], heap[j]] = [heap[j], heap[i]]
+        position[heap[i]] = i
+        position[heap[j]] = j
+    }
+    const up = (i: number) => {
+        while (i > 0) {
+            const parent = (i - 1) >> 1
+            if (!less(i, parent)) break
+            swap(i, parent)
+            i = parent
+        }
+    }
+    const down = (i: number) => {
+        for (;;) {
+            const l = 2 * i + 1
+            const r = l + 1
+            let smallest = i
+            if (l < heap.length && less(l, smallest)) smallest = l
+            if (r < heap.length && less(r, smallest)) smallest = r
+            if (smallest === i) return
+            swap(i, smallest)
+            i = smallest
+        }
+    }
+    const push = (i: number) => {
+        position[i] = heap.length
+        heap.push(i)
+        up(heap.length - 1)
+    }
+    const remove = (i: number) => {
+        const at = position[i]
+        const last = heap.pop()!
+        position[i] = -1
+        if (at < heap.length) {
+            heap[at] = last
+            position[last] = at
+            up(at)
+            down(position[last])
+        }
+    }
+
+    for (let i = 1; i < n - 1; i++) {
+        weight[i] = area(i - 1, i, i + 1)
+        push(i)
+    }
+
+    let floor = 0
+    const final = new Float64Array(n)
+    final[0] = final[n - 1] = Infinity
+    while (heap.length > 0) {
+        const i = heap[0]
+        remove(i)
+        floor = Math.max(floor, weight[i])
+        final[i] = floor
+        const p = prev[i]
+        const q = next[i]
+        if (p >= 0) next[p] = q
+        if (q < n) prev[q] = p
+        for (const j of [p, q]) {
+            if (j <= 0 || j >= n - 1 || position[j] < 0) continue
+            remove(j)
+            weight[j] = area(prev[j], j, next[j])
+            push(j)
+        }
+    }
+
+    for (let i = 0; i < n; i++) buckets[i] = weightBucket(final[i])
+    return buckets
+}
+
+export function weightBucket(weight: number): number {
+    if (weight === Infinity) return 0
+    if (!(weight > 0)) return 255
+    return Math.min(254, Math.max(1, Math.round(-2 * Math.log2(weight))))
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from "./border";
+export { NODES } from "./nodes";

package/src/nodes.ts

@@ -0,0 +1,16 @@
+import { GeoBorder } from "./border";
+
+/**
+ * Every node type this package publishes.
+ *
+ * A host registers these by handing the array to an engine —
+ * `new Engine(platform, { nodes: NODES })` — which reads each component's key.
+ * Defining a component only *declares* that key: nothing is registered by
+ * importing a module, so a registry holds exactly what its owner asked for.
+ *
+ * Listing the component **values** is also what survives bundling: this package
+ * declares `sideEffects: false`, and a document names a node type by string, so
+ * an import kept only for its side effect is exactly what gets shaken out.
+ */
+// Typed by name, so the declaration names each component rather than spelling out its type through core.
+export const NODES: (typeof GeoBorder)[] = [GeoBorder];