astro-viewer 2.0.0 → 3.0.0

package/lib-esm/AstroSphere.d.ts

@@ -9,6 +9,8 @@ import { FootprintSetGL, HoveredFootprintDetail } from './model/footprints/Footp
 import { EquatorialGrid } from './model/grid/EquatorialGrid.js';
 import { HealpixGrid } from './model/grid/HealpixGrid.js';
 import { ColorMap } from './model/ColorMaps.js';
+import { XYZLayer } from './model/earth/XYZLayer.js';
+import type { WMTSLayerConfig, XYZDebugStats, XYZLayerConfig } from './model/earth/types.js';
 export type PointCoordinates = {
     astroDeg: AstroCoords;
     raHMS: HMS;
@@ -54,6 +56,8 @@ declare class AstroSphere {
     private pointerDownY;
     private pointerDownAt;
     private _activeHiPS;
+    private _activeXYZ;
+    private _activeBaseLayer;
     private startup;
     private fov;
     private activeCatalogues;
@@ -83,7 +87,10 @@ declare class AstroSphere {
     private emitCameraChanged;
     private addEventListeners;
     getPhiThetaDeg(canvas: HTMLCanvasElement): SphericalCoords;
+    private collectViewportSphericalSamples;
     activateHiPS(hipsDescriptor: HiPSDescriptor): void;
+    activateXYZ(config: XYZLayerConfig): void;
+    activateWMTS(config: WMTSLayerConfig): void;
     showCatalogue(cat: CatalogueGL): Promise<CatalogueGL>;
     deleteCatalogue(catalogue: CatalogueGL): void;
     showFootprintSet(fset: FootprintSetGL): Promise<FootprintSetGL>;
@@ -107,6 +114,8 @@ declare class AstroSphere {
     private prevCentralRaDeg;
     private prevCentralDecDeg;
     get activeHiPS(): HiPS | null;
+    get activeXYZ(): XYZLayer | null;
+    getXYZDebugStats(): XYZDebugStats;
     draw(canvas: HTMLCanvasElement): void;
     private emitHoveredSourceIfChanged;
 }

package/lib-esm/AstroSphere.js

@@ -12,6 +12,9 @@ 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';
 /**
  * AstroSphere — main WebGL scene controller (TS port)
  */
@@ -36,6 +39,8 @@ class AstroSphere {
     pointerDownY = null;
     pointerDownAt = 0;
     _activeHiPS = null;
+    _activeXYZ = null;
+    _activeBaseLayer = null;
     startup = true;
     fov;
     activeCatalogues = [];
@@ -392,8 +397,35 @@ class AstroSphere {
         const pickerPoint = RayPickingUtils.getIntersectionPointWithSingleModel(maxX / 2, maxY / 2, this._healpixGrid, this._webgl, this._camera, this._perspectiveMatrixManager.pMatrix);
         return cartesianToSpherical(pickerPoint);
     }
+    collectViewportSphericalSamples(sampleCount = 5) {
+        const rect = this.canvas.getBoundingClientRect();
+        const width = rect.width;
+        const height = rect.height;
+        const samples = [];
+        for (let ix = 0; ix < sampleCount; ix++) {
+            const x = sampleCount === 1 ? width / 2 : (ix / (sampleCount - 1)) * width;
+            for (let iy = 0; iy < sampleCount; iy++) {
+                const y = sampleCount === 1 ? height / 2 : (iy / (sampleCount - 1)) * height;
+                const hit = RayPickingUtils.getIntersectionPointWithSingleModel(x, y, this._healpixGrid, this._webgl, this._camera, this._perspectiveMatrixManager.pMatrix);
+                if (hit && hit.length > 0) {
+                    samples.push(cartesianToSpherical(hit));
+                }
+            }
+        }
+        return samples;
+    }
     activateHiPS(hipsDescriptor) {
         this._activeHiPS = new HiPS(1, [0.0, 0.0, 0.0], 0, 0, hipsDescriptor, this._webgl, this._healpixGrid);
+        this._activeBaseLayer = 'hips';
+    }
+    activateXYZ(config) {
+        this._activeXYZ = new XYZLayer(config, this._webgl);
+        this._activeBaseLayer = 'xyz';
+    }
+    activateWMTS(config) {
+        const adapter = new WMTSAdapter(config);
+        this._activeXYZ = new XYZLayer(adapter.toXYZLayerConfig(), this._webgl);
+        this._activeBaseLayer = 'xyz';
     }
     // Catalogue section
     async showCatalogue(cat) {
@@ -524,12 +556,22 @@ class AstroSphere {
     get activeHiPS() {
         return this._activeHiPS;
     }
+    get activeXYZ() {
+        return this._activeXYZ;
+    }
+    getXYZDebugStats() {
+        return {
+            activeBaseLayer: this._activeBaseLayer,
+            layer: this._activeXYZ?.getDebugStats() ?? null,
+            requests: xyzTileRequestScheduler.getDebugStats(),
+        };
+    }
     draw(canvas) {
         if (this._refreshingStatus)
             return;
         if (!this._webgl)
             return;
-        if (!this._activeHiPS)
+        if (!this._activeHiPS && !this._activeXYZ)
             return;
         if (!this._healpixGrid || Object.keys(this._healpixGrid).length === 0)
             return;
@@ -613,15 +655,25 @@ 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);
-        const visibleOrder = Math.min(this._healpixGrid.visibleorder, this._activeHiPS.maxOrder);
-        this._healpixGrid.visibleTilesManager.computeVisiblePixels(visibleOrder, this._webgl, this._camera, this._perspectiveMatrixManager.pMatrix);
+        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 skyEntityDrawInput = {
             fovDeg: this._healpixGrid.getMinFoV(),
             camera: this._camera,
-            pMatrix: this._perspectiveMatrixManager.pMatrix
+            pMatrix: this._perspectiveMatrixManager.pMatrix,
+            centerSphericalDeg: this.updateCentralPoint().sphericalDeg,
+            fovPolygon: this._activeBaseLayer === 'xyz' ? this.getFoVPolygon() : undefined,
+            viewportSphericalSamples: this._activeBaseLayer === 'xyz' ? this.collectViewportSphericalSamples(7) : undefined,
         };
-        this._activeHiPS.draw(skyEntityDrawInput);
+        if (this._activeBaseLayer === 'hips') {
+            this._activeHiPS?.draw(skyEntityDrawInput);
+        }
+        if (this._activeBaseLayer === 'xyz') {
+            this._activeXYZ?.draw(skyEntityDrawInput);
+        }
         this._healpixGrid.draw(skyEntityDrawInput);
         this._equatorialGrid.draw(skyEntityDrawInput);
         this._webgl.enable(this._webgl.DEPTH_TEST);
@@ -642,14 +694,16 @@ class AstroSphere {
             });
         }
         this.activeCatalogues.forEach(cat => {
-            if (this._activeHiPS) {
-                cat.draw(this._activeHiPS.getModelMatrix(), this.mouseHelper, this._camera.getCameraMatrix(), this._perspectiveMatrixManager.pMatrix);
+            const activeModelMatrix = this._activeHiPS?.getModelMatrix() ?? this._activeXYZ?.getModelMatrix();
+            if (activeModelMatrix) {
+                cat.draw(activeModelMatrix, this.mouseHelper, this._camera.getCameraMatrix(), this._perspectiveMatrixManager.pMatrix);
             }
         });
         this.emitHoveredSourceIfChanged();
         this.activeFootprintSets.forEach(fst => {
-            if (this._activeHiPS) {
-                fst.draw(this._activeHiPS.getModelMatrix(), this.mouseHelper, this._camera.getCameraMatrix(), this._perspectiveMatrixManager.pMatrix);
+            const activeModelMatrix = this._activeHiPS?.getModelMatrix() ?? this._activeXYZ?.getModelMatrix();
+            if (activeModelMatrix) {
+                fst.draw(activeModelMatrix, this.mouseHelper, this._camera.getCameraMatrix(), this._perspectiveMatrixManager.pMatrix);
             }
         });
     }

package/lib-esm/AstroViewer.d.ts

@@ -9,6 +9,10 @@ import Camera from './Camera.js';
 import { ReadonlyMat4 } from 'gl-matrix';
 import { ColorMap, ColorMapName } from './model/ColorMaps.js';
 import { HiPS } from './model/hips/HiPS.js';
+import { XYZLayer } from './model/earth/XYZLayer.js';
+import type { WMTSLayerConfig, XYZDebugStats, XYZLayerConfig } from './model/earth/types.js';
+import { TerraPointSetGL } from './model/terra/TerraPointSetGL.js';
+import { TerraFootprintSetGL } from './model/terra/TerraFootprintSetGL.js';
 export declare class AstroViewer {
     private astroSphere;
     private canvas;
@@ -32,14 +36,28 @@ export declare class AstroViewer {
     showFootprintSet(footprintSet: FootprintSetGL): void;
     hideFootprintSet(footprintSet: FootprintSetGL, isVisible: boolean): void;
     deleteFootprintSet(footprintSet: FootprintSetGL): void;
+    createTerraPointSet(pointSetName: string, pointSetDescription: string, providerUrl: string, metadataManager: MetadataManager): TerraPointSetGL;
+    showTerraPointSet(pointSet: TerraPointSetGL): void;
+    hideTerraPointSet(pointSet: TerraPointSetGL, isVisible: boolean): void;
+    deleteTerraPointSet(pointSet: TerraPointSetGL): void;
+    createTerraFootprintSet(footprintSetName: string, footprintSetDescription: string, providerUrl: string, metadataManager: MetadataManager): TerraFootprintSetGL;
+    showTerraFootprintSet(footprintSet: TerraFootprintSetGL): void;
+    hideTerraFootprintSet(footprintSet: TerraFootprintSetGL, isVisible: boolean): void;
+    deleteTerraFootprintSet(footprintSet: TerraFootprintSetGL): void;
     changeFootprintSetColor(footprintSet: FootprintSetGL, hexColor: string): void;
     getHoveredFootprints(): HoveredFootprintDetail[];
     getDefaultHiPSURL(): string;
     activateHiPS(hipsDescriptor: HiPSDescriptor): void;
+    activateXYZ(config: XYZLayerConfig): void;
+    activateWMTS(config: WMTSLayerConfig): void;
+    setXYZMaxConcurrentRequests(value: number): void;
+    getXYZMaxConcurrentRequests(): number;
+    getXYZDebugStats(): XYZDebugStats;
     loadHiPS(baseUrl: string): Promise<string>;
     changeColorMap(colorMapName: ColorMapName): void;
     changeCustomColorMap(colorMap: ColorMap): void;
     getActiveHiPS(): HiPS | null;
+    getActiveXYZ(): XYZLayer | null;
     setCamera(camera: Camera): void;
     setCameraPosition(pos: [number, number, number]): void;
     setCameraMatrix(viewMatrix: Float32Array): void;

package/lib-esm/AstroViewer.js

@@ -5,6 +5,9 @@ import { CatalogueGL } from './model/catalogues/CatalogueGL.js';
 import { FootprintSetGL } from './model/footprints/FootprintSetGL.js';
 import { bootSetup } from './Config.js';
 import ColorMaps from './model/ColorMaps.js';
+import { xyzTileRequestScheduler } from './model/earth/XYZTileRequestScheduler.js';
+import { TerraPointSetGL } from './model/terra/TerraPointSetGL.js';
+import { TerraFootprintSetGL } from './model/terra/TerraFootprintSetGL.js';
 // & {
 //   viewportWidth: number
 //   viewportHeight: number
@@ -71,6 +74,31 @@ export class AstroViewer {
     deleteFootprintSet(footprintSet) {
         this.astroSphere.deleteFootprintSet(footprintSet);
     }
+    // TERRA OVERLAYS
+    createTerraPointSet(pointSetName, pointSetDescription, providerUrl, metadataManager) {
+        return new TerraPointSetGL(pointSetName, pointSetDescription, providerUrl, metadataManager, this.webgl, this.astroSphere.healpixGrid.visibleTilesManager);
+    }
+    showTerraPointSet(pointSet) {
+        this.astroSphere.showCatalogue(pointSet);
+    }
+    hideTerraPointSet(pointSet, isVisible) {
+        pointSet.setIsVisible(isVisible);
+    }
+    deleteTerraPointSet(pointSet) {
+        this.astroSphere.deleteCatalogue(pointSet);
+    }
+    createTerraFootprintSet(footprintSetName, footprintSetDescription, providerUrl, metadataManager) {
+        return new TerraFootprintSetGL(footprintSetName, footprintSetDescription, providerUrl, metadataManager, this.webgl, this.astroSphere.healpixGrid.visibleTilesManager);
+    }
+    showTerraFootprintSet(footprintSet) {
+        this.astroSphere.showFootprintSet(footprintSet);
+    }
+    hideTerraFootprintSet(footprintSet, isVisible) {
+        footprintSet.setIsVisible(isVisible);
+    }
+    deleteTerraFootprintSet(footprintSet) {
+        this.astroSphere.deleteFootprintSet(footprintSet);
+    }
     changeFootprintSetColor(footprintSet, hexColor) {
         // footprintSet.footprintsetProps.changeColor(hexColor)
         footprintSet.changeColor(hexColor);
@@ -85,6 +113,21 @@ export class AstroViewer {
     activateHiPS(hipsDescriptor) {
         this.astroSphere.activateHiPS(hipsDescriptor);
     }
+    activateXYZ(config) {
+        this.astroSphere.activateXYZ(config);
+    }
+    activateWMTS(config) {
+        this.astroSphere.activateWMTS(config);
+    }
+    setXYZMaxConcurrentRequests(value) {
+        xyzTileRequestScheduler.setMaxConcurrent(value);
+    }
+    getXYZMaxConcurrentRequests() {
+        return xyzTileRequestScheduler.getMaxConcurrent();
+    }
+    getXYZDebugStats() {
+        return this.astroSphere.getXYZDebugStats();
+    }
     async loadHiPS(baseUrl) {
         const hipsUrl = baseUrl.endsWith('/') ? baseUrl : baseUrl + '/';
         const resp = await fetch(hipsUrl + 'properties');
@@ -108,6 +151,9 @@ export class AstroViewer {
     getActiveHiPS() {
         return this.astroSphere.activeHiPS;
     }
+    getActiveXYZ() {
+        return this.astroSphere.activeXYZ;
+    }
     // Camera: GOTOs and COORDS
     setCamera(camera) {
         this.astroSphere.setCamera(camera);

package/lib-esm/index.d.ts

@@ -4,6 +4,8 @@ export { FoV } from './model/FoV.js';
 export type { PointCoordinates, CameraChangedDetail } from './AstroSphere.js';
 export { HoveredFootprintDetail, FootprintSetGL } from './model/footprints/FootprintSetGL.js';
 export { CatalogueGL } from './model/catalogues/CatalogueGL.js';
+export { TerraPointSetGL } from './model/terra/TerraPointSetGL.js';
+export { TerraFootprintSetGL } from './model/terra/TerraFootprintSetGL.js';
 export { MetadataManager } from './model/MetadataManager.js';
 export { MetadataColumn, MetadataInit, ColumnType } from './model/MetadataColumn.js';
 export { Point, SphericalOpts, AstroOpts, PointInitOpts, CartesianOpts } from './model/Point.js';
@@ -12,5 +14,8 @@ export { CoordsType } from './utils/CoordsType.js';
 export { ColorMaps, COLOR_MAP_SAMPLE_COUNT, createColorMapFromSamples } from './model/ColorMaps.js';
 export type { ColorMap, ColorMapName } from './model/ColorMaps.js';
 export { HiPS } from './model/hips/HiPS.js';
+export { XYZLayer } from './model/earth/XYZLayer.js';
+export { WMTSAdapter } from './model/earth/wmts/WMTSAdapter.js';
+export type { XYZLayerConfig, XYZTileCoord, XYZTileMesh, WMTSLayerConfig, WMTSRequestEncoding } from './model/earth/types.js';
 export { Source } from './model/Source.js';
 export { Footprint } from './model/footprints/Footprint.js';

package/lib-esm/index.js

@@ -3,6 +3,8 @@ export { HiPSDescriptor } from './model/hips/HiPSDescriptor.js';
 export { FoV } from './model/FoV.js';
 export { FootprintSetGL } from './model/footprints/FootprintSetGL.js';
 export { CatalogueGL } from './model/catalogues/CatalogueGL.js';
+export { TerraPointSetGL } from './model/terra/TerraPointSetGL.js';
+export { TerraFootprintSetGL } from './model/terra/TerraFootprintSetGL.js';
 export { MetadataManager } from './model/MetadataManager.js';
 export { MetadataColumn, ColumnType } from './model/MetadataColumn.js';
 export { Point } from './model/Point.js';
@@ -10,6 +12,8 @@ export { FoVUtils } from './utils/FoVUtils.js';
 export { CoordsType } from './utils/CoordsType.js';
 export { ColorMaps, COLOR_MAP_SAMPLE_COUNT, createColorMapFromSamples } from './model/ColorMaps.js';
 export { HiPS } from './model/hips/HiPS.js';
+export { XYZLayer } from './model/earth/XYZLayer.js';
+export { WMTSAdapter } from './model/earth/wmts/WMTSAdapter.js';
 export { Source } from './model/Source.js';
 export { Footprint } from './model/footprints/Footprint.js';
 console.log('astroviewer UMD loaded');

package/lib-esm/model/AbstractSkyEntity.d.ts

@@ -4,11 +4,21 @@
 import { vec3, mat4, ReadonlyVec3, ReadonlyMat4 } from "gl-matrix";
 import { HiPSShaderProgram } from '../shader/HiPSShaderProgram.js';
 import Camera from "../Camera.js";
+import { Point } from "./Point.js";
 type GL = WebGLRenderingContext | WebGL2RenderingContext;
 export interface SkyEntityDrawInput {
     fovDeg?: number;
     camera: Camera;
     pMatrix: ReadonlyMat4;
+    centerSphericalDeg?: {
+        phi: number;
+        theta: number;
+    };
+    fovPolygon?: Point[];
+    viewportSphericalSamples?: Array<{
+        phi: number;
+        theta: number;
+    }>;
 }
 export declare abstract class AbstractSkyEntity {
     refreshMe: boolean;

package/lib-esm/model/earth/XYZAncestorMeshCache.d.ts

@@ -0,0 +1,10 @@
+import type { XYZTileCoord, XYZTileGpuMesh } from './types.js';
+import { XYZMeshBuilder } from './XYZMeshBuilder.js';
+export declare class XYZAncestorMeshCache {
+    private _webgl;
+    private _meshBuilder;
+    private _meshes;
+    constructor(webgl: WebGL2RenderingContext, meshBuilder: XYZMeshBuilder);
+    getMesh(targetTile: XYZTileCoord, ancestorTile: XYZTileCoord, segmentsPerSide: number): XYZTileGpuMesh;
+    dispose(): void;
+}

package/lib-esm/model/earth/XYZAncestorMeshCache.js

@@ -0,0 +1,31 @@
+export class XYZAncestorMeshCache {
+    _webgl;
+    _meshBuilder;
+    _meshes = new Map();
+    constructor(webgl, meshBuilder) {
+        this._webgl = webgl;
+        this._meshBuilder = meshBuilder;
+    }
+    getMesh(targetTile, ancestorTile, segmentsPerSide) {
+        const key = `${targetTile.z}/${targetTile.x}/${targetTile.y}->${ancestorTile.z}/${ancestorTile.x}/${ancestorTile.y}@${segmentsPerSide}`;
+        const existing = this._meshes.get(key);
+        if (existing) {
+            return existing;
+        }
+        const mesh = this._meshBuilder.buildAncestorMesh(targetTile, ancestorTile, segmentsPerSide);
+        const uploaded = this._meshBuilder.uploadMesh(mesh, this._webgl);
+        this._meshes.set(key, uploaded);
+        return uploaded;
+    }
+    dispose() {
+        for (const mesh of this._meshes.values()) {
+            if (mesh.positionBuffer)
+                this._webgl.deleteBuffer(mesh.positionBuffer);
+            if (mesh.uvBuffer)
+                this._webgl.deleteBuffer(mesh.uvBuffer);
+            if (mesh.indexBuffer)
+                this._webgl.deleteBuffer(mesh.indexBuffer);
+        }
+        this._meshes.clear();
+    }
+}

package/lib-esm/model/earth/XYZLayer.d.ts

@@ -0,0 +1,31 @@
+import { AbstractSkyEntity, SkyEntityDrawInput } from '../AbstractSkyEntity.js';
+import type { XYZLayerConfig, XYZLayerDebugStats } from './types.js';
+export declare class XYZLayer extends AbstractSkyEntity {
+    private static readonly DEFAULT_MAX_CACHED_TILES;
+    private _config;
+    private _provider;
+    private _visibleTilesManager;
+    private _meshBuilder;
+    private _xyzShaderProgram;
+    private _tileBuffer;
+    private _ancestorMeshCache;
+    private _visibleTileKeys;
+    private _fallbackVisibleTileKeys;
+    private _baseVisibleTileKeys;
+    private _tilePriorities;
+    private _tileSelectionKey;
+    private _currentTileCount;
+    private _fallbackTileCount;
+    private _coreTileCount;
+    private _coverageTileCount;
+    constructor(config: XYZLayerConfig, webgl: WebGL2RenderingContext);
+    get config(): XYZLayerConfig;
+    getDebugStats(): XYZLayerDebugStats;
+    private bootstrapTiles;
+    draw(input: SkyEntityDrawInput): void;
+    private evictCache;
+    private disposeTiles;
+    private getTileKey;
+    private parseTileKey;
+    private findBestAvailableAncestor;
+}

package/lib-esm/model/earth/XYZLayer.js

@@ -0,0 +1,231 @@
+import { AbstractSkyEntity } from '../AbstractSkyEntity.js';
+import { XYZShaderProgram } from '../../shader/XYZShaderProgram.js';
+import { XYZAncestorMeshCache } from './XYZAncestorMeshCache.js';
+import { XYZMeshBuilder } from './XYZMeshBuilder.js';
+import { XYZTileBuffer } from './XYZTileBuffer.js';
+import { XYZTileProvider } from './XYZTileProvider.js';
+import { XYZVisibleTilesManager } from './XYZVisibleTilesManager.js';
+export class XYZLayer extends AbstractSkyEntity {
+    static DEFAULT_MAX_CACHED_TILES = 384;
+    _config;
+    _provider;
+    _visibleTilesManager;
+    _meshBuilder;
+    _xyzShaderProgram;
+    _tileBuffer;
+    _ancestorMeshCache;
+    _visibleTileKeys = [];
+    _fallbackVisibleTileKeys = [];
+    _baseVisibleTileKeys = [];
+    _tilePriorities = new Map();
+    _tileSelectionKey = null;
+    _currentTileCount = 0;
+    _fallbackTileCount = 0;
+    _coreTileCount = 0;
+    _coverageTileCount = 0;
+    constructor(config, webgl) {
+        super(1, [0, 0, 0], 0, 0, 'XYZ Earth Layer', webgl, false);
+        this._config = config;
+        this._provider = new XYZTileProvider(config);
+        this._visibleTilesManager = new XYZVisibleTilesManager(this._provider);
+        this._meshBuilder = new XYZMeshBuilder();
+        this._xyzShaderProgram = new XYZShaderProgram(webgl);
+        this._tileBuffer = new XYZTileBuffer(1, webgl, this._meshBuilder, this._xyzShaderProgram);
+        this._ancestorMeshCache = new XYZAncestorMeshCache(webgl, this._meshBuilder);
+        this.initGL(webgl);
+        this.bootstrapTiles(180, null, null);
+    }
+    get config() {
+        return this._config;
+    }
+    getDebugStats() {
+        let readyTileCount = 0;
+        let loadingTileCount = 0;
+        let coolingDownTileCount = 0;
+        const now = Date.now();
+        const allTiles = [
+            ...Array.from(this._tileBuffer.activeTiles.values(), (entry) => entry.tile),
+            ...Array.from(this._tileBuffer.cachedTiles.values(), (entry) => entry.tile),
+        ];
+        for (const tile of allTiles) {
+            if (tile.ready) {
+                readyTileCount += 1;
+            }
+            if (tile.loading) {
+                loadingTileCount += 1;
+            }
+            if (tile.failedUntil > now) {
+                coolingDownTileCount += 1;
+            }
+        }
+        const currentZoom = this._visibleTileKeys.reduce((maxZoom, tileKey) => {
+            const zoom = Number.parseInt(tileKey.split('/')[0] ?? '', 10);
+            if (!Number.isFinite(zoom)) {
+                return maxZoom;
+            }
+            return maxZoom == null ? zoom : Math.max(maxZoom, zoom);
+        }, null);
+        return {
+            cacheSize: this._tileBuffer.size,
+            visibleTileCount: this._visibleTileKeys.length,
+            currentTileCount: this._currentTileCount,
+            fallbackTileCount: this._fallbackTileCount,
+            coreTileCount: this._coreTileCount,
+            coverageTileCount: this._coverageTileCount,
+            readyTileCount,
+            loadingTileCount,
+            coolingDownTileCount,
+            currentZoom,
+            tileSelectionKey: this._tileSelectionKey,
+            isSettling: false,
+            coarseTileCount: 0,
+            hasPendingSelection: false,
+            pendingSelectionKey: null,
+        };
+    }
+    bootstrapTiles(fovDeg, camera, centerSphericalDeg, fovPolygon = null, viewportSphericalSamples = null) {
+        const selection = camera
+            ? this._visibleTilesManager.selectTiles({
+                fovDeg,
+                camera,
+                pMatrix: new Float32Array(),
+                centerSphericalDeg: centerSphericalDeg ?? undefined,
+                fovPolygon: fovPolygon ?? undefined,
+                viewportSphericalSamples: viewportSphericalSamples ?? undefined,
+            })
+            : {
+                key: 'initial',
+                currentTiles: this._provider.getInitialTiles(),
+                fallbackTiles: [],
+                currentZoom: 1,
+                coreTileCount: this._provider.getInitialTiles().length,
+                coverageTileCount: 0,
+            };
+        if (selection.key === this._tileSelectionKey) {
+            return;
+        }
+        this._tileSelectionKey = selection.key;
+        this._currentTileCount = selection.currentTiles.length;
+        this._fallbackTileCount = selection.fallbackTiles.length;
+        this._coreTileCount = selection.coreTileCount;
+        this._coverageTileCount = selection.coverageTileCount;
+        const segments = this._config.segmentsPerSide ?? 16;
+        const baseTiles = this._provider.getInitialTiles();
+        const coreTileKeys = new Set(selection.currentTiles
+            .slice(0, selection.coreTileCount)
+            .map((tileCoord) => this.getTileKey(tileCoord)));
+        const baseTileKeys = new Set(baseTiles.map((tileCoord) => this.getTileKey(tileCoord)));
+        const prioritizedBaseTiles = baseTiles.map((tileCoord, index) => ({
+            tileCoord,
+            priority: 5000 + (baseTiles.length - index),
+            role: 'base',
+        }));
+        const prioritizedCurrentTiles = selection.currentTiles.map((tileCoord, index) => ({
+            tileCoord,
+            priority: 10000 + (selection.currentTiles.length - index),
+            role: coreTileKeys.has(this.getTileKey(tileCoord)) ? 'current' : 'coverage',
+        }));
+        const prioritizedFallbackTiles = selection.fallbackTiles.map((tileCoord, index) => ({
+            tileCoord,
+            priority: 1000 + (selection.fallbackTiles.length - index),
+            role: 'fallback',
+        }));
+        const requestedTiles = [...prioritizedBaseTiles, ...prioritizedCurrentTiles, ...prioritizedFallbackTiles];
+        this._tilePriorities.clear();
+        this._fallbackVisibleTileKeys = [];
+        this._baseVisibleTileKeys = [];
+        const orderedRequests = requestedTiles
+            .sort((a, b) => a.tileCoord.z - b.tileCoord.z)
+            .map(({ tileCoord, priority, role }) => {
+            const tileKey = this.getTileKey(tileCoord);
+            this._tilePriorities.set(tileKey, priority);
+            return {
+                tileCoord,
+                priority,
+                url: this._provider.getTileUrl(tileCoord),
+                role,
+            };
+        });
+        const ensuredKeys = this._tileBuffer.ensureTiles(orderedRequests, segments);
+        const fallbackKeySet = new Set(selection.fallbackTiles.map((tileCoord) => this.getTileKey(tileCoord)));
+        this._baseVisibleTileKeys = ensuredKeys.filter((tileKey) => baseTileKeys.has(tileKey));
+        this._fallbackVisibleTileKeys = ensuredKeys.filter((tileKey) => fallbackKeySet.has(tileKey) && !baseTileKeys.has(tileKey));
+        this._visibleTileKeys = ensuredKeys.filter((tileKey) => !fallbackKeySet.has(tileKey) && !baseTileKeys.has(tileKey));
+        this.evictCache();
+    }
+    draw(input) {
+        const vMatrix = input.camera.getCameraMatrix();
+        if (!vMatrix)
+            return;
+        this.bootstrapTiles(input.fovDeg ?? 180, input.camera, input.centerSphericalDeg ?? null, input.fovPolygon ?? null, input.viewportSphericalSamples ?? null);
+        const pMatrix = input.pMatrix;
+        const mMatrix = this.getModelMatrix();
+        for (const tileKey of this._baseVisibleTileKeys) {
+            const tile = this._tileBuffer.getActiveTile(tileKey);
+            if (!tile)
+                continue;
+            tile.draw(pMatrix, vMatrix, mMatrix, this._tilePriorities.get(tileKey) ?? 0);
+        }
+        for (const tileKey of this._fallbackVisibleTileKeys) {
+            const tile = this._tileBuffer.getActiveTile(tileKey);
+            if (!tile)
+                continue;
+            tile.draw(pMatrix, vMatrix, mMatrix, this._tilePriorities.get(tileKey) ?? 0, false);
+        }
+        for (const tileKey of this._visibleTileKeys) {
+            const tile = this._tileBuffer.getActiveTile(tileKey);
+            if (tile?.ready) {
+                tile.draw(pMatrix, vMatrix, mMatrix, this._tilePriorities.get(tileKey) ?? 0);
+                continue;
+            }
+            const targetCoord = this.parseTileKey(tileKey);
+            if (targetCoord) {
+                const ancestorTile = this.findBestAvailableAncestor(targetCoord);
+                if (ancestorTile) {
+                    const ancestorMesh = this._ancestorMeshCache.getMesh(targetCoord, ancestorTile.coord, this._config.segmentsPerSide ?? 16);
+                    ancestorTile.drawRemapped(ancestorMesh, pMatrix, vMatrix, mMatrix);
+                }
+            }
+            tile?.draw(pMatrix, vMatrix, mMatrix, this._tilePriorities.get(tileKey) ?? 0);
+        }
+    }
+    evictCache() {
+        const maxCachedTiles = this._config.maxCachedTiles ?? XYZLayer.DEFAULT_MAX_CACHED_TILES;
+        this._tileBuffer.evictCached(maxCachedTiles);
+    }
+    disposeTiles() {
+        this._tileBuffer.dispose();
+        this._ancestorMeshCache.dispose();
+        this._visibleTileKeys = [];
+        this._fallbackVisibleTileKeys = [];
+        this._baseVisibleTileKeys = [];
+    }
+    getTileKey(tileCoord) {
+        return `${tileCoord.z}/${tileCoord.x}/${tileCoord.y}`;
+    }
+    parseTileKey(tileKey) {
+        const [zRaw, xRaw, yRaw] = tileKey.split('/');
+        const z = Number.parseInt(zRaw ?? '', 10);
+        const x = Number.parseInt(xRaw ?? '', 10);
+        const y = Number.parseInt(yRaw ?? '', 10);
+        if (!Number.isFinite(z) || !Number.isFinite(x) || !Number.isFinite(y)) {
+            return null;
+        }
+        return { z, x, y };
+    }
+    findBestAvailableAncestor(targetCoord) {
+        for (let z = targetCoord.z - 1; z >= this._provider.minZoom; z--) {
+            const dz = targetCoord.z - z;
+            const ancestorCoord = {
+                z,
+                x: targetCoord.x >> dz,
+                y: targetCoord.y >> dz,
+            };
+            const ancestor = this._tileBuffer.getAnyTile(this.getTileKey(ancestorCoord));
+            if (ancestor?.ready) {
+                return ancestor;
+            }
+        }
+        return null;
+    }
+}

package/lib-esm/model/earth/XYZMeshBuilder.d.ts

@@ -0,0 +1,6 @@
+import type { XYZTileCoord, XYZTileMesh, XYZTileGpuMesh } from './types.js';
+export declare class XYZMeshBuilder {
+    buildTileMesh(tile: XYZTileCoord, segmentsPerSide?: number): XYZTileMesh;
+    buildAncestorMesh(targetTile: XYZTileCoord, ancestorTile: XYZTileCoord, segmentsPerSide?: number): XYZTileMesh;
+    uploadMesh(mesh: XYZTileMesh, webgl: WebGL2RenderingContext): XYZTileGpuMesh;
+}