bruce-cesium 7.2.1 → 7.2.2

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

@@ -6,6 +6,87 @@ const Cesium = require("cesium");
 const image_utils_1 = require("../internal/image-utils");
 var TextureFrameSeriesAnimator;
 (function (TextureFrameSeriesAnimator) {
+    // Values are measured up from the ground beneath them.
+    TextureFrameSeriesAnimator.QUANTITY_THICKNESS = "thickness";
+    // Values are heights against a vertical datum, so they need that datum to be placed.
+    TextureFrameSeriesAnimator.QUANTITY_ELEVATION = "elevation";
+    TextureFrameSeriesAnimator.LAYOUT_TILES = "tiles";
+    /**
+     * The generator that produced an archive, for telling a stale one from a current one.
+     *
+     * Read the version rather than sniffing for fields: an archive can legitimately omit Tiles or
+     * GeoidSeparation and still be current, so their absence says nothing about its age.
+     * @param metadata the archive's Data.generation
+     */
+    function GeneratorVersion(metadata) {
+        if (!metadata || typeof metadata.GeneratorVersion !== "number") {
+            return 1;
+        }
+        return metadata.GeneratorVersion;
+    }
+    TextureFrameSeriesAnimator.GeneratorVersion = GeneratorVersion;
+    /**
+     * Whether an archive is an adaptive pyramid rather than one raster.
+     * @param metadata the archive's Data.generation
+     */
+    function IsTiledLayout(metadata) {
+        return (Boolean(metadata && metadata.Layout === TextureFrameSeriesAnimator.LAYOUT_TILES &&
+            metadata.Tiles && metadata.Tiles.length > 0));
+    }
+    TextureFrameSeriesAnimator.IsTiledLayout = IsTiledLayout;
+    // Frames carry the value as the source reported it.
+    TextureFrameSeriesAnimator.MEASURE_ABSOLUTE = "absolute";
+    // Frames carry the value minus each cell's own minimum over the series.
+    TextureFrameSeriesAnimator.MEASURE_ANOMALY = "anomaly";
+    /**
+     * 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;
+    /**
+     * Whether the frames are a departure from each cell's own normal rather than a raw reading.
+     *
+     * Worth asking before labelling anything: the two measures need different words for the same
+     * number, and calling an anomaly "water depth" is a worse error than the coarse ramp it replaced.
+     * @param metadata the archive's Data.generation
+     */
+    function IsAnomalyMeasure(metadata) {
+        return Boolean(metadata && metadata.Measure === TextureFrameSeriesAnimator.MEASURE_ANOMALY);
+    }
+    TextureFrameSeriesAnimator.IsAnomalyMeasure = IsAnomalyMeasure;
+    /**
+     * How much the value moves anywhere in the series, in source units.
+     *
+     * Falls back to the published range, which is the right answer for an anomaly archive (its range
+     * IS the movement) and the only available one for an archive predating AnomalyMax.
+     * @param metadata the archive's Data.generation
+     */
+    function MovingRange(metadata) {
+        if (!metadata) {
+            return undefined;
+        }
+        if (typeof metadata.AnomalyMax === "number" && metadata.AnomalyMax > 0) {
+            return metadata.AnomalyMax;
+        }
+        if (typeof metadata.ValueMin === "number" && typeof metadata.ValueMax === "number") {
+            return Math.abs(metadata.ValueMax - metadata.ValueMin);
+        }
+        return undefined;
+    }
+    TextureFrameSeriesAnimator.MovingRange = MovingRange;
     /**
      * 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.
@@ -15,15 +96,51 @@ var TextureFrameSeriesAnimator;
         return Boolean(data && data.generation && Array.isArray(data.generation.Frames) && data.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.
-     *
-     * 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.
      */
     function dilateValues(value, width, height, passes) {
         const texels = width * height;
@@ -69,7 +186,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;
@@ -95,8 +212,12 @@ var TextureFrameSeriesAnimator;
             // forcing Cesium to re-upload the texture only when something changed.
             this.pool = [document.createElement("canvas"), document.createElement("canvas")];
             this.poolIdx = 0;
+            this.scratch = null;
             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 +229,41 @@ 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 === null || mask === void 0 ? void 0 : 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.metadata = options.metadata;
+            this.drapeExtent = options.drapeExtent;
+            this.tiles = IsTiledLayout(options.metadata) ? options.metadata.Tiles : undefined;
             this.baselineMaskEntry = options.baselineMask || null;
-            this.maskBaseline = (_b = options.maskBaseline) !== null && _b !== void 0 ? _b : Boolean(options.baselineMask);
+            this.maskBaseline = (_c = options.maskBaseline) !== null && _c !== void 0 ? _c : Boolean(options.baselineMask);
             this.valueCanvas = this.produceValueCanvas ? document.createElement("canvas") : null;
             this.driveMaterial = options.driveMaterial !== false;
             this.originalMaterial = options.entity.polygon.material;
@@ -153,6 +299,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 +317,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,11 +438,33 @@ 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 buffer = await response.arrayBuffer();
+            const tiles = this.tiles;
+            let buffer;
+            let span = 0;
+            if (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);
+                }
+                span = lo;
+                const response = await fetch(this.archiveUrl, { headers: { Range: `bytes=${lo}-${hi - 1}` } });
+                buffer = await response.arrayBuffer();
+            }
+            else {
+                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}` } });
+                buffer = await response.arrayBuffer();
+            }
             if (this.disposed) {
                 return;
             }
@@ -293,7 +474,9 @@ var TextureFrameSeriesAnimator;
             if (this.disposed) {
                 return;
             }
-            const decoded = await this.decodeAndTint(buffer);
+            const decoded = tiles
+                ? await this.composeTiles(tiles, idx, buffer, span)
+                : await this.decodeAndTint(buffer);
             if (this.disposed) {
                 return;
             }
@@ -322,21 +505,438 @@ var TextureFrameSeriesAnimator;
             canvas.height = image.height;
             const ctx = canvas.getContext("2d");
             ctx.drawImage(image, 0, 0);
-            const imageData = ctx.getImageData(0, 0, canvas.width, canvas.height);
+            return this.tint(ctx.getImageData(0, 0, canvas.width, canvas.height));
+        }
+        /*
+         * Draws every tile of one frame into a single raster covering the drape extent.
+         */
+        async composeTiles(tiles, idx, buffer, spanStart) {
+            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);
+            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);
+            // 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);
             }
             return { pixels: imageData.data, width: canvas.width, height: canvas.height, valuePixels };
         }
+        /*
+         * Paints one frame's pixels onto a canvas, resampled into the drape extent when there is one.
+         */
+        writeInto(canvas, pixels, dims) {
+            const rect = this.sourceRect(dims);
+            if (!rect) {
+                canvas.width = dims.width;
+                canvas.height = dims.height;
+                const direct = canvas.getContext("2d");
+                const image = direct.createImageData(dims.width, dims.height);
+                image.data.set(pixels);
+                direct.putImageData(image, 0, 0);
+                return;
+            }
+            if (!this.scratch) {
+                this.scratch = document.createElement("canvas");
+            }
+            this.scratch.width = dims.width;
+            this.scratch.height = dims.height;
+            const scratchCtx = this.scratch.getContext("2d");
+            const image = scratchCtx.createImageData(dims.width, dims.height);
+            image.data.set(pixels);
+            scratchCtx.putImageData(image, 0, 0);
+            canvas.width = dims.width;
+            canvas.height = dims.height;
+            const ctx = canvas.getContext("2d");
+            // Nearest neighbour: a value texel has to survive the resample exactly, or a label reads
+            // a blend of two cells rather than the cell it points at.
+            ctx.imageSmoothingEnabled = false;
+            ctx.clearRect(0, 0, dims.width, dims.height);
+            ctx.drawImage(this.scratch, rect.x, rect.y, rect.width, rect.height, 0, 0, dims.width, dims.height);
+        }
+        /*
+         * The part of the archive raster that the drape extent covers, in source pixels.
+         */
+        sourceRect(dims) {
+            const drape = this.drapeExtent;
+            const m = this.metadata;
+            // A composited frame was drawn into the drape extent already, so resampling it again
+            // would apply the same correction twice.
+            if (this.tiles) {
+                return null;
+            }
+            if (!drape || !m || m.West == null || m.East == null || m.South == null || m.North == null) {
+                return null;
+            }
+            const spanLon = m.East - m.West;
+            const spanLat = m.North - m.South;
+            if (!(spanLon > 0) || !(spanLat > 0)) {
+                return null;
+            }
+            const x = (drape.West - m.West) / spanLon * dims.width;
+            const width = (drape.East - drape.West) / spanLon * dims.width;
+            const y = (m.North - drape.North) / spanLat * dims.height;
+            const height = (drape.North - drape.South) / spanLat * dims.height;
+            // A drape that already matches the archive is the common case and must not pay for a
+            // resample, nor lose a half pixel to rounding.
+            if (Math.abs(x) < 0.01 && Math.abs(y) < 0.01
+                && Math.abs(width - dims.width) < 0.01 && Math.abs(height - dims.height) < 0.01) {
+                return null;
+            }
+            return { x, y, width, height };
+        }
+        /**
+         * 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) {
+                return this.extremesLoad;
+            }
+            if (this.tiles) {
+                this.extremesLoad = this.loadTiledExtremes();
+                return this.extremesLoad;
+            }
+            const floor = this.metadata && this.metadata.Floor;
+            const ceiling = this.metadata && this.metadata.Ceiling;
+            if (!floor && !ceiling) {
+                this.extremesLoad = Promise.resolve();
+                return this.extremesLoad;
+            }
+            this.extremesLoad = Promise.all([
+                floor ? this.loadImageDataAt(floor) : Promise.resolve(null),
+                ceiling ? this.loadImageDataAt(ceiling) : Promise.resolve(null)
+            ]).then(([f, c]) => {
+                if (this.disposed) {
+                    return;
+                }
+                this.floorPixels = f;
+                this.ceilingPixels = c;
+            }).catch((e) => {
+                // Missing extremes cost a label its range, and must not take the animation with them.
+                console.warn("TextureFrameSeriesAnimator: could not load the extremes rasters.", e);
+            });
+            return this.extremesLoad;
+        }
+        /*
+         * Composites each tile's baseline mask into one covering the composited frames.
+         *
+         * A tiled archive publishes the mask per tile, so reading the archive level BaselineMask
+         * finds nothing and hiding dry cells silently does nothing at all.
+         */
+        async loadTiledBaselineMask() {
+            const tiles = this.tiles;
+            if (!tiles) {
+                return;
+            }
+            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 tiled archive has no whole-extent extremes to fetch, only per-tile ones, and a label
+         * indexes them by the same texel as the value canvas, so they have to be laid out the same way.
+         */
+        async loadTiledExtremes() {
+            const tiles = this.tiles;
+            if (!tiles) {
+                return;
+            }
+            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);
+                }
+            }));
+        }
+        /*
+         * Range GETs one entry and decodes it to an image.
+         */
+        async loadImageAt(entry) {
+            const start = entry.ByteOffset;
+            const end = entry.ByteOffset + entry.ByteLength - 1;
+            const response = await fetch(this.archiveUrl, { headers: { Range: `bytes=${start}-${end}` } });
+            const buffer = await response.arrayBuffer();
+            const objectUrl = URL.createObjectURL(new Blob([buffer], { type: "image/png" }));
+            try {
+                return await (0, image_utils_1.loadImage)(objectUrl);
+            }
+            finally {
+                URL.revokeObjectURL(objectUrl);
+            }
+        }
+        /*
+         * Puts a static raster through the same resample the frames get.
+         */
+        remap(image) {
+            if (!image) {
+                return null;
+            }
+            const rect = this.sourceRect({ width: image.width, height: image.height });
+            if (!rect) {
+                return image;
+            }
+            const from = document.createElement("canvas");
+            from.width = image.width;
+            from.height = image.height;
+            from.getContext("2d").putImageData(image, 0, 0);
+            const to = document.createElement("canvas");
+            to.width = image.width;
+            to.height = image.height;
+            const ctx = to.getContext("2d");
+            ctx.imageSmoothingEnabled = false;
+            ctx.clearRect(0, 0, image.width, image.height);
+            ctx.drawImage(from, rect.x, rect.y, rect.width, rect.height, 0, 0, image.width, image.height);
+            return ctx.getImageData(0, 0, image.width, image.height);
+        }
+        /*
+         * Range GETs one entry out of the blob and decodes it to pixels.
+         */
+        async loadImageDataAt(entry) {
+            const start = entry.ByteOffset;
+            const end = entry.ByteOffset + entry.ByteLength - 1;
+            const response = await fetch(this.archiveUrl, { headers: { Range: `bytes=${start}-${end}` } });
+            const buffer = await response.arrayBuffer();
+            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);
+            }
+            const canvas = document.createElement("canvas");
+            canvas.width = image.width;
+            canvas.height = image.height;
+            const ctx = canvas.getContext("2d");
+            ctx.drawImage(image, 0, 0);
+            return ctx.getImageData(0, 0, canvas.width, canvas.height);
+        }
         /**
          * 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 +1049,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;