astro-viewer 3.0.0 → 3.2.0

package/lib-esm/AstroSphere.js

@@ -1,20 +1,34 @@
-import { bootSetup } from './Config.js';
-import Camera from './Camera.js';
-import RayPickingUtils from './utils/RayPickingUtils.js';
-import global from './Global.js';
-import MouseHelper from './utils/MouseHelper.js';
-import { cartesianToSpherical, sphericalToAstroDeg, raDegToHMS, decDegToDMS, } from './utils/Utils.js';
-import { HiPS } from './model/hips/HiPS.js';
-import { PerspectiveMatrixManager } from './utils/PerspectiveMatrixManager.js';
-import { Point } from './model/Point.js';
-import { FoVUtils } from './utils/FoVUtils.js';
-import { EquatorialGrid } from './model/grid/EquatorialGrid.js';
-import { HealpixGrid } from './model/grid/HealpixGrid.js';
-import { CoordsType } from './utils/CoordsType.js';
-import ColorMaps from './model/ColorMaps.js';
-import { XYZLayer } from './model/earth/XYZLayer.js';
-import { xyzTileRequestScheduler } from './model/earth/XYZTileRequestScheduler.js';
-import { WMTSAdapter } from './model/earth/wmts/WMTSAdapter.js';
+/*
+ * AstroViewer
+ * Copyright (C) Fabrizio Giordano
+ * SPDX-License-Identifier: LicenseRef-AstroViewer-Dual-License
+ *
+ * This file is part of AstroViewer.
+ * AstroViewer is distributed under a dual-license model.
+ * Commercial use requires a separate commercial license.
+ * Non-commercial use is governed by LICENSE-NONCOMMERCIAL.md.
+ *
+ * See LICENSE.md, LICENSE-COMMERCIAL.md, and LICENSE-NONCOMMERCIAL.md for details.
+ */
+import { bootSetup } from "./Config.js";
+import Camera from "./Camera.js";
+import RayPickingUtils from "./utils/RayPickingUtils.js";
+import global from "./Global.js";
+import MouseHelper from "./utils/MouseHelper.js";
+import { cartesianToSpherical, sphericalToAstroDeg, raDegToHMS, decDegToDMS, } from "./utils/Utils.js";
+import { HiPS } from "./model/hips/HiPS.js";
+import { PerspectiveMatrixManager } from "./utils/PerspectiveMatrixManager.js";
+import { Point } from "./model/Point.js";
+import { FoVUtils } from "./utils/FoVUtils.js";
+import { EquatorialGrid } from "./model/grid/EquatorialGrid.js";
+import { HealpixGrid } from "./model/grid/HealpixGrid.js";
+import { CoordsType } from "./utils/CoordsType.js";
+import ColorMaps from "./model/ColorMaps.js";
+import { xyzTileRequestScheduler } from "./model/earth/XYZTileRequestScheduler.js";
+import { WMTSAdapter } from "./model/earth/WMTSAdapter.js";
+import { XYZMapDescriptor } from "./model/earth/XYZMapDescriptor.js";
+import { XYZMap } from "./model/earth/XYZMap.js";
+import { mat4, vec3, vec4 } from "gl-matrix";
 /**
  * AstroSphere — main WebGL scene controller (TS port)
  */
