astro-viewer 3.10.0 → 3.11.0

package/README.md

@@ -21,8 +21,12 @@ AstroViewer is developed from scratch without depending on visualization framewo
 - HiPS coverage handling
 - HEALPix hierarchical sky tessellation
 - FITS astronomical data support
+- FITS display scaling (linear, sqrt, log, asinh, gamma)
+- FITS display range modes
+- Runtime color maps
 - Astronomical coordinate systems and transformations
 - Field-of-view calculations
+- Interactive navigation and animated Fly To
 - Grid and coordinate visualization
 - TAP-based astronomical data access
 
@@ -34,6 +38,7 @@ AstroViewer is developed from scratch without depending on visualization framewo
 - GeoJSON geometries and overlays
 - Satellite tracks and observation geometry
 - Sensor footprints and cones
+- Longitude/latitude navigation and animated Fly To
 - Earth-oriented coordinate and picking utilities
 
 ### 3D and Scientific Visualization
@@ -42,7 +47,7 @@ AstroViewer is developed from scratch without depending on visualization framewo
 - Inside/outside sphere visualization
 - MeshHiPS OBJ tiled meshes
 - Runtime color maps
-- Interactive camera and navigation
+- Interactive camera, navigation and animated Fly To
 - Ray picking
 - Scientific overlays and geometries
 - Framework-independent architecture
@@ -100,6 +105,7 @@ A HiPS survey can be activated using a `HiPSDescriptor`:
 import { AstroViewer, HiPSDescriptor } from "astro-viewer";
 
 const canvas = document.getElementById("astrocanvas");
+
 const viewer = new AstroViewer(canvas);
 
 const hipsUrl = "https://alasky.cds.unistra.fr/DSS/DSSColor/";
@@ -189,6 +195,26 @@ AstroViewer supports conventional image-based HiPS tiles and FITS HiPS tiles.
 
 ---
 
+## FITS HiPS Visualization
+
+AstroViewer can render FITS tiles directly as part of the HiPS rendering pipeline.
+
+FITS visualization supports multiple display scaling functions:
+
+```text
+linear
+sqrt
+log
+asinh
+gamma
+```
+
+The display range and scaling parameters can be changed at runtime, allowing scientific image data with different dynamic ranges to be explored interactively.
+
+Color maps can also be applied at runtime to FITS-based HiPS data.
+
+---
+
 ## HiPS Coverage
 
 AstroViewer supports survey coverage information associated with HiPS datasets.
@@ -199,6 +225,38 @@ This is particularly useful for partial-sky surveys.
 
 ---
 
+## Navigation and Fly To
+
+AstroViewer provides immediate and animated camera navigation.
+
+The viewer can move directly to a target coordinate:
+
+```js
+viewer.goTo(firstDeg, secondDeg);
+```
+
+or smoothly animate the camera towards the target:
+
+```js
+viewer.flyTo(firstDeg, secondDeg);
+```
+
+An optional duration can be specified in milliseconds:
+
+```js
+viewer.flyTo(firstDeg, secondDeg, 1500);
+```
+
+The coordinate semantics depend on the active visualization domain:
+
+- Astronomy uses right ascension and declination.
+- Earth visualization uses longitude and latitude.
+- Planetary and MeshHiPS visualization uses longitude and latitude.
+
+Fly To uses spherical interpolation and integrates with the viewer rendering loop. User interaction interrupts an active Fly To operation, allowing normal interactive navigation to resume immediately.
+
+---
+
 ## Earth Maps
 
 AstroViewer also supports tiled Earth observation maps.
@@ -265,17 +323,21 @@ addHiPS(...)
 addHiPSFromUrl(...)
 removeHiPS(...)
 removeAllHiPS()
-
 getActiveHiPS()
 getActiveHiPSLayers()
 setActiveHiPS(...)
-
 getActiveHiPSFormats()
 changeHiPSFormat(...)
