astro-viewer 2.0.0 → 3.1.0

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

@@ -0,0 +1,97 @@
+/*
+ * 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.
+ */
+function replaceTokens(template, values) {
+    return Object.entries(values).reduce((result, [key, value]) => result.replace(new RegExp(`\\{${key}\\}`, 'g'), value), template);
+}
+export class WMTSAdapter {
+    _config;
+    constructor(config) {
+        this._config = config;
+    }
+    toXYZLayerConfig() {
+        const inferredMaxZoom = this.getInferredMaxZoom();
+        return {
+            urlTemplate: this._config.urlTemplate ?? this._config.baseUrl,
+            minZoom: this._config.minZoom,
+            maxZoom: inferredMaxZoom,
+            segmentsPerSide: this._config.segmentsPerSide,
+            tileSize: this._config.tileSize,
+            maxCachedTiles: this._config.maxCachedTiles,
+            subdomains: this._config.subdomains,
+            attribution: this._config.attribution,
+            flipY: this._config.flipY,
+            urlResolver: (tile) => this.getTileUrl(tile),
+        };
+    }
+    getInferredMaxZoom() {
+        const matrixLabelCount = this._config.matrixLabels?.length ?? 0;
+        const maxFromLabels = matrixLabelCount > 0 ? matrixLabelCount - 1 : undefined;
+        if (maxFromLabels == null) {
+            return this._config.maxZoom;
+        }
+        if (this._config.maxZoom == null) {
+            return maxFromLabels;
+        }
+        return Math.min(this._config.maxZoom, maxFromLabels);
+    }
+    getTileUrl(tile) {
+        return this._config.requestEncoding === 'rest'
+            ? this.buildRestUrl(tile)
+            : this.buildKvpUrl(tile);
+    }
+    buildRestUrl(tile) {
+        const template = this._config.urlTemplate ?? this._config.baseUrl;
+        const values = this.getCommonTokenValues(tile);
+        const resolved = replaceTokens(template, values);
+        return resolved.replace(/(?<!:)\/{2,}/g, '/');
+    }
+    buildKvpUrl(tile) {
+        const baseUrl = new URL(this._config.baseUrl);
+        const values = this.getCommonTokenValues(tile);
+        const params = baseUrl.searchParams;
+        params.set('SERVICE', 'WMTS');
+        params.set('REQUEST', 'GetTile');
+        params.set('VERSION', this._config.version ?? '1.0.0');
+        params.set('LAYER', this._config.layer);
+        params.set('STYLE', this._config.style ?? 'default');
+        params.set('FORMAT', this._config.format ?? 'image/png');
+        params.set('TILEMATRIXSET', this._config.tileMatrixSet);
+        params.set('TILEMATRIX', values.TileMatrix);
+        params.set('TILEROW', values.TileRow);
+        params.set('TILECOL', values.TileCol);
+        for (const [key, value] of Object.entries(this._config.dimensions ?? {})) {
+            params.set(key, value);
+        }
+        return baseUrl.toString();
+    }
+    getCommonTokenValues(tile) {
+        const dim = 2 ** tile.z;
+        const effectiveY = this._config.flipY ? dim - 1 - tile.y : tile.y;
+        const matrixLabel = this._config.matrixLabels?.[tile.z] ?? String(tile.z);
+        const tileFormat = this._config.format ?? 'image/png';
+        const tileFormatExtension = tileFormat.replace(/^image\//, '');
+        return {
+            Layer: this._config.layer,
+            Style: this._config.style ?? 'default',
+            Time: this._config.time ?? '',
+            TileMatrixSet: this._config.tileMatrixSet,
+            TileMatrix: matrixLabel,
+            TileRow: String(effectiveY),
+            TileCol: String(tile.x),
+            Format: tileFormatExtension,
+            TileFormat: tileFormat,
+            TileFormatExtension: tileFormatExtension,
+            ...Object.fromEntries(Object.entries(this._config.dimensions ?? {}).map(([key, value]) => [key, value])),
+        };
+    }
+}

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

@@ -0,0 +1,17 @@
+import { XYZShaderProgram } from '../../shader/XYZShaderProgram.js';
+import { XYZMeshBuilder } from './XYZMeshBuilder.js';
+import { XYZTile } from './XYZTile.js';
+import type { XYZTileCoord } from './XYZTypes.js';
+type Mat4 = Float32Array;
+export declare class XYZAnchestorTile extends XYZTile {
+    private _ancestorMeshBuilder;
+    private _ancestorWebgl;
+    private _segmentsPerSide;
+    private _meshCache;
+    constructor(coord: XYZTileCoord, url: string, webgl: WebGL2RenderingContext, shaderProgram: XYZShaderProgram, meshBuilder?: XYZMeshBuilder, segmentsPerSide?: number);
+    draw(pMatrixOrVisibleZoom: Mat4 | number, vMatrixOrVisibleTiles: Mat4 | XYZTileCoord[], mMatrixOrAncestorsMap: Mat4 | Map<string, XYZTileCoord>, colorMapIdxOrPMatrix: number | Mat4, vMatrix?: Mat4, mMatrix?: Mat4, colorMapIdx?: number): boolean;
+    dispose(): void;
+    private getRemappedMesh;
+    private isAncestorOf;
+}
+export { XYZAnchestorTile as XYZAncestorTile };

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

@@ -0,0 +1,87 @@
+/*
+ * 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 { XYZMeshBuilder } from './XYZMeshBuilder.js';
+import { XYZTile } from './XYZTile.js';
+export class XYZAnchestorTile extends XYZTile {
+    _ancestorMeshBuilder;
+    _ancestorWebgl;
+    _segmentsPerSide;
+    _meshCache = new Map();
+    constructor(coord, url, webgl, shaderProgram, meshBuilder = new XYZMeshBuilder(), segmentsPerSide = 16) {
+        super(coord, url, webgl, shaderProgram, meshBuilder, segmentsPerSide);
+        this._ancestorMeshBuilder = meshBuilder;
+        this._ancestorWebgl = webgl;
+        this._segmentsPerSide = segmentsPerSide;
+    }
+    draw(pMatrixOrVisibleZoom, vMatrixOrVisibleTiles, mMatrixOrAncestorsMap, colorMapIdxOrPMatrix, vMatrix, mMatrix, colorMapIdx) {
+        if (typeof pMatrixOrVisibleZoom !== 'number') {
+            return super.draw(pMatrixOrVisibleZoom, vMatrixOrVisibleTiles, mMatrixOrAncestorsMap, colorMapIdxOrPMatrix);
+        }
+        if (!vMatrix || !mMatrix || colorMapIdx === undefined) {
+            return false;
+        }
+        const visibleZoom = pMatrixOrVisibleZoom;
+        const visibleTiles = vMatrixOrVisibleTiles;
+        const ancestorsMap = mMatrixOrAncestorsMap;
+        const pMatrix = colorMapIdxOrPMatrix;
+        let drawn = false;
+        if (visibleZoom <= this.coord.z) {
+            return super.draw(pMatrix, vMatrix, mMatrix, colorMapIdx);
+        }
+        for (const targetTile of visibleTiles) {
+            if (!this.isAncestorOf(targetTile)) {
+                continue;
+            }
+            const ancestorKey = `${this.coord.z}/${this.coord.x}/${this.coord.y}`;
+            if (!ancestorsMap.has(ancestorKey)) {
+                continue;
+            }
+            const mesh = this.getRemappedMesh(targetTile);
+            drawn = super.drawRemapped(mesh, pMatrix, vMatrix, mMatrix, colorMapIdx) || drawn;
+        }
+        return drawn;
+    }
+    dispose() {
+        for (const mesh of this._meshCache.values()) {
+            if (mesh.positionBuffer)
+                this._ancestorWebgl.deleteBuffer(mesh.positionBuffer);
+            if (mesh.uvBuffer)
+                this._ancestorWebgl.deleteBuffer(mesh.uvBuffer);
+            if (mesh.indexBuffer)
+                this._ancestorWebgl.deleteBuffer(mesh.indexBuffer);
+        }
+        this._meshCache.clear();
+        super.dispose();
+    }
+    getRemappedMesh(targetTile) {
+        const key = `${targetTile.z}/${targetTile.x}/${targetTile.y}->${this.coord.z}/${this.coord.x}/${this.coord.y}`;
+        const existing = this._meshCache.get(key);
+        if (existing) {
+            return existing;
+        }
+        const mesh = this._ancestorMeshBuilder.buildAncestorMesh(targetTile, this.coord, this._segmentsPerSide);
+        const uploaded = this._ancestorMeshBuilder.uploadMesh(mesh, this._ancestorWebgl);
+        this._meshCache.set(key, uploaded);
+        return uploaded;
+    }
+    isAncestorOf(targetTile) {
+        if (targetTile.z <= this.coord.z) {
+            return targetTile.z === this.coord.z
+                && targetTile.x === this.coord.x
+                && targetTile.y === this.coord.y;
+        }
+        const dz = targetTile.z - this.coord.z;
+        return (targetTile.x >> dz) === this.coord.x && (targetTile.y >> dz) === this.coord.y;
+    }
+}
+export { XYZAnchestorTile as XYZAncestorTile };

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

@@ -0,0 +1,72 @@
+import type { XYZTileCoord } from './XYZTypes.js';
+export type XYZLayerConfig = {
+    urlTemplate: string;
+    name?: string;
+    minZoom?: number;
+    maxZoom?: number;
+    segmentsPerSide?: number;
+    tileSize?: number;
+    maxCachedTiles?: number;
+    interactionDebounceMs?: number;
+    subdomains?: string[];
+    attribution?: string;
+    flipY?: boolean;
+    urlResolver?: (tile: XYZTileCoord) => string;
+};
+export type XYZLayerDebugStats = {
+    cacheSize: number;
+    visibleTileCount: number;
+    currentTileCount: number;
+    fallbackTileCount: number;
+    coreTileCount: number;
+    coverageTileCount: number;
+    readyTileCount: number;
+    loadingTileCount: number;
+    coolingDownTileCount: number;
+    currentZoom: number | null;
+    tileSelectionKey: string | null;
+    isSettling: boolean;
+    coarseTileCount: number;
+    hasPendingSelection: boolean;
+    pendingSelectionKey: string | null;
+};
+export type XYZRequestBackoffDebugEntry = {
+    host: string;
+    cooldownMs: number;
+    consecutiveFailures: number;
+};
+export type XYZRequestSchedulerDebugStats = {
+    activeRequests: number;
+    queuedRequests: number;
+    inflightRequests: number;
+    maxConcurrentRequests: number;
+    highestQueuedPriority: number | null;
+    hostsInBackoff: XYZRequestBackoffDebugEntry[];
+};
+export type XYZDebugStats = {
+    activeBaseLayer: 'hips' | 'xyz' | null;
+    layer: XYZLayerDebugStats | null;
+    requests: XYZRequestSchedulerDebugStats;
+};
+export type WMTSRequestEncoding = 'kvp' | 'rest';
+export type WMTSLayerConfig = {
+    baseUrl: string;
+    layer: string;
+    tileMatrixSet: string;
+    style?: string;
+    time?: string;
+    format?: string;
+    requestEncoding?: WMTSRequestEncoding;
+    version?: string;
+    dimensions?: Record<string, string>;
+    matrixLabels?: string[];
+    urlTemplate?: string;
+    minZoom?: number;
+    maxZoom?: number;
+    segmentsPerSide?: number;
+    tileSize?: number;
+    maxCachedTiles?: number;
+    subdomains?: string[];
+    attribution?: string;
+    flipY?: boolean;
+};

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

@@ -0,0 +1,13 @@
+/*
+ * 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.
+ */
+export {};

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

@@ -0,0 +1,9 @@
+declare class XYZFoVHelper {
+    getZoom(fov: number): number;
+    getLonLatSteps(fov: number): {
+        lonStep: number;
+        latStep: number;
+    };
+}
+export declare const xyzFovHelper: XYZFoVHelper;
+export default XYZFoVHelper;

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

@@ -0,0 +1,101 @@
+/*
+ * 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.
+ */
+// FoVHelper.ts
+'use strict';
+class XYZFoVHelper {
+    getZoom(fov) {
+        if (fov >= 179)
+            return 2;
+        if (fov >= 90)
+            return 3;
+        if (fov >= 30)
+            return 4;
+        if (fov >= 20)
+            return 5;
+        if (fov >= 6)
+            return 6;
+        if (fov >= 3.2)
+            return 7;
+        if (fov >= 1.6)
+            return 8;
+        if (fov >= 0.85)
+            return 9;
+        if (fov >= 0.42)
+            return 10;
+        if (fov >= 0.21)
+            return 11;
+        if (fov >= 0.12)
+            return 12;
+        if (fov >= 0.06)
+            return 13;
+        if (fov >= 0.015)
+            return 14;
+        return 15;
+    }
+    // used in grid drawing
+    getLonLatSteps(fov) {
+        let lonStep;
+        let latStep;
+        if (fov >= 179) {
+            lonStep = 10;
+            latStep = 10;
+        }
+        else if (fov >= 25) {
+            lonStep = 9;
+            latStep = 9;
+        }
+        else if (fov >= 12.5) {
+            lonStep = 8;
+            latStep = 8;
+        }
+        else if (fov >= 6) {
+            lonStep = 6;
+            latStep = 6;
+        }
+        else if (fov >= 3.2) {
+            lonStep = 5;
+            latStep = 5;
+        }
+        else if (fov >= 1.6) {
+            lonStep = 4;
+            latStep = 4;
+        }
+        else if (fov >= 0.85) {
+            lonStep = 3;
+            latStep = 3;
+        }
+        else if (fov >= 0.42) {
+            lonStep = 2;
+            latStep = 2;
+        }
+        else if (fov >= 0.21) {
+            lonStep = 1;
+            latStep = 1;
+        }
+        else if (fov >= 0.12) {
+            lonStep = 0.5;
+            latStep = 0.5;
+        }
+        else if (fov >= 0.06) {
+            lonStep = 0.25;
+            latStep = 0.25;
+        }
+        else {
+            lonStep = 10;
+            latStep = 10;
+        }
+        return { lonStep, latStep };
+    }
+}
+export const xyzFovHelper = new XYZFoVHelper();
+export default XYZFoVHelper;

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

@@ -0,0 +1,31 @@
+import { AbstractSkyEntity, SkyEntityDrawInput } from "../AbstractSkyEntity.js";
+import { XYZMapDescriptor } from "./XYZMapDescriptor.js";
+import { ColorMap } from "../ColorMaps.js";
+import { SphereFoV } from "../SphereFoV.js";
+import type { XYZLayerDebugStats } from "./XYZConfig.js";
+export declare class XYZMap extends AbstractSkyEntity {
+    private _xyzShaderProgram;
+    private _descriptor;
+    private _visibleTilesManager;
+    private _tileBuffer;
+    private _meshBuilder;
+    private _baseurl;
+    private _zoom;
+    private _latLonGrid;
+    private _colorMapIdx;
+    private _colorMap;
+    constructor(radius: number, position: [number, number, number], xrad: number, yrad: number, descriptor: XYZMapDescriptor, webgl: WebGL2RenderingContext);
+    changeColorMap(colorMap: ColorMap): void;
+    private initShaders;
+    isLonLatGridVisible(): boolean;
+    toggleLonLatGrid(): boolean;
+    getFoV(): SphereFoV;
+    private refresh;
+    draw(input: SkyEntityDrawInput): void;
+    private createTile;
+    private getTilesToEnsure;
+    private findBestAvailableAncestor;
+    private resolveTileUrl;
+    getDebugStats(): XYZLayerDebugStats;
+    private tileKey;
+}

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

@@ -0,0 +1,208 @@
+/*
+ * 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 { AbstractSkyEntity } from "../AbstractSkyEntity.js";
+import { XYZVisibleTilesManager } from "./XYZVisibleTilesManager.js";
+import { xyzFovHelper } from "./XYZFoVHelper.js";
+import { ColorMaps } from "../ColorMaps.js";
+import { LatLonGrid } from "../grid/LonLatGrid.js";
+import { XYZShaderProgram } from "../../shader/XYZShaderProgram.js";
+import { XYZTileBuffer } from "./XYZTileBuffer.js";
+import { XYZAnchestorTile } from "./XYZAnchestorTile.js";
+import { XYZMeshBuilder } from "./XYZMeshBuilder.js";
+export class XYZMap extends AbstractSkyEntity {
+    _xyzShaderProgram;
+    _descriptor;
+    _visibleTilesManager;
+    _tileBuffer;
+    _meshBuilder;
+    _baseurl;
+    _zoom;
+    _latLonGrid;
+    _colorMapIdx = 0;
+    _colorMap = ColorMaps['native'];
+    constructor(radius, position, xrad, yrad, descriptor, webgl) {
+        super(radius, position, xrad, yrad, descriptor.name, webgl, false);
+        this._descriptor = descriptor;
+        this._xyzShaderProgram = new XYZShaderProgram(webgl);
+        this._meshBuilder = new XYZMeshBuilder();
+        this._tileBuffer = new XYZTileBuffer(1);
+        this.initGL(webgl);
+        this._latLonGrid = new LatLonGrid(radius, position, xrad, yrad, 'LatLonGrid', this._webgl);
+        this._visibleTilesManager = new XYZVisibleTilesManager();
+        this._baseurl = descriptor.url;
+        this.initShaders();
+        const fov = 180;
+        this._zoom = xyzFovHelper.getZoom(fov);
+    }
+    changeColorMap(colorMap) {
+        this._colorMap = colorMap;
+        switch (colorMap.name) {
+            case 'grayscale':
+                this._colorMapIdx = 1;
+                this._colorMap = ColorMaps['grayscale'];
+                break;
+            case 'planck':
+                this._colorMapIdx = 2;
+                this._colorMap = ColorMaps['planck'];
+                break;
+            case 'cmb':
+                this._colorMapIdx = 3;
+                this._colorMap = ColorMaps['cmb'];
+                break;
+            case 'rainbow':
+                this._colorMapIdx = 4;
+                this._colorMap = ColorMaps['rainbow'];
+                break;
+            case 'eosb':
+                this._colorMapIdx = 5;
+                this._colorMap = ColorMaps['eosb'];
+                break;
+            case 'cubehelix':
+                this._colorMapIdx = 6;
+                this._colorMap = ColorMaps['cubehelix'];
+                break;
+            case 'hot':
+                this._colorMapIdx = 7;
+                this._colorMap = ColorMaps['hot'];
+                break;
+            case 'gray':
+                this._colorMapIdx = 8;
+                this._colorMap = ColorMaps['gray'];
+                break;
+            case 'native':
+                this._colorMapIdx = 0;
+                this._colorMap = ColorMaps['native'];
+                break;
+            default:
+                this._colorMapIdx = 9;
+                this._colorMap = colorMap;
+        }
+    }
+    initShaders() {
+        this._xyzShaderProgram.enableProgram();
+    }
+    isLonLatGridVisible() {
+        return this._latLonGrid.isVisible();
+    }
+    toggleLonLatGrid() {
+        return this._latLonGrid.toggleShowGrid();
+    }
+    getFoV() {
+        return this._latLonGrid.getFoV();
+    }
+    refresh(input) {
+        const fov = this._latLonGrid.refreshFoV(input);
+        // this._zoom = this.resolveVisibleZoom(fov)
+        this._zoom = xyzFovHelper.getZoom(fov);
+    }
+    draw(input) {
+        const vMatrix = input.camera.getCameraMatrix();
+        if (!vMatrix)
+            return;
+        const pMatrix = input.pMatrix;
+        if (!pMatrix)
+            return;
+        this.refresh(input);
+        const mMatrix = this.getModelMatrix();
+        this._xyzShaderProgram.setRuntimeColorMap(this._colorMap);
+        const tileSelection = this._visibleTilesManager.computeVisibleTiles(this._zoom, this, this._webgl, input.camera, input.pMatrix);
+        const visibleTiles = tileSelection.visibleTiles;
+        const ancestorsMap = tileSelection.ancestorsMap;
+        const tileKeys = this._tileBuffer.ensureTiles(this.getTilesToEnsure(visibleTiles, ancestorsMap), (coord) => this.createTile(coord));
+        this._tileBuffer.evictCached(this._descriptor.maxCachedTiles);
+        for (const tileKey of tileKeys) {
+            const tile = this._tileBuffer.getActiveTile(tileKey);
+            if (!tile || tile.coord.z !== tileSelection.currentZoom) {
+                continue;
+            }
+            const drawn = tile.draw(pMatrix, vMatrix, mMatrix, this._colorMapIdx);
+            if (drawn) {
+                continue;
+            }
+            const ancestorTile = this.findBestAvailableAncestor(tile.coord);
+            ancestorTile?.draw(tileSelection.currentZoom, [tile.coord], ancestorsMap, pMatrix, vMatrix, mMatrix, this._colorMapIdx);
+        }
+        this._latLonGrid.draw(input);
+    }
+    createTile(coord) {
+        return new XYZAnchestorTile(coord, this.resolveTileUrl(coord), this._webgl, this._xyzShaderProgram, this._meshBuilder, this._descriptor.segmentsPerSide);
+    }
+    getTilesToEnsure(visibleTiles, ancestorsMap) {
+        const tilesByKey = new Map();
+        for (const tile of visibleTiles) {
+            tilesByKey.set(this.tileKey(tile), tile);
+        }
+        for (const ancestor of ancestorsMap.values()) {
+            tilesByKey.set(this.tileKey(ancestor), ancestor);
+        }
+        return Array.from(tilesByKey.values());
+    }
+    findBestAvailableAncestor(targetTile) {
+        for (let z = targetTile.z - 1; z >= 0; z--) {
+            const dz = targetTile.z - z;
+            const ancestorCoord = {
+                z,
+                x: targetTile.x >> dz,
+                y: targetTile.y >> dz,
+            };
+            const ancestorTile = this._tileBuffer.getAnyTile(this.tileKey(ancestorCoord));
+            if (ancestorTile?.ready) {
+                return ancestorTile;
+            }
+        }
+        return null;
+    }
+    resolveTileUrl(tile) {
+        const urlResolver = this._descriptor.urlResolver;
+        if (urlResolver) {
+            return urlResolver(tile);
+        }
+        const dim = 2 ** tile.z;
+        const y = this._descriptor.flipY ? dim - 1 - tile.y : tile.y;
+        const subdomains = this._descriptor.subdomains;
+        const subdomain = subdomains.length > 0
+            ? subdomains[Math.abs(tile.x + tile.y + tile.z) % subdomains.length]
+            : '';
+        return this._baseurl
+            .replace(/\{z\}/g, String(tile.z))
+            .replace(/\{x\}/g, String(tile.x))
+            .replace(/\{y\}/g, String(y))
+            .replace(/\{s\}/g, subdomain ?? '');
+    }
+    getDebugStats() {
+        const activeTiles = Array.from(this._tileBuffer.activeTiles.values(), (entry) => entry.tile);
+        const cachedTiles = Array.from(this._tileBuffer.cachedTiles.values(), (entry) => entry.tile);
+        const allTiles = [...activeTiles, ...cachedTiles];
+        const selection = this._visibleTilesManager.selection;
+        return {
+            cacheSize: this._tileBuffer.size,
+            visibleTileCount: selection.visibleTiles.length,
+            currentTileCount: activeTiles.filter((tile) => tile.coord.z === selection.currentZoom).length,
+            fallbackTileCount: selection.ancestorsMap.size,
+            coreTileCount: selection.visibleTiles.length,
+            coverageTileCount: selection.visibleTiles.length,
+            readyTileCount: allTiles.filter((tile) => tile.ready).length,
+            loadingTileCount: allTiles.filter((tile) => tile.loading).length,
+            coolingDownTileCount: 0,
+            currentZoom: selection.currentZoom,
+            tileSelectionKey: selection.key,
+            isSettling: false,
+            coarseTileCount: selection.ancestorsMap.size,
+            hasPendingSelection: false,
+            pendingSelectionKey: null,
+        };
+    }
+    tileKey(tile) {
+        return `${tile.z}/${tile.x}/${tile.y}`;
+    }
+}

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

@@ -0,0 +1,29 @@
+import type { XYZTileCoord } from './XYZTypes.js';
+export declare class XYZMapDescriptor {
+    _name: string;
+    _url: string;
+    _urlResolver?: (tile: XYZTileCoord) => string;
+    _minZoom?: number;
+    _maxZoom?: number;
+    _segmentsPerSide?: number;
+    _tileSize?: number;
+    _maxCachedTiles?: number;
+    _interactionDebounceMs?: number;
+    _subdomains?: string[];
+    _attribution?: string;
+    _flipY?: boolean;
+    _maxConcurrentLoads?: number;
+    constructor(name: string, url: string, minZoom?: number, maxZoom?: number, segmentsPerSide?: number, maxCachedTiles?: number, maxConcurrentLoads?: number, urlResolver?: (tile: XYZTileCoord) => string);
+    get url(): string;
+    get urlResolver(): ((tile: XYZTileCoord) => string) | undefined;
+    get name(): string;
+    get minZoom(): number;
+    get maxZoom(): number;
+    get segmentsPerSide(): number;
+    get maxCachedTiles(): number;
+    get interactionDebounceMs(): number;
+    get subdomains(): string[];
+    get attribution(): string;
+    get flipY(): boolean;
+    get maxConcurrentLoads(): number;
+}