feat(geo): generate a quadkey mapper for tile sets that are not quite square

packages/geo/src/__tests__/tms.quad.key.test.ts

@@ -0,0 +1,68 @@
+import { GoogleTms } from '../tms/google';
+import { TileMatrixSetQuadKey } from '../tms.quad.key';
+import { Nztm2000Tms } from '../tms/nztm2000';
+import * as o from 'ospec';
+import { QuadKey } from '../quad.key';
+
+o.spec('TileMatrixSetQuadKey', () => {
+    const googleQk = new TileMatrixSetQuadKey(GoogleTms);
+    const Nztm2000Qk = new TileMatrixSetQuadKey(Nztm2000Tms);
+
+    o.spec('GoogleTmsQk', () => {
+        o('toTile', () => {
+            o(googleQk.toTile('')).deepEquals({ x: 0, y: 0, z: 0 });
+            o(googleQk.toTile('31')).deepEquals({ x: 3, y: 2, z: 2 });
+            o(googleQk.toTile('31021')).deepEquals({ x: 25, y: 18, z: 5 });
+        });
+
+        o('toTile all zooms', () => {
+            for (let z = 0; z < googleQk.tms.zooms.length; z++) {
+                const qk = QuadKey.fromTile({ x: 0, y: 0, z });
+                o(googleQk.toTile(qk)).deepEquals({ x: 0, y: 0, z });
+            }
+        });
+
+        o('fromTile', () => {
+            o(googleQk.fromTile({ x: 0, y: 0, z: 0 })).equals('');
+            o(googleQk.fromTile({ x: 3, y: 2, z: 2 })).equals('31');
+            o(googleQk.fromTile({ x: 25, y: 18, z: 5 })).equals('31021');
+            o(googleQk.fromTile({ x: 2 ** 24 - 1, y: 0, z: 24 })).equals('111111111111111111111111');
+            o(googleQk.fromTile({ x: 0, y: 2 ** 24 - 1, z: 24 })).equals('222222222222222222222222');
+            o(googleQk.fromTile({ x: 2 ** 24 - 1, y: 2 ** 24 - 1, z: 24 })).equals('333333333333333333333333');
+        });
+    });
+
+    o.spec('Nztm2000Qk', () => {
+        o('should calculate offsets', () => {
+            o(Nztm2000Qk.zMax).equals(8);
+            o(Nztm2000Qk.zOffset).equals(2);
+        });
+
+        o('toTile', () => {
+            o(Nztm2000Qk.toTile('22')).deepEquals({ x: 0, y: 3, z: 0 });
+            o(Nztm2000Qk.toTile('213')).deepEquals({ x: 3, y: 5, z: 1 });
+            o(Nztm2000Qk.toTile('21021')).deepEquals({ x: 9, y: 18, z: 3 });
+        });
+
+        o('should throw if out of bounds', () => {
+            o(() => Nztm2000Qk.toTile('')).throws(Error);
+            o(() => Nztm2000Qk.toTile('33')).throws(Error);
+            o(() => Nztm2000Qk.toTile('0'.repeat(10))).throws(Error);
+            o(() => Nztm2000Qk.fromTile({ x: 0, y: 0, z: 8 })).throws(Error);
+        });
+
+        o('round trip all of z0-z8', () => {
+            for (let z = 0; z < 8; z++) {
+                const zoom = Nztm2000Tms.zooms[z];
+                for (let x = 0; x < Math.min(zoom.matrixWidth, 25); x++) {
+                    for (let y = 0; y < Math.min(zoom.matrixHeight, 25); y++) {
+                        const sourceTile = { x, y, z };
+                        const qk = Nztm2000Qk.fromTile(sourceTile);
+                        const reverse = Nztm2000Qk.toTile(qk);
+                        o(reverse).deepEquals(sourceTile);
+                    }
+                }
+            }
+        });
+    });
+});

packages/geo/src/index.ts

@@ -4,3 +4,4 @@ export { GeoJson } from './geo.json';
 export { Epsg, EpsgCode } from './epsg';
 export { TileMatrixSet, Tile } from './tile.matrix.set';
 export { WmtsLayer, WmtsProvider } from './wmts/wmts';
