gps-plus-slam-app-framework 1.0.6 → 1.1.0

package/dist/visualization/gps-anchor.js

@@ -0,0 +1,217 @@
+import { registerFrameUpdate } from "../ar/frame-loop.js";
+import { isObjectInCameraFrustum } from "./frustum-visibility.js";
+import { calcRelativeCoordsInMeters } from "../core/index.js";
+import { nueToArLocal } from "./frame-conversions.js";
+import * as THREE from "three";
+//#region ../src/visualization/gps-anchor.ts
+/**
+* `createGpsAnchor` — GPS-anchored placement of a single `THREE.Object3D`.
+*
+* See the colocated sidecar (`gps-anchor.ts.md`) and the port plan at
+* `gps-plus-slam/GpsPlusSlamJs_Docs/docs/2026-05-13-gps-anchor-port-plan.md`
+* for the full design, state machine, and test matrix.
+*
+* This file implements sub-steps 2 (bootstrap phase), 3 (steady-state
+* `'snap-every-tick'` + distance-scaled threshold gate), and 4
+* (`'snap-when-offscreen'` mode gate, with a one-time initial-placement
+* exemption for `skipBootstrap` anchors). Floor-Y correction is sub-step
+* 6 and remains deferred.
+*/
+/**
+* Module-level registry of objects currently owned by a `GpsAnchor`.
+* Used to detect nested anchors (parent + child both anchored) which
+* we explicitly forbid; mirrors the C# invariant.
+*/
+const anchoredObjects = /* @__PURE__ */ new WeakSet();
+function isObjectInAnchoredChain(object) {
+	let cursor = object;
+	while (cursor) {
+		if (anchoredObjects.has(cursor)) return true;
+		cursor = cursor.parent;
+	}
+	return false;
+}
+/**
+* Returns true iff `object` is `arWorldGroup` itself or a descendant of it.
+* The anchor's `object3D` MUST satisfy this: only then does it ride the
+* alignment applied to `arWorldGroup.matrix` (the node the camera also lives
+* under) via scene-graph propagation. An anchor parented to the scene root
+* instead never receives the alignment, so each steady-state re-registration
+* snaps the full alignment delta and the object visibly slides as the user
+* moves — the exact instability the anchor exists to prevent.
+*/
+function isDescendantOf(object, arWorldGroup) {
+	let cursor = object;
+	while (cursor) {
+		if (cursor === arWorldGroup) return true;
+		cursor = cursor.parent;
+	}
+	return false;
+}
+function median(values) {
+	const sorted = [...values].sort((a, b) => a - b);
+	const mid = Math.floor(sorted.length / 2);
+	if (sorted.length % 2 === 0) return (sorted[mid - 1] + sorted[mid]) / 2;
+	return sorted[mid];
+}
+function medianPoint(samples) {
+	const lat = median(samples.map((s) => s.lat));
+	const lon = median(samples.map((s) => s.lon));
+	const alts = samples.map((s) => "altitude" in s ? s.altitude : void 0).filter((a) => typeof a === "number");
+	if (alts.length > 0) return {
+		lat,
+		lon,
+		altitude: median(alts)
+	};
+	return {
+		lat,
+		lon
+	};
+}
+function createGpsAnchor(options) {
+	if (isObjectInAnchoredChain(options.object3D)) throw new Error("createGpsAnchor: nested GpsAnchors are not supported — the supplied object3D is already inside an anchored parent chain.");
+	if (!isDescendantOf(options.object3D, options.arWorldGroup)) throw new Error("createGpsAnchor: object3D must be a descendant of arWorldGroup (the alignment-bearing node the camera lives under); parenting an anchor to the scene root defeats AR stability.");
+	anchoredObjects.add(options.object3D);
+	const sampleCount = options.secondsToAccumulateGpsPose ?? 7;
+	if (sampleCount < 1) {
+		anchoredObjects.delete(options.object3D);
+		throw new Error("createGpsAnchor: secondsToAccumulateGpsPose must be >= 1 — use skipBootstrap:true to bypass the accumulation phase.");
+	}
+	const settlingSeconds = options.settlingSeconds ?? 0;
+	const distanceThreshold = options.distanceThreshold ?? 2;
+	options.angleThresholdInDegrees;
+	const mode = options.mode ?? "snap-when-offscreen";
+	const scratchTarget = new THREE.Vector3();
+	const scratchCamWorld = new THREE.Vector3();
+	const scratchObjWorld = new THREE.Vector3();
+	let phase = options.skipBootstrap === true ? "anchored" : "bootstrap";
+	let isFullyAnchored = phase === "anchored";
+	let gpsPoint = options.gpsPoint;
+	let phaseEnteredAtElapsed = null;
+	let lastSampleAtElapsed = null;
+	const samples = [];
+	/**
+	* The one-time "initial placement" exemption from the `snap-when-offscreen`
+	* frustum gate. A `skipBootstrap` anchor is `anchored` from frame one but its
+	* `object3D` still sits at the AR origin (local 0,0,0 — "inside the user")
+	* until its first steady-state commit. That first commit MUST land even while
+	* the object is on-screen, otherwise the marker stays stuck at the origin
+	* until the user happens to look away. A fresh appearance is not a "jump", so
+	* it is exempt. Consumed (set false) by the first committed correction; never
+	* re-armed (a re-bootstrap moves an already-placed object, so its later
+	* corrections are normal gated snaps). Anchors that bootstrap are placed at
+	* their seed pose by the host, so they never need this exemption — hence it is
+	* armed only for `skipBootstrap`.
+	*/
+	let firstCommitPending = options.skipBootstrap === true;
+	const enterBootstrap = () => {
+		phase = "bootstrap";
+		isFullyAnchored = false;
+		phaseEnteredAtElapsed = null;
+		lastSampleAtElapsed = null;
+		samples.length = 0;
+	};
+	const commitMedian = () => {
+		gpsPoint = medianPoint(samples);
+		phase = "anchored";
+		isFullyAnchored = true;
+		samples.length = 0;
+		options.onBootstrapComplete?.(gpsPoint);
+	};
+	/**
+	* Steady-state: compute the GPS-world NUE target from the stored
+	* `gpsPoint` and the current `zeroRef`, map it into `arWorldGroup`'s
+	* AR-local frame via the inverse alignment matrix, and commit it to
+	* `object3D.position` iff the (AR-local) position delta exceeds the
+	* distance-scaled threshold AND the mode gate allows it.
+	*
+	* Mode gate: in `'snap-when-offscreen'` a correction is suppressed while the
+	* object is inside the camera frustum — corrections only land when the user
+	* is not looking, so the anchor never visibly jumps. The whole AR frame
+	* (camera + every anchor) rides one lerped `arWorldGroup.matrix`
+	* (`enableArWorldGroupAlignment`), so an on-screen alignment change is
+	* absorbed smoothly for the entire view and never needs a per-anchor
+	* on-screen snap. The one exception is the first placement of a `skipBootstrap`
+	* anchor (see `firstCommitPending`), which must escape the origin even while
+	* on-screen. See
+	* `gps-plus-slam/GpsPlusSlamJs_Docs/docs/2026-06-06-anchor-starter-cachehit-jump-investigation.md`.
+	*
+	* Frame note: `arWorldGroup.matrix` IS the alignment matrix, which maps
+	* **AR-odometry NUE → GPS-world NUE**. `object3D.position` is a *local*
+	* transform in that AR-odometry frame. To make the object's *world*
+	* position equal the GPS-world `nue`, the local target must be
+	* `alignment⁻¹ · nue` — writing raw `nue` would double-apply the
+	* alignment (world = `alignment · nue`). See
+	* `gps-plus-slam/GpsPlusSlamJs_Docs/docs/2026-05-31-gps-anchor-alignment-frame-bug.md`.
+	*
+	* Returns silently on missing inputs (no `zeroRef`, or no alignment
+	* matrix yet — an AR-local object cannot be placed without knowing the
+	* AR↔NUE transform).
+	*/
+	const maybeCommitSteadyState = () => {
+		const zero = options.getGpsZeroRef();
+		if (zero === null || zero === void 0) return;
+		const currentAlignment = options.getAlignmentMatrix();
+		if (currentAlignment === null || currentAlignment === void 0) return;
+		const targetAlt = "altitude" in gpsPoint && typeof gpsPoint.altitude === "number" ? gpsPoint.altitude : 0;
+		const nue = calcRelativeCoordsInMeters(zero, gpsPoint, targetAlt, 0);
+		nueToArLocal(currentAlignment, [
+			nue[0],
+			nue[1],
+			nue[2]
+		], scratchTarget);
+		options.camera.getWorldPosition(scratchCamWorld);
+		options.object3D.getWorldPosition(scratchObjWorld);
+		const scale = 1 + 10 * scratchCamWorld.distanceTo(scratchObjWorld) / 100;
+		if (options.object3D.position.distanceTo(scratchTarget) >= distanceThreshold * scale) {
+			if (!(mode === "snap-when-offscreen" && !firstCommitPending && isObjectInCameraFrustum(options.camera, options.object3D))) {
+				options.object3D.position.copy(scratchTarget);
+				firstCommitPending = false;
+			}
+		}
+	};
+	const tick = (_dt, elapsed) => {
+		if (phase === "anchored") {
+			maybeCommitSteadyState();
+			return;
+		}
+		if (phaseEnteredAtElapsed === null) {
+			phaseEnteredAtElapsed = elapsed;
+			lastSampleAtElapsed = elapsed - 1;
+		}
+		if (elapsed - phaseEnteredAtElapsed < settlingSeconds) return;
+		if (lastSampleAtElapsed !== null && elapsed - lastSampleAtElapsed < 1) return;
+		const sample = options.getCurrentGpsPoint();
+		if (sample === null || sample === void 0) return;
+		samples.push(sample);
+		lastSampleAtElapsed = elapsed;
+		if (samples.length >= sampleCount) commitMedian();
+	};
+	const unregister = registerFrameUpdate(tick);
+	return {
+		get phase() {
+			return phase;
+		},
+		get isFullyAnchored() {
+			return isFullyAnchored;
+		},
+		get gpsPoint() {
+			return gpsPoint;
+		},
+		markMovedExternally() {
+			enterBootstrap();
+		},
+		setGpsPoint(point) {
+			gpsPoint = point;
+		},
+		dispose() {
+			unregister();
+			anchoredObjects.delete(options.object3D);
+		},
+		__tickForTests(dt, elapsed) {
+			tick(dt, elapsed);
+		}
+	};
+}
+//#endregion
+export { createGpsAnchor };

