uomtiles 0.1.0

package/dist/src/core/png.js

@@ -0,0 +1,192 @@
+import { deflateSync, inflateSync } from 'node:zlib';
+const SIGNATURE = Buffer.from('89504e470d0a1a0a', 'hex');
+const CRC_TABLE = new Uint32Array(256);
+for (let n = 0; n < 256; n++) {
+    let value = n;
+    for (let k = 0; k < 8; k++)
+        value = value & 1 ? 0xedb88320 ^ (value >>> 1) : value >>> 1;
+    CRC_TABLE[n] = value >>> 0;
+}
+function crc32(data) {
+    let crc = 0xffffffff;
+    for (const byte of data)
+        crc = CRC_TABLE[(crc ^ byte) & 0xff] ^ (crc >>> 8);
+    return (crc ^ 0xffffffff) >>> 0;
+}
+function chunk(type, data) {
+    const typeBytes = Buffer.from(type, 'ascii');
+    const body = Buffer.from(data);
+    const output = Buffer.allocUnsafe(body.length + 12);
+    output.writeUInt32BE(body.length, 0);
+    typeBytes.copy(output, 4);
+    body.copy(output, 8);
+    output.writeUInt32BE(crc32(Buffer.concat([typeBytes, body])), body.length + 8);
+    return output;
+}
+function decodeIndexedPng(png, allowLegacyCanonicalPhys) {
+    const input = Buffer.from(png);
+    if (!input.subarray(0, 8).equals(SIGNATURE))
+        throw new Error('UOM WMS did not return a PNG signature');
+    let offset = 8;
+    let width = 0, height = 0, bitDepth = 0, colorType = -1, interlace = -1;
+    let alpha = new Uint8Array(0);
+    let paletteEntries = 0;
+    const idat = [];
+    const chunkTypes = [];
+    while (offset + 12 <= input.length) {
+        const length = input.readUInt32BE(offset);
+        if (offset + length + 12 > input.length)
+            throw new Error('truncated UOM PNG chunk');
+        const type = input.toString('ascii', offset + 4, offset + 8);
+        chunkTypes.push(type);
+        const data = input.subarray(offset + 8, offset + 8 + length);
+        const expected = input.readUInt32BE(offset + 8 + length);
+        if (crc32(input.subarray(offset + 4, offset + 8 + length)) !== expected)
+            throw new Error(`invalid PNG ${type} CRC`);
+        if (type === 'IHDR') {
+            width = data.readUInt32BE(0);
+            height = data.readUInt32BE(4);
+            bitDepth = data[8];
+            colorType = data[9];
+            interlace = data[12];
+            if (data[10] !== 0 || data[11] !== 0)
+                throw new Error('unsupported UOM PNG compression or filter method');
+        }
+        else if (type === 'PLTE') {
+            if (data.length === 0 || data.length % 3 !== 0 || data.length > 768)
+                throw new Error('invalid UOM PNG palette');
+            paletteEntries = data.length / 3;
+        }
+        else if (type === 'tRNS')
+            alpha = Uint8Array.from(data);
+        else if (type === 'IDAT')
+            idat.push(data);
+        else if (type === 'IEND') {
+            offset += length + 12;
+            break;
+        }
+        offset += length + 12;
+    }
+    const hasIdatTail = (start) => chunkTypes.length > start + 1 &&
+        chunkTypes.at(-1) === 'IEND' && chunkTypes.slice(start, -1).every(type => type === 'IDAT');
+    const exactUom = chunkTypes[0] === 'IHDR' && chunkTypes[1] === 'PLTE' && chunkTypes[2] === 'tRNS' && hasIdatTail(3);
+    let canonicalDataStart = 2;
+    if (chunkTypes[canonicalDataStart] === 'tRNS')
+        canonicalDataStart++;
+    if (chunkTypes[canonicalDataStart] === 'pHYs')
+        canonicalDataStart++;
+    const legacyCanonical = allowLegacyCanonicalPhys && chunkTypes[0] === 'IHDR' && chunkTypes[1] === 'PLTE' && hasIdatTail(canonicalDataStart);
+    if ((!exactUom && !legacyCanonical) || offset !== input.length) {
+        throw new Error(`unexpected UOM PNG chunks: ${chunkTypes.join(',')}`);
+    }
+    if (width <= 0 || height <= 0 || colorType !== 3 || ![1, 2, 4, 8].includes(bitDepth) || interlace !== 0) {
+        throw new Error(`unexpected UOM PNG IHDR ${width}x${height} depth=${bitDepth} type=${colorType} interlace=${interlace}`);
+    }
+    if (paletteEntries === 0 || alpha.length > paletteEntries)
+        throw new Error('invalid UOM PNG palette transparency');
+    let hasVisiblePaletteEntry = false;
+    for (let index = 0; index < paletteEntries; index++) {
+        if ((alpha[index] ?? 255) >= 102) {
+            hasVisiblePaletteEntry = true;
+            break;
+        }
+    }
+    if (!hasVisiblePaletteEntry) {
+        return { width, height, bitDepth: bitDepth, paletteEntries, indexes: new Uint8Array(width * height), alpha };
+    }
+    const rowBytes = Math.ceil(width * bitDepth / 8);
+    const compressed = Buffer.concat(idat);
+    const expectedInflatedSize = (rowBytes + 1) * height;
+    const filtered = inflateSync(compressed, { maxOutputLength: expectedInflatedSize });
+    if (filtered.length !== expectedInflatedSize)
+        throw new Error('unexpected UOM PNG inflated size');
+    const rows = Buffer.allocUnsafe(rowBytes * height);
+    for (let y = 0; y < height; y++) {
+        const filter = filtered[y * (rowBytes + 1)];
+        const source = y * (rowBytes + 1) + 1;
+        const target = y * rowBytes;
+        for (let x = 0; x < rowBytes; x++) {
+            const raw = filtered[source + x];
+            const left = x > 0 ? rows[target + x - 1] : 0;
+            const up = y > 0 ? rows[target - rowBytes + x] : 0;
+            const upLeft = x > 0 && y > 0 ? rows[target - rowBytes + x - 1] : 0;
+            if (filter === 0)
+                rows[target + x] = raw;
+            else if (filter === 1)
+                rows[target + x] = (raw + left) & 0xff;
+            else if (filter === 2)
+                rows[target + x] = (raw + up) & 0xff;
+            else if (filter === 3)
+                rows[target + x] = (raw + Math.floor((left + up) / 2)) & 0xff;
+            else if (filter === 4) {
+                const p = left + up - upLeft;
+                const pa = Math.abs(p - left), pb = Math.abs(p - up), pc = Math.abs(p - upLeft);
+                rows[target + x] = (raw + (pa <= pb && pa <= pc ? left : pb <= pc ? up : upLeft)) & 0xff;
+            }
+            else
+                throw new Error(`unexpected UOM PNG row filter ${filter}`);
+        }
+    }
+    const indexes = new Uint8Array(width * height);
+    for (let y = 0; y < height; y++)
+        for (let x = 0; x < width; x++) {
+            const pixelsPerByte = 8 / bitDepth;
+            const packed = rows[y * rowBytes + Math.floor(x / pixelsPerByte)];
+            const shift = 8 - bitDepth * (x % pixelsPerByte + 1);
+            indexes[y * width + x] = (packed >> shift) & ((1 << bitDepth) - 1);
+            if (indexes[y * width + x] >= paletteEntries)
+                throw new Error('UOM PNG pixel index exceeds palette');
+        }
+    return { width, height, bitDepth: bitDepth, paletteEntries, indexes, alpha };
+}
+export function decodeUomIndexedPng(png) {
+    return decodeIndexedPng(png, false);
+}
+function alphaMask(image, expectedWidth, expectedHeight = expectedWidth) {
+    if (expectedWidth !== undefined && (image.width !== expectedWidth || image.height !== expectedHeight)) {
+        throw new Error(`UOM WMS returned ${image.width}x${image.height}, expected ${expectedWidth}x${expectedHeight}`);
+    }
+    const mask = new Uint8Array(image.indexes.length);
+    let hasVisiblePaletteEntry = false;
+    for (let index = 0; index < image.paletteEntries; index++) {
+        if ((image.alpha[index] ?? 255) >= 102) {
+            hasVisiblePaletteEntry = true;
+            break;
+        }
+    }
+    if (!hasVisiblePaletteEntry)
+        return mask;
+    for (let i = 0; i < mask.length; i++)
+        if ((image.alpha[image.indexes[i]] ?? 255) >= 102)
+            mask[i] = 1;
+    return mask;
+}
+export function decodeUomAlphaMask(png, expectedWidth, expectedHeight = expectedWidth) {
+    return alphaMask(decodeIndexedPng(png, false), expectedWidth, expectedHeight);
+}
+export function decodeCanonicalAlphaMask(png, expectedWidth, expectedHeight = expectedWidth) {
+    return alphaMask(decodeIndexedPng(png, true), expectedWidth, expectedHeight);
+}
+export function encodeIndexedPng(width, height, indexes, palette, alpha) {
+    if (indexes.length !== width * height)
+        throw new RangeError('indexed PNG dimensions do not match pixels');
+    if (palette.length === 0 || palette.length % 3 !== 0 || palette.length / 3 > 256)
+        throw new RangeError('invalid indexed PNG palette');
+    const raw = Buffer.allocUnsafe((width + 1) * height);
+    for (let y = 0; y < height; y++) {
+        raw[y * (width + 1)] = 0;
+        raw.set(indexes.subarray(y * width, (y + 1) * width), y * (width + 1) + 1);
+    }
+    const ihdr = Buffer.alloc(13);
+    ihdr.writeUInt32BE(width, 0);
+    ihdr.writeUInt32BE(height, 4);
+    ihdr[8] = 8;
+    ihdr[9] = 3;
+    ihdr[10] = 0;
+    ihdr[11] = 0;
+    ihdr[12] = 0;
+    return Buffer.concat([SIGNATURE, chunk('IHDR', ihdr), chunk('PLTE', palette), chunk('tRNS', alpha), chunk('IDAT', deflateSync(raw, { level: 9 })), chunk('IEND', Buffer.alloc(0))]);
+}
+export function encodeCanonicalMask(mask, width = 256, height = 256) {
+    return encodeIndexedPng(width, height, mask, Uint8Array.of(0, 0, 0, 0x29, 0x80, 0xb9), Uint8Array.of(0, 255));
+}

