gps-plus-slam-app-framework 1.0.0

package/dist/visualization/map-overlay.js

@@ -0,0 +1,241 @@
+import { createLogger } from "../utils/logger.js";
+import { disposeObject3D } from "./three-dispose.js";
+import * as THREE from "three";
+//#region ../src/visualization/map-overlay.ts
+/**
+* Map Overlay Module
+*
+* Creates and manages a 3D map overlay that displays OSM tiles
+* floating below the user in the AR scene. The map is attached
+* as a child of the camera so it automatically follows the user
+* and is always visible at a fixed position in the camera's
+* local coordinate space (below and slightly in front).
+*
+* ARCHITECTURE NOTE:
+* - Map mesh is a child of the camera (camera-local space)
+* - Position is fixed relative to camera: below + slightly in front
+* - No per-frame position update needed — Three.js handles it
+* - OSM tiles are loaded as textures on a PlaneGeometry
+*/
+const log = createLogger("MapOverlay");
+/** Default zoom level for OSM tiles (higher = more detail, smaller area) */
+const DEFAULT_ZOOM = 17;
+/** Default map size in meters */
+const DEFAULT_MAP_SIZE = 10;
+/** Default height offset below camera (negative = below) */
+const DEFAULT_HEIGHT_OFFSET = -4;
+/**
+* Convert latitude/longitude to tile X/Y coordinates.
+* Uses Web Mercator projection (EPSG:3857).
+*
+* @param lat - Latitude in degrees
+* @param lon - Longitude in degrees
+* @param zoom - Zoom level (0-19)
+* @returns [tileX, tileY] as integers
+*/
+function latLonToTileXY(lat, lon, zoom) {
+	const n = Math.pow(2, zoom);
+	const latRad = lat * Math.PI / 180;
+	const x = Math.floor((lon + 180) / 360 * n);
+	const y = Math.floor((1 - Math.log(Math.tan(latRad) + 1 / Math.cos(latRad)) / Math.PI) / 2 * n);
+	return [Math.max(0, Math.min(n - 1, x)), Math.max(0, Math.min(n - 1, y))];
+}
+/**
+* Convert tile X/Y coordinates back to latitude/longitude.
+* Returns the top-left corner of the tile.
+*
+* @param x - Tile X coordinate
+* @param y - Tile Y coordinate
+* @param zoom - Zoom level
+* @returns [lat, lon] in degrees
+*/
+function tileXYToLatLon(x, y, zoom) {
+	const n = Math.pow(2, zoom);
+	const lon = x / n * 360 - 180;
+	return [Math.atan(Math.sinh(Math.PI * (1 - 2 * y / n))) * 180 / Math.PI, lon];
+}
+/**
+* Interactive 3D map overlay that displays OSM tiles in the AR scene.
+* The map floats below the user and follows their horizontal movement.
+*/
+var MapOverlay = class {
+	scene;
+	camera;
+	options;
+	onTileError;
+	mapParent;
+	mesh = null;
+	material = null;
+	geometry = null;
+	textureLoader;
+	gpsPosition = null;
+	currentTile = null;
+	visible = false;
+	/**
+	* Create a new map overlay.
+	*
+	* @param scene - The Three.js scene to add the map to
+	* @param camera - The camera to follow (for positioning)
+	* @param options - Configuration options
+	*/
+	constructor(scene, camera, options = {}) {
+		this.scene = scene;
+		this.camera = camera;
+		this.options = {
+			mapSize: options.mapSize ?? 10,
+			heightOffset: options.heightOffset ?? -4,
+			zoomLevel: options.zoomLevel ?? 17,
+			tileServerUrl: options.tileServerUrl ?? "https://tile.openstreetmap.org/{z}/{x}/{y}.png"
+		};
+		this.textureLoader = options.textureLoader ?? new THREE.TextureLoader();
+		this.onTileError = options.onTileError;
+		this.mapParent = options.mapParent ?? camera;
+	}
+	/**
+	* Set the current GPS position for tile loading.
+	*
+	* @param lat - Latitude in degrees
+	* @param lon - Longitude in degrees
+	*/
+	setGpsPosition(lat, lon) {
+		this.gpsPosition = {
+			lat,
+			lon
+		};
+		if (this.visible) this.updateTile();
+	}
+	/**
+	* Get the current GPS position.
+	*/
+	getGpsPosition() {
+		return this.gpsPosition;
+	}
+	/**
+	* Show the map overlay.
+	* Requires GPS position to be set first.
+	*/
+	show() {
+		if (!this.gpsPosition) {
+			log.warn("Cannot show map - no GPS position set");
+			return;
+		}
+		if (this.visible) return;
+		this.createMesh();
+		this.updateTile();
+		this.visible = true;
+		log.info("Map overlay shown");
+	}
+	/**
+	* Hide the map overlay.
+	*/
+	hide() {
+		if (!this.visible) return;
+		this.removeMesh();
+		this.visible = false;
+		log.info("Map overlay hidden");
+	}
+	/**
+	* Toggle map visibility.
+	*/
+	toggle() {
+		if (this.visible) this.hide();
+		else this.show();
+	}
+	/**
+	* Check if the map is currently visible.
+	*/
+	isVisible() {
+		return this.visible;
+	}
+	/**
+	* Get the map size in meters.
+	*/
+	getMapSize() {
+		return this.options.mapSize;
+	}
+	/**
+	* Get the height offset below camera.
+	*/
+	getHeightOffset() {
+		return this.options.heightOffset;
+	}
+	/**
+	* Get the mesh (for testing).
+	*/
+	getMesh() {
+		return this.mesh;
+	}
+	/**
+	* Update the map position to follow the camera.
+	*
+	* Since the mesh is now a child of the camera, Three.js handles
+	* world-space transforms automatically. This method is kept for
+	* backward compatibility but is a no-op (position is set once in
+	* createMesh and doesn't need per-frame updates).
+	*/
+	updatePosition() {}
+	/**
+	* Clean up resources.
+	*/
+	dispose() {
+		this.hide();
+		if (this.mesh) disposeObject3D(this.mesh);
+		this.geometry = null;
+		this.material = null;
+		this.mesh = null;
+		this.currentTile = null;
+	}
+	/**
+	* Create the map mesh (plane facing up).
+	*/
+	createMesh() {
+		if (this.mesh) {
+			this.mapParent.add(this.mesh);
+			return;
+		}
+		this.geometry = new THREE.PlaneGeometry(this.options.mapSize, this.options.mapSize);
+		this.material = new THREE.MeshBasicMaterial({
+			color: 16777215,
+			side: THREE.DoubleSide,
+			transparent: true,
+			opacity: .9
+		});
+		this.mesh = new THREE.Mesh(this.geometry, this.material);
+		this.mesh.name = "map-overlay";
+		this.mesh.rotation.x = -Math.PI / 2;
+		this.mesh.position.set(0, this.options.heightOffset, -.5);
+		this.mapParent.add(this.mesh);
+	}
+	/**
+	* Remove the mesh from the camera.
+	*/
+	removeMesh() {
+		if (this.mesh) this.mapParent.remove(this.mesh);
+	}
+	/**
+	* Update the tile texture based on current GPS position.
+	*/
+	updateTile() {
+		if (!this.gpsPosition || !this.material) return;
+		const [x, y] = latLonToTileXY(this.gpsPosition.lat, this.gpsPosition.lon, this.options.zoomLevel);
+		if (this.currentTile?.x === x && this.currentTile?.y === y) return;
+		this.currentTile = {
+			x,
+			y
+		};
+		const url = this.options.tileServerUrl.replace("{z}", String(this.options.zoomLevel)).replace("{x}", String(x)).replace("{y}", String(y));
+		log.info(`Loading tile: z=${this.options.zoomLevel}, x=${x}, y=${y}`);
+		this.textureLoader.load(url, (texture) => {
+			if (this.material) {
+				if (this.material.map) this.material.map.dispose();
+				this.material.map = texture;
+				this.material.needsUpdate = true;
+			}
+		}, void 0, (error) => {
+			log.error("Failed to load map tile:", error);
+			this.onTileError?.(error);
+		});
+	}
+};
+//#endregion
+export { DEFAULT_HEIGHT_OFFSET, DEFAULT_MAP_SIZE, DEFAULT_ZOOM, MapOverlay, latLonToTileXY, tileXYToLatLon };

