@motionscript/geo 0.0.0-stage → 0.1.0-alpha.3

package/src/border/registry.ts

@@ -0,0 +1,191 @@
+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)
+        // Supabase Storage answers a missing object 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
+
+    const toRing = (ring: readonly Position[]): GeoRingRef => {
+        const closed = ring.length > 0 && ring[0][0] === ring[ring.length - 1][0] && ring[0][1] === ring[ring.length - 1][1]
+        const coordinates = closed ? ring : [...ring, ring[0]]
+        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) => [toRing(ring)])
+        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/globe/atmosphere.ts

@@ -0,0 +1,98 @@
+/**
+ * The halo around the planet's edge — a shell, seen from the inside.
+ *
+ * The trick is old and still the best one: draw a sphere slightly larger than
+ * the planet, keep only its **back** faces, and light nothing. What survives is
+ * the far wall of the shell, which the planet hides everywhere except around the
+ * silhouette — so the brightness only has to be a function of how edge-on the
+ * surface is, and the occlusion comes free from the depth buffer.
+ *
+ * That is why it is a shader rather than a material with a gradient: the value
+ * needed is `1 - |n · v|`, which no material exposes, and which is *per pixel*.
+ * A gradient painted onto a sphere is fixed to the geometry and slides as the
+ * camera turns; this is anchored to the eye, so the rim stays on the horizon
+ * wherever the globe is looked at from.
+ *
+ * Additively blended, because atmosphere adds light rather than covering
+ * anything — which also means it never darkens the stars or the planet behind
+ * it, and needs no sorting against them.
+ */
+
+import { Mat, type Material3D, type NormalizedColor } from "@motionscript/sdk"
+
+/**
+ * The eye-facing rim term, and nothing else.
+ *
+ * `vView` is the fragment's direction to the camera in view space, where the eye
+ * is the origin — so it needs no camera uniform, and the same shader works for
+ * an orthographic camera where a `cameraPosition` version would not.
+ */
+const VERTEX = /* glsl */ `
+varying vec3 vNormal;
+varying vec3 vView;
+
+void main() {
+  vec4 viewPosition = modelViewMatrix * vec4(position, 1.0);
+  vNormal = normalize(normalMatrix * normal);
+  vView = -viewPosition.xyz;
+  gl_Position = projectionMatrix * viewPosition;
+}
+`
+
+/**
+ * `abs` on the dot product, deliberately: these are back faces, so the normal
+ * points away from the eye and the un-absolute term would be brightest face-on —
+ * a disc over the planet instead of a ring around it.
+ */
+const FRAGMENT = /* glsl */ `
+uniform vec3 uColor;
+uniform float uFalloff;
+uniform float uIntensity;
+
+varying vec3 vNormal;
+varying vec3 vView;
+
+void main() {
+  float facing = abs(dot(normalize(vNormal), normalize(vView)));
+  float rim = pow(clamp(1.0 - facing, 0.0, 1.0), uFalloff) * uIntensity;
+  gl_FragColor = vec4(uColor * rim, rim);
+}
+`
+
+/**
+ * The atmosphere's material — including which faces it keeps and how it blends.
+ *
+ * Those two belong *on the descriptor* rather than in the mesh shorthand beside
+ * it, and not as a matter of taste: `resolveMaterialShorthand3D` returns an
+ * explicit `material` immediately and never reaches the shorthand's own `faces`
+ * or `blend`. Set them out there and they are silently dropped — the shell keeps
+ * its front faces, covers the planet in a bright disc, and the only clue is that
+ * the globe has gone.
+ *
+ * `color` arrives as core's resolved `[r, g, b, a]` and is handed on as three
+ * numbers rather than four: the uniform coercion reads a numeric array of length
+ * four as a `vec4`, never as a colour, so passing the tuple whole would bind
+ * alpha where the shader expects nothing and shift the hue. Alpha has nothing to
+ * say here anyway — the rim term is the opacity.
+ */
+export function atmosphereMaterial(
+  color: NormalizedColor,
+  falloff: number,
+  intensity: number
+): Material3D {
+  return Mat.shader({
+    vertex: VERTEX,
+    fragment: FRAGMENT,
+    uniforms: {
+      uColor: [color[0], color[1], color[2]],
+      uFalloff: falloff,
+      uIntensity: intensity,
+    },
+    faces: "back",
+    blend: "additive",
+    transparent: true,
+    // Nothing here writes depth: the shell is a light, and one that occluded
+    // would hide the planet it is drawn around.
+    depthWrite: false,
+  })
+}

package/src/globe/borders.ts