@@ -39,7 +53,7 @@ class AstroSphere {
     pointerDownY = null;
     pointerDownAt = 0;
     _activeHiPS = null;
-    _activeXYZ = null;
+    _activeXYZ2 = null;
     _activeBaseLayer = null;
     startup = true;
     fov;
@@ -48,16 +62,21 @@ class AstroSphere {
     _webgl;
     _selectedColorMap;
     _cameraStatusChanged = false;
+    lastCameraChangedAt = 0;
+    lastCameraMotionAt = 0;
     lastHoveredSource = null;
     lastHoveredCatalogue = null;
     zoomSensitivity = 1.0;
+    lockedEastWestRaDeg = null;
+    lockedNorthSouthDecDeg = null;
+    keepCameraNorthUp = true;
     constructor(canvas, webgl) {
-        console.log('[AstroSphere] new instance for canvas', canvas.id);
+        console.log("[AstroSphere] new instance for canvas", canvas.id);
         // Keep global GL context (as in original JS)
         this._webgl = webgl;
         this.mouseHelper = new MouseHelper();
         this.canvas = canvas;
-        const nativeColorMap = 'native';
+        const nativeColorMap = "native";
         this._selectedColorMap = ColorMaps[nativeColorMap];
         global.insideSphere = bootSetup.insideSphere;
         this.initCamera();
@@ -105,20 +124,26 @@ class AstroSphere {
             astroDeg: astroCoords,
             sphericalDeg: sphericalCoords,
             raHMS: raHMS,
-            decDMS: decDMS
+            decDMS: decDMS,
         };
         return this.centralPoinCoords;
     }
     updateLastMousePoint() {
-        const sphericalCoords = { phi: this.mouseHelper.phi, theta: this.mouseHelper.theta };
-        const astroCoords = { ra: this.mouseHelper.ra, dec: this.mouseHelper.dec };
+        const sphericalCoords = {
+            phi: this.mouseHelper.phi,
+            theta: this.mouseHelper.theta,
+        };
+        const astroCoords = {
+            ra: this.mouseHelper.ra,
+            dec: this.mouseHelper.dec,
+        };
         const raHMS = this.mouseHelper.raHMS;
         const decDMS = this.mouseHelper.decDMS;
         this.mousePointCoords = {
             astroDeg: astroCoords,
             sphericalDeg: sphericalCoords,
             raHMS: raHMS,
-            decDMS: decDMS
+            decDMS: decDMS,
         };
         return this.mousePointCoords;
     }
@@ -138,9 +163,6 @@ class AstroSphere {
     computeZoomStep(currentFov, deltaY) {
         const direction = deltaY < 0 ? -1 : 1;
         const wheelScale = this.clamp(Math.abs(deltaY) / 120, AstroSphere.MIN_WHEEL_SCALE, AstroSphere.MAX_WHEEL_SCALE);
-        // Continuous wheel response:
-        // - broad FoV stays responsive without large jumps
-        // - narrow FoV keeps a usable floor to avoid the 0.1 -> 0.02 deg stall
         const baseMagnitude = this.clamp(0.0012 + 0.0025 * Math.sqrt(Math.max(currentFov, 0)), 0.0012, 0.04);
         return direction * baseMagnitude * wheelScale * this.zoomSensitivity;
     }
@@ -150,6 +172,119 @@ class AstroSphere {
     getZoomSensitivity() {
         return this.zoomSensitivity;
     }
+    filterRotationDeltaByAstroLocks(deltaX, deltaY) {
+        const lockEastWest = this._camera.isRotationLockedY();
+        const lockNorthSouth = this._camera.isRotationLockedX();
+        if (!lockEastWest && !lockNorthSouth) {
+            return { deltaX, deltaY };
+        }
+        const center = RayPickingUtils.getIntersectionPointWithSingleModel(this.canvas.clientWidth / 2, this.canvas.clientHeight / 2, this._healpixGrid, this._webgl, this._camera, this._perspectiveMatrixManager.pMatrix);
+        if (!center || center.length < 3) {
+            return { deltaX, deltaY };
+        }
+        const centerVec = vec3.normalize(vec3.create(), vec3.fromValues(center[0], center[1], center[2]));
+        const northAxis = vec3.fromValues(0, 0, 1);
+        const eastVec = vec3.cross(vec3.create(), northAxis, centerVec);
+        if (vec3.length(eastVec) < 1e-6) {
+            vec3.set(eastVec, 1, 0, 0);
+        }
+        else {
+            vec3.normalize(eastVec, eastVec);
+        }
+        const northProjection = vec3.scale(vec3.create(), centerVec, vec3.dot(northAxis, centerVec));
+        const northVec = vec3.subtract(vec3.create(), northAxis, northProjection);
+        if (vec3.length(northVec) < 1e-6) {
+            vec3.cross(northVec, centerVec, eastVec);
+        }
+        vec3.normalize(northVec, northVec);
+        const eastScreen = this.projectModelDirectionToScreen(centerVec, eastVec);
+        const northScreen = this.projectModelDirectionToScreen(centerVec, northVec);
+        if (!eastScreen || !northScreen) {
+            return { deltaX, deltaY };
+        }
+        let nextDeltaX = deltaX;
+        let nextDeltaY = deltaY;
+        if (lockEastWest) {
+            const amount = nextDeltaX * eastScreen.x + nextDeltaY * eastScreen.y;
+            nextDeltaX -= amount * eastScreen.x;
+            nextDeltaY -= amount * eastScreen.y;
+        }
+        if (lockNorthSouth) {
+            const amount = nextDeltaX * northScreen.x + nextDeltaY * northScreen.y;
+            nextDeltaX -= amount * northScreen.x;
+            nextDeltaY -= amount * northScreen.y;
+        }
+        return {
+            deltaX: nextDeltaX,
+            deltaY: nextDeltaY,
+        };
+    }
+    projectModelDirectionToScreen(centerModel, directionModel) {
+        const offsetModel = vec3.scaleAndAdd(vec3.create(), centerModel, directionModel, 0.01);
+        const centerScreen = this.projectModelPointToScreen(centerModel);
+        const offsetScreen = this.projectModelPointToScreen(offsetModel);
+        if (!centerScreen || !offsetScreen) {
+            return null;
+        }
+        const x = offsetScreen.x - centerScreen.x;
+        const y = offsetScreen.y - centerScreen.y;
+        const len = Math.hypot(x, y);
+        if (len < 1e-6) {
+            return null;
+        }
+        return { x: x / len, y: y / len };
+    }
+    projectModelPointToScreen(pointModel) {
+        const vMatrix = this._camera.getCameraMatrix();
+        const mMatrix = this._healpixGrid.getModelMatrix();
+        const mvMatrix = mat4.create();
+        const mvpMatrix = mat4.create();
+        mat4.multiply(mvMatrix, vMatrix, mMatrix);
+        mat4.multiply(mvpMatrix, this._perspectiveMatrixManager.pMatrix, mvMatrix);
+        const clip = vec4.fromValues(pointModel[0], pointModel[1], pointModel[2], 1);
+        vec4.transformMat4(clip, clip, mvpMatrix);
+        if (Math.abs(clip[3]) < 1e-6) {
+            return null;
+        }
+        return {
+            x: clip[0] / clip[3],
+            y: -(clip[1] / clip[3]),
+        };
+    }
+    enforceAstronomicalRotationLocks() {
+        if (this.lockedEastWestRaDeg == null &&
+            this.lockedNorthSouthDecDeg == null) {
+            return false;
+        }
+        const center = this.updateCentralPoint();
+        if (!center) {
+            return false;
+        }
+        const nextRa = this.lockedEastWestRaDeg ?? center.astroDeg.ra;
+        const nextDec = this.lockedNorthSouthDecDeg ?? center.astroDeg.dec;
+        const needsCorrection = Math.abs(nextRa - center.astroDeg.ra) > 1e-6 ||
+            Math.abs(nextDec - center.astroDeg.dec) > 1e-6;
+        if (!needsCorrection) {
+            return false;
+        }
+        this._camera.goTo(nextRa, nextDec);
+        this._perspectiveMatrixManager.computePerspectiveMatrix(this.canvas, this._camera, bootSetup.camera_fov_deg, bootSetup.camera_near_plane, global.insideSphere);
+        this.updateCentralPoint();
+        return true;
+    }
+    enforceCameraNorthUp() {
+        if (!this.keepCameraNorthUp) {
+            return false;
+        }
+        const center = this.updateCentralPoint();
+        if (!center) {
+            return false;
+        }
+        this._camera.goTo(center.astroDeg.ra, center.astroDeg.dec);
+        this._perspectiveMatrixManager.computePerspectiveMatrix(this.canvas, this._camera, bootSetup.camera_fov_deg, bootSetup.camera_near_plane, global.insideSphere);
+        this.updateCentralPoint();
+        return true;
+    }
     emitCameraChanged(reason) {
         // avoid dispatch before scene is ready
         if (!this._activeHiPS)
@@ -161,7 +296,7 @@ class AstroSphere {
             return;
         // optional debug
         // console.log('[AstroSphere] emit camera-changed:', reason);
-        this.canvas.dispatchEvent(new CustomEvent('camera-changed', {
+        this.canvas.dispatchEvent(new CustomEvent("camera-changed", {
             detail,
             bubbles: true,
             composed: true,
@@ -169,7 +304,7 @@ class AstroSphere {
     }
     addEventListeners(canvas) {
         if (global.debug) {
-            console.log('[AstroSphere::addEventListeners]');
+            console.log("[AstroSphere::addEventListeners]");
         }
         const CLICK_MAX_DISTANCE_PX = 4;
         const CLICK_MAX_DURATION_MS = 250;
@@ -199,7 +334,7 @@ class AstroSphere {
         const handleMouseUp = (event) => {
             canvas.releasePointerCapture(event.pointerId);
             this.mouseDown = false;
-            document.body.style.cursor = 'auto';
+            document.body.style.cursor = "auto";
             if (event.button !== 0) {
                 event.preventDefault();
                 return false;
@@ -221,7 +356,7 @@ class AstroSphere {
                         const clickResult = cat.selectPrimarySourceFromClick(this.mouseHelper);
                         if (!clickResult?.sources.length)
                             continue;
-                        this._webgl.canvas.dispatchEvent(new CustomEvent('source-clicked', {
+                        this._webgl.canvas.dispatchEvent(new CustomEvent("source-clicked", {
                             detail: {
                                 source: clickResult.sources,
                                 selectionState: clickResult.selectionState,
@@ -235,7 +370,7 @@ class AstroSphere {
                         const clickResult = fset.selectPrimaryFootprintFromClick(this.mouseHelper);
                         if (!clickResult?.footprints.length)
                             continue;
-                        this._webgl.canvas.dispatchEvent(new CustomEvent('footprint-clicked', {
+                        this._webgl.canvas.dispatchEvent(new CustomEvent("footprint-clicked", {
                             detail: {
                                 footprint: clickResult.footprints,
                                 selectionState: clickResult.selectionState,
@@ -262,12 +397,16 @@ class AstroSphere {
             if (!this._healpixGrid)
                 return;
             if (this.mouseDown) {
-                document.body.style.cursor = 'grab';
-                // Rotation deltas – either use client-space or local-space, but be consistent
-                const deltaX = ((newX - (this.lastMouseX ?? newX)) * Math.PI) / canvas.width;
-                const deltaY = ((newY - (this.lastMouseY ?? newY)) * Math.PI) / canvas.height;
-                this.inertiaX += 0.1 * deltaX;
-                this.inertiaY += 0.1 * deltaY;
+                document.body.style.cursor = "grab";
+                const dragDirection = global.insideSphere ? -1 : 1;
+                const dragSpeed = global.insideSphere ? 10.0 : 1;
+                const deltaX = (dragDirection * dragSpeed * (newX - (this.lastMouseX ?? newX)) * Math.PI) /
+                    canvas.width;
+                const deltaY = (dragDirection * dragSpeed * (newY - (this.lastMouseY ?? newY)) * Math.PI) /
+                    canvas.height;
+                const filteredDelta = this.filterRotationDeltaByAstroLocks(deltaX, deltaY);
+                this.inertiaX += 0.1 * filteredDelta.deltaX;
+                this.inertiaY += 0.1 * filteredDelta.deltaY;
                 this.updateCentralPoint();
             }
             else {
@@ -299,10 +438,11 @@ class AstroSphere {
             // direction feels responsive instead of "buffered".
             this.zoomInertia = 0;
             this._camera.zoom(zoomStep);
+            this.lastCameraMotionAt = performance.now();
             this.fov = this._healpixGrid.refreshFoV(this._camera, this._perspectiveMatrixManager.pMatrix);
             this._camera.refreshFoV(this.fov.minFoV);
             this._cameraStatusChanged = true;
-            this.emitCameraChanged('wheel');
+            this.emitCameraChanged("wheel");
             event.preventDefault();
         };
         const handleContextMenu = (event) => {
@@ -320,7 +460,7 @@ class AstroSphere {
                 const pickResult = cat.getSourcesFromPointer(this.mouseHelper);
                 if (!pickResult?.sources.length)
                     continue;
-                this._webgl.canvas.dispatchEvent(new CustomEvent('source-contextmenu', {
+                this._webgl.canvas.dispatchEvent(new CustomEvent("source-contextmenu", {
                     detail: {
                         source: pickResult.sources,
                         catalogue: cat,
@@ -336,7 +476,7 @@ class AstroSphere {
                 const pickResult = fset.getFootprintsFromPointer(this.mouseHelper);
                 if (!pickResult?.footprints.length)
                     continue;
-                this._webgl.canvas.dispatchEvent(new CustomEvent('footprint-contextmenu', {
+                this._webgl.canvas.dispatchEvent(new CustomEvent("footprint-contextmenu", {
                     detail: {
                         footprint: pickResult.footprints,
                         footprintSet: fset,
@@ -356,40 +496,40 @@ class AstroSphere {
             }
             // console.log('[AstroSphere::onKeyDown] key=', evt.key)
             switch (evt.key) {
-                case '1':
+                case "1":
                     // Free camera
                     this._camera.clearRotationLock();
                     break;
-                case '2':
+                case "2":
                     // Lock X axis rotation
                     this._camera.setRotationLock({ x: true, y: false, z: false });
                     break;
-                case '3':
+                case "3":
                     // Lock Y axis rotation
                     this._camera.setRotationLock({ x: false, y: true, z: false });
                     break;
-                case '4':
+                case "4":
                     // Lock Z axis rotation
                     this._camera.setRotationLock({ x: false, y: false, z: true });
                     break;
             }
         };
-        console.log('[AstroSphere] registering pointer and wheel listeners on canvas');
+        console.log("[AstroSphere] registering pointer and wheel listeners on canvas");
         canvas.onpointerdown = handleMouseDown;
         canvas.onpointerup = handleMouseUp;
         canvas.onpointermove = handleMouseMove;
         canvas.onpointerleave = () => {
             this.clearLastMousePoint();
             this._cameraStatusChanged = true;
-            this.emitCameraChanged('pointerleave');
+            this.emitCameraChanged("pointerleave");
         };
-        console.log('[AstroSphere] adding wheel event listener with passive: false');
-        canvas.addEventListener('wheel', handleMouseWheel, { passive: false });
-        canvas.addEventListener('contextmenu', handleContextMenu);
-        console.log('[AstroSphere] registering global keydown listener on document');
-        document.addEventListener('keydown', onKeyDown, { capture: true });
+        console.log("[AstroSphere] adding wheel event listener with passive: false");
+        canvas.addEventListener("wheel", handleMouseWheel, { passive: false });
+        canvas.addEventListener("contextmenu", handleContextMenu);
+        console.log("[AstroSphere] registering global keydown listener on document");
+        document.addEventListener("keydown", onKeyDown, { capture: true });
     }
-    // REVIEW THIS METHOD AND MOVE IT 
+    // REVIEW THIS METHOD AND MOVE IT
     getPhiThetaDeg(canvas) {
         const rect = canvas.getBoundingClientRect();
         const maxX = rect.width;
@@ -416,16 +556,21 @@ class AstroSphere {
     }
     activateHiPS(hipsDescriptor) {
         this._activeHiPS = new HiPS(1, [0.0, 0.0, 0.0], 0, 0, hipsDescriptor, this._webgl, this._healpixGrid);
-        this._activeBaseLayer = 'hips';
+        this._activeBaseLayer = "hips";
     }
     activateXYZ(config) {
-        this._activeXYZ = new XYZLayer(config, this._webgl);
-        this._activeBaseLayer = 'xyz';
+        this.activateXYZ2(new XYZMapDescriptor(config.name ?? "XYZ Earth2 Layer", config.urlTemplate, config.minZoom ?? 0, config.maxZoom ?? 8, config.segmentsPerSide ?? 48, config.maxCachedTiles ?? 384, 8, config.urlResolver));
+        this._activeBaseLayer = "xyz";
+    }
+    activateXYZ2(config) {
+        this._activeXYZ2 = new XYZMap(1, [0.0, 0.0, 0.0], 0, 0, config, this._webgl);
+        this._activeBaseLayer = "xyz";
     }
     activateWMTS(config) {
         const adapter = new WMTSAdapter(config);
-        this._activeXYZ = new XYZLayer(adapter.toXYZLayerConfig(), this._webgl);
-        this._activeBaseLayer = 'xyz';
+        const xyzConfig = adapter.toXYZLayerConfig();
+        this._activeXYZ2 = new XYZMap(1, [0.0, 0.0, 0.0], 0, 0, new XYZMapDescriptor(config.layer ? `WMTS ${config.layer}` : "WMTS Earth2 Layer", xyzConfig.urlTemplate, xyzConfig.minZoom ?? 0, xyzConfig.maxZoom ?? 8, xyzConfig.segmentsPerSide ?? 48, xyzConfig.maxCachedTiles ?? 384, 8, xyzConfig.urlResolver), this._webgl);
+        this._activeBaseLayer = "xyz";
     }
     // Catalogue section
     async showCatalogue(cat) {
@@ -435,7 +580,7 @@ class AstroSphere {
         return cat;
     }
     deleteCatalogue(catalogue) {
-        this.activeCatalogues = this.activeCatalogues.filter(c => c !== catalogue);
+        this.activeCatalogues = this.activeCatalogues.filter((c) => c !== catalogue);
     }
     // End Catalogue section
     // Footprint section
@@ -446,11 +591,11 @@ class AstroSphere {
         return fset;
     }
     deleteFootprintSet(footprintSet) {
-        this.activeFootprintSets = this.activeFootprintSets.filter(fst => fst !== footprintSet);
+        this.activeFootprintSets = this.activeFootprintSets.filter((fst) => fst !== footprintSet);
     }
     getHoveredFootprints() {
         let footprintsHovered = [];
-        this.activeFootprintSets.forEach(fset => {
+        this.activeFootprintSets.forEach((fset) => {
             footprintsHovered.push(fset.hoveredFootprints);
         });
         return footprintsHovered;
@@ -459,7 +604,39 @@ class AstroSphere {
     goTo(raDeg, decDeg) {
         this._camera.goTo(raDeg, decDeg);
     }
+    getActiveCoordinateMode() {
+        if (this._activeBaseLayer === "xyz") {
+            return "lonlat";
+        }
+        if (this._activeBaseLayer === "hips" && this._activeHiPS?.isGalacticHips) {
+            return "galactic";
+        }
+        return "equatorial";
+    }
+    resetAxesOrientation() {
+        const center = this.updateCentralPoint();
+        if (!center)
+            return;
+        this.inertiaX = 0;
+        this.inertiaY = 0;
+        this._camera.goTo(center.astroDeg.ra, center.astroDeg.dec);
+        this._perspectiveMatrixManager.computePerspectiveMatrix(this.canvas, this._camera, bootSetup.camera_fov_deg, bootSetup.camera_near_plane, global.insideSphere);
+        this.updateCentralPoint();
+        this._cameraStatusChanged = true;
+    }
+    setKeepCameraNorthUp(enabled) {
+        this.keepCameraNorthUp = enabled;
+        if (enabled) {
+            this.resetAxesOrientation();
+        }
+    }
+    isKeepCameraNorthUp() {
+        return this.keepCameraNorthUp;
+    }
     getFoV() {
+        if (this._activeBaseLayer === "xyz" && this._activeXYZ2) {
+            return this._activeXYZ2.getFoV();
+        }
         return this.fov;
     }
     getFoVPolygon() {
@@ -474,11 +651,15 @@ class AstroSphere {
         this._camera.refreshFoV(this.fov.minFoV);
     }
     changeFoV2(deg) {
-        const newCameraPos = this._healpixGrid.getFoV().computeCameraPositionForFoV(deg);
+        const newCameraPos = this._healpixGrid
+            .getFoV()
+            .computeCameraPositionForFoV(deg);
         this._camera.setCameraPosition(newCameraPos);
     }
     changeFoV3(deg) {
-        const newPos = this._healpixGrid.getFoV().computeCameraPositionForAngularDiameter(deg);
+        const newPos = this._healpixGrid
+            .getFoV()
+            .computeCameraPositionForAngularDiameter(deg);
         this._camera.setCameraPosition(newPos);
         // Recompute projection after moving the camera
         this._perspectiveMatrixManager.computePerspectiveMatrix(this.canvas, this._camera, bootSetup.camera_fov_deg, bootSetup.camera_near_plane, false);
@@ -487,9 +668,22 @@ class AstroSphere {
         return global.insideSphere;
     }
     toggleInsideSphere() {
+        const centerBeforeToggle = this.updateCentralPoint();
+        this.inertiaX = 0;
+        this.inertiaY = 0;
+        this.zoomInertia = 0;
         global.insideSphere = !global.insideSphere;
         // console.log(global.insideSphere)
         this._camera.toggleInsideSphere();
+        this._camera.goTo(centerBeforeToggle.astroDeg.ra, centerBeforeToggle.astroDeg.dec);
+        this._perspectiveMatrixManager.computePerspectiveMatrix(this.canvas, this._camera, bootSetup.camera_fov_deg, bootSetup.camera_near_plane, global.insideSphere);
+        this.fov = this._healpixGrid.refreshFoV(this._camera, this._perspectiveMatrixManager.pMatrix);
+        this._camera.refreshFoV(this.fov.minFoV);
+        this.updateCentralPoint();
+        this.lastCameraMotionAt = performance.now();
+        this._cameraStatusChanged = true;
+        this.emitCameraChanged("inside-sphere-toggle");
+        requestAnimationFrame(() => this.draw(this.canvas));
     }
     // imposta posizione camera
     setCameraPosition(pos) {
@@ -538,17 +732,18 @@ class AstroSphere {
             centralPoint: new Point({ raDeg: centralradeg, decDeg: centraldecdeg }, CoordsType.ASTRO),
             mouseHoverPoint: this.mousePointCoords,
             colorMap: this._selectedColorMap,
-            getFoVPolygon: this.getFoVPolygon(),
+            getFoVPolygon: [],
         };
         return detail;
         // }
         // return null
     }
     changeColorMap(cm) {
-        if (!this._activeHiPS)
+        if (!this._activeHiPS && !this._activeXYZ2)
             return;
         this._selectedColorMap = cm;
         this._activeHiPS?.changeColorMap(cm);
+        this._activeXYZ2?.changeColorMap(cm);
     }
     prevFov = 0;
     prevCentralRaDeg = null;
@@ -557,21 +752,54 @@ class AstroSphere {
         return this._activeHiPS;
     }
     get activeXYZ() {
-        return this._activeXYZ;
+        return this._activeXYZ2;
+    }
+    isLonLatGridVisible() {
+        return this._activeXYZ2?.isLonLatGridVisible() ?? false;
+    }
+    toggleLonLatGrid() {
+        return this._activeXYZ2?.toggleLonLatGrid() ?? false;
+    }
+    setEastWestRotationLocked(locked) {
+        this._camera.setRotationLock({ y: locked });
+        if (locked)
+            this.inertiaX = 0;
+        this.lockedEastWestRaDeg = locked
+            ? (this.updateCentralPoint()?.astroDeg.ra ?? null)
+            : null;
+    }
+    isEastWestRotationLocked() {
+        return this._camera.isRotationLockedY();
+    }
+    setNorthSouthRotationLocked(locked) {
+        this._camera.setRotationLock({ x: locked });
+        if (locked)
+            this.inertiaY = 0;
+        this.lockedNorthSouthDecDeg = locked
+            ? (this.updateCentralPoint()?.astroDeg.dec ?? null)
+            : null;
+    }
+    isNorthSouthRotationLocked() {
+        return this._camera.isRotationLockedX();
     }
     getXYZDebugStats() {
         return {
             activeBaseLayer: this._activeBaseLayer,
-            layer: this._activeXYZ?.getDebugStats() ?? null,
+            layer: this._activeXYZ2?.getDebugStats() ?? null,
             requests: xyzTileRequestScheduler.getDebugStats(),
         };
     }
+    getHiPSDebugStats() {
+        if (!this._activeHiPS)
+            return null;
+        return this._activeHiPS.getDebugStats();
+    }
     draw(canvas) {
         if (this._refreshingStatus)
             return;
         if (!this._webgl)
             return;
-        if (!this._activeHiPS && !this._activeXYZ)
+        if (!this._activeHiPS && !this._activeXYZ2)
             return;
         if (!this._healpixGrid || Object.keys(this._healpixGrid).length === 0)
             return;
@@ -591,6 +819,7 @@ class AstroSphere {
             if (Math.abs(this.zoomInertia) > 0.0001) {
                 this._camera.zoom(this.zoomInertia);
                 this.zoomInertia *= 0.95;
+                this.lastCameraMotionAt = performance.now();
                 this.fov = this._healpixGrid.refreshFoV(this._camera, this._perspectiveMatrixManager.pMatrix);
                 this._camera.refreshFoV(this.fov.minFoV);
                 if (this.prevFov !== this.fov.minFoV) {
@@ -606,19 +835,33 @@ class AstroSphere {
             this._cameraStatusChanged = true;
         }
         // Rotation inertia
-        if (this.mouseDown || Math.abs(this.inertiaX) > 0.02 || Math.abs(this.inertiaY) > 0.02) {
+        if (this.mouseDown ||
+            Math.abs(this.inertiaX) > 0.02 ||
+            Math.abs(this.inertiaY) > 0.02) {
             cameraRotated = true;
-            THETA = this.inertiaY;
-            PHI = this.inertiaX;
-            this.inertiaX *= 0.95;
-            this.inertiaY *= 0.95;
+            const filteredInertia = this.filterRotationDeltaByAstroLocks(this.inertiaX, this.inertiaY);
+            PHI = filteredInertia.deltaX;
+            THETA = filteredInertia.deltaY;
+            this.inertiaX = filteredInertia.deltaX * 0.95;
+            this.inertiaY = filteredInertia.deltaY * 0.95;
             this._camera.rotate(PHI, THETA);
+            this.lastCameraMotionAt = performance.now();
             this._perspectiveMatrixManager.computePerspectiveMatrix(canvas, this._camera, bootSetup.camera_fov_deg, bootSetup.camera_near_plane, global.insideSphere);
+            const lockCorrected = this.enforceAstronomicalRotationLocks();
+            if (!lockCorrected) {
+                this.enforceCameraNorthUp();
+            }
         }
         else {
             this.inertiaY = 0;
             this.inertiaX = 0;
         }
+        const nextFoV = this._healpixGrid.refreshFoV(this._camera, this._perspectiveMatrixManager.pMatrix);
+        if (Number.isFinite(nextFoV.minFoV) && nextFoV.minFoV > 0) {
+            this.fov = nextFoV;
+            this._camera.refreshFoV(this.fov.minFoV);
+            this.prevFov = this.fov.minFoV;
+        }
         // Se la camera è ruotata (anche solo per inerzia), aggiorna punto centrale + emetti cameraChanged
         if (cameraRotated) {
             // Ricalcola il punto centrale
@@ -636,16 +879,20 @@ class AstroSphere {
             }
         }
         if (this._cameraStatusChanged) {
-            const detail = this.getCurrentStatus();
+            const now = performance.now();
+            const shouldEmitCameraChanged = !this.mouseDown || now - this.lastCameraChangedAt > 100;
+            const detail = shouldEmitCameraChanged ? this.getCurrentStatus() : null;
             if (detail) {
                 // console.log('[AstroSphere::draw] emitting camera-changed event due to camera status change', detail)
                 // console.log('[AstroSphere::draw] inertia', this.zoomInertia, this.inertiaX, this.inertiaY)
-                this.canvas.dispatchEvent(new CustomEvent('camera-changed', {
+                this.canvas.dispatchEvent(new CustomEvent("camera-changed", {
                     detail,
-                    bubbles: true, composed: true,
+                    bubbles: true,
+                    composed: true,
                 }));
+                this.lastCameraChangedAt = now;
             }
-            if (!this.startup) {
+            if (!this.startup && shouldEmitCameraChanged) {
                 this._cameraStatusChanged = false;
             }
         }
@@ -655,24 +902,40 @@ class AstroSphere {
         this._webgl.enable(this._webgl.CULL_FACE);
         this._webgl.cullFace(global.insideSphere ? this._webgl.FRONT : this._webgl.BACK);
         this._webgl.blendFunc(this._webgl.SRC_ALPHA, this._webgl.ONE_MINUS_SRC_ALPHA);
-        if (this._activeBaseLayer === 'hips' && this._activeHiPS) {
+        if (this._activeBaseLayer === "hips" && this._activeHiPS) {
             const visibleOrder = Math.min(this._healpixGrid.visibleorder, this._activeHiPS.maxOrder);
             this._healpixGrid.visibleTilesManager.computeVisiblePixels(visibleOrder, this._webgl, this._camera, this._perspectiveMatrixManager.pMatrix);
         }
         // DRAW HiPS
+        const stableFovDeg = this.fov?.minFoV ?? this._healpixGrid.getMinFoV();
+        const nowForGrid = performance.now();
+        const cameraMovingForGrid = this.mouseDown ||
+            Math.abs(this.zoomInertia) > 0.0001 ||
+            Math.abs(this.inertiaX) > 0.02 ||
+            Math.abs(this.inertiaY) > 0.02 ||
+            nowForGrid - this.lastCameraMotionAt < 220;
+        // const skyEntityDrawInput: SkyEntityDrawInput = {
+        // fovDeg: this._healpixGrid.getMinFoV(),
+        //   camera: this._camera,
+        //   pMatrix: this._perspectiveMatrixManager.pMatrix,
+        //   centerSphericalDeg: this.updateCentralPoint().sphericalDeg,
+        //   fovPolygon: this._activeBaseLayer === 'xyz' ? this.getFoVPolygon() : undefined,
+        //   viewportSphericalSamples: this._activeBaseLayer === 'xyz' ? this.collectViewportSphericalSamples(7) : undefined,
+        // }
         const skyEntityDrawInput = {
-            fovDeg: this._healpixGrid.getMinFoV(),
+            fovDeg: stableFovDeg,
             camera: this._camera,
             pMatrix: this._perspectiveMatrixManager.pMatrix,
             centerSphericalDeg: this.updateCentralPoint().sphericalDeg,
-            fovPolygon: this._activeBaseLayer === 'xyz' ? this.getFoVPolygon() : undefined,
-            viewportSphericalSamples: this._activeBaseLayer === 'xyz' ? this.collectViewportSphericalSamples(7) : undefined,
+            fovPolygon: undefined,
+            viewportSphericalSamples: undefined,
+            cameraMoving: cameraMovingForGrid,
         };
-        if (this._activeBaseLayer === 'hips') {
+        if (this._activeBaseLayer === "hips") {
             this._activeHiPS?.draw(skyEntityDrawInput);
         }
-        if (this._activeBaseLayer === 'xyz') {
-            this._activeXYZ?.draw(skyEntityDrawInput);
+        if (this._activeBaseLayer === "xyz") {
+            this._activeXYZ2?.draw(skyEntityDrawInput);
         }
         this._healpixGrid.draw(skyEntityDrawInput);
         this._equatorialGrid.draw(skyEntityDrawInput);
@@ -684,24 +947,27 @@ class AstroSphere {
             const raDecDeg = sphericalToAstroDeg(phiTheta.phi, phiTheta.theta);
             const raHMS = raDegToHMS(raDecDeg.ra);
             const decDMS = decDegToDMS(raDecDeg.dec);
-            this.prevFov = this._healpixGrid.getMinFoV();
+            // this.prevFov = this._healpixGrid.getMinFoV();
+            this.prevFov = this.fov?.minFoV ?? this._healpixGrid.getMinFoV();
             this._cameraStatusChanged = true;
-            console.log('(startup coords)', {
+            console.log("(startup coords)", {
                 raDeg: raDecDeg.ra,
                 decDeg: raDecDeg.dec,
                 raHMS,
                 decDMS,
             });
         }
-        this.activeCatalogues.forEach(cat => {
-            const activeModelMatrix = this._activeHiPS?.getModelMatrix() ?? this._activeXYZ?.getModelMatrix();
+        this.activeCatalogues.forEach((cat) => {
+            const activeModelMatrix = this._activeHiPS?.getModelMatrix() ??
+                this._activeXYZ2?.getModelMatrix();
             if (activeModelMatrix) {
                 cat.draw(activeModelMatrix, this.mouseHelper, this._camera.getCameraMatrix(), this._perspectiveMatrixManager.pMatrix);
             }
         });
         this.emitHoveredSourceIfChanged();
-        this.activeFootprintSets.forEach(fst => {
-            const activeModelMatrix = this._activeHiPS?.getModelMatrix() ?? this._activeXYZ?.getModelMatrix();
+        this.activeFootprintSets.forEach((fst) => {
+            const activeModelMatrix = this._activeHiPS?.getModelMatrix() ??
+                this._activeXYZ2?.getModelMatrix();
             if (activeModelMatrix) {
                 fst.draw(activeModelMatrix, this.mouseHelper, this._camera.getCameraMatrix(), this._perspectiveMatrixManager.pMatrix);
             }
@@ -718,13 +984,13 @@ class AstroSphere {
             nextHoveredCatalogue = cat;
             break;
         }
-        const unchanged = nextHoveredSource === this.lastHoveredSource
-            && nextHoveredCatalogue === this.lastHoveredCatalogue;
+        const unchanged = nextHoveredSource === this.lastHoveredSource &&
+            nextHoveredCatalogue === this.lastHoveredCatalogue;
         if (unchanged)
             return;
         this.lastHoveredSource = nextHoveredSource;
         this.lastHoveredCatalogue = nextHoveredCatalogue;
-        this._webgl.canvas.dispatchEvent(new CustomEvent('source-hovered', {
+        this._webgl.canvas.dispatchEvent(new CustomEvent("source-hovered", {
             detail: { source: nextHoveredSource, catalogue: nextHoveredCatalogue },
             bubbles: true,
             composed: true,