package/dist/visualization/reference-points.d.ts

@@ -0,0 +1,2 @@
+import { n as refPointVisualizer, t as RefPointVisualizer } from "../reference-points-CFWy8_wj.js";
+export { RefPointVisualizer, refPointVisualizer };

package/dist/visualization/reference-points.js

@@ -0,0 +1,160 @@
+import { createLogger } from "../utils/logger.js";
+import { disposeMeshArray } from "./three-dispose.js";
+import { getScene } from "../ar/webxr-session.js";
+import { VIS_COLORS } from "./vis-colors.js";
+import * as THREE from "three";
+import { calcRelativeCoordsInMeters } from "gps-plus-slam-js";
+//#region ../src/visualization/reference-points.ts
+/**
+* Reference Point Visualizer
+*
+* Creates and manages Three.js meshes for visualizing reference points
+* in GPS-aligned 3D space.
+*
+* ARCHITECTURE NOTE:
+* - Prior reference points (green) are added to scene root (GPS world space)
+* - Current session points (red) are also in GPS world space
+* - Spheres stay in GPS coordinates, independent of alignment matrix
+*/
+const log = createLogger("RefPointVisualizer");
+/** Sphere radius in meters (10cm) */
+const REF_POINT_RADIUS = .1;
+/**
+* Manager for reference point visualization
+*/
+var RefPointVisualizer = class {
+	priorRefMeshes = [];
+	currentRefMeshes = [];
+	zeroRef = null;
+	/** Shared geometry for prior-session ref point meshes (lazy-created) */
+	priorRefGeometry = null;
+	/** Shared material for prior-session ref point meshes (lazy-created) */
+	priorRefMaterial = null;
+	/** Shared geometry for current-session ref point meshes (lazy-created) */
+	currentRefGeometry = null;
+	/**
+	* Set the GPS zero reference (origin for coordinate conversion).
+	* Must be called before displaying reference points.
+	*
+	* @param zero - GPS coordinates of the origin
+	*/
+	setZeroRef(zero) {
+		this.zeroRef = zero;
+	}
+	/**
+	* Get the current zero reference
+	*/
+	getZeroRef() {
+		return this.zeroRef;
+	}
+	/**
+	* Display reference points from prior sessions.
+	* Clears any existing prior ref points first.
+	*
+	* @param refPoints - Array of reference point marks to visualize
+	*/
+	displayPriorRefPoints(refPoints) {
+		if (!this.zeroRef) {
+			log.warn("No zero reference set");
+			return;
+		}
+		const scene = getScene();
+		if (!scene) {
+			log.warn("Scene not available");
+			return;
+		}
+		this.clearPriorRefPoints();
+		const geometry = this.priorRefGeometry ??= new THREE.SphereGeometry(REF_POINT_RADIUS, 16, 16);
+		const material = this.priorRefMaterial ??= new THREE.MeshBasicMaterial({ color: VIS_COLORS.PRIOR_REF_POINT.hex });
+		let visibleCount = 0;
+		for (const refPoint of refPoints) {
+			if (!refPoint.gpsPosition) continue;
+			const coords = calcRelativeCoordsInMeters(this.zeroRef, {
+				lat: refPoint.gpsPosition.lat,
+				lon: refPoint.gpsPosition.lon
+			}, refPoint.gpsPosition.altitude ?? 0, 0);
+			const mesh = new THREE.Mesh(geometry, material);
+			mesh.position.set(coords[0], coords[1], coords[2]);
+			mesh.name = `prior-ref-${refPoint.id}`;
+			scene.add(mesh);
+			this.priorRefMeshes.push(mesh);
+			visibleCount++;
+		}
+		log.info(`Displayed ${visibleCount}/${refPoints.length} prior reference points`);
+	}
+	/**
+	* Add a reference point from the current session.
+	*
+	* @param refPoint - Reference point mark to visualize
+	*/
+	addCurrentRefPoint(refPoint) {
+		if (!this.zeroRef || !refPoint.gpsPosition) {
+			log.warn("Cannot add current ref point - missing zero ref or GPS position");
+			return;
+		}
+		const scene = getScene();
+		if (!scene) {
+			log.warn("Scene not available");
+			return;
+		}
+		const coords = calcRelativeCoordsInMeters(this.zeroRef, {
+			lat: refPoint.gpsPosition.lat,
+			lon: refPoint.gpsPosition.lon
+		}, refPoint.gpsPosition.altitude ?? 0, 0);
+		const geometry = this.currentRefGeometry ??= new THREE.SphereGeometry(REF_POINT_RADIUS, 16, 16);
+		const material = new THREE.MeshBasicMaterial({ color: VIS_COLORS.CURRENT_REF_POINT.hex });
+		const mesh = new THREE.Mesh(geometry, material);
+		mesh.position.set(coords[0], coords[1], coords[2]);
+		mesh.name = `current-ref-${refPoint.id}`;
+		scene.add(mesh);
+		this.currentRefMeshes.push(mesh);
+		log.info(`Added current ref point: ${refPoint.id}`);
+	}
+	/**
+	* Clear all prior reference point meshes from the scene.
+	*/
+	clearPriorRefPoints() {
+		const scene = getScene();
+		disposeMeshArray(this.priorRefMeshes, scene, {
+			skipGeometry: true,
+			skipMaterial: true
+		});
+		this.priorRefGeometry?.dispose();
+		this.priorRefGeometry = null;
+		this.priorRefMaterial?.dispose();
+		this.priorRefMaterial = null;
+	}
+	/**
+	* Clear current session reference point meshes from the scene.
+	*/
+	clearCurrentRefPoints() {
+		const scene = getScene();
+		disposeMeshArray(this.currentRefMeshes, scene, { skipGeometry: true });
+		this.currentRefGeometry?.dispose();
+		this.currentRefGeometry = null;
+	}
+	/**
+	* Clear all visualizations and reset state.
+	*/
+	clearAll() {
+		this.clearPriorRefPoints();
+		this.clearCurrentRefPoints();
+		this.zeroRef = null;
+	}
+	/**
+	* Get count of visible reference points.
+	*/
+	getCounts() {
+		return {
+			prior: this.priorRefMeshes.length,
+			current: this.currentRefMeshes.length
+		};
+	}
+};
+/**
+* Singleton instance for global use.
+* Import this to visualize reference points.
+*/
+const refPointVisualizer = new RefPointVisualizer();
+//#endregion
+export { RefPointVisualizer, refPointVisualizer };