package/dist/visualization/gps-compass-cubes.d.ts

@@ -1,2 +1,2 @@
-import { i as createGpsCompassCubes, n as COMPASS_CUBE_SIZE, r as GpsCompassCubes, t as COMPASS_CUBE_DISTANCE } from "../gps-compass-cubes-jRIJMOuh.js";
+import { i as createGpsCompassCubes, n as COMPASS_CUBE_SIZE, r as GpsCompassCubes, t as COMPASS_CUBE_DISTANCE } from "../gps-compass-cubes-Ys6Hf1nc.js";
 export { COMPASS_CUBE_DISTANCE, COMPASS_CUBE_SIZE, GpsCompassCubes, createGpsCompassCubes };

package/dist/visualization/gps-event-markers.d.ts

@@ -1,2 +1,2 @@
-import { n as gpsEventVisualizer, t as GpsEventVisualizer } from "../gps-event-markers-sVyO9utS.js";
-export { GpsEventVisualizer, gpsEventVisualizer };
+import { n as GpsEventVisualizer, r as gpsEventVisualizer, t as GpsEventAccuracy } from "../gps-event-markers-BlHq3jYV.js";
+export { GpsEventAccuracy, GpsEventVisualizer, gpsEventVisualizer };

package/dist/visualization/gps-event-markers.js

