@walkthru-earth/objex 1.3.0 → 1.4.0

package/dist/utils/cog-histogram.js

@@ -0,0 +1,424 @@
+/**
+ * Streaming histogram + GDAL stats reader for COGs.
+ *
+ * This module owns the canonical `HISTOGRAM_BINS` constant (128) and a
+ * tile-by-tile histogram builder. The streamer fetches tiles from the
+ * coarsest overview, bins pixel values into a `Uint32Array` of length
+ * `HISTOGRAM_BINS`, and emits a snapshot via `onProgress` after each
+ * tile so the UI can fill in the histogram chart incrementally.
+ *
+ * When GDAL_METADATA `STATISTICS_MINIMUM` / `STATISTICS_MAXIMUM` are
+ * present we use them as fixed bin edges (single-pass streaming). When
+ * they are absent we fall back to a two-pass scan (min/max first, then
+ * bin), in which case progress fires only at the end, bin edges are
+ * not stable until the first pass finishes.
+ *
+ * Runs in workers and on the main thread. No DOM APIs (window,
+ * document, DOMParser), no Svelte runes. XML parsing is a tolerant
+ * regex over the GDAL_METADATA tag string, not a DOMParser pass.
+ */
+import { buildHistogramFromGeotiff, defaultRescaleForGeotiff, percentileFromHistogram } from './cog.js';
+/** Number of histogram buckets. PR #3 bumps from 64 to 128. */
+export const HISTOGRAM_BINS = 128;
+const DEFAULT_MAX_TILES = 32;
+/**
+ * Parse per-band stats out of the GDAL_METADATA tag. Tolerant of
+ * malformed XML, uses a regex pass over `<Item ...>...</Item>` rather
+ * than DOMParser so this can run inside a Web Worker.
+ *
+ * Prefers the library's pre-parsed `geotiff.storedStats` when present,
+ * falls back to scanning the raw `cachedTags.gdalMetadata` string when
+ * the library could not parse it but the tag is still present (defensive
+ * path, rarely fires with current @developmentseed/geotiff but cheap).
+ *
+ * Returns an empty Map when no usable per-band ranges are found.
+ */
+export function readGdalStats(geotiff) {
+    const out = new Map();
+    const stored = geotiff.storedStats;
+    if (stored) {
+        for (const [band, stats] of stored) {
+            if (stats.min === null || stats.max === null)
+                continue;
+            if (!(stats.min < stats.max))
+                continue;
+            const entry = { min: stats.min, max: stats.max };
+            if (stats.mean !== null && Number.isFinite(stats.mean))
+                entry.mean = stats.mean;
+            if (stats.std !== null && Number.isFinite(stats.std))
+                entry.stddev = stats.std;
+            out.set(band, entry);
+        }
+        if (out.size > 0)
+            return out;
+    }
+    // Defensive fallback, parse the raw XML if the library handed us a
+    // string but no parsed stats. Most builds will never hit this.
+    const rawTags = geotiff.cachedTags;
+    const xml = rawTags?.gdalMetadata ?? rawTags?.GdalMetadata ?? rawTags?.GDAL_METADATA;
+    if (typeof xml !== 'string' || xml.length === 0)
+        return out;
+    parseGdalMetadataXml(xml, out);
+    return out;
+}
+/**
+ * Append per-band stats parsed from a GDAL_METADATA XML string. Tolerant
+ * regex parser. Handles entries like:
+ *   `<Item name="STATISTICS_MINIMUM" sample="0">123.4</Item>`
+ * Mean and stddev are picked up from STATISTICS_MEAN / STATISTICS_STDDEV.
+ */
+function parseGdalMetadataXml(xml, out) {
+    // `sample` is 0-based in GDAL_METADATA, we expose 1-based to mirror the
+    // rest of the codebase and @developmentseed/geotiff's `storedStats`.
+    const itemRe = /<Item\b([^>]*)>([\s\S]*?)<\/Item>/g;
+    const attrRe = /(\w+)\s*=\s*"([^"]*)"/g;
+    const partials = new Map();
+    let m;
+    // biome-ignore lint/suspicious/noAssignInExpressions: idiomatic regex iteration
+    while ((m = itemRe.exec(xml)) !== null) {
+        const attrs = {};
+        let a;
+        attrRe.lastIndex = 0;
+        // biome-ignore lint/suspicious/noAssignInExpressions: idiomatic regex iteration
+        while ((a = attrRe.exec(m[1] ?? '')) !== null)
+            attrs[a[1]] = a[2];
+        const sampleStr = attrs.sample;
+        const nameAttr = attrs.name;
+        if (sampleStr === undefined || nameAttr === undefined)
+            continue;
+        const sample = Number.parseInt(sampleStr, 10);
+        if (!Number.isFinite(sample) || sample < 0)
+            continue;
+        const bandIdx = sample + 1;
+        const valueStr = (m[2] ?? '').trim();
+        const value = Number.parseFloat(valueStr);
+        if (!Number.isFinite(value))
+            continue;
+        let p = partials.get(bandIdx);
+        if (!p) {
+            p = {};
+            partials.set(bandIdx, p);
+        }
+        switch (nameAttr) {
+            case 'STATISTICS_MINIMUM':
+                p.min = value;
+                break;
+            case 'STATISTICS_MAXIMUM':
+                p.max = value;
+                break;
+            case 'STATISTICS_MEAN':
+                p.mean = value;
+                break;
+            case 'STATISTICS_STDDEV':
+                p.stddev = value;
+                break;
+            default:
+                break;
+        }
+    }
+    for (const [band, p] of partials) {
+        if (p.min === undefined || p.max === undefined)
+            continue;
+        if (!(p.min < p.max))
+            continue;
+        const entry = { min: p.min, max: p.max };
+        if (p.mean !== undefined)
+            entry.mean = p.mean;
+        if (p.stddev !== undefined)
+            entry.stddev = p.stddev;
+        out.set(band, entry);
+    }
+}
+/**
+ * Iterate band `b` (0-based) of a `RasterArray`, layout-agnostic. Yields
+ * raw sample values in row-major order without copying.
+ */
+function* iterBand(arr, b) {
+    if (arr.layout === 'band-separate') {
+        const data = arr.bands?.[b];
+        if (!data)
+            return;
+        const len = data.length;
+        for (let i = 0; i < len; i++)
+            yield data[i];
+    }
+    else {
+        const data = arr.data;
+        if (!data)
+            return;
+        const stride = arr.count ?? 1;
+        const len = data.length;
+        for (let i = b; i < len; i += stride)
+            yield data[i];
+    }
+}
+/**
+ * Pick which tiles of the chosen overview to read. Below the cap we read
+ * every tile (exact min/max plus every-pixel histogram), above the cap we
+ * fall back to a 3x3 spatial sample (corners + edge midpoints + center,
+ * deduplicated) so a COG without a deep overview pyramid does not trigger
+ * a multi-GB scan.
+ */
+function pickSampleCoords(tileCount, cap) {
+    if (tileCount.x <= 0 || tileCount.y <= 0)
+        return [];
+    if (tileCount.x * tileCount.y <= cap) {
+        const out = [];
+        for (let y = 0; y < tileCount.y; y++) {
+            for (let x = 0; x < tileCount.x; x++)
+                out.push([x, y]);
+        }
+        return out;
+    }
+    const xs = Array.from(new Set([0, Math.floor(tileCount.x / 2), tileCount.x - 1])).filter((n) => n >= 0 && n < tileCount.x);
+    const ys = Array.from(new Set([0, Math.floor(tileCount.y / 2), tileCount.y - 1])).filter((n) => n >= 0 && n < tileCount.y);
+    const out = [];
+    for (const y of ys) {
+        for (const x of xs)
+            out.push([x, y]);
+    }
+    return out;
+}
+/** Resolve the source IFD for histogram sampling. */
+function resolveSource(geotiff, overviewIndex) {
+    const ovs = geotiff.overviews ?? [];
+    if (typeof overviewIndex === 'number') {
+        if (overviewIndex >= 0 && overviewIndex < ovs.length)
+            return ovs[overviewIndex];
+    }
+    // Default, lowest-resolution overview (smallest source).
+    if (ovs.length > 0)
+        return ovs[ovs.length - 1];
+    return geotiff;
+}
+/**
+ * Stream a 128-bin histogram for a single band. Fires `onProgress` after
+ * each tile so the UI can fill in the chart incrementally, the snapshots
+ * share no buffer references between calls (each `bins` is a fresh
+ * `Uint32Array`).
+ *
+ * Algorithm:
+ *  - With GDAL priors, one pass, known bin edges, progressive snapshots.
+ *  - Without priors, two passes, pass 1 finds min/max across all
+ *    selected tiles, pass 2 bins into 128 buckets. Snapshots fire
+ *    per-cached-tile in pass 2 so the UI still sees the histogram fill
+ *    in on the no-priors path, bin edges aren't stable during pass 1.
+ *
+ * Honors `signal.aborted` between every tile fetch and after each bin
+ * pass. Throws no error on abort, returns silently with whatever
+ * partial snapshot the caller already received.
+ */
+export async function streamHistogram(opts) {
+    const { geotiff, bandIndex, signal, onProgress } = opts;
+    const maxTiles = opts.maxTiles ?? DEFAULT_MAX_TILES;
+    if (bandIndex < 1)
+        return;
+    const source = resolveSource(geotiff, opts.overviewIndex);
+    const tileCount = source.tileCount;
+    const coords = pickSampleCoords(tileCount, maxTiles);
+    if (coords.length === 0)
+        return;
+    const nodata = geotiff.nodata;
+    const priors = readGdalStats(geotiff);
+    const prior = priors.get(bandIndex);
+    if (prior) {
+        await streamWithPriors({
+            source,
+            coords,
+            bandIdx0: bandIndex - 1,
+            min: prior.min,
+            max: prior.max,
+            nodata,
+            signal,
+            onProgress
+        });
+        return;
+    }
+    await streamTwoPass({
+        source,
+        coords,
+        bandIdx0: bandIndex - 1,
+        nodata,
+        signal,
+        onProgress
+    });
+}
+async function streamWithPriors(ctx) {
+    const { source, coords, bandIdx0, min, max, nodata, signal, onProgress } = ctx;
+    const range = max - min;
+    if (!(range > 0))
+        return;
+    const scale = HISTOGRAM_BINS / range;
+    const bins = new Uint32Array(HISTOGRAM_BINS);
+    const total = coords.length;
+    for (let i = 0; i < total; i++) {
+        if (signal.aborted)
+            return;
+        const [x, y] = coords[i];
+        let tile;
+        try {
+            tile = await source.fetchTile(x, y, { signal });
+        }
+        catch {
+            // Honor abort, but also tolerate edge-tile fetch failures.
+            if (signal.aborted)
+                return;
+            continue;
+        }
+        if (signal.aborted)
+            return;
+        const arr = tile.array;
+        if (bandIdx0 < 0 || bandIdx0 >= arr.count)
+            return;
+        for (const v of iterBand(arr, bandIdx0)) {
+            if (nodata !== null && v === nodata)
+                continue;
+            if (!Number.isFinite(v))
+                continue;
+            let idx = Math.floor((v - min) * scale);
+            if (idx < 0)
+                idx = 0;
+            else if (idx >= HISTOGRAM_BINS)
+                idx = HISTOGRAM_BINS - 1;
+            bins[idx]++;
+        }
+        // Fresh snapshot each emit so subscribers can hold refs without
+        // risk of mutation.
+        onProgress({
+            bins: new Uint32Array(bins),
+            min,
+            max,
+            tilesProcessed: i + 1,
+            tilesTotal: total
+        });
+    }
+}
+async function streamTwoPass(ctx) {
+    const { source, coords, bandIdx0, nodata, signal, onProgress } = ctx;
+    // Pass 1, min/max. Cache the decoded tiles so pass 2 doesn't refetch.
+    const decoded = [];
+    let min = Number.POSITIVE_INFINITY;
+    let max = Number.NEGATIVE_INFINITY;
+    let any = false;
+    for (let i = 0; i < coords.length; i++) {
+        if (signal.aborted)
+            return;
+        const [x, y] = coords[i];
+        try {
+            const tile = await source.fetchTile(x, y, { signal });
+            const arr = tile.array;
+            if (bandIdx0 < 0 || bandIdx0 >= arr.count)
+                return;
+            decoded.push(arr);
+            for (const v of iterBand(arr, bandIdx0)) {
+                if (nodata !== null && v === nodata)
+                    continue;
+                if (!Number.isFinite(v))
+                    continue;
+                if (v < min)
+                    min = v;
+                if (v > max)
+                    max = v;
+                any = true;
+            }
+        }
+        catch {
+            if (signal.aborted)
+                return;
+        }
+    }
+    if (signal.aborted)
+        return;
+    if (!any || !(min < max))
+        return;
+    // Pass 2, bin. Emits an incremental snapshot per cached tile so the
+    // UI sees the histogram fill in even on the no-priors path.
+    const range = max - min;
+    const scale = HISTOGRAM_BINS / range;
+    const bins = new Uint32Array(HISTOGRAM_BINS);
+    const total = decoded.length;
+    for (let i = 0; i < total; i++) {
+        if (signal.aborted)
+            return;
+        const arr = decoded[i];
+        for (const v of iterBand(arr, bandIdx0)) {
+            if (nodata !== null && v === nodata)
+                continue;
+            if (!Number.isFinite(v))
+                continue;
+            let idx = Math.floor((v - min) * scale);
+            if (idx < 0)
+                idx = 0;
+            else if (idx >= HISTOGRAM_BINS)
+                idx = HISTOGRAM_BINS - 1;
+            bins[idx]++;
+        }
+        onProgress({
+            bins: new Uint32Array(bins),
+            min,
+            max,
+            tilesProcessed: i + 1,
+            tilesTotal: total
+        });
+    }
+}
+/**
+ * Seed a {@link RescaleConfig} for a freshly opened COG in the same
+ * normalized shader-space [0, 1] coordinate system the rescale slider
+ * operates on. The GPU's hardware normalization (`r8unorm` / `r16unorm`)
+ * and the `Colormap` CPU baker both divide raw integer samples by the
+ * format's max (255 for uint8, 65535 for uint16) before sampling, and
+ * `CogControls`'s `setRescaleMin/Max` clamps the slider via `clamp01`.
+ * Storing raw GeoTIFF stats (e.g. `{min: 0, max: 10000}` for uint16
+ * reflectance) here would snap back to `{0, 1}` on the user's first
+ * slider touch.
+ *
+ * Fallback chain:
+ *   1. GDAL `STATISTICS_MINIMUM` / `STATISTICS_MAXIMUM` for the band,
+ *      normalized to shader space by dividing by the sample-format
+ *      factor (255 for uint8, 65535 for uint ≥ 8 bps). Float bands are
+ *      passed through unchanged because they already live near [0, 1].
+ *   2. `buildHistogramFromGeotiff` + p2 / p98 percentile lookup so a
+ *      uint16 reflectance band with no STATISTICS tag still gets a
+ *      contrasted preview from the first tile of the smallest overview.
+ *   3. {@link defaultRescaleForGeotiff} bit-depth-aware constants.
+ */
+export async function seedRescaleFromGeotiff(geotiff, options) {
+    const signal = options?.signal;
+    const bandIndex = options?.bandIndex ?? 1;
+    // 1) GDAL_METADATA STATISTICS_MIN/MAX, normalize raw values into shader [0, 1].
+    const stats = readGdalStats(geotiff).get(bandIndex);
+    if (stats && Number.isFinite(stats.min) && Number.isFinite(stats.max) && stats.min < stats.max) {
+        const tags = geotiff.cachedTags;
+        const sampleFormat = tags.sampleFormat?.[0] ?? 1;
+        const bps = tags.bitsPerSample?.[0] ?? 8;
+        // Float bands already live in [0, 1]-ish space; integer bands need to
+        // be divided by their format max so the slider operates on shader-space.
+        const norm = sampleFormat === 1 ? (bps <= 8 ? 255 : 65535) : 1;
+        const min = stats.min / norm;
+        const max = stats.max / norm;
+        if (Number.isFinite(min) && Number.isFinite(max) && min < max) {
+            return { min, max };
+        }
+    }
+    if (signal?.aborted)
+        return defaultRescaleForGeotiff(geotiff);
+    // 2) p2 / p98 from a single-tile shader-space histogram.
+    try {
+        const bins = await buildHistogramFromGeotiff(geotiff, signal);
+        if (signal?.aborted)
+            return defaultRescaleForGeotiff(geotiff);
+        if (bins) {
+            const p2 = percentileFromHistogram(bins, 0.02);
+            const p98 = percentileFromHistogram(bins, 0.98);
+            if (p2 !== null && p98 !== null && p2 < p98) {
+                return { min: p2, max: p98 };
+            }
+        }
+    }
+    catch {
+        // Fall through to defaults.
+    }
+    // 3) Bit-depth-aware defaults.
+    return defaultRescaleForGeotiff(geotiff);
+}