package/dist/visualization/three-dispose.d.ts

@@ -0,0 +1,2 @@
+import { n as disposeMeshArray, r as disposeObject3D, t as DisposeOptions } from "../three-dispose-CCBHjE_a.js";
+export { DisposeOptions, disposeMeshArray, disposeObject3D };

package/dist/visualization/three-dispose.js

@@ -0,0 +1,55 @@
+//#region ../src/visualization/three-dispose.ts
+/**
+* Traverse an Object3D and all its descendants, disposing GPU resources:
+* geometries (Mesh), materials (Mesh + Sprite), and material textures.
+*
+* Does NOT remove root from its parent — callers handle that.
+*
+* @param root The Object3D tree root to clean up.
+* @param opts Optional flags (e.g. skipGeometry for shared geometries).
+*/
+function disposeObject3D(root, opts) {
+	const disposed = /* @__PURE__ */ new Set();
+	root.traverse((object) => {
+		if ("geometry" in object && object.geometry) {
+			const geo = object.geometry;
+			if (!opts?.skipGeometry && !disposed.has(geo)) {
+				disposed.add(geo);
+				geo.dispose();
+			}
+		}
+		if (!opts?.skipMaterial && "material" in object) {
+			const raw = object.material;
+			const materials = Array.isArray(raw) ? raw : [raw];
+			for (const mat of materials) {
+				if (!mat || disposed.has(mat)) continue;
+				disposed.add(mat);
+				if ("map" in mat && mat.map) {
+					const tex = mat.map;
+					if (!disposed.has(tex)) {
+						disposed.add(tex);
+						tex.dispose();
+					}
+				}
+				mat.dispose();
+			}
+		}
+	});
+}
+/**
+* Remove meshes from a parent, dispose their GPU resources, and clear
+* the array in-place.
+*
+* @param meshes Array of meshes (mutated — emptied after disposal).
+* @param parent The Object3D to remove meshes from. Pass null/undefined to skip removal.
+* @param opts   Optional flags (e.g. skipGeometry for shared geometries).
+*/
+function disposeMeshArray(meshes, parent, opts) {
+	for (const mesh of meshes) {
+		if (parent) parent.remove(mesh);
+		disposeObject3D(mesh, opts);
+	}
+	meshes.length = 0;
+}
+//#endregion
+export { disposeMeshArray, disposeObject3D };

