bruce-cesium 7.2.1 → 7.2.3

package/dist/lib/rendering/texture-frame-series-animator.js

@@ -6,26 +6,317 @@ const Cesium = require("cesium");
 const image_utils_1 = require("../internal/image-utils");
 var TextureFrameSeriesAnimator;
 (function (TextureFrameSeriesAnimator) {
+    TextureFrameSeriesAnimator.LAYOUT_TILES = "tiles";
+    // The only generation this renderer draws. Anything else is refused rather than half read: the
+    // shapes differ enough that a partial reading produces a plausible wrong surface, which is worse
+    // than an empty one.
+    TextureFrameSeriesAnimator.SUPPORTED_VERSION = 3;
+    // Value in R at 8 bits, or high in R and low in G at 16.
+    TextureFrameSeriesAnimator.FORMAT_U8 = "u8";
+    TextureFrameSeriesAnimator.FORMAT_RG16 = "rg16";
+    // Declared as a field with one value, so a second mode can be added later without an absent
+    // Encoding having to mean anything.
+    TextureFrameSeriesAnimator.ENCODING_ABSOLUTE = "absolute";
+    TextureFrameSeriesAnimator.LAYER_VALUE = "Value";
+    TextureFrameSeriesAnimator.LAYER_VALUE_MIN = "ValueMin";
+    TextureFrameSeriesAnimator.LAYER_VALUE_MAX = "ValueMax";
+    TextureFrameSeriesAnimator.LAYER_BASELINE = "Baseline";
+    // The per-texel correction that was applied, published only on an archive that was transformed.
+    TextureFrameSeriesAnimator.LAYER_VALUE_SHIFT = "ValueShift";
+    /**
+     * Turns a published value map into the flat shape this renderer works in, or null when it cannot be drawn.
+     * @param published the archive's Data.generation
+     */
+    function Adapt(published) {
+        if (!published || published.Version !== TextureFrameSeriesAnimator.SUPPORTED_VERSION) {
+            const found = published && published.Version != null ? published.Version : "none";
+            const at = published && published.Identity ? published.Identity.Generated : undefined;
+            // In theory should be no files.
+            console.warn("bruce-cesium: value map version " + found + " is not supported (this build reads "
+                + TextureFrameSeriesAnimator.SUPPORTED_VERSION + "), so nothing will be drawn for it."
+                + (at ? " The archive was generated at " + at + " and needs regenerating." : ""));
+            return null;
+        }
+        const geometry = published.Geometry || {};
+        const tiles = published.Tiles || [];
+        if (geometry.Layout !== TextureFrameSeriesAnimator.LAYOUT_TILES || tiles.length === 0) {
+            const at = published.Identity ? published.Identity.Generated : undefined;
+            console.warn("bruce-cesium: value map declares no tiles, so nothing will be drawn for it."
+                + (at ? " The archive was generated at " + at + " and needs regenerating." : ""));
+            return null;
+        }
+        const value = published.Value || {};
+        if (value.Encoding && value.Encoding !== TextureFrameSeriesAnimator.ENCODING_ABSOLUTE) {
+            const at = published.Identity ? published.Identity.Generated : undefined;
+            console.warn("bruce-cesium: value map encoding " + value.Encoding + " is not supported"
+                + " (this build reads " + TextureFrameSeriesAnimator.ENCODING_ABSOLUTE + "), so nothing will be drawn for it."
+                + (at ? " The archive was generated at " + at + " and needs regenerating." : ""));
+            return null;
+        }
+        const series = published.Series || {};
+        const layerRange = declaredRange(published, TextureFrameSeriesAnimator.LAYER_VALUE_MIN);
+        const flat = {
+            Frames: [],
+            ValueMin: value.Min,
+            ValueMax: value.Max,
+            Format: value.Format || TextureFrameSeriesAnimator.FORMAT_U8,
+            Encoding: value.Encoding || TextureFrameSeriesAnimator.ENCODING_ABSOLUTE,
+            Units: value.Units,
+            West: geometry.West,
+            East: geometry.East,
+            South: geometry.South,
+            North: geometry.North,
+            ResolutionX: geometry.ResolutionX,
+            ResolutionY: geometry.ResolutionY,
+            PixelPlacement: geometry.PixelPlacement,
+            Times: series.Times,
+            ExtremesValueMin: layerRange ? layerRange.min : undefined,
+            ExtremesValueMax: layerRange ? layerRange.max : undefined,
+            // The delivered values are what gets drawn. What the source called them, and any shift
+            // applied on the way, travel for labels and analysis rather than for placement.
+            SourceVerticalDatum: published.ValueSource ? published.ValueSource.VerticalDatum : undefined,
+            Transform: published.ValueSource ? published.ValueSource.Transform : undefined,
+            SourceUnits: published.ValueSource ? published.ValueSource.Units : undefined,
+            SourceValueMin: published.ValueSource ? published.ValueSource.Min : undefined,
+            SourceValueMax: published.ValueSource ? published.ValueSource.Max : undefined
+        };
+        flat.Tiles = tiles.map((tile) => adaptTile(tile, series.Times));
+        // The coarsest tile covers the whole extent, so it is what a caller wanting one time list reads.
+        flat.Frames = flat.Tiles[0].Frames;
+        warnIfUnshifted(published, flat);
+        return flat;
+    }
+    TextureFrameSeriesAnimator.Adapt = Adapt;
+    /*
+     * Says so when an archive's heights are not on the ellipsoid they will be drawn against.
+     */
+    function warnIfUnshifted(published, flat) {
+        const datum = flat.SourceVerticalDatum;
+        if (!datum || datum === TextureFrameSeriesAnimator.DATUM_ELLIPSOIDAL || flat.Transform) {
+            return;
+        }
+        const at = published.Identity ? published.Identity.Generated : undefined;
+        console.warn("bruce-cesium: value map heights are in " + datum + " and report no transform, so"
+            + " they are not ellipsoidal and will draw at the wrong height when placed absolutely."
+            + (at ? " The archive was generated at " + at + " and needs regenerating with the shift"
+                + " applied." : ""));
+    }
+    /*
+     * The Min and Max a named layer declares, since a statistics layer is encoded over the true data
+     * range rather than over the frames' own.
+     */
+    function declaredRange(published, name) {
+        const layers = published.Layers || [];
+        for (const layer of layers) {
+            if (layer.Name === name && typeof layer.Min === "number" && typeof layer.Max === "number") {
+                return { min: layer.Min, max: layer.Max };
+            }
+        }
+        return null;
+    }
+    /*
+     * One tile, with its per-time value rasters lined up against the shared time list.
+     */
+    function adaptTile(tile, times) {
+        const layers = tile.Layers || {};
+        const perTime = layers[TextureFrameSeriesAnimator.LAYER_VALUE] || [];
+        const frames = perTime.map((entry, index) => ({
+            Timestamp: times && times[index] ? times[index] : "",
+            ByteOffset: entry.Bytes.Offset,
+            ByteLength: entry.Bytes.Length
+        }));
+        return {
+            Level: tile.Level,
+            X: tile.X,
+            Y: tile.Y,
+            West: tile.West,
+            East: tile.East,
+            South: tile.South,
+            North: tile.North,
+            TexelMetres: tile.TexelMetres,
+            ResolutionX: tile.ResolutionX,
+            ResolutionY: tile.ResolutionY,
+            Frames: frames,
+            Floor: single(layers[TextureFrameSeriesAnimator.LAYER_VALUE_MIN]),
+            Ceiling: single(layers[TextureFrameSeriesAnimator.LAYER_VALUE_MAX]),
+            BaselineMask: single(layers[TextureFrameSeriesAnimator.LAYER_BASELINE])
+        };
+    }
+    function single(layer) {
+        if (!layer || !layer.Bytes) {
+            return undefined;
+        }
+        return { ByteOffset: layer.Bytes.Offset, ByteLength: layer.Bytes.Length };
+    }
+    /**
+     * How to turn a delivered value into the number the source published, or null when the archive
+     * does not say enough to do it.
+     * @param metadata the archive's Data.generation
+     */
+    function SourceMap(metadata) {
+        if (!metadata) {
+            return null;
+        }
+        const { ValueMin, ValueMax, SourceValueMin, SourceValueMax } = metadata;
+        if (typeof ValueMin !== "number" || typeof ValueMax !== "number"
+            || typeof SourceValueMin !== "number" || typeof SourceValueMax !== "number") {
+            return null;
+        }
+        const delivered = ValueMax - ValueMin;
+        // A single delivered value describes no line, so all that can be recovered is where it sits.
+        const scale = delivered !== 0 ? (SourceValueMax - SourceValueMin) / delivered : 1;
+        return { scale, offset: SourceValueMin - ValueMin * scale };
+    }
+    TextureFrameSeriesAnimator.SourceMap = SourceMap;
+    /**
+     * A delivered value in the source's own terms, or unchanged when it cannot be turned back.
+     * @param map from SourceMap(), null when the archive does not say enough
+     */
+    function ToSource(map, value) {
+        return map ? value * map.scale + map.offset : value;
+    }
+    TextureFrameSeriesAnimator.ToSource = ToSource;
+    /**
+     * Whether the archive's frames carry a 16 bit value packed across R and G.
+     *
+     * Every consumer that reads a texel has to ask: taking R alone from a packed frame yields a
+     * plausible surface quantised to 255 steps of the full range rather than an obvious failure.
+     * @param metadata the archive's Data.generation
+     */
+    function IsPackedValue(metadata) {
+        return Boolean(metadata && metadata.Format === TextureFrameSeriesAnimator.FORMAT_RG16);
+    }
+    TextureFrameSeriesAnimator.IsPackedValue = IsPackedValue;
+    /**
+     * The normalised 0 to 1 value at a texel, from whichever format the archive packed it in.
+     * @param metadata the archive's Data.generation
+     * @param pixels untinted RGBA value pixels
+     * @param at index of the texel's red channel
+     */
+    function NormalisedAt(metadata, pixels, at) {
+        if (IsPackedValue(metadata)) {
+            return (pixels[at] * 256 + pixels[at + 1]) / 65535;
+        }
+        return pixels[at] / 255;
+    }
+    TextureFrameSeriesAnimator.NormalisedAt = NormalisedAt;
+    // Values already sit on the ellipsoid Cesium measures against, so nothing is added to place them.
+    TextureFrameSeriesAnimator.DATUM_ELLIPSOIDAL = "WGS84";
+    /**
+     * Whether the values are heights against a vertical datum rather than a thickness.
+     *
+     * A thickness rises from wherever the polygon sits and a height already knows where it belongs, so
+     * this is what decides whether the polygon's own altitude may be added underneath it.
+     * @param metadata the archive's Data.generation
+     */
+    function IsDatumHeight(metadata) {
+        return Boolean(metadata && metadata.SourceVerticalDatum);
+    }
+    TextureFrameSeriesAnimator.IsDatumHeight = IsDatumHeight;
+    /**
+     * The archive's tiles, which Adapt() guarantees are present.
+     * @param metadata the archive's Data.generation
+     */
+    function TilesOf(metadata) {
+        return (metadata && metadata.Tiles) || [];
+    }
+    TextureFrameSeriesAnimator.TilesOf = TilesOf;
+    /**
+     * Turns a value in the attribute's own units into the 0 to 1 position the ramp is indexed by.
+     *
+     * Stops are authored in real units, since "hide anything under 0.1 m" is the sentence a user
+     * actually has, and the archive's own published range is what makes that expressible.
+     * @param metadata the archive's Data.generation
+     * @param value in the attribute's units
+     */
+    function NormalisePosition(metadata, value) {
+        const lo = metadata && typeof metadata.ValueMin === "number" ? metadata.ValueMin : 0;
+        const hi = metadata && typeof metadata.ValueMax === "number" ? metadata.ValueMax : 1;
+        const span = hi - lo;
+        if (!(span > 0)) {
+            return 0;
+        }
+        return Math.min(1, Math.max(0, (value - lo) / span));
+    }
+    TextureFrameSeriesAnimator.NormalisePosition = NormalisePosition;
     /**
      * Detects whether a ClientFile's `Data.generation` metadata describes a frame archive rather than a single static image,
      * so a caller can decide whether to construct an Animator or fall back to the existing static-texture path.
-     * @param data ClientFile.Data (the `IFile.Data` field), as returned by ClientFile.Get().
+     * @param data ClientFile.Data
      */
     function IsFrameArchiveMetadata(data) {
-        return Boolean(data && data.generation && Array.isArray(data.generation.Frames) && data.generation.Frames.length > 0);
+        const generation = data && data.generation;
+        if (!generation) {
+            return false;
+        }
+        return (typeof generation.Version === "number" ||
+            (Array.isArray(generation.Frames) && generation.Frames.length > 0));
     }
     TextureFrameSeriesAnimator.IsFrameArchiveMetadata = IsFrameArchiveMetadata;
-    // How far covered values bleed outward into uncovered texels before the GPU samples them.
+    // First resolvable static number out of a calculator field list, since that is all a border needs.
+    function resolveNumber(fields) {
+        if (!fields) {
+            return 0;
+        }
+        for (const field of fields) {
+            const value = Number(field && field.value);
+            if (Number.isFinite(value)) {
+                return value;
+            }
+        }
+        return 0;
+    }
+    // First resolvable static colour out of a calculator field list.
+    function resolveColor(fields) {
+        if (!fields) {
+            return null;
+        }
+        for (const field of fields) {
+            const parsed = typeof (field === null || field === void 0 ? void 0 : field.value) === "string"
+                ? bruce_models_1.Color.ColorFromStr(field.value)
+                : null;
+            if (parsed) {
+                return parsed;
+            }
+        }
+        return null;
+    }
+    /*
+     * Everything about an Animator that a style can change, as a comparable string.
+     */
+    function AppearanceSignature(options) {
+        var _a, _b, _c;
+        return JSON.stringify([
+            (_a = options.textureColorMask) !== null && _a !== void 0 ? _a : null,
+            (_b = options.cellBorder) !== null && _b !== void 0 ? _b : null,
+            (_c = options.cellTexels) !== null && _c !== void 0 ? _c : null,
+            Boolean(options.maskBaseline)
+        ]);
+    }
+    TextureFrameSeriesAnimator.AppearanceSignature = AppearanceSignature;
+    const MAX_COMPOSITE_TEXELS = 2048;
     const VALUE_DILATE_PASSES = 2;
     /*
-     * Bleeds covered values outward into uncovered texels, leaving alpha untouched.
+     * Rewrites a packed 16 bit value as the 8 bit grey the colour ramps index on.
      *
-     * The GPU samples the value texture with linear filtering, so an uncovered texel's RGB still gets
-     * averaged into the vertices next to it even though its alpha is zero. Land sits at one end of the
-     * ramp, so without this the coastline grows a row of spikes exactly where the data stops. Masking the
-     * baseline creates more of these edges, which is what makes this necessary rather than cosmetic.
+     * All three channels, since a ramp is free to read any of them and a leftover low byte in G would
+     * show up as a green cast on the one that reads them all.
+     */
+    function flattenPacked(pixels, packed) {
+        if (!packed) {
+            return;
+        }
+        for (let i = 0; i < pixels.length; i += 4) {
+            const grey = Math.round((pixels[i] * 256 + pixels[i + 1]) / 65535 * 255);
+            pixels[i] = grey;
+            pixels[i + 1] = grey;
+            pixels[i + 2] = grey;
+        }
+    }
+    /*
+     * Bleeds covered values outward into uncovered texels, leaving alpha untouched.
      */
-    function dilateValues(value, width, height, passes) {
+    function dilateValues(value, width, height, passes, packed) {
         const texels = width * height;
         const filled = new Uint8Array(texels);
         for (let p = 0; p < texels; p++) {
@@ -49,15 +340,25 @@ var TextureFrameSeriesAnimator;
                             if (nx < 0 || ny < 0 || nx >= width || ny >= height || !wasFilled[ny * width + nx]) {
                                 continue;
                             }
-                            sum += source[(ny * width + nx) * 4];
+                            const at = (ny * width + nx) * 4;
+                            // Averaged as a value rather than per byte: averaging a packed low byte
+                            // on its own wraps at every 256th step and speckles the bled edge.
+                            sum += packed ? source[at] * 256 + source[at + 1] : source[at];
                             hits++;
                         }
                     }
                     if (hits > 0) {
                         const v = Math.round(sum / hits);
-                        value[p * 4] = v;
-                        value[p * 4 + 1] = v;
-                        value[p * 4 + 2] = v;
+                        if (packed) {
+                            value[p * 4] = (v >> 8) & 255;
+                            value[p * 4 + 1] = v & 255;
+                            value[p * 4 + 2] = 0;
+                        }
+                        else {
+                            value[p * 4] = v;
+                            value[p * 4 + 1] = v;
+                            value[p * 4 + 2] = v;
+                        }
                         filled[p] = 1;
                     }
                 }
@@ -69,7 +370,7 @@ var TextureFrameSeriesAnimator;
     const DEFAULT_HIGH_COLOR = { red: 21, green: 96, blue: 196, alpha: 0.92 };
     class Animator {
         constructor(options) {
-            var _a, _b;
+            var _a, _b, _c;
             this.removeOnTick = null;
             this.removeCrossfadeTick = null;
             this.disposed = false;
@@ -97,6 +398,9 @@ var TextureFrameSeriesAnimator;
             this.poolIdx = 0;
             this.valueDims = null;
             this.presentVersion = 0;
+            this.extremesLoad = null;
+            this.floorPixels = null;
+            this.ceilingPixels = null;
             if (!options.entity.polygon) {
                 throw new Error("TextureFrameSeriesAnimator requires an entity with polygon graphics.");
             }
@@ -108,16 +412,40 @@ var TextureFrameSeriesAnimator;
             this.archiveUrl = options.archiveUrl;
             this.frames = options.frames;
             this.crossfadeMs = (_a = options.crossfadeMs) !== null && _a !== void 0 ? _a : DEFAULT_CROSSFADE_MS;
+            this.appearance = AppearanceSignature(options);
             const mask = options.textureColorMask;
             this.lowColor = (mask && bruce_models_1.Color.ColorFromStr(mask.minColor)) || DEFAULT_LOW_COLOR;
             this.highColor = (mask && bruce_models_1.Color.ColorFromStr(mask.maxColor)) || DEFAULT_HIGH_COLOR;
+            // Positions are authored in the attribute's units and normalised once here, so the
+            // per-pixel loop stays a comparison against 0 to 1 like the two-colour path.
+            const points = mask && mask.points;
+            this.rampStops = (points && points.length > 0)
+                ? points.map((p) => ({
+                    position: NormalisePosition(options.metadata, p.position),
+                    color: bruce_models_1.Color.ColorFromStr(p.color) || DEFAULT_LOW_COLOR
+                }))
+                : null;
+            const border = options.cellBorder;
+            const borderWidth = border ? resolveNumber(border.width) : 0;
+            const borderColor = border ? resolveColor(border.color) : null;
+            // Zero width or a fully transparent colour means no grid, matching how the polygon's own
+            // outline behaves, so an existing style that wants no border keeps getting none.
+            this.cellBorder = (border && borderWidth > 0 && borderColor && borderColor.alpha > 0)
+                ? {
+                    cellTexels: Math.max(1, Math.round((_b = options.cellTexels) !== null && _b !== void 0 ? _b : 1)),
+                    widthTexels: borderWidth,
+                    color: borderColor
+                }
+                : null;
             this.frameDates = this.frames.map((f) => Cesium.JulianDate.fromIso8601(f.Timestamp));
             this.frameCache = new Array(this.frames.length).fill(null);
             this.frameDims = new Array(this.frames.length).fill(null);
             this.valueCache = new Array(this.frames.length).fill(null);
             this.produceValueCanvas = Boolean(options.produceValueCanvas);
-            this.baselineMaskEntry = options.baselineMask || null;
-            this.maskBaseline = (_b = options.maskBaseline) !== null && _b !== void 0 ? _b : Boolean(options.baselineMask);
+            this.metadata = options.metadata;
+            this.drapeExtent = options.drapeExtent;
+            this.tiles = TilesOf(options.metadata);
+            this.maskBaseline = (_c = options.maskBaseline) !== null && _c !== void 0 ? _c : this.tiles.some((tile) => Boolean(tile.BaselineMask));
             this.valueCanvas = this.produceValueCanvas ? document.createElement("canvas") : null;
             this.driveMaterial = options.driveMaterial !== false;
             this.originalMaterial = options.entity.polygon.material;
@@ -153,6 +481,10 @@ var TextureFrameSeriesAnimator;
         IsDisposed() {
             return this.disposed;
         }
+        // What this Animator was built to look like, for deciding whether it can be reused.
+        GetAppearanceSignature() {
+            return this.appearance;
+        }
         /**
          * The archive URL this instance was constructed with,
          * lets a caller re-rendering the same entity tell whether an existing instance is already correct, without reaching into private state.
@@ -167,6 +499,15 @@ var TextureFrameSeriesAnimator;
         GetImageProperty() {
             return this.imageProperty;
         }
+        /**
+         * The presented frame's TINTED pixels, where alpha is what the ramp actually painted.
+         *
+         * Distinct from the value canvas, whose alpha only says a texel has data. A cell can hold a
+         * reading and still be painted nothing, which is exactly what a hidden floor band does.
+         */
+        GetDisplayedPixels() {
+            return this.displayedPixels;
+        }
         /**
          * The untinted canvas carrying the presented frame's value in RGB and its coverage in alpha,
          * or null unless the instance was constructed with produceValueCanvas.
@@ -279,10 +620,20 @@ var TextureFrameSeriesAnimator;
             });
         }
         async fetchAndTint(idx) {
-            const entry = this.frames[idx];
-            const start = entry.ByteOffset;
-            const end = entry.ByteOffset + entry.ByteLength - 1;
-            const response = await fetch(this.archiveUrl, { headers: { Range: `bytes=${start}-${end}` } });
+            const tiles = this.tiles;
+            // Every tile's frame for one timestep sits contiguously, because the generator writes
+            // frame major. So a tiled frame is still ONE range request, not one per tile.
+            let lo = Number.MAX_SAFE_INTEGER;
+            let hi = 0;
+            for (const tile of tiles) {
+                const at = tile.Frames[idx];
+                if (!at) {
+                    continue;
+                }
+                lo = Math.min(lo, at.ByteOffset);
+                hi = Math.max(hi, at.ByteOffset + at.ByteLength);
+            }
+            const response = await fetch(this.archiveUrl, { headers: { Range: `bytes=${lo}-${hi - 1}` } });
             const buffer = await response.arrayBuffer();
             if (this.disposed) {
                 return;
@@ -293,7 +644,7 @@ var TextureFrameSeriesAnimator;
             if (this.disposed) {
                 return;
             }
-            const decoded = await this.decodeAndTint(buffer);
+            const decoded = await this.composeTiles(tiles, idx, buffer, lo);
             if (this.disposed) {
                 return;
             }
@@ -304,39 +655,292 @@ var TextureFrameSeriesAnimator;
                 this.beginCrossfadeTo(idx);
             }
         }
-        /**
-         * Decodes one frame's raw PNG bytes (as returned by a Range GET) and applies the grayscale color mask.
+        /*
+         * Draws every tile of one frame into a single raster covering the drape extent.
          */
-        async decodeAndTint(buffer) {
-            const blob = new Blob([buffer], { type: "image/png" });
-            const objectUrl = URL.createObjectURL(blob);
-            let image;
-            try {
-                image = await (0, image_utils_1.loadImage)(objectUrl);
-            }
-            finally {
-                URL.revokeObjectURL(objectUrl);
-            }
+        async composeTiles(tiles, idx, buffer, spanStart) {
+            const target = this.compositeExtent();
+            const size = this.compositeSize(tiles, target);
             const canvas = document.createElement("canvas");
-            canvas.width = image.width;
-            canvas.height = image.height;
+            canvas.width = size.width;
+            canvas.height = size.height;
             const ctx = canvas.getContext("2d");
-            ctx.drawImage(image, 0, 0);
-            const imageData = ctx.getImageData(0, 0, canvas.width, canvas.height);
+            ctx.imageSmoothingEnabled = false;
+            ctx.clearRect(0, 0, size.width, size.height);
+            const images = await this.decodeSlices(buffer, spanStart, tiles.map((tile) => tile.Frames[idx]));
+            for (let i = 0; i < tiles.length; i++) {
+                const image = images[i];
+                if (!image || this.disposed) {
+                    continue;
+                }
+                const at = this.tileRect(tiles[i], target, size);
+                ctx.drawImage(image, at.x, at.y, at.w, at.h);
+            }
+            return this.tint(ctx.getImageData(0, 0, size.width, size.height));
+        }
+        /*
+         * Where a composited frame is draped, which is the polygon's rectangle when there is one.
+         */
+        compositeExtent() {
+            if (this.drapeExtent) {
+                return this.drapeExtent;
+            }
+            const m = this.metadata;
+            return {
+                West: m && m.West != null ? m.West : -180,
+                East: m && m.East != null ? m.East : 180,
+                South: m && m.South != null ? m.South : -90,
+                North: m && m.North != null ? m.North : 90
+            };
+        }
+        /*
+         * Composite resolution, capped by what can be uploaded as a texture every frame.
+         */
+        compositeSize(tiles, target) {
+            let finest = Number.MAX_VALUE;
+            for (const tile of tiles) {
+                if (tile.TexelMetres > 0) {
+                    finest = Math.min(finest, tile.TexelMetres);
+                }
+            }
+            if (!(finest > 0) || finest === Number.MAX_VALUE) {
+                finest = 1;
+            }
+            const mid = (target.South + target.North) / 2 * Math.PI / 180;
+            const widthM = Math.max((target.East - target.West) * 111320 * Math.cos(mid), 1);
+            const heightM = Math.max((target.North - target.South) * 110574, 1);
+            let width = Math.ceil(widthM / finest);
+            let height = Math.ceil(heightM / finest);
+            const longest = Math.max(width, height);
+            if (longest > MAX_COMPOSITE_TEXELS) {
+                const shrink = MAX_COMPOSITE_TEXELS / longest;
+                width = Math.max(1, Math.round(width * shrink));
+                height = Math.max(1, Math.round(height * shrink));
+            }
+            return { width: Math.max(1, width), height: Math.max(1, height) };
+        }
+        /*
+         * Applies the ramp, borders and baseline mask to raw value pixels, whatever produced them.
+         */
+        tint(imageData) {
+            const canvas = { width: imageData.width, height: imageData.height };
             // Copied before tinting: the ramp is a lerp between two colours, so the value cannot be
             // recovered from the tinted pixels afterwards.
             const valuePixels = this.produceValueCanvas ? new Uint8ClampedArray(imageData.data) : undefined;
-            (0, image_utils_1.ApplyGrayscaleColorMask)(imageData, this.lowColor, this.highColor);
+            // The ramp indexes on R as an 8 bit grey, so a packed frame is flattened to one here
+            // rather than teaching every ramp function a second format.
+            // The copy above keeps the packed pair, which is what displacement and labels read.
+            flattenPacked(imageData.data, IsPackedValue(this.metadata));
+            // Stops win when supplied: they can express a band and a hidden floor, which a two
+            // colour ramp cannot. The pair stays the fallback so an older style still draws.
+            if (this.rampStops && this.rampStops.length > 0) {
+                (0, image_utils_1.ApplyGradientStops)(imageData, this.rampStops);
+            }
+            else {
+                (0, image_utils_1.ApplyGrayscaleColorMask)(imageData, this.lowColor, this.highColor);
+            }
+            if (this.cellBorder) {
+                (0, image_utils_1.ApplyCellBorders)(imageData, this.cellBorder.cellTexels, this.cellBorder.widthTexels, this.cellBorder.color);
+            }
             this.applyBaselineMask(imageData.data, valuePixels, canvas.width, canvas.height);
             if (valuePixels) {
-                dilateValues(valuePixels, canvas.width, canvas.height, VALUE_DILATE_PASSES);
+                dilateValues(valuePixels, canvas.width, canvas.height, VALUE_DILATE_PASSES, IsPackedValue(this.metadata));
             }
             return { pixels: imageData.data, width: canvas.width, height: canvas.height, valuePixels };
         }
+        /*
+         * Paints one frame's composited pixels onto a canvas.
+         */
+        writeInto(canvas, pixels, dims) {
+            canvas.width = dims.width;
+            canvas.height = dims.height;
+            const ctx = canvas.getContext("2d");
+            const image = ctx.createImageData(dims.width, dims.height);
+            image.data.set(pixels);
+            ctx.putImageData(image, 0, 0);
+        }
+        /**
+         * The archive's per-cell floor and ceiling rasters, once EnsureExtremes has resolved.
+         */
+        GetExtremes() {
+            return { floor: this.floorPixels, ceiling: this.ceilingPixels };
+        }
+        /**
+         * Fetches and decodes the floor and ceiling rasters, at most once.
+         */
+        EnsureExtremes() {
+            if (!this.extremesLoad) {
+                this.extremesLoad = this.loadTiledExtremes();
+            }
+            return this.extremesLoad;
+        }
+        /*
+         * Composites each tile's baseline mask into one covering the composited frames.
+         */
+        async loadTiledBaselineMask() {
+            const tiles = this.tiles;
+            const entries = tiles.map((tile) => tile.BaselineMask);
+            let lo = Number.MAX_SAFE_INTEGER;
+            let hi = 0;
+            for (const at of entries) {
+                if (!at) {
+                    continue;
+                }
+                lo = Math.min(lo, at.ByteOffset);
+                hi = Math.max(hi, at.ByteOffset + at.ByteLength);
+            }
+            if (!(hi > lo)) {
+                return;
+            }
+            try {
+                const response = await fetch(this.archiveUrl, { headers: { Range: `bytes=${lo}-${hi - 1}` } });
+                const block = await response.arrayBuffer();
+                if (this.disposed) {
+                    return;
+                }
+                const images = await this.decodeSlices(block, lo, entries);
+                if (this.disposed) {
+                    return;
+                }
+                const target = this.compositeExtent();
+                const size = this.compositeSize(tiles, target);
+                const canvas = document.createElement("canvas");
+                canvas.width = size.width;
+                canvas.height = size.height;
+                const ctx = canvas.getContext("2d");
+                ctx.imageSmoothingEnabled = false;
+                ctx.clearRect(0, 0, size.width, size.height);
+                for (let i = 0; i < tiles.length; i++) {
+                    if (!images[i]) {
+                        continue;
+                    }
+                    const at = this.tileRect(tiles[i], target, size);
+                    ctx.drawImage(images[i], at.x, at.y, at.w, at.h);
+                }
+                const pixels = ctx.getImageData(0, 0, size.width, size.height).data;
+                const flags = new Uint8Array(size.width * size.height);
+                for (let p = 0; p < flags.length; p++) {
+                    flags[p] = pixels[p * 4 + 3] >= 128 ? 1 : 0;
+                }
+                this.baselineFlags = flags;
+                this.baselineDims = { width: size.width, height: size.height };
+            }
+            catch (e) {
+                console.warn("TextureFrameSeriesAnimator: could not load the tiled baseline mask.", e);
+            }
+        }
+        /*
+         * Composites each tile's floor and ceiling into rasters matching the composited frames.
+         *
+         * A label indexes them by the same texel as the value canvas, so they have to be laid out the
+         * same way rather than fetched as whole-extent rasters.
+         */
+        async loadTiledExtremes() {
+            const tiles = this.tiles;
+            const target = this.compositeExtent();
+            const size = this.compositeSize(tiles, target);
+            // One request for the whole extremes block. They sit contiguously after the frames, so
+            // fetching per tile would be 164 round trips for an 82 tile pyramid.
+            let lo = Number.MAX_SAFE_INTEGER;
+            let hi = 0;
+            for (const tile of tiles) {
+                for (const at of [tile.Floor, tile.Ceiling]) {
+                    if (!at) {
+                        continue;
+                    }
+                    lo = Math.min(lo, at.ByteOffset);
+                    hi = Math.max(hi, at.ByteOffset + at.ByteLength);
+                }
+            }
+            if (!(hi > lo)) {
+                return;
+            }
+            const response = await fetch(this.archiveUrl, { headers: { Range: `bytes=${lo}-${hi - 1}` } });
+            const block = await response.arrayBuffer();
+            if (this.disposed) {
+                return;
+            }
+            const draw = async (pick) => {
+                const images = await this.decodeSlices(block, lo, tiles.map(pick));
+                if (this.disposed) {
+                    return null;
+                }
+                const canvas = document.createElement("canvas");
+                canvas.width = size.width;
+                canvas.height = size.height;
+                const ctx = canvas.getContext("2d");
+                ctx.imageSmoothingEnabled = false;
+                ctx.clearRect(0, 0, size.width, size.height);
+                let drew = false;
+                for (let i = 0; i < tiles.length; i++) {
+                    const image = images[i];
+                    if (!image) {
+                        continue;
+                    }
+                    const at = this.tileRect(tiles[i], target, size);
+                    ctx.drawImage(image, at.x, at.y, at.w, at.h);
+                    drew = true;
+                }
+                return drew ? ctx.getImageData(0, 0, size.width, size.height) : null;
+            };
+            try {
+                this.floorPixels = await draw((tile) => tile.Floor);
+                this.ceilingPixels = await draw((tile) => tile.Ceiling);
+            }
+            catch (e) {
+                console.warn("TextureFrameSeriesAnimator: could not load the tiled extremes.", e);
+            }
+        }
+        /*
+         * Where one tile lands on the composite, snapped to whole pixels.
+         *
+         * Rounding each edge rather than the origin and size is what makes neighbours meet exactly:
+         * a tile's right edge and the next tile's left edge round to the same pixel, so no seam of
+         * background shows between them.
+         */
+        tileRect(tile, target, size) {
+            const spanLon = target.East - target.West;
+            const spanLat = target.North - target.South;
+            const x0 = Math.round((tile.West - target.West) / spanLon * size.width);
+            const x1 = Math.round((tile.East - target.West) / spanLon * size.width);
+            const y0 = Math.round((target.North - tile.North) / spanLat * size.height);
+            const y1 = Math.round((target.North - tile.South) / spanLat * size.height);
+            return { x: x0, y: y0, w: Math.max(1, x1 - x0), h: Math.max(1, y1 - y0) };
+        }
+        /*
+         * Decodes many tile images at once.
+         *
+         * Serially awaiting each decode makes a frame cost as many round trips through the image
+         * decoder as there are tiles, which for an 82 tile pyramid is seconds rather than one.
+         */
+        decodeSlices(block, base, entries) {
+            return Promise.all(entries.map(async (at) => {
+                if (!at) {
+                    return null;
+                }
+                const slice = block.slice(at.ByteOffset - base, at.ByteOffset - base + at.ByteLength);
+                const objectUrl = URL.createObjectURL(new Blob([slice], { type: "image/png" }));
+                try {
+                    return await (0, image_utils_1.loadImage)(objectUrl);
+                }
+                catch {
+                    return null;
+                }
+                finally {
+                    URL.revokeObjectURL(objectUrl);
+                }
+            }));
+        }
         /**
          * Fetches and decodes the archive's static baseline mask, at most once.
          */
         ensureBaselineMask() {
+            if (this.maskBaseline && this.tiles) {
+                if (!this.baselineLoad) {
+                    this.baselineLoad = this.loadTiledBaselineMask();
+                }
+                return this.baselineLoad;
+            }
             if (!this.maskBaseline || !this.baselineMaskEntry) {
                 return Promise.resolve();
             }
@@ -449,24 +1053,17 @@ var TextureFrameSeriesAnimator;
         presentPixels(pixels, dims, valuePixels) {
             this.poolIdx = 1 - this.poolIdx;
             const target = this.pool[this.poolIdx];
-            target.width = dims.width;
-            target.height = dims.height;
-            const ctx = target.getContext("2d");
-            const imgData = ctx.createImageData(dims.width, dims.height);
-            imgData.data.set(pixels);
-            ctx.putImageData(imgData, 0, 0);
+            this.writeInto(target, pixels, dims);
             this.displayedPixels = pixels;
             if (this.valueCanvas && valuePixels) {
-                this.valueCanvas.width = dims.width;
-                this.valueCanvas.height = dims.height;
-                const valueCtx = this.valueCanvas.getContext("2d");
-                const valueImgData = valueCtx.createImageData(dims.width, dims.height);
-                valueImgData.data.set(valuePixels);
-                valueCtx.putImageData(valueImgData, 0, 0);
+                this.writeInto(this.valueCanvas, valuePixels, dims);
                 this.displayedValuePixels = valuePixels;
                 this.valueDims = dims;
             }
             this.presentVersion++;
+            if (this.viewer && this.viewer.scene && this.viewer.scene.requestRenderMode) {
+                this.viewer.scene.requestRender();
+            }
         }
     }
     TextureFrameSeriesAnimator.Animator = Animator;