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

package/src/border/format.ts

@@ -0,0 +1,147 @@
+import { geoArea } from "d3-geo"
+
+/** The on-disk shape `@motionscript/geo-data` writes; see its `generate.mjs`. */
+export const GEO_DATA_FORMAT = 1
+
+export interface GeoFileData {
+    format: number
+    source?: string
+    transform: { scale: [number, number]; translate: [number, number] }
+    /** Global arc id per local arc — identical across files for a shared border. */
+    arcIds: number[]
+    /** Per arc, flat `[x0, y0, w0, dx, dy, w, …]`: delta-encoded quantized lon/lat and a weight bucket. */
+    arcs: number[][]
+    features: GeoFeatureData[]
+}
+
+export interface GeoFeatureData {
+    code: string
+    name: string
+    nameNl?: string
+    parent: string | null
+    first: boolean
+    listed: boolean
+    remote?: boolean
+    area: number
+    mainland: number[] | null
+    areas: number[]
+    /** Polygons → rings → arc refs (`~i` is arc `i` reversed). */
+    polygons: number[][][]
+}
+
+/** `[code, name, nameNl, parent, first]` per listed region. */
+export type GeoIndexEntry = [string, string, string, string | null, 0 | 1]
+
+export interface GeoIndex {
+    format: number
+    source?: string
+    regions: GeoIndexEntry[]
+}
+
+export interface GeoArc {
+    /** Identity for de-duplicating a border drawn by two regions, across files. */
+    key: number | string
+    /** Interleaved lon/lat, in degrees. */
+    points: Float64Array
+    /** Per point: 0 always survives, higher buckets are less significant; see `thresholdBucket`. */
+    buckets: Uint8Array
+}
+
+export interface GeoRingRef {
+    arc: GeoArc
+    reversed: boolean
+}
+
+export interface GeoPolygon {
+    rings: GeoRingRef[][]
+    /** Per ring, in steradians — exterior first, then holes. */
+    ringAreas: number[]
+    area: number
+    mainland: boolean
+}
+
+export interface GeoFeature {
+    code: string
+    name: string
+    nameNl: string
+    parent: string | null
+    first: boolean
+    listed: boolean
+    remote: boolean
+    polygons: GeoPolygon[]
+}
+
+export interface DecodedGeoFile {
+    features: Map<string, GeoFeature>
+}
+
+function decodeArc(encoded: number[], key: number, [kx, ky]: [number, number], [tx, ty]: [number, number]): GeoArc {
+    const count = encoded.length / 3
+    const points = new Float64Array(count * 2)
+    const buckets = new Uint8Array(count)
+    let x = 0
+    let y = 0
+    for (let i = 0; i < count; i++) {
+        x += encoded[i * 3]
+        y += encoded[i * 3 + 1]
+        points[i * 2] = x * kx + tx
+        points[i * 2 + 1] = y * ky + ty
+        buckets[i] = encoded[i * 3 + 2]
+    }
+    return { key, points, buckets }
+}
+
+export function ringCoordinates(ring: readonly GeoRingRef[]): [number, number][] {
+    const out: [number, number][] = []
+    for (const { arc, reversed } of ring) {
+        const n = arc.buckets.length
+        for (let j = out.length === 0 ? 0 : 1; j < n; j++) {
+            const i = reversed ? n - 1 - j : j
+            out.push([arc.points[i * 2], arc.points[i * 2 + 1]])
+        }
+    }
+    return out
+}
+
+/** A ring's area in steradians, whichever way it winds. */
+export function ringArea(ring: readonly GeoRingRef[]): number {
+    const coordinates = ringCoordinates(ring)
+    if (coordinates.length < 4) return 0
+    const area = geoArea({ type: "Polygon", coordinates: [coordinates] })
+    return area > 2 * Math.PI ? 4 * Math.PI - area : area
+}
+
+export function decodeGeoFile(data: GeoFileData): DecodedGeoFile {
+    if (data.format !== GEO_DATA_FORMAT) {
+        throw new Error(`geo data format ${data.format} is not supported (expected ${GEO_DATA_FORMAT})`)
+    }
+    const arcs = data.arcs.map((encoded, i) =>
+        decodeArc(encoded, data.arcIds[i], data.transform.scale, data.transform.translate)
+    )
+    const ref = (index: number): GeoRingRef =>
+        index < 0 ? { arc: arcs[~index], reversed: true } : { arc: arcs[index], reversed: false }
+
+    const features = new Map<string, GeoFeature>()
+    for (const f of data.features) {
+        const mainland = f.mainland ? new Set(f.mainland) : null
+        features.set(f.code, {
+            code: f.code,
+            name: f.name,
+            nameNl: f.nameNl ?? f.name,
+            parent: f.parent,
+            first: f.first,
+            listed: f.listed,
+            remote: f.remote === true,
+            polygons: f.polygons.map((rings, i) => {
+                const resolved = rings.map((ring) => ring.map(ref))
+                return {
+                    rings: resolved,
+                    ringAreas: resolved.map((ring, r) => (r === 0 ? f.areas[i] : ringArea(ring))),
+                    area: f.areas[i],
+                    mainland: mainland === null || mainland.has(i),
+                }
+            }),
+        })
+    }
+    return { features }
+}