package/dist/visualization/vis-colors.d.ts

@@ -0,0 +1,2 @@
+import { t as VIS_COLORS } from "../vis-colors-Qi2vlRGt.js";
+export { VIS_COLORS };

package/dist/visualization/vis-colors.js

@@ -0,0 +1,74 @@
+//#region ../src/visualization/vis-colors.ts
+/**
+* Centralized Visualization Color Palette
+*
+* Single source of truth for all semantic colors used across the app's
+* visualization layers (Three.js 3D scene and Leaflet 2D summary map).
+*
+* Each entry provides both hex (number, for Three.js) and css (string,
+* for Leaflet/CSS) formats. Some entries intentionally use different 3D/2D
+* shades — see inline comments.
+*
+* Tailwind classes in index.html (e.g., bg-yellow-400) cannot be dynamically
+* generated and must be kept in sync manually — search for "vis-colors" in
+* the HTML legend to find them.
+*/
+const VIS_COLORS = {
+	/** Raw GPS marker — yellow */
+	RAW_GPS: {
+		hex: 16776960,
+		css: "#ffff00"
+	},
+	/** Fused VIO marker — cyan */
+	FUSED_VIO: {
+		hex: 65535,
+		css: "#00ffff"
+	},
+	/** Alignment snapshot marker — red */
+	ALIGNMENT_SNAPSHOT: {
+		hex: 16711680,
+		css: "#ff0000"
+	},
+	/** Prior reference point — green */
+	PRIOR_REF_POINT: {
+		hex: 65280,
+		css: "#00ff00"
+	},
+	/** Current reference point — bright red in 3D, lighter red (#ff6b6b) in 2D for map visibility */
+	CURRENT_REF_POINT: {
+		hex: 16711680,
+		css: "#ff6b6b"
+	},
+	/** Compass north indicator — red */
+	COMPASS_NORTH: {
+		hex: 16711680,
+		css: "#ff0000"
+	},
+	/** Compass east indicator — blue */
+	COMPASS_EAST: {
+		hex: 255,
+		css: "#0000ff"
+	},
+	/** Compass south indicator — dark red */
+	COMPASS_SOUTH: {
+		hex: 8930372,
+		css: "#884444"
+	},
+	/** Compass west indicator — dark blue */
+	COMPASS_WEST: {
+		hex: 4473992,
+		css: "#444488"
+	},
+	/** Compass up indicator — green */
+	COMPASS_UP: {
+		hex: 65280,
+		css: "#00ff00"
+	},
+	/** User GPS position marker — blue */
+	USER_POSITION: {
+		hex: 3900150,
+		css: "#3b82f6"
+	}
+};
+//#endregion
+export { VIS_COLORS };