@honua/app-platform 0.0.20-alpha.0

package/scene-workspace/analysis-widgets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analysis-widgets.d.ts","sourceRoot":"","sources":["../../../src/scene-workspace/analysis-widgets.ts"],"names":[],"mappings":"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"}

package/scene-workspace/analysis-widgets.js

@@ -0,0 +1,424 @@
+/**
+ * Interactive 3D analysis + measurement widgets for the scene workspace.
+ *
+ * These widgets consume the server's elevation/analysis endpoints (line-of-sight,
+ * viewshed, elevation profile) and render the results into a live Cesium
+ * `SceneView`, plus a fully client-side 3D distance/area measurement widget.
+ *
+ * Like {@link module:scene-workspace/cesium-adapter}, this module never imports
+ * CesiumJS statically: the rendering helpers pull the runtime in lazily via
+ * `await import("cesium")` so 2D-only consumers never pay the bundle cost. The
+ * pure request-shaping and client-side geometry math (haversine distance,
+ * spherical polygon area, WKT serialization) carry no Cesium dependency at all
+ * and are unit-testable without a WebGL `Viewer`.
+ *
+ * Server calls go through a caller-supplied {@link SceneAnalysisRequestExecutor}
+ * — typically `(...args) => client.pipelineRequestJson(...args)` against a
+ * `HonuaClient` — so the widgets reuse the SDK's auth / retry / timeout /
+ * interceptor pipeline instead of issuing ad-hoc `fetch` calls.
+ *
+ * @experimental Part of the experimental `scene-workspace` surface; not yet
+ *   covered by the SDK's semver contract prior to `1.0.0`.
+ * @module
+ */
+const JSON_HEADERS = { "Content-Type": "application/json", Accept: "application/json" };
+function encodePath(datasetId, suffix) {
+    return `/elevation/${encodeURIComponent(datasetId)}/${suffix}`;
+}
+function appendQuery(path, params) {
+    const search = new URLSearchParams();
+    for (const [key, value] of Object.entries(params)) {
+        if (value !== undefined)
+            search.set(key, String(value));
+    }
+    const query = search.toString();
+    return query ? `${path}?${query}` : path;
+}
+// ---------------------------------------------------------------------------
+// Client-side geometry (no Cesium, no server)
+// ---------------------------------------------------------------------------
+const DEG2RAD = Math.PI / 180;
+/** WGS84 mean Earth radius in metres — used for haversine / spherical area. */
+const EARTH_RADIUS_METERS = 6_378_137;
+/**
+ * Great-circle (haversine) distance in metres between two lon/lat positions,
+ * ignoring height. Pure; the basis of the horizontal leg of a 3D measurement.
+ */
+export function haversineMeters(a, b) {
+    const lat1 = a.latitude * DEG2RAD;
+    const lat2 = b.latitude * DEG2RAD;
+    const dLat = (b.latitude - a.latitude) * DEG2RAD;
+    const dLon = (b.longitude - a.longitude) * DEG2RAD;
+    const h = Math.sin(dLat / 2) ** 2 + Math.cos(lat1) * Math.cos(lat2) * Math.sin(dLon / 2) ** 2;
+    return 2 * EARTH_RADIUS_METERS * Math.asin(Math.min(1, Math.sqrt(h)));
+}
+/**
+ * Slant (3D) distance in metres between two positions: the horizontal
+ * great-circle distance combined with the height delta via Pythagoras. Heights
+ * default to `0`. Pure.
+ */
+export function slantDistanceMeters(a, b) {
+    const ground = haversineMeters(a, b);
+    const dz = (b.height ?? 0) - (a.height ?? 0);
+    return Math.sqrt(ground * ground + dz * dz);
+}
+/**
+ * Total 3D path length in metres along an ordered polyline (sum of per-segment
+ * slant distances). Returns `0` for fewer than two positions. Pure.
+ */
+export function pathLengthMeters(positions) {
+    let total = 0;
+    for (let i = 1; i < positions.length; i++) {
+        total += slantDistanceMeters(positions[i - 1], positions[i]);
+    }
+    return total;
+}
+/**
+ * Spherical polygon area in square metres for a ring of lon/lat positions,
+ * using L'Huilier's spherical-excess formula projected onto the WGS84 mean
+ * sphere. The ring is auto-closed; returns `0` for fewer than three positions.
+ * The result is unsigned (absolute area). Pure; the basis of the measure
+ * widget's area readout.
+ */
+export function sphericalPolygonAreaSquareMeters(positions) {
+    if (positions.length < 3)
+        return 0;
+    let total = 0;
+    const n = positions.length;
+    for (let i = 0; i < n; i++) {
+        const p1 = positions[i];
+        const p2 = positions[(i + 1) % n];
+        // Normalize the longitude delta into [-180, 180] so edges crossing the
+        // antimeridian use the short arc: e.g. 179.9 → -179.9 must read as +0.2°,
+        // not -359.8°, otherwise the area is inflated by orders of magnitude.
+        const dLon = normalizeLongitudeDeltaDegrees(p2.longitude - p1.longitude);
+        total += dLon * DEG2RAD * (2 + Math.sin(p1.latitude * DEG2RAD) + Math.sin(p2.latitude * DEG2RAD));
+    }
+    return Math.abs((total * EARTH_RADIUS_METERS * EARTH_RADIUS_METERS) / 2);
+}
+/**
+ * Wrap a longitude difference (degrees) into `(-180, 180]` so polygon edges that
+ * cross the ±180° antimeridian are integrated along the short arc. Pure.
+ */
+function normalizeLongitudeDeltaDegrees(deltaDegrees) {
+    let d = deltaDegrees % 360;
+    if (d > 180)
+        d -= 360;
+    else if (d <= -180)
+        d += 360;
+    return d;
+}
+/**
+ * Serialize an ordered list of positions as a 2D WKT `LINESTRING` (lon lat),
+ * the geometry shape the elevation profile endpoint expects on its `line`
+ * query parameter. Height is dropped (the profile endpoint samples the surface).
+ * Pure.
+ */
+export function positionsToWktLineString(positions) {
+    const coords = positions.map((p) => `${p.longitude} ${p.latitude}`).join(", ");
+    return `LINESTRING (${coords})`;
+}
+function normalizeProfileResponse(datasetId, raw) {
+    const samples = (raw.samples ?? []).map((sample) => ({
+        distanceMeters: sample.distanceMeters ?? 0,
+        elevation: sample.elevation ?? null,
+        noData: sample.noData ?? sample.elevation == null,
+    }));
+    return {
+        datasetId: raw.datasetId ?? datasetId,
+        layerId: raw.layerId ?? -1,
+        sampleCount: raw.sampleCount ?? samples.length,
+        lineLengthMeters: raw.lineLengthMeters ?? 0,
+        lineSrid: raw.lineSrid ?? 4326,
+        isAllNoData: raw.isAllNoData ?? samples.every((sample) => sample.noData),
+        samples,
+    };
+}
+/**
+ * Build the relative request path (with query string) for an elevation-profile
+ * request, including the WKT-serialized `line`. Exported so the request shape is
+ * directly unit-testable without a transport. The profile endpoint is a `GET`.
+ */
+export function buildElevationProfilePath(request) {
+    return appendQuery(encodePath(request.datasetId, "profile"), {
+        line: positionsToWktLineString(request.polyline),
+        sampleCount: request.sampleCount,
+        interval: request.intervalMeters,
+        srid: request.srid,
+        mosaicRule: request.mosaicRule,
+    });
+}
+/**
+ * Request an elevation profile along a polyline and return the decoded samples.
+ * Charting is left to the consumer; pair this with
+ * {@link renderElevationProfilePolyline} to draw the sampled line in the scene.
+ */
+export async function requestElevationProfile(execute, request) {
+    if (request.polyline.length < 2) {
+        throw new Error("requestElevationProfile requires a polyline with at least two positions.");
+    }
+    const raw = await execute("GET", buildElevationProfilePath(request), undefined, request.signal);
+    return normalizeProfileResponse(request.datasetId, raw);
+}
+/**
+ * Build the FLAT JSON request body sent to the line-of-sight endpoint. Pure.
+ *
+ * The server contract is flat (`observerLon/observerLat/observerHeight/...`)
+ * and treats `observerHeight`/`targetHeight` as the height OFFSET above the
+ * terrain surface. We therefore fold the ergonomic offset into that field with
+ * precedence `offsetMeters ?? position.height ?? 0`.
+ */
+export function buildLineOfSightBody(request) {
+    return {
+        observerLon: request.observer.longitude,
+        observerLat: request.observer.latitude,
+        observerHeight: request.observerOffsetMeters ?? request.observer.height ?? 0,
+        targetLon: request.target.longitude,
+        targetLat: request.target.latitude,
+        targetHeight: request.targetOffsetMeters ?? request.target.height ?? 0,
+        sampleCount: request.sampleCount,
+        mosaicRule: request.mosaicRule,
+    };
+}
+function normalizeLosResponse(datasetId, raw) {
+    const obstruction = raw.obstruction && raw.obstruction.lon != null && raw.obstruction.lat != null
+        ? {
+            longitude: raw.obstruction.lon,
+            latitude: raw.obstruction.lat,
+            height: raw.obstruction.elevation ?? 0,
+        }
+        : undefined;
+    return {
+        datasetId: raw.datasetId ?? datasetId,
+        layerId: raw.layerId,
+        visible: raw.visible ?? obstruction === undefined,
+        obstruction,
+        obstructionDistanceMeters: raw.obstruction?.distanceMeters,
+        distanceMeters: raw.distanceMeters,
+        observerElevation: raw.observerElevation,
+        targetElevation: raw.targetElevation,
+        sampleCount: raw.sampleCount,
+        hasNoDataSamples: raw.hasNoDataSamples,
+    };
+}
+/**
+ * Request a line-of-sight analysis between an observer and a target. Pair the
+ * result with {@link renderLineOfSight} to draw the sightline (green visible /
+ * red obstructed segments) and an obstruction marker into the scene.
+ */
+export async function requestLineOfSight(execute, request) {
+    const raw = await execute("POST", encodePath(request.datasetId, "line-of-sight"), { headers: { ...JSON_HEADERS }, body: JSON.stringify(buildLineOfSightBody(request)) }, request.signal);
+    return normalizeLosResponse(request.datasetId, raw);
+}
+/**
+ * Build the FLAT JSON request body sent to the viewshed endpoint. Pure.
+ *
+ * The server runs a full-360° radial cast controlled by `rayCount` /
+ * `samplesPerRay`; there is no azimuth sweep. `observerHeight`/`targetHeight`
+ * are terrain-relative offsets (precedence `offset ?? position.height ?? 0` for
+ * the observer).
+ */
+export function buildViewshedBody(request) {
+    return {
+        observerLon: request.observer.longitude,
+        observerLat: request.observer.latitude,
+        observerHeight: request.observerOffsetMeters ?? request.observer.height ?? 0,
+        targetHeight: request.targetHeightMeters,
+        radiusMeters: request.radiusMeters,
+        rayCount: request.rayCount,
+        samplesPerRay: request.samplesPerRay,
+        mosaicRule: request.mosaicRule,
+    };
+}
+function normalizeViewshedResponse(request, raw) {
+    const samples = (raw.samples ?? []).map((sample) => ({
+        position: {
+            longitude: sample.lon ?? 0,
+            latitude: sample.lat ?? 0,
+            height: sample.elevation ?? 0,
+        },
+        azimuthDegrees: sample.azimuthDegrees ?? 0,
+        distanceMeters: sample.distanceMeters ?? 0,
+        visible: sample.visible ?? false,
+    }));
+    return {
+        datasetId: raw.datasetId ?? request.datasetId,
+        layerId: raw.layerId,
+        observer: request.observer,
+        radiusMeters: raw.radiusMeters ?? request.radiusMeters,
+        rayCount: raw.rayCount,
+        samplesPerRay: raw.samplesPerRay,
+        sampleCount: raw.sampleCount ?? samples.length,
+        visibleSampleCount: raw.visibleSampleCount ?? samples.filter((sample) => sample.visible).length,
+        samples,
+    };
+}
+/**
+ * Request a viewshed analysis from an observer position. Pair the result with
+ * {@link renderViewshed} to draw the visible / obstructed radial samples.
+ */
+export async function requestViewshed(execute, request) {
+    const raw = await execute("POST", encodePath(request.datasetId, "viewshed"), { headers: { ...JSON_HEADERS }, body: JSON.stringify(buildViewshedBody(request)) }, request.signal);
+    return normalizeViewshedResponse(request, raw);
+}
+/**
+ * Compute a 3D distance or area measurement from an ordered list of positions
+ * (typically picked off the scene). For `distance` the result carries the total
+ * 3D path length and per-segment slant distances; for `area` it additionally
+ * carries the spherical polygon area. Pure.
+ */
+export function measureScenePositions(positions, mode = "distance") {
+    const segmentMeters = [];
+    for (let i = 1; i < positions.length; i++) {
+        segmentMeters.push(slantDistanceMeters(positions[i - 1], positions[i]));
+    }
+    const measurement = {
+        positions,
+        lengthMeters: segmentMeters.reduce((sum, segment) => sum + segment, 0),
+        segmentMeters,
+        mode,
+    };
+    if (mode === "area") {
+        return { ...measurement, areaSquareMeters: sphericalPolygonAreaSquareMeters(positions) };
+    }
+    return measurement;
+}
+/**
+ * Lazily import the CesiumJS runtime. Kept in its own function so the dynamic
+ * `import("cesium")` is the only reference to the package here, which is what
+ * keeps Cesium out of the 2D bundle (asserted by the static-import guard test).
+ */
+async function loadAnalysisCesium() {
+    return (await import("cesium"));
+}
+function flattenHeights(positions) {
+    const out = [];
+    for (const position of positions) {
+        out.push(position.longitude, position.latitude, position.height ?? 0);
+    }
+    return out;
+}
+function makeOverlay(kind, entities, added) {
+    return {
+        kind,
+        entities: added,
+        remove() {
+            for (const entity of added)
+                entities.remove(entity);
+        },
+    };
+}
+/**
+ * Render a line-of-sight result into the scene's entity collection: the
+ * observer→target sightline (lime when visible, red when obstructed) plus a
+ * yellow point marking the first obstruction when present. Returns an overlay
+ * handle so the caller can clear it before re-running. Cesium is loaded lazily.
+ */
+export async function renderLineOfSight(entities, request, result, cesium) {
+    const mod = cesium ?? (await loadAnalysisCesium());
+    const added = [];
+    const sightline = entities.add({
+        name: "line-of-sight",
+        polyline: {
+            positions: mod.Cartesian3.fromDegreesArrayHeights(flattenHeights([request.observer, request.target])),
+            width: 3,
+            material: result.visible ? mod.Color.LIME : mod.Color.RED,
+        },
+    });
+    added.push(sightline);
+    if (result.obstruction) {
+        const marker = entities.add({
+            name: "line-of-sight-obstruction",
+            position: mod.Cartesian3.fromDegrees(result.obstruction.longitude, result.obstruction.latitude, result.obstruction.height ?? 0),
+            point: { pixelSize: 10, color: mod.Color.YELLOW },
+        });
+        added.push(marker);
+    }
+    return makeOverlay("line-of-sight", entities, added);
+}
+/**
+ * Render a viewshed result into the scene's entity collection: one point per
+ * radial sample — green (`Color.LIME`) where the observer can see the sample,
+ * red (`Color.RED`) where it is obstructed. Returns an overlay handle. Cesium
+ * is loaded lazily.
+ */
+export async function renderViewshed(entities, result, cesium) {
+    const mod = cesium ?? (await loadAnalysisCesium());
+    const added = [];
+    for (const sample of result.samples) {
+        const point = entities.add({
+            name: sample.visible ? "viewshed-visible" : "viewshed-obstructed",
+            position: mod.Cartesian3.fromDegrees(sample.position.longitude, sample.position.latitude, sample.position.height ?? 0),
+            point: { pixelSize: 4, color: sample.visible ? mod.Color.LIME : mod.Color.RED },
+        });
+        added.push(point);
+    }
+    return makeOverlay("viewshed", entities, added);
+}
+/**
+ * Render an elevation profile's sampled line into the scene's entity collection
+ * as a polyline draped at the sampled positions. Because the server returns
+ * distance/elevation samples (not lon/lat), the caller passes the original
+ * `polyline` so the rendered line aligns with the requested geometry; the
+ * sample elevations are not required for the line render and charting is left to
+ * the consumer. Returns an overlay handle. Cesium is loaded lazily.
+ */
+export async function renderElevationProfilePolyline(entities, polyline, cesium) {
+    const mod = cesium ?? (await loadAnalysisCesium());
+    const line = entities.add({
+        name: "elevation-profile",
+        polyline: {
+            positions: mod.Cartesian3.fromDegreesArrayHeights(flattenHeights(polyline)),
+            width: 2,
+            material: mod.Color.fromCssColorString("#1e90ff"),
+            clampToGround: true,
+        },
+    });
+    return makeOverlay("elevation-profile", entities, [line]);
+}
+/**
+ * Render a measurement into the scene's entity collection: the measured
+ * polyline (or closed polygon outline for `area`) plus a label at the last
+ * vertex with the formatted length / area. Returns an overlay handle. Cesium is
+ * loaded lazily.
+ */
+export async function renderMeasurement(entities, measurement, cesium) {
+    const mod = cesium ?? (await loadAnalysisCesium());
+    const added = [];
+    const positions = measurement.positions;
+    if (positions.length >= 2) {
+        const closed = measurement.mode === "area" ? [...positions, positions[0]] : positions;
+        const line = entities.add({
+            name: "measurement-line",
+            polyline: {
+                positions: mod.Cartesian3.fromDegreesArrayHeights(flattenHeights(closed)),
+                width: 2,
+                material: mod.Color.YELLOW,
+            },
+        });
+        added.push(line);
+    }
+    const last = positions[positions.length - 1];
+    if (last) {
+        const label = entities.add({
+            name: "measurement-label",
+            position: mod.Cartesian3.fromDegrees(last.longitude, last.latitude, last.height ?? 0),
+            label: { text: formatMeasurementLabel(measurement) },
+        });
+        added.push(label);
+    }
+    return makeOverlay("measurement", entities, added);
+}
+/**
+ * Format a human-readable label for a measurement (km/m for distance, km²/m²
+ * for area). Pure; exported so consumers can reuse the same formatting in
+ * their own UI/labels.
+ */
+export function formatMeasurementLabel(measurement) {
+    if (measurement.mode === "area" && measurement.areaSquareMeters !== undefined) {
+        const area = measurement.areaSquareMeters;
+        return area >= 1_000_000 ? `${(area / 1_000_000).toFixed(2)} km²` : `${area.toFixed(1)} m²`;
+    }
+    const length = measurement.lengthMeters;
+    return length >= 1000 ? `${(length / 1000).toFixed(2)} km` : `${length.toFixed(1)} m`;
+}