@faclon-labs/app-sdk 0.1.0 → 0.3.0

package/vendor/map-engine/cesium/renderer.d.ts

@@ -0,0 +1,149 @@
+/**
+ * CesiumRenderer — the full-3D renderer (ADR-027, phase 3D): a true globe with terrain, objects at their real height,
+ * models and extrusions, behind the same Renderer contract as MapLibre. The runtime can switch to it and back
+ * (setRenderer) keeping layers, camera, selection and time.
+ *
+ * - No Cesium Ion and no cloud service: imagery from the basemap's tile URL, terrain from the same DEM tiles MapLibre
+ *   uses (terrarium.ts), static assets served from `baseUrl` (self-hostable).
+ * - One Cesium entity per scene object; markers stay visible over terrain; areas and lines drape on the ground.
+ * - Heights (ADR-028): msl as-is in the same frame as the (sea-level) terrain, agl relative to the ground,
+ *   ellipsoid warned once (no geoid model). Scene vertical exaggeration applies to terrain and heights alike.
+ * No business logic, no data queries; picks report stable objectIds.
+ */
+import type * as CesiumNS from 'cesium';
+import type { BasemapConfig, MapConfig, MapViewport, Position, RendererCapabilities, ScenePatch, SceneState, Size, TerrainConfig, TilesetConfig, Unsubscribe } from '../core/types.js';
+import type { MapClickEvent, PickEvent, Renderer, RendererOptions } from '../render/renderer.js';
+type C = typeof CesiumNS;
+type Listener<T> = (value: T) => void;
+export interface CesiumTheme {
+    markerColor: string;
+    lineColor: string;
+    fillColor: string;
+    trackColor: string;
+    selectionColor: string;
+    hoverColor: string;
+    labelColor: string;
+    labelHalo: string;
+    background: string;
+}
+export declare const DEFAULT_CESIUM_THEME: CesiumTheme;
+export interface CesiumRendererOptions {
+    /** Inject the module (tests, or apps that loaded it). Default: lazy `import('cesium')`. */
+    cesium?: C;
+    /** Where Cesium's static assets (Workers, Assets, Widgets, ThirdParty) are served from. Required in the browser. */
+    baseUrl?: string;
+    theme?: Partial<CesiumTheme>;
+    /** Heightmap samples per terrain tile edge. Default 65. */
+    terrainSamples?: number;
+}
+export declare class CesiumRenderer implements Renderer {
+    private readonly options;
+    private lib;
+    private viewer;
+    private handler;
+    private readonly offs;
+    private gen;
+    private readonly theme;
+    private readonly layers;
+    private readonly objects;
+    /** Every entity id drawn for an object (shape, stem, outline, parts, label), so removal is complete. */
+    private readonly drawn;
+    /** How each point object was drawn, apart from where: when only its position changes it is moved, not rebuilt. */
+    private readonly looks;
+    private hoverKey;
+    private fontName;
+    private terrain;
+    /** Loaded 3D Tiles by id, with the config they were loaded from. */
+    private readonly tilesets;
+    private warnedEllipsoid;
+    private warnedStyleBasemap;
+    /** Longest side of each model file once measured (sizeMeters). */
+    private readonly extents;
+    private readonly measuring;
+    /** Ground under volume origins, as drawn (exaggerated metres), by position; filled by one batched terrain sample. */
+    private readonly grounds;
+    private readonly groundQueue;
+    private readonly listeners;
+    /** A true globe: heights, models, extrusions, sensor volumes and 3D Tiles. */
+    readonly capabilities: RendererCapabilities;
+    constructor(options?: CesiumRendererOptions);
+    initialize(container: HTMLElement, options: RendererOptions): Promise<void>;
+    setViewport(viewport: MapViewport, options?: {
+        animate?: boolean;
+    }): void;
+    render(scene: SceneState): void;
+    update(patch: ScenePatch): void;
+    /**
+     * 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.
+     */
+    private redraw;
+    /** What a point object looks like apart from its position (layer, selection, properties). */
+    private lookOf;
+    /**
+     * 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.
+     */
+    private move;
+    resize(): void;
+    getSize(): Size;
+    project(position: Position): {
+        x: number;
+        y: number;
+    } | null;
+    onCameraMove(l: () => void): Unsubscribe;
+    setBasemap(basemap: BasemapConfig): Promise<void>;
+    /** Cesium always draws a globe; a flat (mercator) request keeps the globe, which reads the same up close. */
+    setProjection(_projection: NonNullable<MapConfig['projection']>): void;
+    setTerrain(terrain: TerrainConfig | null): void;
+    /** 3D Tiles scenery from URLs (no Cesium Ion): added, replaced, shown/hidden and removed by id. */
+    setTilesets(tilesets: TilesetConfig[]): void;
+    sampleElevation(positions: Position[]): Promise<Array<number | null>>;
+    destroy(): void;
+    onViewportChange(l: Listener<MapViewport>): Unsubscribe;
+    onPick(l: Listener<PickEvent>): Unsubscribe;
+    onMapClick(l: Listener<MapClickEvent>): Unsubscribe;
+    onHover(l: Listener<PickEvent | null>): Unsubscribe;
+    onError(l: Listener<Error>): Unsubscribe;
+    /** The basemap as Cesium imagery: a tile URL works as is; a vector style URL needs a raster fallback. */
+    private imageryLayer;
+    /** Terrain from the configured DEM tiles (same as MapLibre), or a smooth ellipsoid. */
+    private terrainProvider;
+    /** Takes the new layer list; returns the objects to draw again and the keys to drop (their layer went away). */
+    private applyLayers;
+    private drop;
+    /** Adds or replaces the entities of one scene object. */
+    private put;
+    /** Draws one scene object (nothing of it may be drawn yet). */
+    private draw;
+    /**
+     * 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.
+     */
+    private groundReference;
+    /**
+     * 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.
+     */
+    private applyContours;
+    /** The drawn ground height under a point: cached, else the loaded tiles' guess now and a precise sample soon. */
+    private groundHeight;
+    private sampleGrounds;
+    private drawnHeight;
+    /** Measures a model file once (its longest side), then redraws the objects that use it (sizeMeters). */
+    private measure;
+    private bindEvents;
+    private hitTest;
+    /** The ground (terrain, else ellipsoid) under a screen point. */
+    private groundAt;
+    private currentViewport;
+    private emitError;
+    private add;
+}
+export {};