package/src/border/geo-border.ts

@@ -0,0 +1,260 @@
+import {
+    Clip,
+    Graphics2D,
+    ShapeNode,
+    node,
+    property,
+    type AssetScope,
+    type FillResolved,
+    type NodeConfig,
+    type PathBounds,
+    type RenderContext2D,
+    type ShadowResolved,
+    type ShapeProps,
+    type StrokeResolved,
+} from "@motionscript/core"
+import { snapValue } from "@motionscript/core/component"
+
+import { geoGeometry, type GeoBorders, type GeoContour, type GeoGeometry, type GeoProjectionKind } from "./geometry"
+import { geoDataVersion, geoLoader } from "./loader"
+import { geoRegistry } from "./registry"
+import { geoFilesFor, normalizeIso, selectGeoFeatures, type GeoFrame, type GeoLevel } from "./selection"
+
+export interface GeoBorderProps extends ShapeProps {
+    /** ISO 3166-1 alpha-2 (`"FR"`) or ISO 3166-2 (`"US-CA"`) codes. */
+    iso: string | readonly string[]
+    level: GeoLevel
+    /** 0–1: 1 is full resolution, lower is a more stylised outline. */
+    detail: number
+    projection: GeoProjectionKind
+    frame: GeoFrame
+    borders: GeoBorders
+}
+
+interface Chunk {
+    data: string
+    /** Where this chunk's contours sit along the whole drawing, as fractions of its length. */
+    from: number
+    to: number
+}
+
+interface Drawn {
+    geometry: GeoGeometry
+    width: number
+    height: number
+    fills: Chunk[]
+    lines: Chunk[]
+}
+
+// Skia's cost for one path grows faster than its contour count, and a shape
+// drawn as several paths under one paint is unioned every frame — so a region
+// is cut into paths of bounded size, each painted on its own.
+const CONTOURS_PER_PATH = 256
+const POINTS_PER_PATH = 40_000
+
+const coordinate = (value: number) => String(Math.round(value * 100) / 100)
+
+function chunk(contours: readonly GeoContour[], total: number, scale: number): Chunk[] {
+    const chunks: Chunk[] = []
+    let parts: string[] = []
+    let count = 0
+    let points = 0
+    let from = 0
+    let length = 0
+    const flush = () => {
+        if (count === 0) return
+        const to = total > 0 ? Math.min(1, length / total) : 1
+        chunks.push({ data: parts.join(""), from, to })
+        from = to
+        parts = []
+        count = 0
+        points = 0
+    }
+    for (const contour of contours) {
+        const p = contour.points
+        // Path data is y-down; the unit geometry is y-up.
+        for (let i = 0; i < p.length; i += 2) {
+            parts.push(i === 0 ? "M" : "L", coordinate(p[i] * scale), " ", coordinate(-p[i + 1] * scale))
+        }
+        if (contour.closed) parts.push("Z")
+        count++
+        points += p.length / 2
+        length += contour.length
+        if (count >= CONTOURS_PER_PATH || points >= POINTS_PER_PATH) flush()
+    }
+    flush()
+    return chunks
+}
+
+/**
+ * Country and subdivision outlines by ISO 3166 code, fitted into the node's box.
+ *
+ *   <GeoBorder iso={["FR", "DE"]} detail={0.4} stroke={{ weight: 2, fill: "white" }} />
+ *
+ * Geometry comes from whatever `geoRegistry` has been given — a URL, a loader,
+ * or shapes defined by hand — and loads as a declared asset, so a frame never
+ * draws half a country. Fill and stroke are separate geometry: the fill is each
+ * region's polygons, the stroke is every border once, which is why a border two
+ * selected regions share is not drawn twice and why `stroke.align` does not
+ * apply.
+ */
+@node({
+    key: "geoBorder",
+    parentKey: "shape",
+    forkable: true,
+    layout: {
+        children: "freeform",
+        acceptsChildren: true,
+        defaultWidthMode: "fixed",
+        defaultHeightMode: "fixed",
+    },
+    seed: { width: 480, height: 480 },
+})
+export class GeoBorder extends ShapeNode<GeoBorderProps> {
+    @property({ default: ["FR"], mapper: normalizeIso, tween: snapValue })
+    declare iso: string | readonly string[]
+
+    @property({ default: "country", tween: snapValue, options: ["country", "state"] })
+    declare level: GeoLevel
+
+    @property({ default: 0.5, min: 0, max: 1, step: 0.01 })
+    declare detail: number
+
+    @property({
+        default: "conic",
+        tween: snapValue,
+        options: ["conic", "mercator", "equirectangular", "orthographic"],
+    })
+    declare projection: GeoProjectionKind
+
+    @property({ default: "mainland", tween: snapValue, options: ["mainland", "all"] })
+    declare frame: GeoFrame
+
+    @property({ default: "all", tween: snapValue, options: ["all", "outline"] })
+    declare borders: GeoBorders
+
+    constructor(props?: NodeConfig<GeoBorder, GeoBorderProps>) {
+        super(props as NodeConfig<ShapeNode<GeoBorderProps>, GeoBorderProps>)
+    }
+
+    override declareAssets(assets: AssetScope): void {
+        super.declareAssets(assets)
+        for (const file of geoFilesFor(this.iso as string[], this.level)) {
+            assets.loader(`geo:${file}`, geoLoader(file), { gate: "render" })
+        }
+    }
+
+    protected override renderSelf(ctx: RenderContext2D): void {
+        const drawn = this._drawn()
+        const fill = this.fill as FillResolved[]
+        if (!drawn || drawn.fills.length === 0) return
+        const shadow = this.shadow as ShadowResolved[]
+        const g = new Graphics2D()
+        for (const chunk of drawn.fills) {
+            if (!this._pathOp(g, chunk)) continue
+            if (shadow.length > 0) g.shadow(shadow)
+            g.fill(fill)
+        }
+        ctx.draw(g)
+    }
+
+    protected override renderOverlay(ctx: RenderContext2D): void {
+        const overlay = this.overlay as FillResolved[]
+        if (overlay.length === 0) return
+        const drawn = this._drawn()
+        if (!drawn) return
+        const g = new Graphics2D()
+        for (const chunk of drawn.fills) if (this._pathOp(g, chunk)) g.fill(overlay)
+        ctx.draw(g)
+    }
+
+    protected override renderStroke(ctx: RenderContext2D): void {
+        const stroke = this.stroke as StrokeResolved[]
+        if (stroke.length === 0) return
+        const drawn = this._drawn()
+        if (!drawn || drawn.lines.length === 0) return
+        const centred = stroke.map((layer) => (layer.align === 0 ? layer : { ...layer, align: 0 }))
+        const shadow = this.shadow as ShadowResolved[]
+        const castsShadow = shadow.length > 0 && !(this.fill as FillResolved[]).some((layer) => (layer.opacity ?? 1) > 0)
+        const g = new Graphics2D()
+        for (const chunk of drawn.lines) {
+            if (!this._pathOp(g, chunk)) continue
+            if (castsShadow) g.shadow(shadow)
+            g.stroke(centred)
+        }
+        ctx.draw(g)
+    }
+
+    // The box, not the outline: a path clip has no winding test, and a country's
+    // bounding box is what the selection shows.
+    protected override clipSelf(): Clip {
+        return new Clip().rect({
+            x: 0,
+            y: 0,
+            width: this.layoutBounds.width,
+            height: this.layoutBounds.height,
+        })
+    }
+
+    private _drawnCache: Drawn | null = null
+    private readonly _warned = new Set<string>()
+
+    private _pathOp(g: Graphics2D, chunk: Chunk): boolean {
+        const start = this.start
+        const end = this.end
+        const width = this.layoutBounds.width
+        const height = this.layoutBounds.height
+        const centerBounds: PathBounds = [-width / 2, -height / 2, width / 2, height / 2]
+        if (start <= 0 && end >= 1) {
+            g.path({ data: chunk.data, centerBounds })
+            return true
+        }
+        const span = chunk.to - chunk.from
+        if (span <= 0) return false
+        const localStart = Math.max(0, (start - chunk.from) / span)
+        const localEnd = Math.min(1, (end - chunk.from) / span)
+        if (localEnd <= localStart) return false
+        g.path({ data: chunk.data, centerBounds, start: localStart, end: localEnd })
+        return true
+    }
+
+    private _drawn(): Drawn | null {
+        const codes = this.iso as string[]
+        const level = this.level
+        const frame = this.frame
+        const selection = selectGeoFeatures(codes, level, frame)
+        for (const code of selection.unknown) {
+            if (this._warned.has(code)) continue
+            this._warned.add(code)
+            console.warn(`[GeoBorder] no region with code ${code}`)
+        }
+        if (selection.features.length === 0) return null
+
+        const geometry = geoGeometry({
+            selectionKey: `${geoRegistry.generation}:${geoDataVersion()}:${level}:${frame}:${codes.join(",")}`,
+            features: selection.features,
+            frame,
+            projection: this.projection,
+            borders: this.borders,
+            detail: this.detail,
+        })
+        if (!geometry) return null
+
+        const width = this.layoutBounds.width
+        const height = this.layoutBounds.height
+        const cached = this._drawnCache
+        if (cached && cached.geometry === geometry && cached.width === width && cached.height === height) {
+            return cached
+        }
+        const scale = Math.min(width / geometry.width, height / geometry.height)
+        const drawn: Drawn = {
+            geometry,
+            width,
+            height,
+            fills: chunk(geometry.fills, geometry.fillLength, scale),
+            lines: chunk(geometry.lines, geometry.lineLength, scale),
+        }
+        this._drawnCache = drawn
+        return drawn
+    }
+}