@faclon-labs/app-sdk 0.1.0 → 0.2.0

package/vendor/map-engine/cesium/renderer.js

@@ -0,0 +1,837 @@
+import { tokenFor, volumeOf } from '../layers/layers.js';
+import { spatial } from '../spatial/index.js';
+import { cameraPitch, enginePitch, rangeForZoom, zoomForRange } from './camera.js';
+import { loadHeights, tileUrl } from '../render/terrarium.js';
+export const DEFAULT_CESIUM_THEME = {
+    markerColor: '#4CC3FF',
+    lineColor: '#C9A66B',
+    fillColor: '#4CC3FF',
+    trackColor: '#4CC3FF',
+    selectionColor: '#FFD43B',
+    hoverColor: '#FFFFFF',
+    labelColor: '#1f2328',
+    labelHalo: '#FFFFFF',
+    background: '#0E1512',
+};
+const STEM = '#stem';
+const OUTLINE = '#outline';
+const LABEL = '#label';
+const keyOf = (id) => id.split('#')[0];
+const splitKey = (key) => {
+    const i = key.indexOf(':');
+    return [key.slice(0, i), key.slice(i + 1)];
+};
+const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : typeof v === 'string' && v.trim() !== '' && Number.isFinite(Number(v)) ? Number(v) : undefined);
+/**
+ * The layout Cesium needs to fill its container (canvas size, credit placement). Cesium's widgets.css carries the
+ * same rules; without it the canvas stays at the browser default 300x150. Zero specificity (`:where`), so an app
+ * that loads widgets.css or styles these itself still wins.
+ */
+const BASE_STYLE_ID = 'map-engine-cesium-base';
+const BASE_STYLE = [
+    ':where(.cesium-viewer),:where(.cesium-viewer-cesiumWidgetContainer),:where(.cesium-widget){position:relative;display:block;width:100%;height:100%;overflow:hidden}',
+    ':where(.cesium-widget canvas){display:block;width:100%;height:100%;touch-action:none}',
+    ':where(.cesium-viewer-bottom){position:absolute;bottom:0;left:0;padding-right:5px}',
+    ':where(.cesium-widget-credits){position:absolute;bottom:0;left:0;font:10px sans-serif;color:#fff;text-shadow:0 0 2px #000}',
+    ':where(.cesium-viewer .cesium-widget-credits){position:static;display:inline}',
+    ':where(.cesium-widget-credits a){color:#fff}',
+].join('');
+function ensureBaseStyle() {
+    if (typeof document === 'undefined' || document.getElementById(BASE_STYLE_ID))
+        return;
+    const el = document.createElement('style');
+    el.id = BASE_STYLE_ID;
+    el.textContent = BASE_STYLE;
+    document.head.appendChild(el);
+}
+export class CesiumRenderer {
+    options;
+    lib = null;
+    viewer = null;
+    handler = null;
+    offs = [];
+    gen = 0;
+    theme;
+    layers = new Map();
+    objects = new Map();
+    /** Every entity id drawn for an object (shape, stem, outline, parts, label), so removal is complete. */
+    drawn = new Map();
+    /** How each point object was drawn, apart from where: when only its position changes it is moved, not rebuilt. */
+    looks = new Map();
+    hoverKey = null;
+    fontName;
+    terrain = null;
+    /** Loaded 3D Tiles by id, with the config they were loaded from. */
+    tilesets = new Map();
+    warnedEllipsoid = false;
+    warnedStyleBasemap = false;
+    /** Longest side of each model file once measured (sizeMeters). */
+    extents = new Map();
+    measuring = new Set();
+    /** Ground under volume origins, as drawn (exaggerated metres), by position; filled by one batched terrain sample. */
+    grounds = new Map();
+    groundQueue = new Map();
+    listeners = {
+        viewport: new Set(),
+        pick: new Set(),
+        click: new Set(),
+        hover: new Set(),
+        error: new Set(),
+        move: new Set(),
+    };
+    /** A true globe: heights, models, extrusions, sensor volumes and 3D Tiles. */
+    capabilities = { globe: true, terrain: true, elevation: true, altitude: true, extrusion: true, models: true, volumes: true, tiles3d: true };
+    constructor(options = {}) {
+        this.options = options;
+        this.theme = { ...DEFAULT_CESIUM_THEME, ...options.theme };
+    }
+    async initialize(container, options) {
+        const gen = this.gen;
+        if (this.options.baseUrl && typeof window !== 'undefined')
+            window.CESIUM_BASE_URL = this.options.baseUrl;
+        const lib = this.options.cesium ?? (await import('cesium'));
+        if (gen !== this.gen)
+            return;
+        this.lib = lib;
+        lib.Ion.defaultAccessToken = ''; // never Cesium Ion (ADR-027: self-hostable)
+        this.fontName = options.basemap.font?.name;
+        this.terrain = options.terrain ?? null;
+        ensureBaseStyle();
+        const viewer = new lib.Viewer(container, {
+            baseLayer: this.imageryLayer(options.basemap) ?? false,
+            terrainProvider: this.terrainProvider(this.terrain),
+            animation: false,
+            timeline: false,
+            baseLayerPicker: false,
+            geocoder: false,
+            homeButton: false,
+            sceneModePicker: false,
+            navigationHelpButton: false,
+            fullscreenButton: false,
+            infoBox: false,
+            selectionIndicator: false,
+            scene3DOnly: true,
+        });
+        this.viewer = viewer;
+        viewer.scene.globe.baseColor = lib.Color.fromCssColorString(options.basemap.background ?? this.theme.background);
+        viewer.scene.globe.depthTestAgainstTerrain = true;
+        // Exaggeration is applied by this renderer (terrain heights and object heights alike), not by Cesium, whose
+        // vertical exaggeration treats billboards, polylines and terrain differently.
+        viewer.scene.verticalExaggeration = 1;
+        this.setViewport(options.viewport);
+        this.applyContours();
+        this.bindEvents(lib, viewer);
+        if (options.tilesets?.length)
+            this.setTilesets(options.tilesets);
+    }
+    setViewport(viewport, options) {
+        const lib = this.lib;
+        const v = this.viewer;
+        if (!lib || !v)
+            return;
+        const { latitude, longitude } = viewport.center;
+        const ground = v.scene.globe.getHeight(lib.Cartographic.fromDegrees(longitude, latitude)) ?? 0;
+        const lookPoint = lib.Cartesian3.fromDegrees(longitude, latitude, ground);
+        const fovy = v.camera.frustum.fovy ?? Math.PI / 3;
+        const range = rangeForZoom(viewport.zoom, latitude, this.getSize().height || 600, fovy);
+        const offset = new lib.HeadingPitchRange(lib.Math.toRadians(viewport.bearing ?? 0), lib.Math.toRadians(cameraPitch(viewport.pitch)), range);
+        if (options?.animate) {
+            v.camera.flyToBoundingSphere(new lib.BoundingSphere(lookPoint, 0), { offset, duration: 0.8 });
+        }
+        else {
+            v.camera.lookAt(lookPoint, offset);
+            v.camera.lookAtTransform(lib.Matrix4.IDENTITY); // free the camera again
+        }
+    }
+    render(scene) {
+        if (!this.viewer)
+            return;
+        this.viewer.entities.removeAll();
+        this.objects.clear();
+        this.layers.clear();
+        for (const l of scene.layers)
+            this.layers.set(l.id, structuredClone(l));
+        for (const so of scene.objects)
+            this.put(so);
+    }
+    update(patch) {
+        if (!this.viewer)
+            return;
+        // One batch: Cesium recomputes its entity displays once, not per change.
+        const entities = this.viewer.entities;
+        const rebuild = new Map();
+        const gone = new Set(patch.removed ?? []);
+        entities.suspendEvents();
+        try {
+            for (const x of patch.layers ? this.applyLayers(patch.layers) : []) {
+                if (typeof x === 'string')
+                    gone.add(x);
+                else
+                    rebuild.set(x.key, x);
+            }
+            for (const so of [...(patch.added ?? []), ...(patch.updated ?? [])])
+                if (!this.move(so))
+                    rebuild.set(so.key, so);
+        }
+        finally {
+            entities.resumeEvents();
+        }
+        this.redraw([...rebuild.values()], [...gone]);
+    }
+    /**
+     * Draws objects again, in batches. Cesium merges a removal and an add of the same entity id within one batch
+     * into "nothing changed", and its visualizers keep drawing the old entity — so all removals go in one batch,
+     * which is flushed before the adds.
+     */
+    redraw(list, gone = []) {
+        if (!list.length && !gone.length)
+            return;
+        const entities = this.viewer.entities;
+        entities.suspendEvents();
+        try {
+            for (const key of gone)
+                this.drop(key);
+            for (const so of list)
+                this.drop(so.key);
+        }
+        finally {
+            entities.resumeEvents();
+        }
+        entities.suspendEvents();
+        try {
+            for (const so of list)
+                this.draw(so);
+        }
+        finally {
+            entities.resumeEvents();
+        }
+    }
+    /** What a point object looks like apart from its position (layer, selection, properties). */
+    lookOf(so) {
+        if (so.object.geometry.type !== 'Point')
+            return null;
+        const layer = this.layers.get(so.layerId);
+        return layer ? JSON.stringify([layer, so.selected, so.hovered, so.object.properties ?? null]) : null;
+    }
+    /**
+     * Moves an already drawn point object when only its position changed (the common live update): the entity and
+     * its stem get the new position; nothing is rebuilt. False when it must be drawn again.
+     */
+    move(so) {
+        const lib = this.lib;
+        const before = this.looks.get(so.key);
+        const look = this.lookOf(so);
+        const e = this.viewer.entities.getById(so.key);
+        if (!look || look !== before || !e || so.object.geometry.type !== 'Point')
+            return false;
+        const layer = this.layers.get(so.layerId);
+        if (layer.visualization.type === 'volume')
+            return false; // placed on the sampled ground: drawn again
+        const el = layer.visualization.elevation;
+        const { longitude, latitude, altitude } = so.object.geometry.coordinates;
+        const h = el ? (el.from === 'property' ? num(so.object.properties?.[el.property]) : altitude) : undefined;
+        const position = lib.Cartesian3.fromDegrees(longitude, latitude, h === undefined ? 0 : this.drawnHeight(longitude, latitude, h, el?.reference === 'agl', el?.exaggeration ?? 1));
+        e.position = new lib.ConstantPositionProperty(position);
+        const stem = this.viewer.entities.getById(so.key + STEM);
+        if (stem?.polyline)
+            stem.polyline.positions = new lib.ConstantProperty([position, lib.Cartesian3.fromDegrees(longitude, latitude, 0)]);
+        this.objects.set(so.key, so);
+        return true;
+    }
+    resize() {
+        this.viewer?.resize();
+        if (this.viewer)
+            for (const l of this.listeners.viewport)
+                l(this.currentViewport());
+    }
+    getSize() {
+        const c = this.viewer?.scene.canvas;
+        return { width: c?.clientWidth ?? 0, height: c?.clientHeight ?? 0 };
+    }
+    project(position) {
+        const lib = this.lib;
+        const v = this.viewer;
+        if (!lib || !v)
+            return null;
+        const h = position.altitude ?? v.scene.globe.getHeight(lib.Cartographic.fromDegrees(position.longitude, position.latitude)) ?? 0;
+        const p = lib.SceneTransforms.worldToWindowCoordinates(v.scene, lib.Cartesian3.fromDegrees(position.longitude, position.latitude, h));
+        return p ? { x: p.x, y: p.y } : null;
+    }
+    onCameraMove(l) {
+        const fn = () => l();
+        this.listeners.move.add(fn);
+        return () => this.listeners.move.delete(fn);
+    }
+    async setBasemap(basemap) {
+        const v = this.viewer;
+        if (!v || !this.lib)
+            return;
+        this.fontName = basemap.font?.name;
+        v.imageryLayers.removeAll();
+        const layer = this.imageryLayer(basemap);
+        if (layer)
+            v.imageryLayers.add(layer);
+        v.scene.globe.baseColor = this.lib.Color.fromCssColorString(basemap.background ?? this.theme.background);
+    }
+    /** Cesium always draws a globe; a flat (mercator) request keeps the globe, which reads the same up close. */
+    setProjection(_projection) { }
+    setTerrain(terrain) {
+        const v = this.viewer;
+        if (!v) {
+            this.terrain = terrain;
+            return;
+        }
+        this.terrain = terrain;
+        this.grounds.clear();
+        this.groundQueue.clear();
+        v.terrainProvider = this.terrainProvider(terrain);
+        this.applyContours();
+        // Heights scale with it, and objects on the ground switch between clamped (terrain) and height 0 (none).
+        this.redraw([...this.objects.values()]);
+    }
+    /** 3D Tiles scenery from URLs (no Cesium Ion): added, replaced, shown/hidden and removed by id. */
+    setTilesets(tilesets) {
+        const lib = this.lib;
+        const v = this.viewer;
+        if (!lib || !v)
+            return;
+        const next = new Map(tilesets.map((t) => [t.id, t]));
+        for (const [id, held] of [...this.tilesets]) {
+            const want = next.get(id);
+            if (want && want.url === held.config.url && want.maximumScreenSpaceError === held.config.maximumScreenSpaceError) {
+                if (held.tileset)
+                    held.tileset.show = want.show !== false;
+                held.config = structuredClone(want);
+                continue;
+            }
+            if (held.tileset)
+                v.scene.primitives.remove(held.tileset);
+            this.tilesets.delete(id);
+        }
+        const gen = this.gen;
+        for (const t of tilesets) {
+            if (this.tilesets.has(t.id))
+                continue;
+            const entry = { config: structuredClone(t), tileset: null };
+            this.tilesets.set(t.id, entry);
+            lib.Cesium3DTileset.fromUrl(t.url, { maximumScreenSpaceError: t.maximumScreenSpaceError ?? 16 }).then((tileset) => {
+                // Dropped or replaced while loading, or the renderer was released: do not add it.
+                if (gen !== this.gen || this.tilesets.get(t.id) !== entry || !this.viewer)
+                    return tileset.destroy();
+                tileset.show = entry.config.show !== false;
+                entry.tileset = this.viewer.scene.primitives.add(tileset);
+            }, (e) => this.emitError(new Error(`3D Tiles ${t.id} failed to load: ${e instanceof Error ? e.message : String(e)}`)));
+        }
+    }
+    async sampleElevation(positions) {
+        const lib = this.lib;
+        const v = this.viewer;
+        if (!lib || !v || !this.terrain)
+            return positions.map(() => null);
+        const cartos = positions.map((p) => lib.Cartographic.fromDegrees(p.longitude, p.latitude));
+        // A heightmap provider declares no tile availability, so sample at a fixed detail level (≈ 10 m at level 14).
+        const out = await lib.sampleTerrain(v.terrainProvider, Math.min(14, this.terrain.maxZoom ?? 14), cartos);
+        const k = this.terrain.exaggeration ?? 1; // the terrain is drawn exaggerated; report true metres
+        return out.map((c) => (Number.isFinite(c.height) ? c.height / k : null));
+    }
+    destroy() {
+        this.gen++;
+        for (const off of this.offs.splice(0))
+            off();
+        try {
+            this.handler?.destroy();
+        }
+        catch {
+            // Releasing must always complete.
+        }
+        try {
+            this.viewer?.destroy();
+        }
+        catch {
+            // Releasing must always complete.
+        }
+        this.handler = null;
+        this.viewer = null;
+        this.tilesets.clear(); // destroyed with the viewer's primitives
+        this.layers.clear();
+        this.objects.clear();
+        for (const set of Object.values(this.listeners))
+            set.clear();
+    }
+    onViewportChange(l) {
+        return this.add(this.listeners.viewport, l);
+    }
+    onPick(l) {
+        return this.add(this.listeners.pick, l);
+    }
+    onMapClick(l) {
+        return this.add(this.listeners.click, l);
+    }
+    onHover(l) {
+        return this.add(this.listeners.hover, l);
+    }
+    onError(l) {
+        return this.add(this.listeners.error, l);
+    }
+    // ---------------------------------------------------------------- environment
+    /** The basemap as Cesium imagery: a tile URL works as is; a vector style URL needs a raster fallback. */
+    imageryLayer(basemap) {
+        const lib = this.lib;
+        const url = basemap.kind === 'tiles' ? basemap.tileUrl : basemap.kind === 'style' ? basemap.rasterFallback : undefined;
+        if (basemap.kind === 'style' && !basemap.rasterFallback && !this.warnedStyleBasemap) {
+            this.warnedStyleBasemap = true;
+            this.emitError(new Error('this basemap is a vector style, which the 3D globe cannot draw: give it a `rasterFallback` tile URL'));
+        }
+        if (!url)
+            return undefined;
+        const credit = basemap.kind === 'style' ? (basemap.rasterFallbackAttribution ?? basemap.attribution) : basemap.attribution;
+        const provider = new lib.UrlTemplateImageryProvider({ url, ...(basemap.maxZoom !== undefined ? { maximumLevel: basemap.maxZoom } : {}), ...(credit ? { credit } : {}) });
+        return new lib.ImageryLayer(provider);
+    }
+    /** Terrain from the configured DEM tiles (same as MapLibre), or a smooth ellipsoid. */
+    terrainProvider(terrain) {
+        const lib = this.lib;
+        if (!terrain)
+            return new lib.EllipsoidTerrainProvider();
+        const samples = this.options.terrainSamples ?? 65;
+        const maxZoom = terrain.maxZoom ?? 15;
+        return new lib.CustomHeightmapTerrainProvider({
+            width: samples,
+            height: samples,
+            tilingScheme: new lib.WebMercatorTilingScheme(),
+            ...(terrain.attribution ? { credit: terrain.attribution } : {}),
+            callback: (x, y, level) => {
+                if (level > maxZoom)
+                    return undefined;
+                const k = terrain.exaggeration ?? 1;
+                return loadHeights(tileUrl(terrain.tileUrl, x, y, level), samples, terrain.encoding).then((h) => {
+                    const heights = h ?? new Float32Array(samples * samples);
+                    if (k !== 1)
+                        for (let i = 0; i < heights.length; i++)
+                            heights[i] = heights[i] * k;
+                    return heights;
+                });
+            },
+        });
+    }
+    // ---------------------------------------------------------------- objects
+    /** Takes the new layer list; returns the objects to draw again and the keys to drop (their layer went away). */
+    applyLayers(next) {
+        const out = [];
+        const changed = new Set();
+        const ids = new Set(next.map((l) => l.id));
+        for (const id of [...this.layers.keys()])
+            if (!ids.has(id))
+                changed.add(id);
+        for (const l of next)
+            if (JSON.stringify(this.layers.get(l.id)) !== JSON.stringify(l))
+                changed.add(l.id);
+        this.layers.clear();
+        for (const l of next)
+            this.layers.set(l.id, structuredClone(l));
+        // Redraw the objects of layers that changed (style, visibility, order) or went away.
+        for (const so of this.objects.values())
+            if (changed.has(so.layerId))
+                out.push(ids.has(so.layerId) ? so : so.key);
+        return out;
+    }
+    drop(key) {
+        const e = this.viewer.entities;
+        for (const id of this.drawn.get(key) ?? [])
+            e.removeById(id);
+        this.drawn.delete(key);
+        this.looks.delete(key);
+        this.objects.delete(key);
+    }
+    /** Adds or replaces the entities of one scene object. */
+    put(so) {
+        this.drop(so.key);
+        this.draw(so);
+    }
+    /** Draws one scene object (nothing of it may be drawn yet). */
+    draw(so) {
+        const lib = this.lib;
+        this.objects.set(so.key, so);
+        const ids = [];
+        this.drawn.set(so.key, ids);
+        const look = this.lookOf(so);
+        if (look)
+            this.looks.set(so.key, look);
+        const viewerEntities = this.viewer.entities;
+        const entities = { add: (o) => (ids.push(String(o.id)), viewerEntities.add(o)) };
+        const layer = this.layers.get(so.layerId);
+        if (!layer || !layer.visible)
+            return;
+        const vz = layer.visualization;
+        const props = so.object.properties;
+        const rules = vz.style;
+        const color = (fallback) => (so.selected ? lib.Color.fromCssColorString(this.theme.selectionColor) : lib.Color.fromCssColorString(tokenFor(rules, 'color', props, fallback)).withAlpha(tokenFor(rules, 'opacity', props, 1)));
+        const g = so.object.geometry;
+        const e = vz.elevation;
+        const label = vz.label && this.fontName ? vz.label : undefined;
+        const labelGraphics = (heightReference, offsetY) => label
+            ? {
+                text: String(props?.[label.property] ?? ''),
+                font: `${label.size ?? 12}px "${this.fontName}", sans-serif`,
+                fillColor: lib.Color.fromCssColorString(label.color ?? this.theme.labelColor),
+                outlineColor: lib.Color.fromCssColorString(label.haloColor ?? this.theme.labelHalo),
+                outlineWidth: 3,
+                style: lib.LabelStyle.FILL_AND_OUTLINE,
+                pixelOffset: new lib.Cartesian2(0, offsetY),
+                heightReference,
+                disableDepthTestDistance: Number.POSITIVE_INFINITY,
+            }
+            : undefined;
+        if (g.type === 'Point' && (vz.type === 'marker' || vz.type === 'heatmap' || vz.type === 'model' || vz.type === 'volume')) {
+            const { longitude, latitude, altitude } = g.coordinates;
+            const h = e ? (e.from === 'property' ? num(props?.[e.property]) : altitude) : undefined;
+            if (e?.reference === 'ellipsoid' && !this.warnedEllipsoid) {
+                this.warnedEllipsoid = true;
+                this.emitError(new Error(`layer ${layer.id}: ellipsoid heights are drawn as sea-level heights (no geoid model in this renderer; up to ~100 m off)`));
+            }
+            const relative = e?.reference === 'agl';
+            const heightReference = h === undefined ? this.groundReference() : relative ? lib.HeightReference.RELATIVE_TO_GROUND : lib.HeightReference.NONE;
+            const position = lib.Cartesian3.fromDegrees(longitude, latitude, h === undefined ? 0 : this.drawnHeight(longitude, latitude, h, relative, e?.exaggeration ?? 1));
+            const size = vz.icon?.size ?? 18;
+            const image = tokenFor(rules, 'imageUrl', props, vz.icon?.imageUrl ?? '');
+            const entity = { id: so.key, position };
+            if (vz.type === 'volume') {
+                // A partial ellipsoid in the local east-north-up frame: clock angles run counter-clockwise from east, so an
+                // azimuth (clockwise from north) becomes 90° − azimuth; cone angles run down from the zenith.
+                const vol = volumeOf(vz.volume, props);
+                if (vol) {
+                    const k = this.terrain ? (this.terrain.exaggeration ?? 1) : 1;
+                    // Cesium lifts a clamped or ground-relative ellipsoid by half its height (it rests on the ground like a
+                    // ball), so a volume is placed at an absolute height with its origin at the sensor.
+                    const base = h === undefined ? this.groundHeight(longitude, latitude) : relative ? this.groundHeight(longitude, latitude) + h * k * (e?.exaggeration ?? 1) : this.drawnHeight(longitude, latitude, h, false, e?.exaggeration ?? 1);
+                    entity.position = lib.Cartesian3.fromDegrees(longitude, latitude, base);
+                    const r = lib.Math.toRadians;
+                    const fill = tokenFor(rules, 'color', props, this.theme.fillColor);
+                    entity.ellipsoid = {
+                        radii: new lib.Cartesian3(vol.range, vol.range, vol.range * k),
+                        // Without inner radii Cesium draws only the outer shell (the far end); a tiny one adds the side walls
+                        // back to the sensor, so the volume reads as a wedge or dome.
+                        innerRadii: new lib.Cartesian3(1, 1, k),
+                        minimumClock: vol.shape === 'wedge' ? r(90 - vol.azimuth - vol.beamWidth / 2) : 0,
+                        maximumClock: vol.shape === 'wedge' ? r(90 - vol.azimuth + vol.beamWidth / 2) : 2 * Math.PI,
+                        minimumCone: r(90 - vol.maxElevation),
+                        maximumCone: r(90 - vol.minElevation),
+                        material: so.selected ? lib.Color.fromCssColorString(this.theme.selectionColor).withAlpha(0.35) : lib.Color.fromCssColorString(fill).withAlpha(0.22),
+                        outline: true,
+                        outlineColor: lib.Color.fromCssColorString(fill).withAlpha(0.6),
+                    };
+                }
+            }
+            else if (vz.type === 'model') {
+                const uri = tokenFor(rules, 'modelUrl', props, vz.model?.url ?? '');
+                if (uri) {
+                    const model = vz.model ?? {};
+                    const axis = model.axis ?? {};
+                    const angle = (prop) => (prop ? (num(props?.[prop]) ?? 0) : 0);
+                    // Cesium stands a glTF file (+Y up) upright itself; its heading 0 points the model's +X north, so the
+                    // glTF front (+Z) needs −90°.
+                    const hpr = new lib.HeadingPitchRoll(lib.Math.toRadians(-90 + (axis.yaw ?? 0) + angle(model.headingProperty)), lib.Math.toRadians((axis.pitch ?? 0) + angle(model.pitchProperty)), lib.Math.toRadians((axis.roll ?? 0) + angle(model.rollProperty)));
+                    entity.orientation = lib.Transforms.headingPitchRollQuaternion(position, hpr);
+                    const extent = this.extents.get(uri);
+                    if (model.sizeMeters && extent === undefined)
+                        this.measure(uri);
+                    entity.model = { uri, minimumPixelSize: 36, heightReference, scale: model.sizeMeters && extent ? model.sizeMeters / extent : 1, ...(so.selected ? { silhouetteColor: lib.Color.fromCssColorString(this.theme.selectionColor), silhouetteSize: 2 } : {}) };
+                }
+            }
+            else if (image && h === undefined) {
+                // Icons for objects on the ground. Known limit: Cesium billboards at a height were drawn at the ground in
+                // our views (points are placed correctly), so objects in the air are drawn as points (coloured by the rules).
+                entity.billboard = { image, width: size + (so.selected ? 6 : 0), height: size + (so.selected ? 6 : 0), heightReference, disableDepthTestDistance: Number.POSITIVE_INFINITY };
+            }
+            else {
+                entity.point = {
+                    // A dot standing in for an icon is a modest 14 px; a plain dot layer uses its own size.
+                    pixelSize: (image ? 14 : tokenFor(rules, 'size', props, size / 2) * 2) + (so.selected ? 4 : 0),
+                    color: color(this.theme.markerColor),
+                    outlineColor: so.selected ? lib.Color.fromCssColorString(this.theme.selectionColor) : lib.Color.fromCssColorString(tokenFor(rules, 'strokeColor', props, '#0B100E')),
+                    outlineWidth: 1.5,
+                    heightReference,
+                    disableDepthTestDistance: Number.POSITIVE_INFINITY,
+                };
+            }
+            const lg = labelGraphics(heightReference, size / 2 + 10);
+            if (lg)
+                entity.label = lg;
+            entities.add(entity);
+            // A stem to the ground: a line down to sea level, its lower part hidden by the terrain (depth-tested).
+            if (e?.stems && h !== undefined && !relative) {
+                entities.add({ id: so.key + STEM, polyline: { positions: [position, lib.Cartesian3.fromDegrees(longitude, latitude, 0)], width: 1.5, material: color(this.theme.markerColor).withAlpha(0.6) } });
+            }
+            return;
+        }
+        if (g.type === 'LineString' || g.type === 'MultiLineString') {
+            const lines = g.type === 'LineString' ? [g.coordinates] : g.coordinates;
+            const lift = e?.exaggeration ?? 1;
+            const flat = lines.flat();
+            const positions = flat.map((p) => lib.Cartesian3.fromDegrees(p.longitude, p.latitude, e ? this.drawnHeight(p.longitude, p.latitude, e.from === 'property' ? (num(props?.[e.property]) ?? 0) : (p.altitude ?? 0), e.reference === 'agl', lift) : 0));
+            entities.add({
+                id: so.key,
+                polyline: { positions, width: tokenFor(rules, 'size', props, 3) + (so.selected ? 2 : 0), material: color(vz.type === 'track' ? this.theme.trackColor : this.theme.lineColor), clampToGround: !e },
+            });
+            return;
+        }
+        if (g.type === 'Polygon' || g.type === 'MultiPolygon' || g.type === 'Circle') {
+            const rings = g.type === 'Polygon' ? [g.coordinates] : g.type === 'MultiPolygon' ? g.coordinates : [[circleRing(g.center, g.radiusMeters)]];
+            rings.forEach((poly, i) => {
+                const [outer, ...holes] = poly;
+                const toCart = (ring) => ring.map((p) => lib.Cartesian3.fromDegrees(p.longitude, p.latitude));
+                const hierarchy = new lib.PolygonHierarchy(toCart(outer), holes.map((h) => new lib.PolygonHierarchy(toCart(h))));
+                const id = i === 0 ? so.key : `${so.key}#part${i}`;
+                if (vz.type === 'image') {
+                    // A picture pinned to the ground (doc 28 G12): the polygon textured, turned to its top edge.
+                    const raw = vz.image?.urlProperty ? props?.[vz.image.urlProperty] : undefined;
+                    const url = typeof raw === 'string' && raw ? raw : vz.image?.url;
+                    if (!url || i > 0)
+                        return;
+                    const ring = outer.length > 1 && outer[0].latitude === outer[outer.length - 1].latitude && outer[0].longitude === outer[outer.length - 1].longitude ? outer.slice(0, -1) : outer;
+                    const turn = ring.length === 4 ? spatial.bearingDegrees(ring[0], ring[1]) - 90 : 0;
+                    entities.add({ id, polygon: { hierarchy, material: new lib.ImageMaterialProperty({ image: url, transparent: true, color: lib.Color.WHITE.withAlpha(vz.image?.opacity ?? 0.85) }), stRotation: lib.Math.toRadians(-turn), classificationType: lib.ClassificationType.BOTH } });
+                    if (so.selected || so.hovered)
+                        entities.add({ id: so.key + OUTLINE, polyline: { positions: toCart([...outer, outer[0]]), width: so.selected ? 3 : 2, material: lib.Color.fromCssColorString(so.selected ? this.theme.selectionColor : this.theme.hoverColor), clampToGround: true } });
+                    return;
+                }
+                if (vz.type === 'extrusion') {
+                    const x = vz.extrusion ?? {};
+                    const base = x.baseProperty ? (num(props?.[x.baseProperty]) ?? x.base ?? 0) : (x.base ?? 0);
+                    const height = x.heightProperty ? (num(props?.[x.heightProperty]) ?? x.height ?? 0) : (x.height ?? 0);
+                    entities.add({ id, polygon: { hierarchy, height: base, extrudedHeight: base + height, heightReference: lib.HeightReference.RELATIVE_TO_GROUND, extrudedHeightReference: lib.HeightReference.RELATIVE_TO_GROUND, material: color(this.theme.fillColor).withAlpha(0.85) } });
+                    return;
+                }
+                entities.add({ id, polygon: { hierarchy, material: color(this.theme.fillColor).withAlpha(so.selected ? 0.32 : tokenFor(rules, 'opacity', props, 0.18)), classificationType: lib.ClassificationType.BOTH } });
+                if (i === 0) {
+                    const stroke = so.selected ? this.theme.selectionColor : tokenFor(rules, 'strokeColor', props, tokenFor(rules, 'color', props, this.theme.fillColor));
+                    entities.add({ id: so.key + OUTLINE, polyline: { positions: toCart([...outer, outer[0]]), width: so.selected ? 3 : tokenFor(rules, 'strokeWidth', props, 1.5), material: lib.Color.fromCssColorString(stroke), clampToGround: true } });
+                }
+            });
+            // One label per area, at the same point MapLibre uses (centre, or just inside the top edge).
+            const lg = labelGraphics(this.groundReference(), 0);
+            if (lg) {
+                const at = spatial.labelPoint(g, vz.label?.placement);
+                entities.add({ id: so.key + LABEL, position: lib.Cartesian3.fromDegrees(at.longitude, at.latitude), label: { ...lg, ...(vz.label?.placement === 'top' ? { verticalOrigin: lib.VerticalOrigin.TOP } : {}) } });
+            }
+        }
+    }
+    /**
+     * A height as drawn (ADR-028): Cesium's vertical exaggeration scales the terrain but not absolute heights, so heights
+     * are scaled the same way to keep an aircraft's true relation to the (exaggerated) ground. `lift` multiplies the
+     * height above the ground; `relative` (agl) heights are measured from the ground Cesium places them on.
+     */
+    /**
+     * How things on the ground are placed: clamped to the terrain when there is one; without terrain the ground is
+     * the ellipsoid, so height 0 directly — Cesium updates clamped billboards lazily, and a moving one lagged behind.
+     */
+    groundReference() {
+        return this.terrain ? this.lib.HeightReference.CLAMP_TO_GROUND : this.lib.HeightReference.NONE;
+    }
+    /**
+     * Contour lines (doc 28 G11) as Cesium's elevation-contour material on the globe. This renderer exaggerates the
+     * terrain itself, so the spacing is exaggerated the same way and the lines still sit on true heights.
+     */
+    applyContours() {
+        const lib = this.lib;
+        const globe = this.viewer?.scene.globe;
+        if (!lib || !globe)
+            return;
+        const c = this.terrain?.contours;
+        if (!c) {
+            globe.material = undefined;
+            return;
+        }
+        const k = this.terrain?.exaggeration ?? 1;
+        globe.material = lib.Material.fromType('ElevationContour', { width: 1.2, spacing: c.interval * k, color: lib.Color.fromCssColorString(c.color ?? '#8A6F4E').withAlpha(0.7) });
+    }
+    /** The drawn ground height under a point: cached, else the loaded tiles' guess now and a precise sample soon. */
+    groundHeight(longitude, latitude) {
+        if (!this.terrain || !this.lib || !this.viewer)
+            return 0;
+        const key = `${longitude},${latitude}`;
+        const known = this.grounds.get(key);
+        if (known !== undefined)
+            return known;
+        const carto = this.lib.Cartographic.fromDegrees(longitude, latitude);
+        if (!this.groundQueue.size)
+            queueMicrotask(() => void this.sampleGrounds());
+        this.groundQueue.set(key, carto);
+        return this.viewer.scene.globe.getHeight(carto) ?? 0;
+    }
+    async sampleGrounds() {
+        const lib = this.lib;
+        const v = this.viewer;
+        const terrain = this.terrain;
+        const gen = this.gen;
+        const batch = [...this.groundQueue];
+        this.groundQueue.clear();
+        if (!lib || !v || !terrain || !batch.length)
+            return;
+        let heights;
+        try {
+            const out = await lib.sampleTerrain(v.terrainProvider, Math.min(14, terrain.maxZoom ?? 14), batch.map(([, c]) => c));
+            heights = out.map((c) => (Number.isFinite(c.height) ? c.height : 0)); // exaggerated already, as drawn
+        }
+        catch (err) {
+            this.emitError(new Error(`terrain sample for volumes failed: ${err instanceof Error ? err.message : String(err)}`));
+            heights = batch.map(() => 0);
+        }
+        if (gen !== this.gen || terrain !== this.terrain)
+            return;
+        batch.forEach(([key], i) => this.grounds.set(key, heights[i]));
+        this.redraw([...this.objects.values()].filter((so) => this.layers.get(so.layerId)?.visualization.type === 'volume'));
+    }
+    drawnHeight(longitude, latitude, height, relative, lift) {
+        const k = this.terrain ? (this.terrain.exaggeration ?? 1) : 1;
+        if (relative)
+            return height * k * lift;
+        if (lift === 1)
+            return height * k;
+        const ground = this.viewer?.scene.globe.getHeight(this.lib.Cartographic.fromDegrees(longitude, latitude)) ?? 0; // already exaggerated
+        return ground + (height * k - ground) * lift;
+    }
+    /** Measures a model file once (its longest side), then redraws the objects that use it (sizeMeters). */
+    measure(uri) {
+        const lib = this.lib;
+        if (this.measuring.has(uri))
+            return;
+        this.measuring.add(uri);
+        const gen = this.gen;
+        lib.Model.fromGltfAsync({ url: uri }).then((model) => {
+            // Bounds are known once the model is ready (it must be in a scene to finish loading).
+            this.viewer.scene.primitives.add(model);
+            model.show = false;
+            const off = model.readyEvent.addEventListener(() => {
+                off();
+                // This runs inside Cesium's render loop, where an exception stops the map drawing: report it instead.
+                try {
+                    const size = Math.max(1e-6, model.boundingSphere.radius * 2);
+                    // The scene owns its primitives: removing the model also destroys it, so read it first.
+                    const scene = this.viewer?.scene;
+                    if (scene)
+                        scene.primitives.remove(model);
+                    else if (!model.isDestroyed())
+                        model.destroy();
+                    if (gen !== this.gen)
+                        return;
+                    this.extents.set(uri, size);
+                    this.redraw([...this.objects.values()].filter((so) => this.layers.get(so.layerId)?.visualization.type === 'model'));
+                }
+                catch (err) {
+                    this.emitError(new Error(`model ${uri} could not be measured: ${err instanceof Error ? err.message : String(err)}`));
+                }
+            });
+        }, (e) => this.emitError(new Error(`model ${uri} failed to load: ${e instanceof Error ? e.message : String(e)}`)));
+    }
+    // ---------------------------------------------------------------- events
+    bindEvents(lib, viewer) {
+        const camera = viewer.camera;
+        camera.percentageChanged = 0.001;
+        this.offs.push(camera.moveEnd.addEventListener(() => {
+            const v = this.currentViewport();
+            for (const l of this.listeners.viewport)
+                l(v);
+        }));
+        this.offs.push(camera.changed.addEventListener(() => {
+            for (const l of this.listeners.move)
+                l(undefined);
+        }));
+        this.offs.push(viewer.scene.renderError.addEventListener((_s, err) => this.emitError(err instanceof Error ? err : new Error(String(err)))));
+        const handler = new lib.ScreenSpaceEventHandler(viewer.scene.canvas);
+        this.handler = handler;
+        handler.setInputAction((ev) => {
+            const hit = this.hitTest(ev.position);
+            const position = this.groundAt(ev.position);
+            if (hit)
+                for (const l of this.listeners.pick)
+                    l({ ...hit, ...(position ? { position } : {}) });
+            else if (position)
+                for (const l of this.listeners.click)
+                    l({ position });
+        }, lib.ScreenSpaceEventType.LEFT_CLICK);
+        handler.setInputAction((ev) => {
+            const hit = this.hitTest(ev.endPosition);
+            viewer.scene.canvas.style.cursor = hit ? 'pointer' : '';
+            const key = hit ? `${hit.layerId}:${hit.objectId}` : null;
+            if (key === this.hoverKey)
+                return;
+            this.hoverKey = key;
+            for (const l of this.listeners.hover)
+                l(hit);
+        }, lib.ScreenSpaceEventType.MOUSE_MOVE);
+    }
+    hitTest(point) {
+        const picked = this.viewer?.scene.pick(point);
+        const id = picked?.id?.id;
+        if (typeof id !== 'string')
+            return null;
+        const key = keyOf(id);
+        if (!this.objects.has(key))
+            return null;
+        const [layerId, objectId] = splitKey(key);
+        return { layerId, objectId };
+    }
+    /** The ground (terrain, else ellipsoid) under a screen point. */
+    groundAt(point) {
+        const lib = this.lib;
+        const v = this.viewer;
+        const ray = v.camera.getPickRay(point);
+        const hit = (ray && v.scene.globe.pick(ray, v.scene)) ?? v.camera.pickEllipsoid(point);
+        if (!hit)
+            return null;
+        const c = lib.Cartographic.fromCartesian(hit);
+        return { latitude: lib.Math.toDegrees(c.latitude), longitude: lib.Math.toDegrees(c.longitude) };
+    }
+    currentViewport() {
+        const lib = this.lib;
+        const v = this.viewer;
+        const camera = v.camera;
+        const size = this.getSize();
+        const centrePx = new lib.Cartesian2(size.width / 2, size.height / 2);
+        const ray = camera.getPickRay(centrePx);
+        const lookPoint = (ray && v.scene.globe.pick(ray, v.scene)) ?? camera.pickEllipsoid(centrePx);
+        const fovy = camera.frustum.fovy ?? Math.PI / 3;
+        let center;
+        let zoom;
+        if (lookPoint) {
+            const c = lib.Cartographic.fromCartesian(lookPoint);
+            center = { latitude: lib.Math.toDegrees(c.latitude), longitude: lib.Math.toDegrees(c.longitude) };
+            zoom = zoomForRange(lib.Cartesian3.distance(camera.positionWC, lookPoint), center.latitude, size.height || 600, fovy);
+        }
+        else {
+            // Looking above the horizon: the point under the camera, from its height.
+            const c = camera.positionCartographic;
+            center = { latitude: lib.Math.toDegrees(c.latitude), longitude: lib.Math.toDegrees(c.longitude) };
+            zoom = zoomForRange(c.height, center.latitude, size.height || 600, fovy);
+        }
+        const rect = camera.computeViewRectangle();
+        const deg = (r) => lib.Math.toDegrees(r);
+        return {
+            center,
+            zoom,
+            bearing: ((deg(camera.heading) % 360) + 360) % 360,
+            pitch: enginePitch(deg(camera.pitch)),
+            ...(rect ? { bounds: { west: deg(rect.west), south: deg(rect.south), east: deg(rect.east), north: deg(rect.north) } } : {}),
+        };
+    }
+    emitError(error) {
+        for (const l of this.listeners.error)
+            l(error);
+    }
+    add(set, l) {
+        set.add(l);
+        return () => set.delete(l);
+    }
+}
+/** A circle as a ring of positions (for areas drawn by Cesium polygons). */
+function circleRing(center, radiusMeters, steps = 64) {
+    const out = [];
+    const dLat = radiusMeters / 111_320;
+    const dLng = radiusMeters / (111_320 * Math.cos((center.latitude * Math.PI) / 180));
+    for (let i = 0; i <= steps; i++) {
+        const a = (i / steps) * 2 * Math.PI;
+        out.push({ latitude: center.latitude + dLat * Math.sin(a), longitude: center.longitude + dLng * Math.cos(a) });
+    }
+    return out;
+}