@@ -25,6 +25,38 @@ const GPS_MARKER_RADIUS = .08;
 /** Slightly larger radius for alignment snapshots to stand out */
 const SNAPSHOT_MARKER_RADIUS = .1;
 /**
+* Default opacity for the yellow raw-GPS sphere when it is rendered at the
+* legacy fixed 8 cm radius (no accuracy passed). Matches the original 30 %
+* value so live recording sessions look unchanged.
+*/
+const RAW_GPS_FIXED_OPACITY = .3;
+/**
+* Reduced opacity for the yellow raw-GPS sphere when it is scaled by GPS
+* accuracy (replay mode). At metre-scale ellipsoids the sphere can land on
+* top of the cyan fused / red snapshot markers; a lower alpha keeps those
+* smaller markers visible inside the ellipsoid.
+*/
+const RAW_GPS_ACCURACY_OPACITY = .13;
+/**
+* Validate a {@link GpsEventAccuracy} hint and return the concrete
+* {horizontal, vertical} scale when both axes are usable, or `null` to signal
+* "fall back to the legacy fixed 8 cm sphere". A half-populated, non-positive,
+* or non-finite (`NaN`/`Infinity`) accuracy must NOT produce an ellipsoid:
+* a degenerate or infinite axis would corrupt the mesh transform and can
+* crash Three.js rendering.
+*/
+function resolveEllipsoidScale(accuracy) {
+	if (accuracy == null) return null;
+	const { horizontal, vertical } = accuracy;
+	if (typeof horizontal !== "number" || typeof vertical !== "number") return null;
+	if (!Number.isFinite(horizontal) || !Number.isFinite(vertical)) return null;
+	if (horizontal <= 0 || vertical <= 0) return null;
+	return {
+		horizontal,
+		vertical
+	};
+}
+/**
 * Manager for GPS event visualization
 */
 var GpsEventVisualizer = class {
@@ -55,8 +87,14 @@ var GpsEventVisualizer = class {
 	*
 	* @param gpsCoords - GPS position as [x, y, z] meters from zero reference
 	* @param odomPosition - AR odometry position at the time of GPS reading
+	* @param accuracy - Optional 1σ GPS accuracy. When both fields are positive,
+	*   the raw-GPS marker is rendered as a non-uniform-scaled ellipsoid:
+	*   `mesh.scale.set(horizontal, vertical, horizontal)` over a unit sphere.
+	*   When missing, zero, or negative, the marker falls back to the legacy
+	*   fixed 8 cm sphere (same defensive policy as `preview-map.ts`).
+	*   Cyan fused and red snapshot markers are never affected by this argument.
 	*/
-	addGpsEvent(gpsCoords, odomPosition) {
+	addGpsEvent(gpsCoords, odomPosition, accuracy) {
 		if (!this.zeroRef) {
 			log.warn("No zero reference set");
 			return;
@@ -67,8 +105,13 @@ var GpsEventVisualizer = class {
 			return;
 		}
 		const eventId = this.eventCounter++;
-		const rawMesh = this.createMarkerMesh(VIS_COLORS.RAW_GPS.hex, "raw-gps", eventId);
+		const ellipsoidScale = resolveEllipsoidScale(accuracy);
+		const rawMesh = this.createMarkerMesh(VIS_COLORS.RAW_GPS.hex, "raw-gps", eventId, ellipsoidScale ? 1 : GPS_MARKER_RADIUS, ellipsoidScale ? RAW_GPS_ACCURACY_OPACITY : RAW_GPS_FIXED_OPACITY);
 		rawMesh.position.set(gpsCoords[0], gpsCoords[1], gpsCoords[2]);
+		if (ellipsoidScale) {
+			rawMesh.scale.set(ellipsoidScale.horizontal, ellipsoidScale.vertical, ellipsoidScale.horizontal);
+			rawMesh.renderOrder = -1;
+		}
 		scene.add(rawMesh);
 		this.rawGpsMarkers.push(rawMesh);
 		const arWorldGroup = getArWorldGroup();
@@ -149,6 +192,30 @@ var GpsEventVisualizer = class {
 			snapshots: this.snapshotMarkers.length
 		};
 	}
+	/**
+	* Diagnostic accessor: returns the world-space size (`THREE.Box3.setFromObject`)
+	* of each raw-GPS marker, in insertion order.
+	*
+	* Used by the rec31 accuracy-ellipsoid Playwright spec (§3c) to verify the
+	* relative scaling of two events with different `latLongAccuracy`. This is
+	* the size of the rendered ellipsoid in scene units (= metres in replay
+	* mode), not the underlying geometry radius — so it correctly reflects the
+	* `mesh.scale.set(h, v, h)` applied for accuracy-aware markers.
+	*
+	* @returns array of `{ x, y, z }` sizes — empty array if there are no markers.
+	*/
+	getRawMarkerWorldSizes() {
+		const tmpBox = new THREE.Box3();
+		return this.rawGpsMarkers.map((mesh) => {
+			tmpBox.setFromObject(mesh);
+			const size = tmpBox.getSize(new THREE.Vector3());
+			return {
+				x: size.x,
+				y: size.y,
+				z: size.z
+			};
+		});
+	}
 };
 /**
 * Singleton instance for global use.

package/dist/visualization/hit-test-reticle.d.ts

@@ -0,0 +1,2 @@
+import { n as createReticleMesh, r as updateReticle, t as HitMatrix } from "../hit-test-reticle-BGXOxrUh.js";
+export { HitMatrix, createReticleMesh, updateReticle };

package/dist/visualization/hit-test-reticle.js

@@ -0,0 +1,81 @@
+import { t as WEBXR_TO_NUE } from "../webxr-nue-basis-BbdqhqY6.js";
+import { Matrix4, Mesh, MeshBasicMaterial, RingGeometry } from "three";
+//#region ../src/visualization/hit-test-reticle.ts
+/**
+* Hit-test reticle — the small, deterministic "reticle view-model" shared by
+* the framework's example/starter apps.
+*
+* A faithful port of the reticle from the stock three.js `webxr_ar_hittest`
+* example: a flat ring laid on whatever real-world surface the WebXR
+* `hit-test` API reports under the screen centre. The framework delta is
+* *where* the mesh is parented and *which frame the hit pose is in*: apps add
+* the mesh under `getArWorldGroup()` (NUE local space) rather than the
+* GPS-aligned scene root, so the reticle rides the same lerped `arWorldGroup`
+* alignment as the camera — but the WebXR hit pose arrives in the WebXR
+* reference space, so `updateReticle` applies the `WEBXR_TO_NUE` basis change
+* to it (see that function for the full rationale).
+*
+* The per-frame XR plumbing (requesting the hit-test source, reading
+* `frame.getHitTestResults(...)`) stays in each app's WebXR glue and is
+* verified manually on-device. The two functions here are the unit-tested core:
+* given the latest hit pose (a column-major 4x4 transform matrix) or `null`,
+* drive the mesh's visibility + transform. They are unit tested because that is
+* the logic a porting developer is most likely to get subtly wrong (e.g.
+* forgetting the basis change so the reticle drifts off-centre, forgetting to
+* hide the reticle when no surface is found, or letting Three.js overwrite the
+* matrix).
+*/
+const hitPoseMatrix = /* @__PURE__ */ new Matrix4();
+/**
+* Build the reticle mesh: a thin ring oriented flat (rotated to lie in the
+* XZ plane) so it reads as a marker on the ground/wall.
+*
+* `matrixAutoUpdate` is disabled because the reticle's world transform is
+* written wholesale from the hit-test pose every frame; letting Three.js
+* recompose it from position/quaternion/scale would discard that pose.
+*
+* The mesh starts hidden (`visible = false`) — there is no surface yet.
+*/
+function createReticleMesh() {
+	const reticle = new Mesh(new RingGeometry(.07, .09, 32).rotateX(-Math.PI / 2), new MeshBasicMaterial({ color: 5213439 }));
+	reticle.matrixAutoUpdate = false;
+	reticle.visible = false;
+	return reticle;
+}
+/**
+* Apply the latest hit-test pose to the reticle.
+*
+* - When `matrix` is a 16-element transform, the reticle adopts it (after the
+*   WebXR→NUE basis change, see below) and becomes visible.
+* - When `matrix` is `null` (no surface under the screen centre, or the
+*   hit-test source is not ready yet), the reticle is hidden.
+*
+* Frame handling — the part a porting developer must not get wrong. The
+* hit-test pose is expressed in the **WebXR reference space** (`X=East, Y=Up,
+* Z=South`), the same frame as the live camera pose. The reticle, however, is
+* parented under `getArWorldGroup()`, whose local space is **NUE** (`X=North,
+* Y=Up, Z=East`) — the camera reaches that frame through the static
+* `basisChangeNode` that holds `WEBXR_TO_NUE`. The reticle has no such
+* intermediate node, so we apply the same basis change here:
+* `reticle.matrix = WEBXR_TO_NUE · hitPose`. The reticle's resulting world pose
+* is then `arWorldGroup.matrix · WEBXR_TO_NUE · hitPose` — identical to the
+* transform chain the camera rides, so it stays pinned under the screen centre.
+*
+* Without the basis change the WebXR coordinates were interpreted as NUE: the
+* Up axis matched (both are Y) but East/North were swapped, so the reticle
+* drifted sideways instead of tracking the screen centre.
+*
+* Works on any `Object3D` (not just the mesh from `createReticleMesh`) so it can
+* be unit tested without a WebGL context.
+*/
+function updateReticle(reticle, matrix) {
+	if (matrix === null) {
+		reticle.visible = false;
+		return;
+	}
+	hitPoseMatrix.fromArray(matrix);
+	reticle.matrix.multiplyMatrices(WEBXR_TO_NUE, hitPoseMatrix);
+	reticle.visible = true;
+}
+//#endregion
+export { createReticleMesh, updateReticle };

package/dist/visualization/index.d.ts

@@ -1,12 +1,19 @@
-import { n as createCameraFollower, t as CameraFollower } from "../camera-follower-BMqPddxx.js";
-import { n as createAlignmentLerper, t as AlignmentLerper } from "../alignment-lerper-D9BeDwZX.js";
-import { n as createCss3dRendererManager, t as Css3dRendererManager } from "../css3d-renderer-manager-rgLMVAvd.js";
-import { i as createGpsCompassCubes, n as COMPASS_CUBE_SIZE, r as GpsCompassCubes, t as COMPASS_CUBE_DISTANCE } from "../gps-compass-cubes-jRIJMOuh.js";
-import { n as gpsEventVisualizer, t as GpsEventVisualizer } from "../gps-event-markers-sVyO9utS.js";
-import { a as DEFAULT_Z_OFFSET, n as DEFAULT_LEAFLET_MAP_SIZE_PX, o as LeafletMapOverlay, r as DEFAULT_WORLD_SIZE, s as LeafletMapOverlayOptions } from "../leaflet-map-overlay-CQZcnxbc.js";
-import { n as clampedAlpha, t as DEFAULT_LERP_RATE } from "../lerp-utils-CZgQlrmu.js";
-import { a as MapOverlayOptions, c as tileXYToLatLon, i as MapOverlay, n as DEFAULT_MAP_SIZE, o as TextureLoaderInterface, r as DEFAULT_ZOOM, s as latLonToTileXY, t as DEFAULT_HEIGHT_OFFSET } from "../map-overlay-C9ifl_4-.js";
-import { n as GpsAnchoredMeshManager, r as GpsAnchoredMeshManagerOptions, t as GpsAnchoredItem } from "../gps-anchored-mesh-manager-CovAFK4g.js";
-import { n as disposeMeshArray, r as disposeObject3D, t as DisposeOptions } from "../three-dispose-qt_r5wR1.js";
-import { t as VIS_COLORS } from "../vis-colors-BKkdTIKb.js";
-export { type AlignmentLerper, COMPASS_CUBE_DISTANCE, COMPASS_CUBE_SIZE, type CameraFollower, type Css3dRendererManager, DEFAULT_HEIGHT_OFFSET, DEFAULT_LEAFLET_MAP_SIZE_PX, DEFAULT_LERP_RATE, DEFAULT_MAP_SIZE, DEFAULT_WORLD_SIZE, DEFAULT_ZOOM, DEFAULT_Z_OFFSET, type DisposeOptions, type GpsAnchoredItem, GpsAnchoredMeshManager, type GpsAnchoredMeshManagerOptions, type GpsCompassCubes, GpsEventVisualizer, LeafletMapOverlay, type LeafletMapOverlayOptions, MapOverlay, type MapOverlayOptions, type TextureLoaderInterface, VIS_COLORS, clampedAlpha, createAlignmentLerper, createCameraFollower, createCss3dRendererManager, createGpsCompassCubes, disposeMeshArray, disposeObject3D, gpsEventVisualizer, latLonToTileXY, tileXYToLatLon };
+import { n as createCss3dRendererManager, t as Css3dRendererManager } from "../css3d-renderer-manager-EDED3nvg.js";
+import { n as createCameraFollower, t as CameraFollower } from "../camera-follower-B-nS1sr6.js";
+import { n as createAlignmentLerper, t as AlignmentLerper } from "../alignment-lerper-CCZJf-Xb.js";
+import { n as MapDataInput, r as buildMapData, t as MapData } from "../map-data-BGIBM5rv.js";
+import { n as ArWorldGroupAlignmentOptions, r as enableArWorldGroupAlignment, t as ArWorldGroupAlignmentHandle } from "../ar-world-group-alignment-Dn4rQk_c.js";
+import { i as createGpsCompassCubes, n as COMPASS_CUBE_SIZE, r as GpsCompassCubes, t as COMPASS_CUBE_DISTANCE } from "../gps-compass-cubes-Ys6Hf1nc.js";
+import { i as isSphereInCameraFrustum, n as isObjectInCameraFrustum, r as isPointInCameraFrustum, t as buildCameraFrustum } from "../frustum-visibility-DGnJqls0.js";
+import { n as worldNueToGps, t as nueToArLocal } from "../frame-conversions-D2EYjeNa.js";
+import { n as createReticleMesh, r as updateReticle, t as HitMatrix } from "../hit-test-reticle-BGXOxrUh.js";
+import { a as GpsAnchorSamplePoint, i as GpsAnchorPhase, n as GpsAnchorMode, o as createGpsAnchor, r as GpsAnchorOptions, t as GpsAnchor } from "../gps-anchor-CISLPQIb.js";
+import { n as GpsEventVisualizer, r as gpsEventVisualizer } from "../gps-event-markers-BlHq3jYV.js";
+import { a as DEFAULT_Z_OFFSET, n as DEFAULT_LEAFLET_MAP_SIZE_PX, o as LeafletMapOverlay, r as DEFAULT_WORLD_SIZE, s as LeafletMapOverlayOptions } from "../leaflet-map-overlay-jNt-kcUr.js";
+import { n as clampedAlpha, t as DEFAULT_LERP_RATE } from "../lerp-utils-DNcSmKVX.js";
+import { a as addAccuracyCircles, i as AccuracyCircleSample, n as ACCURACY_CIRCLE_STROKE_OPACITY, r as ACCURACY_CIRCLE_WEIGHT, t as ACCURACY_CIRCLE_FILL_OPACITY } from "../accuracy-circles-DEKr0Hoh.js";
+import { a as MAP_PATH_POLYLINE_OPACITY, c as USER_POSITION_COLOR, i as FUSED_PATH_COLOR, l as drawMapData, n as DrawMapDataOptions, o as MAP_PATH_POLYLINE_WEIGHT, r as DrawnMapData, s as RAW_GPS_COLOR, t as ALIGNMENT_SNAPSHOT_COLOR } from "../map-overlay-draw-DcGs9UV3.js";
+import { a as MapOverlayOptions, c as tileXYToLatLon, i as MapOverlay, n as DEFAULT_MAP_SIZE, o as TextureLoaderInterface, r as DEFAULT_ZOOM, s as latLonToTileXY, t as DEFAULT_HEIGHT_OFFSET } from "../map-overlay-yrFsUtGv.js";
+import { n as disposeMeshArray, r as disposeObject3D, t as DisposeOptions } from "../three-dispose-WTBAfaWU.js";
+import { t as VIS_COLORS } from "../vis-colors-Djnyg_UH.js";
+export { ACCURACY_CIRCLE_FILL_OPACITY, ACCURACY_CIRCLE_STROKE_OPACITY, ACCURACY_CIRCLE_WEIGHT, ALIGNMENT_SNAPSHOT_COLOR, type AccuracyCircleSample, type AlignmentLerper, type ArWorldGroupAlignmentHandle, type ArWorldGroupAlignmentOptions, COMPASS_CUBE_DISTANCE, COMPASS_CUBE_SIZE, type CameraFollower, type Css3dRendererManager, DEFAULT_HEIGHT_OFFSET, DEFAULT_LEAFLET_MAP_SIZE_PX, DEFAULT_LERP_RATE, DEFAULT_MAP_SIZE, DEFAULT_WORLD_SIZE, DEFAULT_ZOOM, DEFAULT_Z_OFFSET, type DisposeOptions, type DrawMapDataOptions, type DrawnMapData, FUSED_PATH_COLOR, type GpsAnchor, type GpsAnchorMode, type GpsAnchorOptions, type GpsAnchorPhase, type GpsAnchorSamplePoint, type GpsCompassCubes, GpsEventVisualizer, type HitMatrix, LeafletMapOverlay, type LeafletMapOverlayOptions, MAP_PATH_POLYLINE_OPACITY, MAP_PATH_POLYLINE_WEIGHT, type MapData, type MapDataInput, MapOverlay, type MapOverlayOptions, RAW_GPS_COLOR, type TextureLoaderInterface, USER_POSITION_COLOR, VIS_COLORS, addAccuracyCircles, buildCameraFrustum, buildMapData, clampedAlpha, createAlignmentLerper, createCameraFollower, createCss3dRendererManager, createGpsAnchor, createGpsCompassCubes, createReticleMesh, disposeMeshArray, disposeObject3D, drawMapData, enableArWorldGroupAlignment, gpsEventVisualizer, isObjectInCameraFrustum, isPointInCameraFrustum, isSphereInCameraFrustum, latLonToTileXY, nueToArLocal, tileXYToLatLon, updateReticle, worldNueToGps };

package/dist/visualization/index.js

@@ -5,8 +5,15 @@ import { createCameraFollower } from "./camera-follower.js";
 import { createAlignmentLerper } from "./alignment-lerper.js";
 import { VIS_COLORS } from "./vis-colors.js";
 import { COMPASS_CUBE_DISTANCE, COMPASS_CUBE_SIZE, createGpsCompassCubes } from "./gps-compass-cubes.js";
+import { buildMapData } from "./map-data.js";
+import { enableArWorldGroupAlignment } from "./ar-world-group-alignment.js";
+import { buildCameraFrustum, isObjectInCameraFrustum, isPointInCameraFrustum, isSphereInCameraFrustum } from "./frustum-visibility.js";
+import { nueToArLocal, worldNueToGps } from "./frame-conversions.js";
+import { createReticleMesh, updateReticle } from "./hit-test-reticle.js";
+import { createGpsAnchor } from "./gps-anchor.js";
 import { GpsEventVisualizer, gpsEventVisualizer } from "./gps-event-markers.js";
+import { ACCURACY_CIRCLE_FILL_OPACITY, ACCURACY_CIRCLE_STROKE_OPACITY, ACCURACY_CIRCLE_WEIGHT, addAccuracyCircles } from "./accuracy-circles.js";
+import { ALIGNMENT_SNAPSHOT_COLOR, FUSED_PATH_COLOR, MAP_PATH_POLYLINE_OPACITY, MAP_PATH_POLYLINE_WEIGHT, RAW_GPS_COLOR, USER_POSITION_COLOR, drawMapData } from "./map-overlay-draw.js";
 import { DEFAULT_LEAFLET_MAP_SIZE_PX, DEFAULT_WORLD_SIZE, DEFAULT_Z_OFFSET, LeafletMapOverlay } from "./leaflet-map-overlay.js";
 import { DEFAULT_HEIGHT_OFFSET, DEFAULT_MAP_SIZE, DEFAULT_ZOOM, MapOverlay, latLonToTileXY, tileXYToLatLon } from "./map-overlay.js";
-import { GpsAnchoredMeshManager } from "./gps-anchored-mesh-manager.js";
-export { COMPASS_CUBE_DISTANCE, COMPASS_CUBE_SIZE, DEFAULT_HEIGHT_OFFSET, DEFAULT_LEAFLET_MAP_SIZE_PX, DEFAULT_LERP_RATE, DEFAULT_MAP_SIZE, DEFAULT_WORLD_SIZE, DEFAULT_ZOOM, DEFAULT_Z_OFFSET, GpsAnchoredMeshManager, GpsEventVisualizer, LeafletMapOverlay, MapOverlay, VIS_COLORS, clampedAlpha, createAlignmentLerper, createCameraFollower, createCss3dRendererManager, createGpsCompassCubes, disposeMeshArray, disposeObject3D, gpsEventVisualizer, latLonToTileXY, tileXYToLatLon };
+export { ACCURACY_CIRCLE_FILL_OPACITY, ACCURACY_CIRCLE_STROKE_OPACITY, ACCURACY_CIRCLE_WEIGHT, ALIGNMENT_SNAPSHOT_COLOR, COMPASS_CUBE_DISTANCE, COMPASS_CUBE_SIZE, DEFAULT_HEIGHT_OFFSET, DEFAULT_LEAFLET_MAP_SIZE_PX, DEFAULT_LERP_RATE, DEFAULT_MAP_SIZE, DEFAULT_WORLD_SIZE, DEFAULT_ZOOM, DEFAULT_Z_OFFSET, FUSED_PATH_COLOR, GpsEventVisualizer, LeafletMapOverlay, MAP_PATH_POLYLINE_OPACITY, MAP_PATH_POLYLINE_WEIGHT, MapOverlay, RAW_GPS_COLOR, USER_POSITION_COLOR, VIS_COLORS, addAccuracyCircles, buildCameraFrustum, buildMapData, clampedAlpha, createAlignmentLerper, createCameraFollower, createCss3dRendererManager, createGpsAnchor, createGpsCompassCubes, createReticleMesh, disposeMeshArray, disposeObject3D, drawMapData, enableArWorldGroupAlignment, gpsEventVisualizer, isObjectInCameraFrustum, isPointInCameraFrustum, isSphereInCameraFrustum, latLonToTileXY, nueToArLocal, tileXYToLatLon, updateReticle, worldNueToGps };

package/dist/visualization/leaflet-map-overlay.d.ts

@@ -1,2 +1,2 @@
-import { a as DEFAULT_Z_OFFSET, i as DEFAULT_ZOOM, n as DEFAULT_LEAFLET_MAP_SIZE_PX, o as LeafletMapOverlay, r as DEFAULT_WORLD_SIZE, s as LeafletMapOverlayOptions, t as DEFAULT_HEIGHT_OFFSET } from "../leaflet-map-overlay-CQZcnxbc.js";
+import { a as DEFAULT_Z_OFFSET, i as DEFAULT_ZOOM, n as DEFAULT_LEAFLET_MAP_SIZE_PX, o as LeafletMapOverlay, r as DEFAULT_WORLD_SIZE, s as LeafletMapOverlayOptions, t as DEFAULT_HEIGHT_OFFSET } from "../leaflet-map-overlay-jNt-kcUr.js";
 export { DEFAULT_HEIGHT_OFFSET, DEFAULT_LEAFLET_MAP_SIZE_PX, DEFAULT_WORLD_SIZE, DEFAULT_ZOOM, DEFAULT_Z_OFFSET, LeafletMapOverlay, LeafletMapOverlayOptions };

package/dist/visualization/leaflet-map-overlay.js

@@ -1,5 +1,6 @@
 import { createLogger } from "../utils/logger.js";
 import { VIS_COLORS } from "./vis-colors.js";
+import { drawMapData } from "./map-overlay-draw.js";
 import { CSS3DObject } from "three/addons/renderers/CSS3DRenderer.js";
 import L from "leaflet";
 //#region ../src/visualization/leaflet-map-overlay.ts
@@ -35,14 +36,9 @@ var LeafletMapOverlay = class {
 	leafletMap = null;
 	tileLayer = null;
 	cssObject = null;
-	rawGpsPoints = [];
-	fusedPoints = [];
-	snapshotPoints = [];
+	latestMapData = null;
+	trajectoryLayers = [];
 	namedMarkers = [];
-	userMarker = null;
-	rawGpsPolyline = null;
-	fusedPolyline = null;
-	snapshotPolyline = null;
 	constructor(scene, camera, options = {}) {
 		this.scene = scene;
 		this.camera = camera;
@@ -60,10 +56,7 @@ var LeafletMapOverlay = class {
 			lat,
 			lon
 		};
-		if (this.leafletMap) {
-			this.leafletMap.setView([lat, lon], this.zoomLevel);
-			this.updateUserMarker();
-		}
+		if (this.leafletMap) this.leafletMap.setView([lat, lon], this.zoomLevel);
 	}
 	getGpsPosition() {
 		return this.gpsPosition;
@@ -93,38 +86,22 @@ var LeafletMapOverlay = class {
 	isVisible() {
 		return this.visible;
 	}
-	addRawGpsPoint(lat, lon) {
-		this.rawGpsPoints.push([lat, lon]);
-		if (this.leafletMap) {
-			if (!this.rawGpsPolyline) this.rawGpsPolyline = L.polyline([], {
-				color: VIS_COLORS.RAW_GPS.css,
-				weight: 3,
-				opacity: .8
-			}).addTo(this.leafletMap);
-			this.rawGpsPolyline.addLatLng([lat, lon]);
-		}
-	}
-	addFusedPoint(lat, lon) {
-		this.fusedPoints.push([lat, lon]);
-		if (this.leafletMap) {
-			if (!this.fusedPolyline) this.fusedPolyline = L.polyline([], {
-				color: VIS_COLORS.FUSED_VIO.css,
-				weight: 3,
-				opacity: .8
-			}).addTo(this.leafletMap);
-			this.fusedPolyline.addLatLng([lat, lon]);
-		}
-	}
-	addAlignmentSnapshot(lat, lon) {
-		this.snapshotPoints.push([lat, lon]);
-		if (this.leafletMap) {
-			if (!this.snapshotPolyline) this.snapshotPolyline = L.polyline([], {
-				color: VIS_COLORS.ALIGNMENT_SNAPSHOT.css,
-				weight: 3,
-				opacity: .8
-			}).addTo(this.leafletMap);
-			this.snapshotPolyline.addLatLng([lat, lon]);
-		}
+	/**
+	* Render a full trajectory snapshot.
+	*
+	* Replaces the previous incremental `addRawGpsPoint` / `addFusedPoint` /
+	* `addAlignmentSnapshot` API with a single full-snapshot path: the caller
+	* builds a {@link MapData} (via the shared `buildMapData`) from the latest
+	* store slices and hands it here. The trajectory layers are redrawn
+	* wholesale through the shared {@link drawMapData} routine, so the live map
+	* stays pixel-identical to the 2D session-summary map and the fused path
+	* recomputes (D2) as the alignment matrix improves.
+	*
+	* Buffered when the map is not yet shown; applied on `show()`.
+	*/
+	render(data) {
+		this.latestMapData = data;
+		if (this.leafletMap) this.drawTrajectory();
 	}
 	/** Add a "current" named marker (red). Buffered if map is not yet shown. */
 	addCurrentMarker(lat, lon, name) {
@@ -199,9 +176,8 @@ var LeafletMapOverlay = class {
 	dispose() {
 		this.hide();
 		this.destroyLeafletMap();
-		this.rawGpsPoints = [];
-		this.fusedPoints = [];
-		this.snapshotPoints = [];
+		this.latestMapData = null;
+		this.trajectoryLayers = [];
 		this.namedMarkers = [];
 		this.cssObject = null;
 		log.info("Leaflet map overlay disposed");
@@ -232,14 +208,8 @@ var LeafletMapOverlay = class {
 		this.tileLayer.addTo(this.leafletMap);
 	}
 	destroyLeafletMap() {
-		this.userMarker?.remove();
-		this.userMarker = null;
-		this.rawGpsPolyline?.remove();
-		this.rawGpsPolyline = null;
-		this.fusedPolyline?.remove();
-		this.fusedPolyline = null;
-		this.snapshotPolyline?.remove();
-		this.snapshotPolyline = null;
+		for (const layer of this.trajectoryLayers) layer.remove();
+		this.trajectoryLayers = [];
 		for (const m of this.namedMarkers) {
 			m.marker?.remove();
 			m.marker = null;
@@ -273,33 +243,17 @@ var LeafletMapOverlay = class {
 	}
 	applyBufferedOverlays() {
 		if (!this.leafletMap) return;
-		this.updateUserMarker();
-		if (this.rawGpsPoints.length > 0) this.rawGpsPolyline = L.polyline(this.rawGpsPoints, {
-			color: VIS_COLORS.RAW_GPS.css,
-			weight: 3,
-			opacity: .8
-		}).addTo(this.leafletMap);
-		if (this.fusedPoints.length > 0) this.fusedPolyline = L.polyline(this.fusedPoints, {
-			color: VIS_COLORS.FUSED_VIO.css,
-			weight: 3,
-			opacity: .8
-		}).addTo(this.leafletMap);
-		if (this.snapshotPoints.length > 0) this.snapshotPolyline = L.polyline(this.snapshotPoints, {
-			color: VIS_COLORS.ALIGNMENT_SNAPSHOT.css,
-			weight: 3,
-			opacity: .8
-		}).addTo(this.leafletMap);
+		this.drawTrajectory();
 		for (const m of this.namedMarkers) if (!m.marker) m.marker = this.createNamedMarker(m.lat, m.lng, m.name, m.isPrior);
 	}
-	updateUserMarker() {
-		if (!this.gpsPosition || !this.leafletMap) return;
-		if (this.userMarker) this.userMarker.setLatLng([this.gpsPosition.lat, this.gpsPosition.lon]);
-		else this.userMarker = L.marker([this.gpsPosition.lat, this.gpsPosition.lon], { icon: L.divIcon({
-			className: "",
-			html: `<div style="background:${VIS_COLORS.USER_POSITION.css};width:14px;height:14px;border-radius:50%;border:3px solid white;box-shadow:0 0 6px rgba(59,130,246,0.6);"></div>`,
-			iconSize: [14, 14],
-			iconAnchor: [7, 7]
-		}) }).addTo(this.leafletMap);
+	/**
+	* Redraw the trajectory layers from {@link latestMapData} via the shared
+	* {@link drawMapData} routine, removing any layers from the previous draw.
+	*/
+	drawTrajectory() {
+		if (!this.leafletMap || !this.latestMapData) return;
+		for (const layer of this.trajectoryLayers) layer.remove();
+		this.trajectoryLayers = drawMapData(this.leafletMap, this.latestMapData, { showUserPosition: true }).layers;
 	}
 	createNamedMarker(lat, lon, name, isPrior) {
 		const color = isPrior ? VIS_COLORS.PRIOR_REF_POINT.css : VIS_COLORS.CURRENT_REF_POINT.css;

package/dist/visualization/lerp-utils.d.ts

@@ -1,2 +1,2 @@
-import { n as clampedAlpha, t as DEFAULT_LERP_RATE } from "../lerp-utils-CZgQlrmu.js";
+import { n as clampedAlpha, t as DEFAULT_LERP_RATE } from "../lerp-utils-DNcSmKVX.js";
 export { DEFAULT_LERP_RATE, clampedAlpha };

package/dist/visualization/map-data.d.ts

@@ -0,0 +1,2 @@
+import { n as MapDataInput, r as buildMapData, t as MapData } from "../map-data-BGIBM5rv.js";
+export { MapData, MapDataInput, buildMapData };