-
 setHiPSOpacity(...)
 ```
 
+### Navigation
+
+```ts
+goTo(...)
+flyTo(...)
+```
+
 ### Maps and visualization
 
 AstroViewer also exposes functionality around:

package/dist/astroviewer.cjs

@@ -43,6 +43,7 @@ __webpack_require__.d(vec3_namespaceObject, {
   dot: () => (dot),
   fromValues: () => (vec3_fromValues),
   length: () => (vec3_length),
+  lerp: () => (lerp),
   normalize: () => (normalize),
   scale: () => (vec3_scale),
   scaleAndAdd: () => (scaleAndAdd),
@@ -3895,6 +3896,7 @@ class AstroSphere {
         const handleMouseDown = (event) => {
             canvas.setPointerCapture(event.pointerId);
             this.mouseDown = true;
+            this._camera.cancelFlyTo();
             const rect = canvas.getBoundingClientRect();
             this.lastMouseX = event.clientX - rect.left; // locale al canvas
             this.lastMouseY = event.clientY - rect.top; // locale al canvas
@@ -4021,6 +4023,7 @@ class AstroSphere {
         const handleMouseWheel = (event) => {
             const currentFov = this._healpixGrid.getMinFoV();
             const zoomStep = this.computeZoomStep(currentFov, event.deltaY);
+            this._camera.cancelFlyTo();
             // Apply wheel zoom immediately and discard any queued inertia so reversing
             // direction feels responsive instead of "buffered".
             this.zoomInertia = 0;
@@ -4286,6 +4289,9 @@ class AstroSphere {
     goTo(raDeg, decDeg) {
         this._camera.goTo(raDeg, decDeg);
     }
+    flyTo(raDeg, decDeg, durationMs = 1200) {
+        this._camera.flyTo(raDeg, decDeg, durationMs);
+    }
     getActiveCoordinateMode() {
         if (this._activeBaseLayer === "xyz") {
             return "lonlat";
@@ -4521,6 +4527,16 @@ class AstroSphere {
         let PHI = 0;
         this._webgl.viewport(0, 0, this._webgl.drawingBufferWidth, this._webgl.drawingBufferHeight);
         this._webgl.clear(this._webgl.COLOR_BUFFER_BIT | this._webgl.DEPTH_BUFFER_BIT);
+        const now = performance.now();
+        const cameraFlying = this._camera.updateFlyTo(now);
+        if (cameraFlying) {
+            this.inertiaX = 0;
+            this.inertiaY = 0;
+            this.lastCameraMotionAt = now;
+            this._cameraStatusChanged = true;
+            this.updateCentralPoint();
+            this._perspectiveMatrixManager.computePerspectiveMatrix(canvas, this._camera, Config_js_1.bootSetup.camera_fov_deg, Config_js_1.bootSetup.camera_near_plane, Global_js_1.default.insideSphere);
+        }
         // Zoom inertia
         if (this.zoomInertia !== 0) {
             if (Math.abs(this.zoomInertia) > 0.0001) {
@@ -5051,6 +5067,9 @@ class AstroViewer {
         // console.log(`AstroViewer.goTo goto(${raDeg}, ${decDeg})`)
         this.astroSphere.goTo(raDeg, decDeg);
     }
+    flyTo(raDeg, decDeg, durationMs = 1200) {
+        this.astroSphere.flyTo(raDeg, decDeg, durationMs);
+    }
     getActiveCoordinateMode() {
         return this.astroSphere.getActiveCoordinateMode();
     }
@@ -5372,6 +5391,7 @@ class Camera {
     lockRotX = false;
     lockRotY = false;
     lockRotZ = false;
+    flyToAnimation = null;
     constructor(in_position, in_sphere) {
         this.init(in_position, in_sphere);
     }
@@ -5381,7 +5401,11 @@ class Camera {
         this.vMatrix = gl_matrix_1.mat4.create();
         this.T = gl_matrix_1.mat4.create();
         this.R = gl_matrix_1.mat4.create();
-        gl_matrix_1.mat4.translate(this.T, this.T, [this.cam_pos[0], this.cam_pos[1], this.cam_pos[2]]);
+        gl_matrix_1.mat4.translate(this.T, this.T, [
+            this.cam_pos[0],
+            this.cam_pos[1],
+            this.cam_pos[2],
+        ]);
         // reset helpers
         this.FoV = this.previousFoV = 180.0;
         this.move = gl_matrix_1.vec3.clone([0, 0, 0]);
@@ -5390,11 +5414,15 @@ class Camera {
         this.goTo(raDeg, decDeg);
     }
     goTo(raDeg, decDeg) {
+        this.cancelFlyTo();
         this.goToPhiTheta((0, Utils_js_1.astroDegToSpherical)(raDeg, decDeg));
     }
     goToPhiTheta(ptDeg) {
         const xyz = (0, Utils_js_1.sphericalToCartesian)(ptDeg.phi, ptDeg.theta, this.cam_pos[2]);
-        const targetDirection = gl_matrix_1.vec3.normalize(gl_matrix_1.vec3.create(), gl_matrix_1.vec3.fromValues(xyz[0], xyz[1], xyz[2]));
+        this.applyCameraPosition(gl_matrix_1.vec3.fromValues(xyz[0], xyz[1], xyz[2]));
+    }
+    applyCameraPosition(cameraPosition) {
+        const targetDirection = gl_matrix_1.vec3.normalize(gl_matrix_1.vec3.create(), cameraPosition);
         const celestialNorth = gl_matrix_1.vec3.fromValues(0.0, 0.0, 1.0);
         const northProjection = gl_matrix_1.vec3.scale(gl_matrix_1.vec3.create(), targetDirection, gl_matrix_1.vec3.dot(celestialNorth, targetDirection));
         const cameraUp = gl_matrix_1.vec3.subtract(gl_matrix_1.vec3.create(), celestialNorth, northProjection);
@@ -5405,9 +5433,13 @@ class Camera {
             gl_matrix_1.vec3.normalize(cameraUp, cameraUp);
         }
         let cameraMatrix = gl_matrix_1.mat4.create();
-        cameraMatrix = gl_matrix_1.mat4.translate(cameraMatrix, cameraMatrix, gl_matrix_1.vec3.fromValues(xyz[0], xyz[1], xyz[2]));
+        cameraMatrix = gl_matrix_1.mat4.translate(cameraMatrix, cameraMatrix, cameraPosition);
         const focusPoint = [0.0, 0.0, 0.0];
-        const cameraPos = [cameraMatrix[12], cameraMatrix[13], cameraMatrix[14]];
+        const cameraPos = [
+            cameraMatrix[12],
+            cameraMatrix[13],
+            cameraMatrix[14],
+        ];
         cameraMatrix = gl_matrix_1.mat4.targetTo(cameraMatrix, cameraPos, focusPoint, cameraUp);
         this.R = gl_matrix_1.mat4.clone(cameraMatrix);
         this.R[12] = 0;
@@ -5419,6 +5451,81 @@ class Camera {
         }
         this.vMatrix = viewMatrix;
     }
+    flyTo(raDeg, decDeg, durationMs = 1200) {
+        const targetSpherical = (0, Utils_js_1.astroDegToSpherical)(raDeg, decDeg);
+        const targetPositionValues = (0, Utils_js_1.sphericalToCartesian)(targetSpherical.phi, targetSpherical.theta, this.cam_pos[2]);
+        const targetPosition = gl_matrix_1.vec3.fromValues(targetPositionValues[0], targetPositionValues[1], targetPositionValues[2]);
+        const currentPosition = this.getCameraPosition();
+        const startDirection = gl_matrix_1.vec3.normalize(gl_matrix_1.vec3.create(), gl_matrix_1.vec3.fromValues(currentPosition[0], currentPosition[1], currentPosition[2]));
+        const targetDirection = gl_matrix_1.vec3.normalize(gl_matrix_1.vec3.create(), targetPosition);
+        this.flyToAnimation = {
+            startDirection,
+            targetDirection,
+            targetPosition,
+            startTime: performance.now(),
+            durationMs: Math.max(1, durationMs),
+        };
+    }
+    updateFlyTo(now) {
+        const animation = this.flyToAnimation;
+        if (!animation) {
+            return false;
+        }
+        const elapsed = now - animation.startTime;
+        const progress = Math.min(1, elapsed / animation.durationMs);
+        const easedProgress = progress < 0.5
+            ? 4 * progress * progress * progress
+            : 1 - Math.pow(-2 * progress + 2, 3) / 2;
+        const direction = this.slerpDirection(animation.startDirection, animation.targetDirection, easedProgress);
+        const radius = Math.abs(this.cam_pos[2]);
+        const cameraPosition = gl_matrix_1.vec3.scale(gl_matrix_1.vec3.create(), direction, radius);
+        this.applyCameraPosition(cameraPosition);
+        if (progress >= 1) {
+            this.applyCameraPosition(animation.targetPosition);
+            this.flyToAnimation = null;
+        }
+        return true;
+    }
+    slerpDirection(start, end, t) {
+        const dot = Math.max(-1, Math.min(1, gl_matrix_1.vec3.dot(start, end)));
+        /*
+         * For almost identical directions, normalized linear interpolation is
+         * numerically more stable than the general SLERP formula.
+         */
+        if (dot > 0.999999) {
+            const result = gl_matrix_1.vec3.lerp(gl_matrix_1.vec3.create(), start, end, t);
+            return gl_matrix_1.vec3.normalize(result, result);
+        }
+        /*
+         * The normal SLERP formula becomes singular for antipodal vectors because
+         * sin(pi) = 0. In that case choose a stable vector orthogonal to start and
+         * rotate through that great circle.
+         */
+        if (dot < -0.999999) {
+            const referenceAxis = Math.abs(start[0]) < 0.9
+                ? gl_matrix_1.vec3.fromValues(1, 0, 0)
+                : gl_matrix_1.vec3.fromValues(0, 1, 0);
+            const orthogonal = gl_matrix_1.vec3.cross(gl_matrix_1.vec3.create(), start, referenceAxis);
+            gl_matrix_1.vec3.normalize(orthogonal, orthogonal);
+            const angle = Math.PI * t;
+            const result = gl_matrix_1.vec3.create();
+            gl_matrix_1.vec3.scale(result, start, Math.cos(angle));
+            gl_matrix_1.vec3.scaleAndAdd(result, result, orthogonal, Math.sin(angle));
+            return gl_matrix_1.vec3.normalize(result, result);
+        }
+        const angle = Math.acos(dot);
+        const sinAngle = Math.sin(angle);
+        const startWeight = Math.sin((1 - t) * angle) / sinAngle;
+        const endWeight = Math.sin(t * angle) / sinAngle;
+        const result = gl_matrix_1.vec3.create();
+        result[0] = start[0] * startWeight + end[0] * endWeight;
+        result[1] = start[1] * startWeight + end[1] * endWeight;
+        result[2] = start[2] * startWeight + end[2] * endWeight;
+        return gl_matrix_1.vec3.normalize(result, result);
+    }
+    cancelFlyTo() {
+        this.flyToAnimation = null;
+    }
     toggleInsideSphere() {
         // if (inside !== global.insideSphere) {
         //   global.insideSphere = inside;
@@ -5676,9 +5783,15 @@ class Camera {
     clearRotationLock() {
         this.lockRotX = this.lockRotY = this.lockRotZ = false;
     }
-    isRotationLockedX() { return this.lockRotX; }
-    isRotationLockedY() { return this.lockRotY; }
-    isRotationLockedZ() { return this.lockRotZ; }
+    isRotationLockedX() {
+        return this.lockRotX;
+    }
+    isRotationLockedY() {
+        return this.lockRotY;
+    }
+    isRotationLockedZ() {
+        return this.lockRotZ;
+    }
 }
 exports["default"] = Camera;
 
@@ -7880,6 +7993,7 @@ class Source {
     _h_pix;
     _shapesize;
     _brightnessFactor;
+    _mediaStyle;
     /**
      * @param in_point Point.js (Cartesian/RA-Dec wrapper)
      * @param in_details Optional array of key/value metadata
@@ -7932,6 +8046,12 @@ class Source {
     set brightnessFactor(factor) {
         this._brightnessFactor = factor;
     }
+    get mediaStyle() {
+        return this._mediaStyle;
+    }
+    set mediaStyle(style) {
+        this._mediaStyle = style;
+    }
 }
 exports.Source = Source;
 
@@ -8157,6 +8277,9 @@ exports.SphereFoV = SphereFoV;
  *
  * See LICENSE.md, LICENSE-AGPL.md, and LICENSE-COMMERCIAL.md for details.
  */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", ({ value: true }));
 exports.CatalogueGL = void 0;
 const Source_js_1 = __webpack_require__(146);
@@ -8165,6 +8288,8 @@ const CoordsType_js_1 = __webpack_require__(8145);
 const Utils_js_1 = __webpack_require__(7930);
 const CatalogueShaderProgram_js_1 = __webpack_require__(3559);
 const MetadataManager_js_1 = __webpack_require__(5403);
+const gl_matrix_1 = __webpack_require__(3890);
+const Global_js_1 = __importDefault(__webpack_require__(4382));
 class CatalogueGL {
     _kind = "CatalogueGL";
     static ELEM_SIZE = 6;
@@ -8196,6 +8321,9 @@ class CatalogueGL {
     _providerUrl;
     _catalogueShaderProgram;
     _visibleTilesManager;
+    _mediaOverlayHost = null;
+    _mediaElements = [];
+    _svgMediaDataUrls = new Map();
     constructor(catalogueName, catalogueDescription, providerUrl, metadataManager, webgl, visibleTilesManager) {
         this._webgl = webgl;
         this._ready = false;
@@ -8366,9 +8494,10 @@ class CatalogueGL {
      * @param in_data Rows of TAP results
      * @param columnsmeta TapMetadataList (unused here because `CatalogueProps` already holds indices)
      */
-    addSources(in_data, columnsmeta) {
+    addSources(in_data, columnsmeta, options = {}) {
         this._ready = false;
         this._sources = [];
+        this.clearMediaOverlay();
         this._metadataManager = new MetadataManager_js_1.MetadataManager(columnsmeta);
         // const raDataIndex = (this.catalogueProps.raColumn as any).index ?? (this.catalogueProps.raColumn as any)._index;
         // const decDataIndex = (this.catalogueProps.decColumn as any).index ?? (this.catalogueProps.decColumn as any)._index;
@@ -8382,6 +8511,10 @@ class CatalogueGL {
                 decDeg: in_data[j][decDataIndex],
             }, CoordsType_js_1.CoordsType.ASTRO);
             const source = new Source_js_1.Source(point, in_data[j]);
+            const mediaStyle = this.extractMediaStyle(in_data[j], columnsmeta, options.mediaColumns);
+            if (mediaStyle) {
+                source.mediaStyle = mediaStyle;
+            }
             // Ensure optional fields exist
             source.shapeSize = source.shapeSize ?? CatalogueGL.STANDARD_SHAPE_SIZE;
             source.brightnessFactor = 3;
@@ -8401,11 +8534,222 @@ class CatalogueGL {
         this._ready = true;
         this._bufferInitialised = false;
     }
+    getColumnIndex(columnsmeta, columnName) {
+        if (!columnName)
+            return -1;
+        return columnsmeta.find((column) => column.name === columnName)?.index ?? -1;
+    }
+    readCell(row, columnsmeta, columnName) {
+        const idx = this.getColumnIndex(columnsmeta, columnName);
+        return idx >= 0 ? row[idx] : undefined;
+    }
+    extractMediaStyle(row, columnsmeta, mediaColumns) {
+        if (!mediaColumns?.src)
+            return undefined;
+        const rawSrc = this.readCell(row, columnsmeta, mediaColumns.src);
+        const src = String(rawSrc ?? "").trim();
+        if (!src)
+            return undefined;
+        const rawKind = String(this.readCell(row, columnsmeta, mediaColumns.type) ?? "sprite").trim().toLowerCase();
+        const kind = rawKind === "model"
+            ? "model"
+            : rawKind === "image"
+                ? "image"
+                : rawKind === "icon"
+                    ? "icon"
+                    : rawKind === "circle"
+                        ? "circle"
+                        : "sprite";
+        if (kind === "circle" || kind === "model")
+            return undefined;
+        const scale = Number(this.readCell(row, columnsmeta, mediaColumns.scale));
+        const rotationDeg = Number(this.readCell(row, columnsmeta, mediaColumns.rotation));
+        const opacity = Number(this.readCell(row, columnsmeta, mediaColumns.opacity));
+        return {
+            kind,
+            src,
+            scale: Number.isFinite(scale) && scale > 0 ? scale : undefined,
+            rotationDeg: Number.isFinite(rotationDeg) ? rotationDeg : undefined,
+            opacity: Number.isFinite(opacity) ? Math.max(0, Math.min(1, opacity)) : undefined,
+        };
+    }
     clearSources() {
         this._sources = [];
         this.hoveredIndexes = [];
         this._healpixDensityMap.clear();
         this.vertexCataloguePosition = new Float32Array(0);
+        this.clearMediaOverlay();
+    }
+    clearMediaOverlay() {
+        this._mediaElements.forEach((el) => el.remove());
+        this._mediaElements = [];
+        if (this._mediaOverlayHost) {
+            this._mediaOverlayHost.remove();
+            this._mediaOverlayHost = null;
+        }
+    }
+    ensureMediaOverlayHost() {
+        const canvas = this._webgl?.canvas;
+        const parent = canvas?.parentElement;
+        if (!canvas || !parent)
+            return null;
+        const parentStyle = window.getComputedStyle(parent);
+        if (parentStyle.position === "static") {
+            parent.style.position = "relative";
+        }
+        if (!this._mediaOverlayHost) {
+            const host = document.createElement("div");
+            host.dataset.astroCatalogueMedia = "true";
+            host.style.position = "absolute";
+            host.style.left = `${canvas.offsetLeft}px`;
+            host.style.top = `${canvas.offsetTop}px`;
+            host.style.width = `${canvas.clientWidth}px`;
+            host.style.height = `${canvas.clientHeight}px`;
+            host.style.pointerEvents = "none";
+            host.style.overflow = "hidden";
+            host.style.zIndex = "4";
+            canvas.style.position = canvas.style.position || "relative";
+            canvas.style.zIndex = canvas.style.zIndex || "0";
+            parent.appendChild(host);
+            this._mediaOverlayHost = host;
+        }
+        else {
+            this._mediaOverlayHost.style.left = `${canvas.offsetLeft}px`;
+            this._mediaOverlayHost.style.top = `${canvas.offsetTop}px`;
+            this._mediaOverlayHost.style.width = `${canvas.clientWidth}px`;
+            this._mediaOverlayHost.style.height = `${canvas.clientHeight}px`;
+        }
+        return this._mediaOverlayHost;
+    }
+    ensureMediaElement(index, style) {
+        let img = this._mediaElements[index];
+        if (!img) {
+            img = document.createElement("img");
+            img.loading = "lazy";
+            img.decoding = "async";
+            img.style.position = "absolute";
+            img.style.objectFit = "contain";
+            img.style.pointerEvents = "none";
+            img.style.transformOrigin = "center center";
+            img.style.filter = "drop-shadow(0 1px 2px rgba(0, 0, 0, 0.55))";
+            img.style.willChange = "transform, left, top";
+            this._mediaElements[index] = img;
+        }
+        const src = String(style.src ?? "").trim();
+        const resolvedSrc = src ? new URL(src, document.baseURI).href : "";
+        if (resolvedSrc && img.getAttribute("src") !== resolvedSrc) {
+            img.removeAttribute("data-astro-media-src-index");
+            img.removeAttribute("data-astro-media-loaded");
+            img.onerror = null;
+            img.onload = null;
+            img.setAttribute("src", resolvedSrc);
+            if (/\.svg(?:[?#].*)?$/i.test(resolvedSrc)) {
+                void this.loadSvgMediaAsDataUrl(img, resolvedSrc);
+            }
+        }
+        return img;
+    }
+    async loadSvgMediaAsDataUrl(img, resolvedSrc) {
+        try {
+            let dataUrl = this._svgMediaDataUrls.get(resolvedSrc);
+            if (!dataUrl) {
+                const response = await fetch(resolvedSrc);
+                if (!response.ok)
+                    return;
+                const svg = await response.text();
+                if (!/^\s*<svg[\s>]/i.test(svg))
+                    return;
+                dataUrl = `data:image/svg+xml;charset=utf-8,${encodeURIComponent(svg)}`;
+                this._svgMediaDataUrls.set(resolvedSrc, dataUrl);
+            }
+            if (img.getAttribute("src") === resolvedSrc) {
+                img.setAttribute("src", dataUrl);
+            }
+        }
+        catch {
+            // Keep the direct image src; remote servers may already provide a valid MIME type.
+        }
+    }
+    isSourceOnVisibleHemisphere(source, in_mMatrix, vMatrix) {
+        if (Global_js_1.default.insideSphere)
+            return true;
+        const invView = gl_matrix_1.mat4.create();
+        if (!gl_matrix_1.mat4.invert(invView, vMatrix))
+            return true;
+        const cameraPos = gl_matrix_1.vec3.fromValues(invView[12], invView[13], invView[14]);
+        const worldPoint4 = gl_matrix_1.vec4.fromValues(source.point.x, source.point.y, source.point.z, 1);
+        gl_matrix_1.vec4.transformMat4(worldPoint4, worldPoint4, in_mMatrix);
+        const worldPoint = gl_matrix_1.vec3.fromValues(worldPoint4[0], worldPoint4[1], worldPoint4[2]);
+        const normal = gl_matrix_1.vec3.normalize(gl_matrix_1.vec3.create(), worldPoint);
+        const toCamera = gl_matrix_1.vec3.subtract(gl_matrix_1.vec3.create(), cameraPos, worldPoint);
+        return gl_matrix_1.vec3.dot(normal, toCamera) > 0;
+    }
+    updateMediaOverlay(in_mMatrix, vMatrix, pMatrix) {
+        const sourcesWithMedia = this._sources.filter((source) => !!source.mediaStyle?.src);
+        if (!sourcesWithMedia.length) {
+            this.clearMediaOverlay();
+            return;
+        }
+        const host = this.ensureMediaOverlayHost();
+        const canvas = this._webgl.canvas;
+        if (!host || !canvas.clientWidth || !canvas.clientHeight)
+            return;
+        const modelView = gl_matrix_1.mat4.create();
+        const mvp = gl_matrix_1.mat4.create();
+        gl_matrix_1.mat4.multiply(modelView, vMatrix, in_mMatrix);
+        gl_matrix_1.mat4.multiply(mvp, pMatrix, modelView);
+        const width = canvas.clientWidth;
+        const height = canvas.clientHeight;
+        for (let i = 0; i < this._sources.length; i++) {
+            const source = this._sources[i];
+            const style = source.mediaStyle;
+            const img = this._mediaElements[i];
+            if (!style?.src) {
+                if (img)
+                    img.style.display = "none";
+                continue;
+            }
+            if (!this.isSourceOnVisibleHemisphere(source, in_mMatrix, vMatrix)) {
+                if (img)
+                    img.style.display = "none";
+                continue;
+            }
+            const projected = gl_matrix_1.vec4.fromValues(source.point.x, source.point.y, source.point.z, 1);
+            gl_matrix_1.vec4.transformMat4(projected, projected, mvp);
+            if (!projected[3]) {
+                if (img)
+                    img.style.display = "none";
+                continue;
+            }
+            const ndcX = projected[0] / projected[3];
+            const ndcY = projected[1] / projected[3];
+            const ndcZ = projected[2] / projected[3];
+            if (ndcX < -1.15 ||
+                ndcX > 1.15 ||
+                ndcY < -1.15 ||
+                ndcY > 1.15 ||
+                ndcZ < -1.15 ||
+                ndcZ > 1.15) {
+                if (img)
+                    img.style.display = "none";
+                continue;
+            }
+            const mediaEl = this.ensureMediaElement(i, style);
+            if (!mediaEl.parentElement)
+                host.appendChild(mediaEl);
+            const px = (ndcX * 0.5 + 0.5) * width;
+            const py = (1 - (ndcY * 0.5 + 0.5)) * height;
+            const baseSize = source.shapeSize || CatalogueGL.STANDARD_SHAPE_SIZE;
+            const size = Math.max(8, baseSize * (style.scale ?? 2.4));
+            const rotation = style.rotationDeg ?? 0;
+            mediaEl.style.display = "block";
+            mediaEl.style.left = `${px - size / 2}px`;
+            mediaEl.style.top = `${py - size / 2}px`;
+            mediaEl.style.width = `${size}px`;
+            mediaEl.style.height = `${size}px`;
+            mediaEl.style.opacity = `${style.opacity ?? 1}`;
+            mediaEl.style.transform = `rotate(${rotation}deg)`;
+        }
     }
     sourceMatches(left, right) {
         if (left === right)
@@ -8745,6 +9089,7 @@ class CatalogueGL {
         // draw
         const numItems = this.vertexCataloguePosition.length / CatalogueGL.ELEM_SIZE;
         this._webgl.drawArrays(this._webgl.POINTS, 0, numItems);
+        this.updateMediaOverlay(in_mMatrix, vMatrix, pMatrix);
         this._oldMouseCoords = in_mouseHelper.xyz;
     }
 }