+export { TileMatrixSetQuadKey } from './tms.quad.key';

packages/geo/src/tms.quad.key.ts

@@ -0,0 +1,88 @@
+import { QuadKey } from './quad.key';
+import { Tile, TileMatrixSet } from './tile.matrix.set';
+
+export class TileMatrixSetQuadKey {
+    tms: TileMatrixSet;
+    /**
+     *  Quadkeys need to have a tile that is 1x1 at the root level qk:""
+     *  this offset is the number of zoom levels that are made up to make "" a 1x1 tile
+     */
+    zOffset = 0;
+
+    /**
+     * Maximum zoom level that can be represented as a quad key
+     *
+     * All tiles have be `tile.z < zMax`
+     */
+    zMax = 0;
+
+    constructor(tms: TileMatrixSet) {
+        this.tms = tms;
+
+        const [firstZoom] = tms.zooms;
+        // If this tile matrix set does not have a 1x1 root tile, we need to zoom out until we can make a psuedo z0
+        if (firstZoom.matrixWidth != 1 || firstZoom.matrixHeight != 1) {
+            this.calculateZOffset();
+        }
+
+        // Find the highest zoom tile that is still a power of two
+        const scaleDenominator = firstZoom.scaleDenominator;
+        for (const z of tms.zooms) {
+            if (z.tileHeight != z.tileWidth) throw new Error('Only square tiles supported');
+            if (z.tileHeight != tms.tileSize) throw new Error('All tiles must have the same tile size');
+
+            const scale = Math.log2(scaleDenominator / z.scaleDenominator);
+            // Is this zoom close to being a power of two, sometimes floating point math gets in the way `1.9999999996`
+            if (!Number.isInteger(Math.round(scale * 1e6) / 1e6)) {
+                break;
+            }
+            this.zMax++;
+        }
+    }
+
+    calculateZOffset(): void {
+        const [firstZoom] = this.tms.zooms;
+
+        const biggestXy = Math.max(firstZoom.matrixWidth, firstZoom.matrixHeight);
+        this.zOffset = Math.log2(biggestXy);
+        // TODO we could pad the width/height out to a power of 2 tile count
+        if (!Number.isInteger(this.zOffset)) throw new Error('Unable to find suitable zOffset');
+    }
+
+    /**
+     * Attempt to convert a quadkey to a tile index
+     *
+     * This will throw if the quadkey does not map to a tile inside the tile matrix set
+     *
+     * @param qk Quadkey to convert
+     */
+    toTile(qk: string): Tile {
+        const tile = QuadKey.toTile(qk);
+        if (this.zOffset != 0) tile.z -= this.zOffset;
+
+        if (tile.z < 0) throw new Error(`QuadKey "${qk}" does not map to a tile`);
+        if (tile.z >= this.zMax) throw new Error(`QuadKey "${qk}" does not map to a tile`);
+
+        const zoom = this.tms.zooms[tile.z];
+        if (zoom == null) throw new Error(`QuadKey "${qk}" does not map to a tile`);
+        if (tile.x >= zoom.matrixWidth) throw new Error(`QuadKey "${qk}" does not map to a tile`);
+        if (tile.y >= zoom.matrixHeight) throw new Error(`QuadKey "${qk}" does not map to a tile`);
+
+        return tile;
+    }
+
+    /**
+     * Convert a tile to a quadkey
+     *
+     * this will throw if tile is outside of the bounds of the quad key
+     *
+     * @param tile Tile to convert
+     */
+    fromTile(tile: Tile): string {
+        const newTile = { x: tile.x, y: tile.y, z: tile.z }; // Do not adjust with the source tile
+        if (tile.z >= this.zMax) throw new Error(`tile ${tile.x},${tile.y} z${tile.z} does not map to a quad key`);
+        if (this.zOffset != 0) newTile.z += this.zOffset;
+
+        return QuadKey.fromTile(newTile);
+    }
+}