package/dist/src/core/raster-style.js

@@ -0,0 +1,33 @@
+import { encodeIndexedPng } from "./png.js";
+export const WEB_MERCATOR_HALF_WORLD = 20037508.342789244;
+export const WEB_MERCATOR_WORLD = WEB_MERCATOR_HALF_WORLD * 2;
+export function parseHexColor(color) {
+    if (!/^#[0-9a-f]{6}$/i.test(color))
+        throw new RangeError('color must use #RRGGBB');
+    return [Number.parseInt(color.slice(1, 3), 16), Number.parseInt(color.slice(3, 5), 16), Number.parseInt(color.slice(5, 7), 16)];
+}
+export function encodeStyledMask(mask, width, height, color, opacity) {
+    if (mask.length !== width * height)
+        throw new RangeError('mask dimensions do not match output');
+    if (!Number.isInteger(opacity) || opacity < 0 || opacity > 100)
+        throw new RangeError('opacity must be an integer from 0 to 100');
+    const [red, green, blue] = parseHexColor(color);
+    return encodeIndexedPng(width, height, mask, Uint8Array.of(0, 0, 0, red, green, blue), Uint8Array.of(0, Math.round(opacity * 2.55)));
+}
+export function zoomForMercatorImage(bbox, width, height, maxZoom = 18) {
+    const resolution = Math.max((bbox.maxx - bbox.minx) / width, (bbox.maxy - bbox.miny) / height);
+    return Math.max(0, Math.min(maxZoom, Math.round(Math.log2(WEB_MERCATOR_WORLD / (256 * resolution)))));
+}
+export function mercatorPixel(bbox, width, height, column, row, zoom) {
+    const mercatorX = bbox.minx + (column + 0.5) / width * (bbox.maxx - bbox.minx);
+    const mercatorY = bbox.maxy - (row + 0.5) / height * (bbox.maxy - bbox.miny);
+    const worldPixels = 256 * 2 ** zoom;
+    const globalX = Math.floor((mercatorX + WEB_MERCATOR_HALF_WORLD) / WEB_MERCATOR_WORLD * worldPixels);
+    const globalY = Math.floor((WEB_MERCATOR_HALF_WORLD - mercatorY) / WEB_MERCATOR_WORLD * worldPixels);
+    return {
+        tileX: Math.floor(globalX / 256),
+        tileY: Math.floor(globalY / 256),
+        pixelX: ((globalX % 256) + 256) % 256,
+        pixelY: ((globalY % 256) + 256) % 256,
+    };
+}

package/dist/src/core/uomtiles.js

@@ -0,0 +1,307 @@
+import { randomUUID } from 'node:crypto';
+import { copyFileSync, existsSync, mkdirSync, renameSync, statSync, unlinkSync } from 'node:fs';
+import { dirname, extname, resolve } from 'node:path';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { DatabaseSync } from 'node:sqlite';
+import { acquireSqliteLease } from "./lease.js";
+import { decodeCanonicalAlphaMask } from "./png.js";
+import { GeographicGridRenderer, PUBLISH_MAX_ZOOM } from "./grid-renderer.js";
+import { xyzYToTmsY } from "../bbox.js";
+const execFileAsync = promisify(execFile);
+const UOMTILES_SCHEMA_VERSION = 1;
+function tables(db) {
+    return new Set(db.prepare("SELECT name FROM sqlite_master WHERE type='table'").all().map(row => row.name));
+}
+function metadata(db) {
+    if (!tables(db).has('metadata'))
+        return {};
+    return Object.fromEntries(db.prepare('SELECT name,value FROM metadata').all().map(row => [row.name, row.value]));
+}
+export function initializeUomtiles(path, publisher) {
+    mkdirSync(dirname(path), { recursive: true });
+    const db = new DatabaseSync(path);
+    try {
+        db.exec(`
+      CREATE TABLE IF NOT EXISTS metadata(name TEXT PRIMARY KEY,value TEXT NOT NULL);
+      CREATE TABLE IF NOT EXISTS uomtiles_task(
+        id TEXT PRIMARY KEY,
+        schema_version INTEGER NOT NULL,
+        state TEXT NOT NULL,
+        publisher TEXT,
+        created_at TEXT NOT NULL,
+        started_at TEXT,
+        finished_at TEXT,
+        tool_version TEXT NOT NULL);
+      CREATE TABLE IF NOT EXISTS uomtiles_review(
+        kind TEXT NOT NULL,
+        object_key TEXT NOT NULL,
+        state TEXT NOT NULL,
+        note TEXT,
+        updated_at TEXT NOT NULL,
+        PRIMARY KEY(kind,object_key));
+      CREATE TABLE IF NOT EXISTS uomtiles_leases(
+        resource TEXT PRIMARY KEY,
+        owner TEXT NOT NULL,
+        pid INTEGER NOT NULL,
+        hostname TEXT NOT NULL,
+        acquired_at INTEGER NOT NULL,
+        heartbeat_at INTEGER NOT NULL,
+        expires_at INTEGER NOT NULL);
+    `);
+        const existing = db.prepare('SELECT id FROM uomtiles_task LIMIT 1').get();
+        if (!existing) {
+            const meta = metadata(db);
+            const createdAt = meta.crawl_started_at || new Date().toISOString();
+            const finishedAt = meta.crawl_finished_at || null;
+            db.prepare(`INSERT INTO uomtiles_task(id,schema_version,state,publisher,created_at,started_at,finished_at,tool_version)
+        VALUES(?,?,?,?,?,?,?,?)`).run(randomUUID(), UOMTILES_SCHEMA_VERSION, finishedAt ? 'completed' : 'incomplete', publisher || null, createdAt, meta.crawl_started_at || null, finishedAt, process.env.npm_package_version || '0.1.0');
+        }
+        const upsert = db.prepare('INSERT OR REPLACE INTO metadata(name,value) VALUES(?,?)');
+        upsert.run('uomtiles_schema_version', String(UOMTILES_SCHEMA_VERSION));
+        if (publisher)
+            upsert.run('publisher', publisher);
+    }
+    finally {
+        db.close();
+    }
+}
+export function migrateToUomtiles(source, target, publisher) {
+    const input = resolve(source);
+    const output = resolve(target);
+    if (!existsSync(input))
+        throw new Error(`输入文件不存在：${input}`);
+    if (existsSync(output))
+        throw new Error(`目标文件已存在：${output}`);
+    mkdirSync(dirname(output), { recursive: true });
+    copyFileSync(input, output, 0);
+    try {
+        initializeUomtiles(output, publisher);
+        return inspectUomtiles(output);
+    }
+    catch (error) {
+        unlinkSync(output);
+        throw error;
+    }
+}
+export function setTaskState(path, state, values = {}) {
+    initializeUomtiles(path, values.publisher);
+    const db = new DatabaseSync(path);
+    try {
+        db.prepare(`UPDATE uomtiles_task SET state=?,publisher=COALESCE(?,publisher),
+      started_at=COALESCE(?,started_at),finished_at=COALESCE(?,finished_at)`).run(state, values.publisher ?? null, values.startedAt ?? null, values.finishedAt ?? null);
+    }
+    finally {
+        db.close();
+    }
+}
+export function inspectUomtiles(path) {
+    const absolute = resolve(path);
+    const db = new DatabaseSync(absolute, { readOnly: true });
+    try {
+        const knownTables = tables(db);
+        const meta = metadata(db);
+        const task = knownTables.has('uomtiles_task')
+            ? db.prepare('SELECT * FROM uomtiles_task LIMIT 1').get()
+            : null;
+        const roots = knownTables.has('grid_roots')
+            ? Object.fromEntries(db.prepare('SELECT state,COUNT(*) count FROM grid_roots GROUP BY state').all().map(row => [row.state, row.count]))
+            : {};
+        const tiles = knownTables.has('tiles')
+            ? db.prepare('SELECT zoom_level z,COUNT(*) count,COALESCE(SUM(length(tile_data)),0) bytes FROM tiles GROUP BY zoom_level ORDER BY zoom_level').all()
+            : [];
+        return {
+            path: absolute,
+            bytes: statSync(absolute).size,
+            schemaVersion: task?.schema_version ?? (meta.uomtiles_schema_version ? Number(meta.uomtiles_schema_version) : null),
+            taskId: task?.id ?? null,
+            state: task?.state === 'completed' || meta.crawl_finished_at ? 'completed' : 'incomplete',
+            publisher: task?.publisher ?? meta.publisher ?? null,
+            createdAt: task?.created_at ?? meta.crawl_started_at ?? null,
+            startedAt: task?.started_at ?? meta.crawl_started_at ?? null,
+            finishedAt: task?.finished_at ?? meta.crawl_finished_at ?? null,
+            sourceZoom: meta.source_zoom ? Number(meta.source_zoom) : null,
+            gridLevel: meta.geographic_grid_level ? Number(meta.geographic_grid_level) : null,
+            roots,
+            tiles,
+        };
+    }
+    finally {
+        db.close();
+    }
+}
+export function exportMbtiles(source, target) {
+    const input = resolve(source);
+    const output = resolve(target);
+    if (extname(output).toLowerCase() !== '.mbtiles')
+        throw new Error('MBTiles 输出文件必须使用 .mbtiles 扩展名');
+    const lock = acquireSqliteLease(input, 'writer');
+    const temporary = `${output}.${process.pid}.tmp`;
+    if (existsSync(temporary))
+        unlinkSync(temporary);
+    mkdirSync(dirname(output), { recursive: true });
+    const sourceDb = new DatabaseSync(input, { readOnly: true });
+    const outputDb = new DatabaseSync(temporary);
+    try {
+        outputDb.exec(`PRAGMA journal_mode=OFF; PRAGMA synchronous=OFF;
+      CREATE TABLE metadata(name TEXT PRIMARY KEY,value TEXT NOT NULL);
+      CREATE TABLE tiles(zoom_level INTEGER NOT NULL,tile_column INTEGER NOT NULL,tile_row INTEGER NOT NULL,tile_data BLOB NOT NULL,
+        PRIMARY KEY(zoom_level,tile_column,tile_row));`);
+        const insertMeta = outputDb.prepare('INSERT INTO metadata(name,value) VALUES(?,?)');
+        const standard = new Set(['name', 'type', 'version', 'description', 'format', 'bounds', 'center', 'minzoom', 'attribution']);
+        const meta = metadata(sourceDb);
+        outputDb.exec('BEGIN');
+        for (const name of standard)
+            if (meta[name])
+                insertMeta.run(name, meta[name]);
+        const summary = inspectUomtiles(input);
+        insertMeta.run('uomtiles:publisher', summary.publisher || 'unknown');
+        insertMeta.run('uomtiles:fetched_at', summary.finishedAt || summary.startedAt || 'unknown');
+        insertMeta.run('uomtiles:source_zoom', String(summary.sourceZoom ?? 'unknown'));
+        insertMeta.run('uomtiles:grid_level', String(summary.gridLevel ?? 'unknown'));
+        const renderer = new GeographicGridRenderer(input);
+        insertMeta.run('maxzoom', String(renderer.available ? PUBLISH_MAX_ZOOM : Math.max(0, ...summary.tiles.map(tile => tile.z))));
+        const insertTile = outputDb.prepare('INSERT INTO tiles VALUES(?,?,?,?)');
+        let copied = 0;
+        if (renderer.available) {
+            for (let z = 0; z <= PUBLISH_MAX_ZOOM; z++)
+                for (const coordinate of renderer.contentCoordinates(z)) {
+                    const tile = renderer.renderTile(z, coordinate.x, coordinate.y);
+                    if (!tile)
+                        continue;
+                    insertTile.run(z, coordinate.x, xyzYToTmsY(z, coordinate.y), tile);
+                    copied++;
+                    if (copied % 1_000 === 0)
+                        lock.heartbeat();
+                }
+        }
+        else {
+            for (const row of sourceDb.prepare('SELECT zoom_level,tile_column,tile_row,tile_data FROM tiles ORDER BY zoom_level,tile_column,tile_row').iterate()) {
+                insertTile.run(row.zoom_level, row.tile_column, row.tile_row, row.tile_data);
+                copied++;
+                if (copied % 1_000 === 0)
+                    lock.heartbeat();
+            }
+        }
+        lock.heartbeat();
+        outputDb.exec('COMMIT');
+        outputDb.exec('CREATE UNIQUE INDEX tile_index ON tiles(zoom_level,tile_column,tile_row); PRAGMA optimize;');
+    }
+    catch (error) {
+        try {
+            outputDb.exec('ROLLBACK');
+        }
+        catch { }
+        throw error;
+    }
+    finally {
+        outputDb.close();
+        sourceDb.close();
+        lock.release();
+    }
+    if (existsSync(output))
+        unlinkSync(output);
+    renameSync(temporary, output);
+    return inspectUomtiles(output);
+}
+export async function exportTiles(source, target, pmtilesCommand = process.env.UOMTILES_PMTILES_COMMAND || 'pmtiles') {
+    const extension = extname(target).toLowerCase();
+    if (extension === '.mbtiles') {
+        exportMbtiles(source, target);
+        return;
+    }
+    if (extension !== '.pmtiles')
+        throw new Error('输出文件必须使用 .mbtiles 或 .pmtiles 扩展名');
+    const intermediate = `${resolve(target)}.${process.pid}.mbtiles`;
+    try {
+        exportMbtiles(source, intermediate);
+        await execFileAsync(pmtilesCommand, ['convert', intermediate, resolve(target), '--force', '--quiet'], { timeout: 30 * 60_000 });
+    }
+    catch (error) {
+        if (error?.code === 'ENOENT')
+            throw new Error(`找不到 ${pmtilesCommand}；请安装 Protomaps pmtiles CLI 或设置 UOMTILES_PMTILES_COMMAND`);
+        throw error;
+    }
+    finally {
+        if (existsSync(intermediate))
+            unlinkSync(intermediate);
+    }
+}
+export function diffUomtiles(leftPath, rightPath) {
+    const left = new DatabaseSync(resolve(leftPath), { readOnly: true });
+    const right = new DatabaseSync(resolve(rightPath), { readOnly: true });
+    try {
+        const tileMap = (db) => new Map(db.prepare('SELECT zoom_level,tile_column,tile_row,tile_data FROM tiles ORDER BY zoom_level,tile_column,tile_row').all()
+            .map(row => [`${row.zoom_level}/${row.tile_column}/${row.tile_row}`, {
+                z: row.zoom_level,
+                x: row.tile_column,
+                y: (2 ** row.zoom_level - 1 - row.tile_row),
+                data: row.tile_data,
+            }]));
+        const ignored = new Set(['version', 'crawl_started_at', 'crawl_finished_at', 'publisher', 'validation_report', 'grid_root_completed']);
+        const isIgnoredMetadata = (name) => ignored.has(name) || /^derived_z\d+_completed_at$/.test(name);
+        const lm = metadata(left), rm = metadata(right);
+        const names = [...new Set([...Object.keys(lm), ...Object.keys(rm)])].filter(name => !isIgnoredMetadata(name)).sort();
+        const metadataDiff = names.filter(name => (lm[name] ?? null) !== (rm[name] ?? null)).map(name => ({ name, left: lm[name] ?? null, right: rm[name] ?? null }));
+        const leftTiles = tileMap(left), rightTiles = tileMap(right);
+        const keys = new Set([...leftTiles.keys(), ...rightTiles.keys()]);
+        const items = [];
+        let compared = 0, missingLeft = 0, missingRight = 0, diffPixels = 0, addedPixels = 0, removedPixels = 0;
+        for (const key of keys) {
+            const leftTile = leftTiles.get(key), rightTile = rightTiles.get(key);
+            if (leftTile && rightTile)
+                compared++;
+            if (!leftTile)
+                missingLeft++;
+            if (!rightTile)
+                missingRight++;
+            const leftMask = leftTile ? decodeCanonicalAlphaMask(leftTile.data, 256) : new Uint8Array(256 * 256);
+            const rightMask = rightTile ? decodeCanonicalAlphaMask(rightTile.data, 256) : new Uint8Array(256 * 256);
+            let tileAdded = 0, tileRemoved = 0, leftPixels = 0, rightPixels = 0;
+            for (let pixel = 0; pixel < leftMask.length; pixel++) {
+                const leftVisible = leftMask[pixel] !== 0, rightVisible = rightMask[pixel] !== 0;
+                if (leftVisible)
+                    leftPixels++;
+                if (rightVisible)
+                    rightPixels++;
+                if (leftVisible === rightVisible)
+                    continue;
+                if (rightVisible)
+                    tileAdded++;
+                else
+                    tileRemoved++;
+            }
+            const tileDiff = tileAdded + tileRemoved;
+            diffPixels += tileDiff;
+            addedPixels += tileAdded;
+            removedPixels += tileRemoved;
+            if (tileDiff === 0)
+                continue;
+            const coordinate = leftTile || rightTile;
+            items.push({
+                z: coordinate.z, x: coordinate.x, y: coordinate.y,
+                diffPixels: tileDiff, diffPercent: tileDiff / (256 * 256) * 100,
+                addedPixels: tileAdded, removedPixels: tileRemoved, leftPixels, rightPixels,
+                missingLeft: !leftTile, missingRight: !rightTile,
+            });
+        }
+        items.sort((a, b) => b.diffPercent - a.diffPercent || b.diffPixels - a.diffPixels || b.z - a.z || a.x - b.x || a.y - b.y);
+        const tiles = {
+            total: keys.size,
+            compared,
+            changed: items.length,
+            identical: keys.size - items.length,
+            missingLeft,
+            missingRight,
+            diffPixels,
+            addedPixels,
+            removedPixels,
+            items,
+        };
+        return { identical: items.length === 0 && metadataDiff.length === 0, tiles, metadata: metadataDiff };
+    }
+    finally {
+        left.close();
+        right.close();
+    }
+}