@@ -0,0 +1,166 @@
+import { world } from "./world"
+
+/**
+ * Every boundary line on the map, each drawn **once**.
+ *
+ * ## The defect this exists to fix
+ *
+ * Country rings are stored per country, so a border between two of them appears
+ * in both — and stroking each country's own path draws that line twice. The
+ * claim that this is harmless with an opaque colour is *wrong*, and visibly so:
+ * a stroke is antialiased, so the fringe pixels either side get composited
+ * twice. Coverage `a` blended over itself is `2a - a²`, which turns a half-lit
+ * edge pixel into a three-quarters-lit one — and the eye reads that as a bolder,
+ * wider line. Internal borders came out looking about twice the weight of
+ * coastlines, which are stroked once because their other side is ocean.
+ *
+ * ## Dedupe by segment, then stitch
+ *
+ * Natural Earth's neighbours share their vertices *exactly* — measured on the
+ * vendored data: of 10,360 segments, 2,658 appear in precisely two rings and
+ * 5,020 in one — so a segment appearing twice is a shared border and one
+ * appearing once is a coast. That makes the dedupe an equality test rather than
+ * a geometric tolerance, which is the only reason this is a small function
+ * instead of a topology library.
+ *
+ * The unique segments are then stitched back into polylines rather than drawn as
+ * ten thousand two-point lines: a run of separate segments has a cap at every
+ * vertex instead of a join, which on a 1.5px stroke reads as a dotted, lumpy
+ * coastline.
+ *
+ * ## What the caller must do with them
+ *
+ * Draw them **instead of** stroking the country paths, not as well. The country
+ * paths are then fill-only, and every line on the map — coast or border — is one
+ * stroke of the same weight.
+ */
+
+/** One boundary run, as flat `[lon, lat, lon, lat, …]` degrees. */
+export type BorderLine = Float64Array
+
+let lines: BorderLine[] | null = null
+
+/** The boundary lines, computed on first use and shared thereafter. */
+export function borderLines(): BorderLine[] {
+  return (lines ??= build())
+}
+
+/**
+ * A vertex's identity.
+ *
+ * The integer form, not the degrees: the decoder divides stored integers by the
+ * quantum, so two rings that share a vertex hold bit-identical doubles — but
+ * keying on the integer says that out loud rather than resting on it, and is a
+ * cheaper string besides.
+ */
+function nodeKey(lon: number, lat: number): number {
+  // Packed into one number rather than a string: 20,000 keys built per pass,
+  // and a numeric Map key skips the hashing a template literal costs.
+  return Math.round(lon * 1000) * 1_000_000 + Math.round(lat * 1000)
+}
+
+interface Segment {
+  a: number
+  b: number
+  /** Endpoint coordinates, kept so a chain can be written out without a lookup. */
+  ax: number
+  ay: number
+  bx: number
+  by: number
+}
+
+function build(): BorderLine[] {
+  // --- Collect each distinct segment once -------------------------------
+  const unique = new Map<string, Segment>()
+  for (const ring of world().rings) {
+    const count = ring.points.length / 2
+    for (let i = 0; i < count; i++) {
+      const j = (i + 1) % count
+      const ax = ring.points[i * 2]!
+      const ay = ring.points[i * 2 + 1]!
+      const bx = ring.points[j * 2]!
+      const by = ring.points[j * 2 + 1]!
+      const a = nodeKey(ax, ay)
+      const b = nodeKey(bx, by)
+      if (a === b) continue
+      // Canonical, so a border walked one way by one country and the other way
+      // by its neighbour collides rather than surviving as two.
+      const key = a < b ? `${a}:${b}` : `${b}:${a}`
+      if (!unique.has(key)) unique.set(key, { a, b, ax, ay, bx, by })
+    }
+  }
+
+  // --- Chain them into runs ---------------------------------------------
+  const segments = [...unique.values()]
+  const at = new Map<number, number[]>()
+  segments.forEach((segment, index) => {
+    for (const node of [segment.a, segment.b]) {
+      const list = at.get(node)
+      if (list) list.push(index)
+      else at.set(node, [index])
+    }
+  })
+
+  const used = new Uint8Array(segments.length)
+  const out: BorderLine[] = []
+
+  /** The next unused segment at `node`, or −1. */
+  const nextAt = (node: number): number => {
+    for (const index of at.get(node) ?? []) if (!used[index]) return index
+    return -1
+  }
+
+  for (let start = 0; start < segments.length; start++) {
+    if (used[start]) continue
+
+    const first = segments[start]!
+    used[start] = 1
+    // Grown from the middle out: forward from `b`, then the backward half is
+    // reversed onto the front. A junction picks an arbitrary unused neighbour,
+    // which is fine — every line is the same colour and weight, so where one run
+    // ends and the next begins is not visible.
+    const forward: number[] = [first.ax, first.ay, first.bx, first.by]
+    let node = first.b
+    for (;;) {
+      const index = nextAt(node)
+      if (index < 0) break
+      used[index] = 1
+      const segment = segments[index]!
+      const far = segment.a === node ? segment.b : segment.a
+      const fx = segment.a === node ? segment.bx : segment.ax
+      const fy = segment.a === node ? segment.by : segment.ay
+      forward.push(fx, fy)
+      node = far
+    }
+
+    const backward: number[] = []
+    node = first.a
+    for (;;) {
+      const index = nextAt(node)
+      if (index < 0) break
+      used[index] = 1
+      const segment = segments[index]!
+      const far = segment.a === node ? segment.b : segment.a
+      const fx = segment.a === node ? segment.bx : segment.ax
+      const fy = segment.a === node ? segment.by : segment.ay
+      backward.push(fx, fy)
+      node = far
+    }
+
+    if (backward.length === 0) {
+      out.push(Float64Array.from(forward))
+      continue
+    }
+    // Reverse the backward half pairwise and prepend it.
+    const points = new Float64Array(backward.length + forward.length)
+    let write = 0
+    for (let i = backward.length - 2; i >= 0; i -= 2) {
+      points[write++] = backward[i]!
+      points[write++] = backward[i + 1]!
+    }
+    points.set(forward, write)
+    out.push(points)
+  }
+
+  return out
+}