uomtiles 0.1.0

package/dist/src/grid-crawl.js

@@ -0,0 +1,478 @@
+import { existsSync, mkdirSync, readFileSync, unlinkSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+import { createHash } from 'node:crypto';
+import pLimit from 'p-limit';
+import { CHINA_BBOX_LL, DEFAULTS } from "./config.js";
+import { tileRangeForBBox, xyzYToTmsY } from "./bbox.js";
+import { GEOGRAPHIC_GRID_LEVEL, geographicGridLines, renderGeographicGrid, vectorizeGeographicGrid } from "./geographic-grid.js";
+import { fetchOfficialSupertileMask } from "./official-grid.js";
+import { UomFetcher } from "./fetcher.js";
+import { TokenStore } from "./token.js";
+import { encodeMask, maskHasContent } from "./mask-image.js";
+import { acquireSqliteLease } from "./core/lease.js";
+import { initializeUomtiles, setTaskState } from "./core/uomtiles.js";
+export const DEFAULT_GRID_CRAWL_OPTIONS = {
+    sourceZ: 12,
+    rootConcurrency: 2,
+    qps: 12,
+    resume: true,
+    root: null,
+};
+const rootZ = 9;
+const materializedZMax = 12;
+const sourceSize = 256 * 2 ** (materializedZMax - rootZ);
+const rootDeadlineMs = 5 * 60_000;
+const maxRootPasses = 3;
+function validateOptions(args) {
+    if (args.sourceZ !== 12)
+        throw new RangeError('validated production source zoom is exactly z12');
+    if (!Number.isInteger(args.rootConcurrency) || args.rootConcurrency < 1 || args.rootConcurrency > 8) {
+        throw new RangeError('root concurrency must be an integer from 1 to 8');
+    }
+}
+function rootsForChina() {
+    const range = tileRangeForBBox(rootZ, CHINA_BBOX_LL.lonMin, CHINA_BBOX_LL.latMin, CHINA_BBOX_LL.lonMax, CHINA_BBOX_LL.latMax);
+    const roots = [];
+    for (let y = range.yMin; y <= range.yMax; y++) {
+        for (let x = range.xMin; x <= range.xMax; x++)
+            roots.push({ x, y });
+    }
+    return roots;
+}
+function encodeRectangles(rects) {
+    const buffer = Buffer.allocUnsafe(rects.length * 8);
+    for (let i = 0; i < rects.length; i++) {
+        const rect = rects[i];
+        buffer.writeUInt16LE(rect.col0, i * 8);
+        buffer.writeUInt16LE(rect.row0, i * 8 + 2);
+        buffer.writeUInt16LE(rect.col1, i * 8 + 4);
+        buffer.writeUInt16LE(rect.row1, i * 8 + 6);
+    }
+    return buffer;
+}
+function extractMask(canvas, size, tileX, tileY) {
+    const tile = new Uint8Array(256 * 256);
+    for (let y = 0; y < 256; y++) {
+        const sourceOffset = (tileY * 256 + y) * size + tileX * 256;
+        tile.set(canvas.subarray(sourceOffset, sourceOffset + 256), y * 256);
+    }
+    return tile;
+}
+function formatDuration(milliseconds) {
+    if (!Number.isFinite(milliseconds))
+        return 'unknown';
+    const seconds = Math.max(0, Math.floor(milliseconds / 1000));
+    return `${Math.floor(seconds / 3600)}h${String(Math.floor(seconds % 3600 / 60)).padStart(2, '0')}m${String(seconds % 60).padStart(2, '0')}s`;
+}
+function removeSqliteSidecars(path) {
+    for (const suffix of ['-wal', '-shm']) {
+        const sidecar = `${path}${suffix}`;
+        if (existsSync(sidecar))
+            unlinkSync(sidecar);
+    }
+}
+class GridDatabase {
+    db;
+    insertTile;
+    constructor(path) {
+        mkdirSync(dirname(path), { recursive: true });
+        this.db = new DatabaseSync(path);
+        this.db.exec(`
+      PRAGMA journal_mode=WAL;
+      PRAGMA synchronous=NORMAL;
+      PRAGMA mmap_size=268435456;
+      PRAGMA page_size=8192;
+      PRAGMA temp_store=MEMORY;
+      CREATE TABLE IF NOT EXISTS metadata(name TEXT PRIMARY KEY, value TEXT NOT NULL);
+      CREATE TABLE IF NOT EXISTS 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));
+      CREATE TABLE IF NOT EXISTS tile_meta(
+        zoom_level INTEGER NOT NULL,
+        tile_column INTEGER NOT NULL,
+        tile_row INTEGER NOT NULL,
+        layer_mask INTEGER NOT NULL,
+        strat_summary TEXT NOT NULL,
+        fetched_at INTEGER NOT NULL,
+        source_kind TEXT NOT NULL,
+        derivation_source_z INTEGER,
+        PRIMARY KEY(zoom_level, tile_column, tile_row));
+      CREATE TABLE IF NOT EXISTS grid_roots(
+        root_z INTEGER NOT NULL,
+        root_x INTEGER NOT NULL,
+        root_y INTEGER NOT NULL,
+        source_z INTEGER NOT NULL,
+        state TEXT NOT NULL,
+        attempts INTEGER NOT NULL DEFAULT 0,
+        rect_count INTEGER NOT NULL DEFAULT 0,
+        rectangles BLOB,
+        rectangles_sha256 TEXT,
+        content_tiles INTEGER NOT NULL DEFAULT 0,
+        last_error TEXT,
+        started_at INTEGER,
+        finished_at INTEGER,
+        heartbeat_at INTEGER NOT NULL,
+        PRIMARY KEY(root_z, root_x, root_y));
+      CREATE INDEX IF NOT EXISTS grid_roots_state ON grid_roots(state);
+    `);
+        this.insertTile = this.db.prepare('INSERT OR REPLACE INTO tiles(zoom_level,tile_column,tile_row,tile_data) VALUES(?,?,?,?)');
+    }
+    setMetadata(values) {
+        const statement = this.db.prepare('INSERT OR REPLACE INTO metadata(name,value) VALUES(?,?)');
+        this.db.exec('BEGIN');
+        try {
+            for (const [name, value] of Object.entries(values))
+                statement.run(name, value);
+            this.db.exec('COMMIT');
+        }
+        catch (error) {
+            this.db.exec('ROLLBACK');
+            throw error;
+        }
+    }
+    initializeRoots(roots) {
+        const statement = this.db.prepare(`INSERT OR IGNORE INTO grid_roots(
+      root_z,root_x,root_y,source_z,state,heartbeat_at) VALUES(?,?,?,?, 'pending', ?)`);
+        const now = Date.now();
+        this.db.exec('BEGIN');
+        try {
+            for (const root of roots)
+                statement.run(rootZ, root.x, root.y, materializedZMax, now);
+            this.db.exec('COMMIT');
+        }
+        catch (error) {
+            this.db.exec('ROLLBACK');
+            throw error;
+        }
+    }
+    completed(root) {
+        const row = this.db.prepare('SELECT state FROM grid_roots WHERE root_z=? AND root_x=? AND root_y=?')
+            .get(rootZ, root.x, root.y);
+        return row?.state === 'completed';
+    }
+    start(root) {
+        const now = Date.now();
+        this.db.prepare(`UPDATE grid_roots SET state='running',attempts=attempts+1,last_error=NULL,
+      started_at=?,heartbeat_at=? WHERE root_z=? AND root_x=? AND root_y=?`).run(now, now, rootZ, root.x, root.y);
+    }
+    fail(root, error) {
+        const now = Date.now();
+        this.db.prepare(`UPDATE grid_roots SET state='failed',last_error=?,heartbeat_at=?
+      WHERE root_z=? AND root_x=? AND root_y=?`).run(error, now, rootZ, root.x, root.y);
+    }
+    commitRoot(root, rects, tiles) {
+        const now = Date.now();
+        const rectangles = encodeRectangles(rects);
+        const checksum = createHash('sha256').update(rectangles).digest('hex');
+        this.db.exec('BEGIN');
+        try {
+            for (let z = rootZ; z <= materializedZMax; z++) {
+                const scale = 2 ** (z - rootZ);
+                this.db.prepare(`DELETE FROM tiles WHERE zoom_level=? AND tile_column>=? AND tile_column<?
+          AND tile_row>=? AND tile_row<?`).run(z, root.x * scale, (root.x + 1) * scale, xyzYToTmsY(z, (root.y + 1) * scale - 1), xyzYToTmsY(z, root.y * scale) + 1);
+                this.db.prepare(`DELETE FROM tile_meta WHERE zoom_level=? AND tile_column>=? AND tile_column<?
+          AND tile_row>=? AND tile_row<?`).run(z, root.x * scale, (root.x + 1) * scale, xyzYToTmsY(z, (root.y + 1) * scale - 1), xyzYToTmsY(z, root.y * scale) + 1);
+            }
+            const insertMeta = this.db.prepare(`INSERT OR REPLACE INTO tile_meta(
+        zoom_level,tile_column,tile_row,layer_mask,strat_summary,fetched_at,source_kind,derivation_source_z)
+        VALUES(?,?,?,?,?,?,?,?)`);
+            for (const tile of tiles) {
+                const tmsY = xyzYToTmsY(tile.z, tile.y);
+                this.insertTile.run(tile.z, tile.x, tmsY, tile.png);
+                insertMeta.run(tile.z, tile.x, tmsY, 1, 'official-grid-z12', now, 'derived-grid', null);
+            }
+            this.db.prepare(`UPDATE grid_roots SET state='completed',rect_count=?,rectangles=?,rectangles_sha256=?,
+        content_tiles=?,last_error=NULL,finished_at=?,heartbeat_at=?
+        WHERE root_z=? AND root_x=? AND root_y=?`).run(rects.length, rectangles, checksum, tiles.length, now, now, rootZ, root.x, root.y);
+            this.db.exec('COMMIT');
+        }
+        catch (error) {
+            this.db.exec('ROLLBACK');
+            throw error;
+        }
+    }
+    summary() {
+        const rows = this.db.prepare(`SELECT state,COUNT(*) count,COALESCE(SUM(rect_count),0) rectangles,
+      COALESCE(SUM(content_tiles),0) content_tiles FROM grid_roots GROUP BY state`).all();
+        const result = { pending: 0, running: 0, completed: 0, failed: 0, rectangles: 0, contentTiles: 0 };
+        for (const row of rows) {
+            if (row.state === 'pending')
+                result.pending = row.count;
+            else if (row.state === 'running')
+                result.running = row.count;
+            else if (row.state === 'completed')
+                result.completed = row.count;
+            else if (row.state === 'failed')
+                result.failed = row.count;
+            result.rectangles += row.rectangles;
+            result.contentTiles += row.content_tiles;
+        }
+        return result;
+    }
+    failedRoots() {
+        return this.db.prepare(`SELECT root_x x,root_y y FROM grid_roots WHERE state IN ('failed','running') ORDER BY root_y,root_x`).all();
+    }
+    retainSourceZoom() {
+        this.db.exec('BEGIN');
+        try {
+            this.db.prepare('DELETE FROM tiles WHERE zoom_level<>?').run(materializedZMax);
+            this.db.prepare('DELETE FROM tile_meta WHERE zoom_level<>?').run(materializedZMax);
+            this.db.exec('COMMIT');
+        }
+        catch (error) {
+            this.db.exec('ROLLBACK');
+            throw error;
+        }
+    }
+    countsByZoom() {
+        return this.db.prepare('SELECT zoom_level z,COUNT(*) count FROM tiles GROUP BY zoom_level ORDER BY zoom_level').all();
+    }
+    optimize() {
+        this.db.exec('PRAGMA optimize');
+    }
+    close() {
+        this.db.close();
+    }
+}
+async function fetchSourceMask(fetcher, token, root, signal) {
+    let lastError;
+    for (let attempt = 0; attempt < DEFAULTS.retryMax; attempt++) {
+        try {
+            return await fetchOfficialSupertileMask({ fetcher, token, z: rootZ, x: root.x, y: root.y, signal }, sourceSize);
+        }
+        catch (error) {
+            lastError = error;
+            if (signal.aborted)
+                throw signal.reason;
+            if (attempt + 1 < DEFAULTS.retryMax)
+                await new Promise(resolve => setTimeout(resolve, 1_000 * (attempt + 1)));
+        }
+    }
+    throw lastError;
+}
+async function materializeRoot(rects, root) {
+    const sourceExtent = { sourceZ: materializedZMax, parentZ: rootZ, parentX: root.x, parentY: root.y, width: sourceSize };
+    const lines = geographicGridLines(sourceExtent);
+    const model = { rects, xLines: lines.xLines, yLines: lines.yLines };
+    const encodeLimit = pLimit(8);
+    const encoded = [];
+    for (const z of [materializedZMax]) {
+        const tilesPerSide = 2 ** (z - rootZ);
+        const size = tilesPerSide * 256;
+        const canvas = renderGeographicGrid(model, sourceSize, size);
+        const jobs = [];
+        for (let localY = 0; localY < tilesPerSide; localY++)
+            for (let localX = 0; localX < tilesPerSide; localX++) {
+                const mask = extractMask(canvas, size, localX, localY);
+                if (!maskHasContent(mask))
+                    continue;
+                jobs.push(encodeLimit(async () => {
+                    const png = await encodeMask(mask);
+                    if (png)
+                        encoded.push({
+                            z,
+                            x: root.x * tilesPerSide + localX,
+                            y: root.y * tilesPerSide + localY,
+                            png,
+                        });
+                }));
+            }
+        await Promise.all(jobs);
+    }
+    return encoded;
+}
+export async function runGridCrawl(args) {
+    validateOptions(args);
+    const auth = JSON.parse(readFileSync(args.auth, 'utf8'));
+    if (!auth.sessionToken)
+        throw new Error('persisted UOM session is unavailable');
+    const lock = acquireSqliteLease(args.db, 'writer');
+    try {
+        initializeUomtiles(args.db, auth.username || null);
+        setTaskState(args.db, 'incomplete', { publisher: auth.username || null, startedAt: new Date().toISOString() });
+    }
+    catch (error) {
+        lock.release();
+        throw error;
+    }
+    const database = new GridDatabase(args.db);
+    const token = new TokenStore({ sessionToken: auth.sessionToken, mapToken: auth.mapToken, mapTokenExpiresAt: auth.mapTokenExpiresAt });
+    const fetcher = new UomFetcher(args.qps);
+    const shutdown = new AbortController();
+    let stopping = false;
+    let leaseFailure = null;
+    const stop = (reason = new Error('grid crawl stopped')) => {
+        if (stopping)
+            return;
+        stopping = true;
+        shutdown.abort(reason);
+        console.error('[grid-crawl] graceful stop requested');
+    };
+    process.once('SIGINT', () => stop());
+    process.once('SIGTERM', () => stop());
+    const assertWriter = () => {
+        try {
+            lock.heartbeat();
+        }
+        catch (error) {
+            if (!leaseFailure) {
+                leaseFailure = new Error('SQLite lease lost; refusing further task writes', { cause: error });
+                console.error(`[grid-crawl] ${leaseFailure.message}`);
+                stop(leaseFailure);
+            }
+            throw leaseFailure;
+        }
+    };
+    const roots = args.root ? [args.root] : rootsForChina();
+    database.initializeRoots(roots);
+    database.setMetadata({
+        name: 'UOM-shifei-geographic-grid',
+        type: 'overlay',
+        version: new Date().toISOString().slice(0, 10),
+        format: 'png',
+        minzoom: '0',
+        maxzoom: '18',
+        bounds: `${CHINA_BBOX_LL.lonMin},${CHINA_BBOX_LL.latMin},${CHINA_BBOX_LL.lonMax},${CHINA_BBOX_LL.latMax}`,
+        attribution: 'CAAC UOM',
+        source_zoom: String(args.sourceZ),
+        stored_zoom: String(materializedZMax),
+        publish_maxzoom: '14',
+        source_method: 'official-z9-bbox-z12-supertile-2048',
+        geographic_grid_level: String(GEOGRAPHIC_GRID_LEVEL),
+        canonical_geometry: 'global-equal-lat-lon-grid-orthogonal-rectangles',
+        canonical_maxzoom: 'unbounded-by-source-raster',
+        validation_report: '/tmp/uom-grid-regions-20260820/report.json',
+        crawl_started_at: new Date().toISOString(),
+    });
+    const startedAt = Date.now();
+    const completedAtStart = database.summary().completed;
+    let lastProgressAt = 0;
+    const progress = (force = false) => {
+        const now = Date.now();
+        if (!force && now - lastProgressAt < 1_000)
+            return;
+        lastProgressAt = now;
+        const summary = database.summary();
+        const done = summary.completed;
+        const rate = Math.max(0, done - completedAtStart) / Math.max(1, (now - startedAt) / 1000);
+        const eta = (roots.length - done) / Math.max(rate, 0.001) * 1000;
+        console.log(`[grid-crawl-progress] ${JSON.stringify({
+            phase: 'fetch-z12', done, total: roots.length, percent: Math.floor(done / roots.length * 100),
+            pending: summary.pending, running: summary.running, failed: summary.failed,
+            rectangles: summary.rectangles, contentTiles: summary.contentTiles,
+            qps: fetcher.ctl.currentQps, inflight: fetcher.ctl.currentInflight,
+            rate: Number(rate.toFixed(2)), eta: formatDuration(eta), heartbeatAt: now,
+        })}`);
+    };
+    const heartbeat = setInterval(() => progress(true), 10_000);
+    const leaseHeartbeat = setInterval(() => {
+        try {
+            assertWriter();
+        }
+        catch {
+            // assertWriter records the failure and aborts in-flight work.
+        }
+    }, 10_000);
+    heartbeat.unref();
+    leaseHeartbeat.unref();
+    async function processRoot(root) {
+        database.start(root);
+        const signal = AbortSignal.any([shutdown.signal, AbortSignal.timeout(rootDeadlineMs)]);
+        try {
+            const source = await fetchSourceMask(fetcher, token, root, signal);
+            const model = vectorizeGeographicGrid(source, {
+                sourceZ: args.sourceZ,
+                parentZ: rootZ,
+                parentX: root.x,
+                parentY: root.y,
+                width: sourceSize,
+            });
+            const tiles = await materializeRoot(model.rects, root);
+            assertWriter();
+            database.commitRoot(root, model.rects, tiles);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            if (!leaseFailure)
+                database.fail(root, message);
+            if (!stopping)
+                console.error(`[grid-crawl] failed z9/${root.x}/${root.y}: ${message}`);
+        }
+        finally {
+            progress();
+        }
+    }
+    let completed = false;
+    try {
+        await token.getMapToken(shutdown.signal);
+        let queue = roots.filter(root => !args.resume || !database.completed(root));
+        let pass = 0;
+        while (!stopping && queue.length > 0 && pass < maxRootPasses) {
+            pass++;
+            console.log(`[grid-crawl] pass=${pass} roots=${queue.length} db=${args.db}`);
+            let cursor = 0;
+            await Promise.all(Array.from({ length: Math.min(args.rootConcurrency, queue.length) }, async () => {
+                while (!stopping) {
+                    const root = queue[cursor++];
+                    if (!root)
+                        return;
+                    await processRoot(root);
+                }
+            }));
+            if (stopping)
+                break;
+            queue = database.failedRoots();
+            if (queue.length > 0) {
+                if (pass >= maxRootPasses)
+                    break;
+                const retryDelay = Math.min(30_000, pass * 5_000);
+                console.error(`[grid-crawl] ${queue.length} roots will be retried after ${retryDelay}ms (pass ${pass}/${maxRootPasses})`);
+                await new Promise(resolve => setTimeout(resolve, retryDelay));
+            }
+        }
+        if (!stopping && queue.length > 0)
+            throw new Error(`抓取在 ${maxRootPasses} 轮后仍有 ${queue.length} 个网格失败；请稍后手动继续`);
+        progress(true);
+        if (leaseFailure)
+            throw leaseFailure;
+        if (!stopping) {
+            database.retainSourceZoom();
+            assertWriter();
+            database.setMetadata({
+                crawl_finished_at: new Date().toISOString(),
+                grid_root_count: String(roots.length),
+                grid_root_completed: String(database.summary().completed),
+            });
+            database.optimize();
+            completed = true;
+            console.log(`[grid-crawl] COMPLETE ${JSON.stringify({ db: args.db, roots: database.summary(), tiles: database.countsByZoom() })}`);
+        }
+        else {
+            process.exitCode = 130;
+        }
+    }
+    finally {
+        clearInterval(heartbeat);
+        clearInterval(leaseHeartbeat);
+        database.close();
+        await fetcher.close();
+        token.close();
+        try {
+            if (!leaseFailure) {
+                setTaskState(args.db, completed ? 'completed' : 'incomplete', completed ? { finishedAt: new Date().toISOString() } : {});
+            }
+        }
+        finally {
+            try {
+                lock.release();
+            }
+            finally {
+                removeSqliteSidecars(args.db);
+            }
+        }
+    }
+}

package/dist/src/mask-image.js

@@ -0,0 +1,16 @@
+import { decodeCanonicalAlphaMask, encodeCanonicalMask } from "./core/png.js";
+export async function decodeMask(png) {
+    if (!png)
+        return new Uint8Array(256 * 256);
+    return decodeCanonicalAlphaMask(png, 256);
+}
+export function maskHasContent(mask) {
+    return mask.some(value => value !== 0);
+}
+export async function encodeMask(mask) {
+    if (mask.length !== 256 * 256)
+        throw new RangeError('mask must be 256x256');
+    if (!maskHasContent(mask))
+        return null;
+    return encodeCanonicalMask(mask);
+}

package/dist/src/official-grid.js

@@ -0,0 +1,51 @@
+import { DEFAULTS, OFFICIAL_WMS_LAYER_GROUPS, STYLE_NAME, WMS_PATH } from "./config.js";
+import { tileToMercBBox } from "./bbox.js";
+import { decodeUomAlphaMask } from "./core/png.js";
+function officialGroupPath(codes, z, x, y, token, size) {
+    const bbox = tileToMercBBox(z, x, y);
+    const layers = codes.map(code => `QGSFKYFW:sf${code}`);
+    const query = new URLSearchParams({
+        token, service: 'WMS', request: 'GetMap', layers: layers.join(','), styles: layers.map(() => STYLE_NAME).join(','),
+        format: 'image/png8', transparent: 'true', version: '1.1.0', srs: 'EPSG:3857', width: String(size), height: String(size),
+        bbox: `${bbox.minx},${bbox.miny},${bbox.maxx},${bbox.maxy}`,
+    });
+    return `${WMS_PATH}?${query}`;
+}
+async function fetchGroup(options, codes, size) {
+    let token = await options.token.getMapToken(options.signal);
+    for (let attempt = 0; attempt < 2; attempt++) {
+        const response = await options.fetcher.get(officialGroupPath(codes, options.z, options.x, options.y, token, size), {
+            timeoutMs: Math.max(DEFAULTS.perLayerTimeoutMs, size / 256 * 5_000), signal: options.signal,
+            headers: { Accept: 'image/png,image/*;q=0.8,*/*;q=0.5', Referer: 'https://uom.caac.gov.cn/web_pub/spaceIndex' },
+        });
+        if (response.status === 200 && response.contentType?.startsWith('image/png'))
+            return decodeUomAlphaMask(response.body, size);
+        let rejected = response.status === 401 || response.status === 403;
+        if (response.status === 200 && response.contentType?.startsWith('application/json')) {
+            try {
+                rejected = JSON.parse(response.body.toString('utf8')).code === 401;
+            }
+            catch { }
+        }
+        if (rejected && attempt === 0) {
+            options.token.invalidate();
+            token = await options.token.getMapToken(options.signal);
+            continue;
+        }
+        throw new Error(`UOM official WMS failed status=${response.status} type=${response.contentType ?? 'none'} bytes=${response.body.length}`);
+    }
+    throw new Error('UOM official WMS token refresh failed');
+}
+export async function fetchOfficialSupertileMask(options, size) {
+    if (options.z !== 9)
+        throw new RangeError('production supertile roots must be z9');
+    if (![256, 512, 1024, 2048, 4096].includes(size))
+        throw new RangeError('unsupported official supertile size');
+    const groups = await Promise.all(OFFICIAL_WMS_LAYER_GROUPS.map(codes => fetchGroup(options, codes, size)));
+    const mask = new Uint8Array(size * size);
+    for (const group of groups)
+        for (let i = 0; i < mask.length; i++)
+            if (group[i])
+                mask[i] = 1;
+    return mask;
+}

package/dist/src/quality.js

@@ -0,0 +1,30 @@
+/** Reconstruct one 256px parent from four 256px XYZ children. */
+export function deriveParentMask(children) {
+    if (children.length !== 4)
+        throw new RangeError('exactly four children are required');
+    const big = new Uint8Array(512 * 512);
+    const offsets = [[0, 0], [256, 0], [0, 256], [256, 256]];
+    for (let index = 0; index < children.length; index++) {
+        const child = children[index];
+        if (!child)
+            continue;
+        if (child.length !== 256 * 256)
+            throw new RangeError('child mask must be 256x256');
+        const [offsetX, offsetY] = offsets[index];
+        for (let y = 0; y < 256; y++) {
+            big.set(child.subarray(y * 256, y * 256 + 256), (offsetY + y) * 512 + offsetX);
+        }
+    }
+    const parent = new Uint8Array(256 * 256);
+    for (let y = 0; y < 256; y++) {
+        for (let x = 0; x < 256; x++) {
+            const sx = x * 2;
+            const sy = y * 2;
+            parent[y * 256 + x] = big[sy * 512 + sx]
+                | big[sy * 512 + sx + 1]
+                | big[(sy + 1) * 512 + sx]
+                | big[(sy + 1) * 512 + sx + 1];
+        }
+    }
+    return parent;
+}