bruce-cesium 7.1.3 → 7.1.5

package/dist/bruce-cesium.umd.js

@@ -39622,15 +39622,68 @@
             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.
+        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;
+            const filled = new Uint8Array(texels);
+            for (let p = 0; p < texels; p++) {
+                filled[p] = value[p * 4 + 3] !== 0 ? 1 : 0;
+            }
+            for (let pass = 0; pass < passes; pass++) {
+                const source = value.slice();
+                const wasFilled = filled.slice();
+                for (let y = 0; y < height; y++) {
+                    for (let x = 0; x < width; x++) {
+                        const p = y * width + x;
+                        if (wasFilled[p]) {
+                            continue;
+                        }
+                        let sum = 0;
+                        let hits = 0;
+                        for (let dy = -1; dy <= 1; dy++) {
+                            for (let dx = -1; dx <= 1; dx++) {
+                                const nx = x + dx;
+                                const ny = y + dy;
+                                if (nx < 0 || ny < 0 || nx >= width || ny >= height || !wasFilled[ny * width + nx]) {
+                                    continue;
+                                }
+                                sum += source[(ny * width + nx) * 4];
+                                hits++;
+                            }
+                        }
+                        if (hits > 0) {
+                            const v = Math.round(sum / hits);
+                            value[p * 4] = v;
+                            value[p * 4 + 1] = v;
+                            value[p * 4 + 2] = v;
+                            filled[p] = 1;
+                        }
+                    }
+                }
+            }
+        }
         const DEFAULT_CROSSFADE_MS = 900;
         const DEFAULT_LOW_COLOR = { red: 255, green: 255, blue: 255, alpha: 0.12 };
         const DEFAULT_HIGH_COLOR = { red: 21, green: 96, blue: 196, alpha: 0.92 };
         class Animator {
             constructor(options) {
-                var _a;
+                var _a, _b;
                 this.removeOnTick = null;
                 this.removeCrossfadeTick = null;
                 this.disposed = false;
+                // One alpha byte per texel, 1 meaning the texel is baseline. Fetched once, the mesh does not move.
+                this.baselineFlags = null;
+                this.baselineDims = null;
+                this.baselineLoad = null;
                 this.currentFrameIndex = -1;
                 // Single-in-flight fetch queue: only one Range GET outstanding at a time, and the NEXT one
                 // is chosen right before sending, this is what makes reprioritizing mid-scrub take effect
@@ -39639,6 +39692,8 @@
                 this.pendingIndex = -1;
                 this.displayedPixels = null;
                 this.fadeFromPixels = null;
+                this.displayedValuePixels = null;
+                this.fadeFromValuePixels = null;
                 this.fadeToIndex = -1;
                 this.fadeToDims = null;
                 this.fadeStartMs = null;
@@ -39647,6 +39702,8 @@
                 // forcing Cesium to re-upload the texture only when something changed.
                 this.pool = [document.createElement("canvas"), document.createElement("canvas")];
                 this.poolIdx = 0;
+                this.valueDims = null;
+                this.presentVersion = 0;
                 if (!options.entity.polygon) {
                     throw new Error("TextureFrameSeriesAnimator requires an entity with polygon graphics.");
                 }
@@ -39664,9 +39721,17 @@
                 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.valueCanvas = this.produceValueCanvas ? document.createElement("canvas") : null;
+                this.driveMaterial = options.driveMaterial !== false;
                 this.originalMaterial = options.entity.polygon.material;
                 this.imageProperty = new Cesium.CallbackProperty(() => this.pool[this.poolIdx], false);
-                options.entity.polygon.material = new Cesium.ImageMaterialProperty({ image: this.imageProperty, transparent: true });
+                if (this.driveMaterial) {
+                    options.entity.polygon.material = new Cesium.ImageMaterialProperty({ image: this.imageProperty, transparent: true });
+                }
                 this.removeCrossfadeTick = this.viewer.scene.postUpdate.addEventListener(() => this.tickCrossfade());
                 this.removeOnTick = this.viewer.clock.onTick.addEventListener((clock) => this.onClockTick(clock.currentTime));
                 this.onClockTick(this.viewer.clock.currentTime);
@@ -39688,7 +39753,7 @@
                     this.removeCrossfadeTick();
                     this.removeCrossfadeTick = null;
                 }
-                if (this.entity && this.entity.polygon) {
+                if (this.driveMaterial && this.entity && this.entity.polygon) {
                     this.entity.polygon.material = this.originalMaterial;
                 }
             }
@@ -39709,6 +39774,20 @@
             GetImageProperty() {
                 return this.imageProperty;
             }
+            /**
+             * 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.
+             */
+            GetValueCanvas() {
+                return this.valueDims ? this.valueCanvas : null;
+            }
+            /**
+             * Increments every time a frame is presented, so a consumer holding the value canvas can tell
+             * whether it needs re-uploading without diffing pixels or subscribing to anything.
+             */
+            GetPresentVersion() {
+                return this.presentVersion;
+            }
             onClockTick(currentTime) {
                 if (this.disposed) {
                     return;
@@ -39815,12 +39894,19 @@
                 if (this.disposed) {
                     return;
                 }
+                // Awaited before decoding rather than applied later, so no frame is ever cached unmasked and
+                // then corrected once the mask lands.
+                await this.ensureBaselineMask();
+                if (this.disposed) {
+                    return;
+                }
                 const decoded = await this.decodeAndTint(buffer);
                 if (this.disposed) {
                     return;
                 }
                 this.frameCache[idx] = decoded.pixels;
                 this.frameDims[idx] = { width: decoded.width, height: decoded.height };
+                this.valueCache[idx] = decoded.valuePixels || null;
                 if (idx === this.currentFrameIndex) {
                     this.beginCrossfadeTo(idx);
                 }
@@ -39844,11 +39930,90 @@
                 const ctx = canvas.getContext("2d");
                 ctx.drawImage(image, 0, 0);
                 const imageData = ctx.getImageData(0, 0, canvas.width, canvas.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;
                 ApplyGrayscaleColorMask(imageData, this.lowColor, this.highColor);
-                return { pixels: imageData.data, width: canvas.width, height: canvas.height };
+                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 };
+            }
+            /**
+             * Fetches and decodes the archive's static baseline mask, at most once.
+             */
+            ensureBaselineMask() {
+                if (!this.maskBaseline || !this.baselineMaskEntry) {
+                    return Promise.resolve();
+                }
+                if (this.baselineLoad) {
+                    return this.baselineLoad;
+                }
+                const entry = this.baselineMaskEntry;
+                const start = entry.ByteOffset;
+                const end = entry.ByteOffset + entry.ByteLength - 1;
+                this.baselineLoad = fetch(this.archiveUrl, { headers: { Range: `bytes=${start}-${end}` } })
+                    .then((response) => response.arrayBuffer())
+                    .then(async (buffer) => {
+                    if (this.disposed) {
+                        return;
+                    }
+                    const blob = new Blob([buffer], { type: "image/png" });
+                    const objectUrl = URL.createObjectURL(blob);
+                    let image;
+                    try {
+                        image = await 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);
+                    const pixels = ctx.getImageData(0, 0, canvas.width, canvas.height).data;
+                    const flags = new Uint8Array(canvas.width * canvas.height);
+                    for (let p = 0; p < flags.length; p++) {
+                        flags[p] = pixels[p * 4 + 3] >= 128 ? 1 : 0;
+                    }
+                    this.baselineFlags = flags;
+                    this.baselineDims = { width: canvas.width, height: canvas.height };
+                })
+                    .catch((e) => {
+                    // A missing or unreadable mask must not stop the animation; it just means nothing is hidden.
+                    console.warn("TextureFrameSeriesAnimator: could not load the baseline mask, drawing it instead.", e);
+                });
+                return this.baselineLoad;
+            }
+            /**
+             * Clears alpha on baseline texels, which is what makes hiding the dry/land sentinel a render choice.
+             */
+            applyBaselineMask(pixels, valuePixels, width, height) {
+                const flags = this.baselineFlags;
+                if (!flags || !this.baselineDims) {
+                    return;
+                }
+                // A mask from a different raster size cannot be indexed against this frame, and guessing a
+                // resampling would silently hide the wrong ground.
+                if (this.baselineDims.width !== width || this.baselineDims.height !== height) {
+                    return;
+                }
+                for (let p = 0; p < flags.length; p++) {
+                    if (flags[p]) {
+                        pixels[p * 4 + 3] = 0;
+                        if (valuePixels) {
+                            valuePixels[p * 4 + 3] = 0;
+                        }
+                    }
+                }
             }
             beginCrossfadeTo(idx) {
                 const to = this.frameCache[idx];
+                this.fadeFromValuePixels = this.displayedValuePixels === null && this.valueCache[idx]
+                    ? new Uint8ClampedArray(this.valueCache[idx].length)
+                    : this.displayedValuePixels;
                 this.fadeFromPixels = this.displayedPixels === null ? new Uint8ClampedArray(to.length) : this.displayedPixels;
                 this.fadeToIndex = idx;
                 this.fadeToDims = this.frameDims[idx];
@@ -39867,13 +40032,28 @@
                 for (let i = 0; i < n; i++) {
                     blended[i] = from[i] + (to[i] - from[i]) * eased;
                 }
-                this.presentPixels(blended, this.fadeToDims);
+                let blendedValue = null;
+                const toValue = this.valueCache[this.fadeToIndex];
+                if (toValue) {
+                    const fromValue = this.fadeFromValuePixels;
+                    blendedValue = new Uint8ClampedArray(toValue.length);
+                    if (fromValue && fromValue.length === toValue.length) {
+                        for (let i = 0; i < toValue.length; i++) {
+                            blendedValue[i] = fromValue[i] + (toValue[i] - fromValue[i]) * eased;
+                        }
+                    }
+                    else {
+                        blendedValue.set(toValue);
+                    }
+                }
+                this.presentPixels(blended, this.fadeToDims, blendedValue);
                 if (t >= 1) {
                     this.fadeStartMs = null;
                     this.fadeFromPixels = null;
+                    this.fadeFromValuePixels = null;
                 }
             }
-            presentPixels(pixels, dims) {
+            presentPixels(pixels, dims, valuePixels) {
                 this.poolIdx = 1 - this.poolIdx;
                 const target = this.pool[this.poolIdx];
                 target.width = dims.width;
@@ -39883,6 +40063,17 @@
                 imgData.data.set(pixels);
                 ctx.putImageData(imgData, 0, 0);
                 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.displayedValuePixels = valuePixels;
+                    this.valueDims = dims;
+                }
+                this.presentVersion++;
             }
         }
         TextureFrameSeriesAnimator.Animator = Animator;
@@ -39894,10 +40085,737 @@
         }
     })(TextureFrameSeriesAnimator || (TextureFrameSeriesAnimator = {}));
 
+    (function (DisplacedSurfacePrimitive) {
+        // Grid densities a tile can draw at, coarsest first.
+        const TIERS = [32, 64, 128, 192];
+        // Tiles per side the extent is cut into.
+        const TILES_PER_SIDE = 6;
+        // Screen pixels one grid cell should cover. Lower means finer meshes sooner.
+        const TARGET_CELL_PIXELS = 12;
+        // Fraction of its distance to the surface the camera must move before densities are reconsidered.
+        const MOVEMENT_THRESHOLD = 0.12;
+        const RESELECT_INTERVAL_MS = 400;
+        // Skirt depth as a fraction of the displaced range. The sheet is translucent, so an oversized
+        // skirt blends through it and paints a seam down every tile boundary.
+        const SKIRT_FRACTION = 0.015;
+        // Alpha below which a texel counts as no-data and is not drawn at all.
+        const COVERAGE_CUTOFF = 0.35;
+        // With no exaggeration stated, the full value range is drawn as this fraction of the extent's shorter side.
+        const AUTO_RELIEF_FRACTION = 0.02;
+        // Terrain is sampled on this grid and interpolated between samples.
+        // Per-texel sampling would be hundreds of thousands of lookups for a surface whose own data is far coarser than that.
+        const GROUND_SAMPLES_PER_SIDE = 64;
+        // Terrain detail level the samples are taken at.
+        // Most-detailed would fetch every tile under a parcel that can be a hundred kilometres across.
+        const GROUND_SAMPLE_LEVEL = 11;
+        // Height window the packed ground texture covers, wide enough for any terrain on Earth.
+        const GROUND_MIN_METRES = -1000;
+        const GROUND_MAX_METRES = 9000;
+        const DEFAULT_LOW_COLOR = { red: 255, green: 255, blue: 255, alpha: 0.12 };
+        const DEFAULT_HIGH_COLOR = { red: 21, green: 96, blue: 196, alpha: 0.92 };
+        const VERTEX_SHADER_GLSL300 = `
+in vec3 position3DHigh;
+in vec3 position3DLow;
+in vec3 normal;
+in vec2 st;
+in float skirt;
+
+uniform sampler2D u_valueTexture;
+uniform sampler2D u_groundTexture;
+uniform float u_valueMin;
+uniform float u_valueRange;
+uniform float u_exaggeration;
+uniform float u_baseHeight;
+uniform float u_skirtDepth;
+uniform float u_groundWeight;
+uniform vec2 u_groundRange;
+uniform vec2 u_groundSize;
+
+out vec2 v_st;
+out float v_value;
+out float v_coverage;
+
+float decodeGround(vec2 uv) {
+    // Channels arrive normalised to 0..1, so they go back to bytes before being reassembled.
+    vec3 packed = texture(u_groundTexture, uv).rgb * 255.0;
+    float normalised = dot(packed, vec3(65536.0, 256.0, 1.0)) / 16777215.0;
+    return u_groundRange.x + normalised * (u_groundRange.y - u_groundRange.x);
+}
+
+/*
+ * Bilinear by hand, because the height is packed across three channels and hardware filtering would
+ * blend the packing rather than the heights, turning a smooth slope into noise at every texel edge.
+ */
+float sampleGround(vec2 uv) {
+    vec2 texel = 1.0 / u_groundSize;
+    vec2 coord = uv * u_groundSize - 0.5;
+    vec2 base = floor(coord);
+    vec2 f = coord - base;
+    vec2 origin = (base + 0.5) * texel;
+    float h00 = decodeGround(origin);
+    float h10 = decodeGround(origin + vec2(texel.x, 0.0));
+    float h01 = decodeGround(origin + vec2(0.0, texel.y));
+    float h11 = decodeGround(origin + texel);
+    return mix(mix(h00, h10, f.x), mix(h01, h11, f.x), f.y);
+}
+
+void main() {
+    vec4 texel = texture(u_valueTexture, st);
+    v_st = st;
+    v_value = texel.r;
+    v_coverage = texel.a;
+
+    float metres = u_valueMin + texel.r * u_valueRange;
+
+    // Value zero sits at the polygon's own altitude, plus the terrain underneath when the polygon
+    // is following the ground rather than absolutely positioned.
+    float ground = sampleGround(st) * u_groundWeight;
+    float displacement = u_baseHeight + ground + metres * u_exaggeration * texel.a - skirt * u_skirtDepth;
+
+    // Added to the LOW half of the encoded position: a metre-scale offset added to the high half
+    // would be lost to float32 rounding at an earth radius.
+    vec4 p = czm_translateRelativeToEye(position3DHigh, position3DLow + normal * displacement);
+    gl_Position = czm_modelViewProjectionRelativeToEye * p;
+}
+`;
+        const FRAGMENT_SHADER_GLSL300 = `
+uniform sampler2D u_valueTexture;
+uniform vec4 u_lowColor;
+uniform vec4 u_highColor;
+uniform float u_coverageCutoff;
+uniform vec2 u_texelSize;
+uniform float u_valueRange;
+uniform float u_exaggeration;
+uniform float u_metresPerTexel;
+
+in vec2 v_st;
+in float v_value;
+in float v_coverage;
+
+void main() {
+    if (v_coverage < u_coverageCutoff) {
+        discard;
+    }
+    vec4 color = mix(u_lowColor, u_highColor, v_value);
+
+    // Relief shading from the value gradient, so the displacement reads at a distance without
+    // recomputing vertex normals every time the texture changes.
+    float left = texture(u_valueTexture, v_st - vec2(u_texelSize.x, 0.0)).r;
+    float right = texture(u_valueTexture, v_st + vec2(u_texelSize.x, 0.0)).r;
+    float down = texture(u_valueTexture, v_st - vec2(0.0, u_texelSize.y)).r;
+    float up = texture(u_valueTexture, v_st + vec2(0.0, u_texelSize.y)).r;
+    float scale = u_valueRange * u_exaggeration;
+    vec3 n = normalize(vec3((left - right) * scale, (down - up) * scale, 2.0 * u_metresPerTexel));
+    float lambert = clamp(dot(n, normalize(vec3(-0.5, -0.6, 0.62))), 0.0, 1.0);
+    color.rgb *= 0.45 + 0.9 * lambert;
+
+    out_FragColor = vec4(color.rgb, color.a * v_coverage);
+}
+`;
+        /*
+         * Rewrites a GLSL 300 es source into the GLSL 100 dialect older Cesium builds author in.
+         */
+        function toGlsl100(source, isFragment) {
+            let result = source
+                .replace(/\btexture\s*\(/g, "texture2D(")
+                .replace(/^in\s+/gm, isFragment ? "varying " : "attribute ")
+                .replace(/^out\s+/gm, "varying ");
+            if (isFragment) {
+                result = result.replace(/\bout_FragColor\b/g, "gl_FragColor");
+            }
+            return result;
+        }
+        let _glsl300Support = null;
+        /*
+         * Works out which GLSL dialect this host's Cesium authors shaders in.
+         */
+        function usesGlsl300(context) {
+            if (_glsl300Support !== null) {
+                return _glsl300Support;
+            }
+            let modernizes = false;
+            try {
+                const probe = new Cesium.ShaderSource({
+                    sources: ["varying float v_probe;\nvoid main() { gl_Position = vec4(0.0); }"],
+                    includeBuiltIns: false
+                });
+                const combined = probe.createCombinedVertexShader(context);
+                modernizes = combined.indexOf("varying") < 0;
+            }
+            catch (e) {
+                // No probe means no evidence the host rewrites anything, so trust the context alone.
+                modernizes = false;
+            }
+            _glsl300Support = Boolean(context.webgl2) && !modernizes;
+            return _glsl300Support;
+        }
+        /*
+         * Places grid node (fx, fy) on the ellipsoid, stepping the way the raster was sampled.
+         * A raster sampled at lon/lat has to be walked in degrees; one sampled linearly across a projected CRS has to be walked in tangent-plane metres.
+         */
+        function makePlacer(extent, pixelPlacement) {
+            if (pixelPlacement === "lonlat") {
+                return (fx, fy) => Cesium.Cartesian3.fromDegrees(Cesium.Math.lerp(extent.West, extent.East, fx), Cesium.Math.lerp(extent.North, extent.South, fy), 0);
+            }
+            const ellipsoid = Cesium.Ellipsoid.WGS84;
+            const centre = Cesium.Cartesian3.fromDegrees((extent.West + extent.East) / 2, (extent.South + extent.North) / 2, 0);
+            const frame = Cesium.Transforms.eastNorthUpToFixedFrame(centre);
+            const toLocal = Cesium.Matrix4.inverse(frame, new Cesium.Matrix4());
+            const southWest = Cesium.Matrix4.multiplyByPoint(toLocal, Cesium.Cartesian3.fromDegrees(extent.West, extent.South, 0), new Cesium.Cartesian3());
+            const northEast = Cesium.Matrix4.multiplyByPoint(toLocal, Cesium.Cartesian3.fromDegrees(extent.East, extent.North, 0), new Cesium.Cartesian3());
+            return (fx, fy) => {
+                const local = new Cesium.Cartesian3(Cesium.Math.lerp(southWest.x, northEast.x, fx), Cesium.Math.lerp(northEast.y, southWest.y, fy), 0);
+                const world = Cesium.Matrix4.multiplyByPoint(frame, local, new Cesium.Cartesian3());
+                return ellipsoid.scaleToGeodeticSurface(world, world);
+            };
+        }
+        /*
+         * Builds one tile's grid, optionally plus a duplicated perimeter ring the shader pushes downwards to
+         * cover the crack where a neighbouring tile at a different density interpolates the shared edge.
+         */
+        function buildGeometry(extent, resolution, patch, pixelPlacement, withSkirt = false) {
+            const cols = resolution;
+            const rows = resolution;
+            const gridCount = (cols + 1) * (rows + 1);
+            const perimeterCount = withSkirt ? 2 * (cols + 1) + 2 * (rows + 1) - 4 : 0;
+            const count = gridCount + perimeterCount;
+            const positions = new Float64Array(count * 3);
+            const normals = new Float32Array(count * 3);
+            const sts = new Float32Array(count * 2);
+            const skirts = new Float32Array(count);
+            const ellipsoid = Cesium.Ellipsoid.WGS84;
+            const place = makePlacer(extent, pixelPlacement);
+            let v = 0;
+            for (let row = 0; row <= rows; row++) {
+                // Texture row 0 is the north edge, so t runs opposite to northing.
+                const fy = Cesium.Math.lerp(patch.v0, patch.v1, row / rows);
+                for (let col = 0; col <= cols; col++) {
+                    const fx = Cesium.Math.lerp(patch.u0, patch.u1, col / cols);
+                    const position = place(fx, fy);
+                    positions[v * 3] = position.x;
+                    positions[v * 3 + 1] = position.y;
+                    positions[v * 3 + 2] = position.z;
+                    const up = ellipsoid.geodeticSurfaceNormal(position, new Cesium.Cartesian3());
+                    normals[v * 3] = up.x;
+                    normals[v * 3 + 1] = up.y;
+                    normals[v * 3 + 2] = up.z;
+                    sts[v * 2] = fx;
+                    sts[v * 2 + 1] = fy;
+                    v++;
+                }
+            }
+            const indices = new Uint32Array(cols * rows * 6 + perimeterCount * 6);
+            let i = 0;
+            for (let row = 0; row < rows; row++) {
+                for (let col = 0; col < cols; col++) {
+                    const topLeft = row * (cols + 1) + col;
+                    const topRight = topLeft + 1;
+                    const bottomLeft = topLeft + (cols + 1);
+                    const bottomRight = bottomLeft + 1;
+                    indices[i++] = topLeft;
+                    indices[i++] = bottomLeft;
+                    indices[i++] = topRight;
+                    indices[i++] = topRight;
+                    indices[i++] = bottomLeft;
+                    indices[i++] = bottomRight;
+                }
+            }
+            // Perimeter walked as one closed loop, so consecutive entries are always neighbours.
+            const loop = [];
+            for (let col = 0; col <= cols; col++) {
+                loop.push(col);
+            }
+            for (let row = 1; row <= rows; row++) {
+                loop.push(row * (cols + 1) + cols);
+            }
+            for (let col = cols - 1; col >= 0; col--) {
+                loop.push(rows * (cols + 1) + col);
+            }
+            for (let row = rows - 1; row >= 1; row--) {
+                loop.push(row * (cols + 1));
+            }
+            const skirtStart = gridCount;
+            if (withSkirt) {
+                loop.forEach((gridIndex, k) => {
+                    const target = skirtStart + k;
+                    positions[target * 3] = positions[gridIndex * 3];
+                    positions[target * 3 + 1] = positions[gridIndex * 3 + 1];
+                    positions[target * 3 + 2] = positions[gridIndex * 3 + 2];
+                    normals[target * 3] = normals[gridIndex * 3];
+                    normals[target * 3 + 1] = normals[gridIndex * 3 + 1];
+                    normals[target * 3 + 2] = normals[gridIndex * 3 + 2];
+                    sts[target * 2] = sts[gridIndex * 2];
+                    sts[target * 2 + 1] = sts[gridIndex * 2 + 1];
+                    skirts[target] = 1;
+                });
+                for (let k = 0; k < loop.length; k++) {
+                    const nextK = (k + 1) % loop.length;
+                    indices[i++] = loop[k];
+                    indices[i++] = skirtStart + k;
+                    indices[i++] = loop[nextK];
+                    indices[i++] = loop[nextK];
+                    indices[i++] = skirtStart + k;
+                    indices[i++] = skirtStart + nextK;
+                }
+            }
+            const geometry = new Cesium.Geometry({
+                attributes: {
+                    position: new Cesium.GeometryAttribute({
+                        componentDatatype: Cesium.ComponentDatatype.DOUBLE,
+                        componentsPerAttribute: 3,
+                        values: positions
+                    }),
+                    normal: new Cesium.GeometryAttribute({
+                        componentDatatype: Cesium.ComponentDatatype.FLOAT,
+                        componentsPerAttribute: 3,
+                        values: normals
+                    }),
+                    st: new Cesium.GeometryAttribute({
+                        componentDatatype: Cesium.ComponentDatatype.FLOAT,
+                        componentsPerAttribute: 2,
+                        values: sts
+                    }),
+                    skirt: new Cesium.GeometryAttribute({
+                        componentDatatype: Cesium.ComponentDatatype.FLOAT,
+                        componentsPerAttribute: 1,
+                        values: skirts
+                    })
+                },
+                indices: indices,
+                primitiveType: Cesium.PrimitiveType.TRIANGLES,
+                boundingSphere: Cesium.BoundingSphere.fromVertices(Array.prototype.slice.call(positions))
+            });
+            // Splits position into the high/low pair Cesium's relative-to-eye shaders expect.
+            Cesium.GeometryPipeline.encodeAttribute(geometry, "position", "position3DHigh", "position3DLow");
+            return geometry;
+        }
+        class Surface {
+            constructor(options, hasCoverage) {
+                var _a, _b, _c, _d;
+                this.show = true;
+                this.valueSource = null;
+                this.lastPresentVersion = -1;
+                this.texture = null;
+                this.textureDirty = true;
+                this.shaderProgram = null;
+                this.renderState = null;
+                this.destroyed = false;
+                this.lastEyePosition = null;
+                this.lastSelectionMs = -Infinity;
+                this.selectionDirty = true;
+                this.groundTexture = null;
+                this.groundPixels = null;
+                this.groundRequested = false;
+                this.followGround = Boolean(options.followGround);
+                this.terrainProvider = options.terrainProvider || null;
+                this.extent = options.extent;
+                this.source = options.source || null;
+                this.valueMin = (_a = options.valueMin) !== null && _a !== void 0 ? _a : 0;
+                this.valueMax = (_b = options.valueMax) !== null && _b !== void 0 ? _b : 1;
+                this.exaggeration = (_c = options.exaggeration) !== null && _c !== void 0 ? _c : autoExaggeration(this.extent, this.valueMin, this.valueMax);
+                this.baseHeight = (_d = options.baseHeight) !== null && _d !== void 0 ? _d : 0;
+                this.pixelPlacement = options.pixelPlacement;
+                this.tileSkirts = Boolean(options.tileSkirts);
+                this.lowColor = toCesiumColor(options.lowColor || DEFAULT_LOW_COLOR);
+                this.highColor = toCesiumColor(options.highColor || DEFAULT_HIGH_COLOR);
+                this.tiles = buildTiles(hasCoverage);
+            }
+            GetFollowsGround() {
+                return this.followGround;
+            }
+            GetPixelPlacement() {
+                return this.pixelPlacement;
+            }
+            GetBaseHeight() {
+                return this.baseHeight;
+            }
+            GetExaggeration() {
+                return this.exaggeration;
+            }
+            GetExtent() {
+                return this.extent;
+            }
+            SetExaggeration(exaggeration) {
+                this.exaggeration = exaggeration;
+            }
+            SetBaseHeight(baseHeight) {
+                this.baseHeight = baseHeight;
+            }
+            /**
+             * Feeds the surface from an animated frame series.
+             * Height and colour advance with the clock without the caller having to push each frame in.
+             */
+            BindAnimator(source) {
+                this.valueSource = source;
+            }
+            /**
+             * Tells the surface its source canvas has been redrawn and the texture needs re-uploading.
+             */
+            MarkSourceDirty() {
+                this.textureDirty = true;
+            }
+            update(frameState) {
+                if (!this.show || this.destroyed || this.tiles.length === 0) {
+                    return;
+                }
+                const context = frameState.context;
+                if (this.valueSource) {
+                    const canvas = this.valueSource.GetValueCanvas();
+                    if (!canvas) {
+                        // No frame decoded yet, so there is nothing to displace against.
+                        return;
+                    }
+                    const version = this.valueSource.GetPresentVersion();
+                    if (canvas !== this.source || version !== this.lastPresentVersion) {
+                        this.source = canvas;
+                        this.lastPresentVersion = version;
+                        this.textureDirty = true;
+                    }
+                }
+                if (!this.source || !this.source.width || !this.source.height) {
+                    return;
+                }
+                this.syncTexture(context);
+                this.requestGround();
+                this.syncGroundTexture(context);
+                // A tile needs one mesh before it has a bounding sphere to measure against.
+                for (const tile of this.tiles) {
+                    if (!tile.centre) {
+                        this.ensureMesh(context, tile, TIERS[0]);
+                    }
+                }
+                const nowMs = now();
+                if (this.shouldReselect(frameState, nowMs)) {
+                    this.selectTiers(frameState);
+                    this.lastSelectionMs = nowMs;
+                    this.lastEyePosition = Cesium.Cartesian3.clone(frameState.camera.positionWC, this.lastEyePosition);
+                    this.selectionDirty = false;
+                }
+                for (const tile of this.tiles) {
+                    const mesh = this.ensureMesh(context, tile, tile.tier);
+                    frameState.commandList.push(this.commandFor(context, tile, mesh));
+                }
+            }
+            isDestroyed() {
+                return this.destroyed;
+            }
+            destroy() {
+                this.destroyed = true;
+                for (const tile of this.tiles) {
+                    tile.meshes.forEach((mesh) => mesh.vertexArray.destroy());
+                    tile.meshes.clear();
+                    tile.command = null;
+                }
+                if (this.shaderProgram) {
+                    this.shaderProgram.destroy();
+                    this.shaderProgram = null;
+                }
+                if (this.texture) {
+                    this.texture.destroy();
+                    this.texture = null;
+                }
+                if (this.groundTexture) {
+                    this.groundTexture.destroy();
+                    this.groundTexture = null;
+                }
+                return undefined;
+            }
+            /*
+             * Samples terrain across the extent once and packs it into a texture the vertex shader reads.
+             *
+             * A texture rather than heights baked into the meshes, because the samples arrive
+             * asynchronously and every cached tile mesh would otherwise have to be rebuilt when they land.
+             */
+            requestGround() {
+                if (this.groundRequested || !this.followGround) {
+                    return;
+                }
+                this.groundRequested = true;
+                const sampler = Cesium.sampleTerrain;
+                if (!this.terrainProvider || typeof sampler !== "function") {
+                    return;
+                }
+                const positions = [];
+                for (let row = 0; row < GROUND_SAMPLES_PER_SIDE; row++) {
+                    const fy = row / (GROUND_SAMPLES_PER_SIDE - 1);
+                    const latitude = Cesium.Math.lerp(this.extent.North, this.extent.South, fy);
+                    for (let col = 0; col < GROUND_SAMPLES_PER_SIDE; col++) {
+                        const fx = col / (GROUND_SAMPLES_PER_SIDE - 1);
+                        const longitude = Cesium.Math.lerp(this.extent.West, this.extent.East, fx);
+                        positions.push(Cesium.Cartographic.fromDegrees(longitude, latitude));
+                    }
+                }
+                Promise.resolve(sampler(this.terrainProvider, GROUND_SAMPLE_LEVEL, positions))
+                    .then((sampled) => {
+                    if (this.destroyed || !sampled) {
+                        return;
+                    }
+                    const pixels = new Uint8Array(GROUND_SAMPLES_PER_SIDE * GROUND_SAMPLES_PER_SIDE * 4);
+                    const span = GROUND_MAX_METRES - GROUND_MIN_METRES;
+                    for (let i = 0; i < sampled.length; i++) {
+                        const height = sampled[i] && isFinite(sampled[i].height) ? sampled[i].height : 0;
+                        const clamped = Math.min(GROUND_MAX_METRES, Math.max(GROUND_MIN_METRES, height));
+                        const packed = Math.round(((clamped - GROUND_MIN_METRES) / span) * 16777215);
+                        pixels[i * 4] = (packed >> 16) & 255;
+                        pixels[i * 4 + 1] = (packed >> 8) & 255;
+                        pixels[i * 4 + 2] = packed & 255;
+                        pixels[i * 4 + 3] = 255;
+                    }
+                    this.groundPixels = pixels;
+                })
+                    .catch(() => {
+                    // Terrain that cannot be sampled leaves the surface on the ellipsoid, which is
+                    // where a clamped polygon sat before this existed.
+                });
+            }
+            /*
+             * Uploads whatever ground samples exist, and a flat stand-in until they arrive, so the
+             * shader always has a texture bound whether or not this surface follows the ground.
+             */
+            syncGroundTexture(context) {
+                if (this.groundTexture && (!this.groundPixels || this.groundTexture.width === GROUND_SAMPLES_PER_SIDE)) {
+                    return;
+                }
+                if (this.groundTexture) {
+                    this.groundTexture.destroy();
+                }
+                const zero = Math.round(((0 - GROUND_MIN_METRES) / (GROUND_MAX_METRES - GROUND_MIN_METRES)) * 16777215);
+                const size = this.groundPixels ? GROUND_SAMPLES_PER_SIDE : 1;
+                const arrayBufferView = this.groundPixels
+                    || new Uint8Array([(zero >> 16) & 255, (zero >> 8) & 255, zero & 255, 255]);
+                this.groundTexture = new Cesium.Texture({
+                    context,
+                    pixelFormat: Cesium.PixelFormat.RGBA,
+                    source: { width: size, height: size, arrayBufferView },
+                    flipY: false,
+                    sampler: new Cesium.Sampler({
+                        wrapS: Cesium.TextureWrap.CLAMP_TO_EDGE,
+                        wrapT: Cesium.TextureWrap.CLAMP_TO_EDGE,
+                        // Nearest, because the shader interpolates decoded heights itself.
+                        minificationFilter: Cesium.TextureMinificationFilter.NEAREST,
+                        magnificationFilter: Cesium.TextureMagnificationFilter.NEAREST
+                    })
+                });
+            }
+            /*
+             * Ground distance between neighbouring texels, so the shading normal is built from a real
+             * slope rather than a made up one.
+             */
+            metresPerTexel() {
+                const southWest = Cesium.Cartesian3.fromDegrees(this.extent.West, this.extent.South, 0);
+                const southEast = Cesium.Cartesian3.fromDegrees(this.extent.East, this.extent.South, 0);
+                const width = Cesium.Cartesian3.distance(southWest, southEast);
+                return Math.max(1, width / Math.max(1, this.source ? this.source.width : 1));
+            }
+            syncTexture(context) {
+                const sizeChanged = this.texture
+                    && (this.texture.width !== this.source.width || this.texture.height !== this.source.height);
+                if (!this.texture || sizeChanged) {
+                    if (this.texture) {
+                        this.texture.destroy();
+                    }
+                    this.texture = new Cesium.Texture({
+                        context,
+                        source: this.source,
+                        // Cesium flips canvas rows on upload by default, which would put the archive's
+                        // row 0 (its north edge) at the south edge and mirror the whole surface.
+                        flipY: false,
+                        sampler: new Cesium.Sampler({
+                            wrapS: Cesium.TextureWrap.CLAMP_TO_EDGE,
+                            wrapT: Cesium.TextureWrap.CLAMP_TO_EDGE,
+                            minificationFilter: Cesium.TextureMinificationFilter.LINEAR,
+                            magnificationFilter: Cesium.TextureMagnificationFilter.LINEAR
+                        })
+                    });
+                    this.textureDirty = false;
+                    return;
+                }
+                if (this.textureDirty) {
+                    this.texture.copyFrom({ source: this.source });
+                    this.textureDirty = false;
+                }
+            }
+            ensureMesh(context, tile, tier) {
+                const cached = tile.meshes.get(tier);
+                if (cached) {
+                    return cached;
+                }
+                const geometry = buildGeometry(this.extent, tier, tile.patch, this.pixelPlacement, this.tileSkirts);
+                const attributeLocations = Cesium.GeometryPipeline.createAttributeLocations(geometry);
+                const mesh = {
+                    attributeLocations,
+                    vertexArray: Cesium.VertexArray.fromGeometry({
+                        context,
+                        geometry,
+                        attributeLocations,
+                        bufferUsage: Cesium.BufferUsage.STATIC_DRAW
+                    }),
+                    boundingSphere: geometry.boundingSphere
+                };
+                tile.meshes.set(tier, mesh);
+                tile.centre = geometry.boundingSphere.center;
+                tile.radius = geometry.boundingSphere.radius;
+                return mesh;
+            }
+            /*
+             * Picks each tile's density from how much screen it covers.
+             */
+            selectTiers(frameState) {
+                const camera = frameState.camera;
+                const fovy = camera.frustum && camera.frustum.fovy ? camera.frustum.fovy : Cesium.Math.PI_OVER_THREE;
+                const pixelsPerRadian = frameState.context.drawingBufferHeight / fovy;
+                for (const tile of this.tiles) {
+                    if (!tile.centre) {
+                        tile.tier = TIERS[0];
+                        continue;
+                    }
+                    const distance = Math.max(1, Cesium.Cartesian3.distance(camera.positionWC, tile.centre) - tile.radius);
+                    const screenPixels = (2 * tile.radius / distance) * pixelsPerRadian;
+                    const wanted = screenPixels / TARGET_CELL_PIXELS;
+                    let tier = TIERS[0];
+                    for (const candidate of TIERS) {
+                        if (candidate <= wanted) {
+                            tier = candidate;
+                        }
+                    }
+                    tile.tier = tier;
+                }
+            }
+            shouldReselect(frameState, nowMs) {
+                if (this.selectionDirty) {
+                    return true;
+                }
+                if (nowMs - this.lastSelectionMs < RESELECT_INTERVAL_MS) {
+                    return false;
+                }
+                const eye = frameState.camera.positionWC;
+                if (!this.lastEyePosition) {
+                    return true;
+                }
+                const moved = Cesium.Cartesian3.distance(eye, this.lastEyePosition);
+                const anchor = this.tiles[0].centre;
+                const reference = anchor ? Math.max(1, Cesium.Cartesian3.distance(eye, anchor)) : 1;
+                return moved / reference > MOVEMENT_THRESHOLD;
+            }
+            commandFor(context, tile, mesh) {
+                if (!this.shaderProgram) {
+                    const glsl300 = usesGlsl300(context);
+                    this.shaderProgram = Cesium.ShaderProgram.fromCache({
+                        context,
+                        vertexShaderSource: glsl300 ? VERTEX_SHADER_GLSL300 : toGlsl100(VERTEX_SHADER_GLSL300, false),
+                        fragmentShaderSource: glsl300 ? FRAGMENT_SHADER_GLSL300 : toGlsl100(FRAGMENT_SHADER_GLSL300, true),
+                        attributeLocations: mesh.attributeLocations
+                    });
+                    this.renderState = Cesium.RenderState.fromCache({
+                        depthTest: { enabled: true },
+                        // Translucent ramp: blend, and leave the depth buffer to the opaque world.
+                        depthMask: false,
+                        blending: Cesium.BlendingState.ALPHA_BLEND,
+                        cull: { enabled: false }
+                    });
+                }
+                if (!tile.command) {
+                    const self = this;
+                    tile.command = new Cesium.DrawCommand({
+                        shaderProgram: this.shaderProgram,
+                        renderState: this.renderState,
+                        pass: Cesium.Pass.TRANSLUCENT,
+                        modelMatrix: Cesium.Matrix4.IDENTITY,
+                        owner: this,
+                        uniformMap: {
+                            u_valueTexture: () => self.texture,
+                            u_groundTexture: () => self.groundTexture,
+                            u_groundWeight: () => (self.followGround && self.groundPixels ? 1 : 0),
+                            u_groundRange: () => new Cesium.Cartesian2(GROUND_MIN_METRES, GROUND_MAX_METRES),
+                            u_groundSize: () => new Cesium.Cartesian2(self.groundPixels ? GROUND_SAMPLES_PER_SIDE : 1, self.groundPixels ? GROUND_SAMPLES_PER_SIDE : 1),
+                            u_metresPerTexel: () => self.metresPerTexel(),
+                            u_valueMin: () => self.valueMin,
+                            u_valueRange: () => self.valueMax - self.valueMin,
+                            u_exaggeration: () => self.exaggeration,
+                            u_baseHeight: () => self.baseHeight,
+                            u_skirtDepth: () => self.tileSkirts
+                                ? Math.max(2, Math.abs(self.valueMax - self.valueMin) * self.exaggeration * SKIRT_FRACTION)
+                                : 0,
+                            u_coverageCutoff: () => COVERAGE_CUTOFF,
+                            u_lowColor: () => self.lowColor,
+                            u_highColor: () => self.highColor,
+                            u_texelSize: () => new Cesium.Cartesian2(1 / self.source.width, 1 / self.source.height)
+                        }
+                    });
+                }
+                // Bounding volume belongs to the mesh, so it follows whichever tier is drawing.
+                tile.command.vertexArray = mesh.vertexArray;
+                tile.command.boundingVolume = mesh.boundingSphere;
+                return tile.command;
+            }
+        }
+        DisplacedSurfacePrimitive.Surface = Surface;
+        /*
+         * Cuts the extent into tiles, dropping any the caller says carry no data.
+         */
+        function buildTiles(hasCoverage) {
+            const tiles = [];
+            for (let row = 0; row < TILES_PER_SIDE; row++) {
+                for (let col = 0; col < TILES_PER_SIDE; col++) {
+                    const patch = {
+                        u0: col / TILES_PER_SIDE,
+                        u1: (col + 1) / TILES_PER_SIDE,
+                        v0: row / TILES_PER_SIDE,
+                        v1: (row + 1) / TILES_PER_SIDE
+                    };
+                    if (hasCoverage && !hasCoverage(patch)) {
+                        continue;
+                    }
+                    tiles.push({
+                        patch,
+                        meshes: new Map(),
+                        tier: TIERS[0],
+                        command: null,
+                        centre: null,
+                        radius: 0
+                    });
+                }
+            }
+            return tiles;
+        }
+        /**
+         * Exaggeration that makes the full value range stand AUTO_RELIEF_FRACTION of the extent tall.
+         *
+         * Derived from the whole extent rather than per tile: scaling each tile to its own size would
+         * make neighbours disagree along their shared edge and tear the surface apart.
+         * @param extent
+         * @param valueMin
+         * @param valueMax
+         */
+        function autoExaggeration(extent, valueMin, valueMax) {
+            const range = Math.abs(valueMax - valueMin);
+            if (!(range > 0)) {
+                return 1;
+            }
+            const southWest = Cesium.Cartesian3.fromDegrees(extent.West, extent.South, 0);
+            const southEast = Cesium.Cartesian3.fromDegrees(extent.East, extent.South, 0);
+            const northWest = Cesium.Cartesian3.fromDegrees(extent.West, extent.North, 0);
+            const shorterSide = Math.min(Cesium.Cartesian3.distance(southWest, southEast), Cesium.Cartesian3.distance(southWest, northWest));
+            if (!(shorterSide > 0)) {
+                return 1;
+            }
+            return (shorterSide * AUTO_RELIEF_FRACTION) / range;
+        }
+        DisplacedSurfacePrimitive.autoExaggeration = autoExaggeration;
+        function toCesiumColor(color) {
+            return new Cesium.Color(color.red / 255, color.green / 255, color.blue / 255, color.alpha);
+        }
+        function now() {
+            return typeof performance !== "undefined" ? performance.now() : Date.now();
+        }
+    })(exports.DisplacedSurfacePrimitive || (exports.DisplacedSurfacePrimitive = {}));
+
     const TEXTURE_FRAME_SERIES_ANIMATOR_KEY = "TextureFrameSeriesAnimator.Animator";
+    const EXTRUSION_ANIMATOR_KEY = "TextureFrameSeriesAnimator.ExtrusionAnimator";
+    const DISPLACED_SURFACE_KEY = "DisplacedSurfacePrimitive.Surface";
     (function (EntityRenderEnginePolygon) {
         async function Render(params) {
-            var _a, _b, _c;
+            var _a, _b, _c, _d;
             const entity = params.entity;
             const style = params.style;
             const pRings = BModels.Entity.GetValue({
@@ -39930,14 +40848,38 @@
                     console.error(`Polygon.Render: failed to resolve textured fill for entity ${((_a = entity === null || entity === void 0 ? void 0 : entity.Bruce) === null || _a === void 0 ? void 0 : _a.ID) || "<NONE>"}:`, e);
                 }
             }
-            const hasFill = fillType === BModels.Style.EPolygonFillType.Texture
-                ? Boolean(textureDataUri || frameArchive || cFillColor.alpha > 0)
-                : cFillColor.alpha > 0;
-            const fillMaterial = textureDataUri
-                ? new Cesium.ImageMaterialProperty({ image: textureDataUri, transparent: true })
-                : frameArchive
-                    ? Cesium.Color.WHITE.withAlpha(0)
-                    : cFillColor;
+            const usesTextureExtrusion = (Boolean(style.useExtrusion) &&
+                style.extrusionType === BModels.Style.EPolygonExtrusionType.Texture);
+            let extrusionArchive = null;
+            if (usesTextureExtrusion && !params.offline) {
+                try {
+                    const resolved = await resolveTextureValue({
+                        api: params.api,
+                        textureValue: style.extrusionTexture || style.texture,
+                        style,
+                        entity,
+                        tags: params.tags
+                    });
+                    extrusionArchive = resolved.frameArchive || null;
+                }
+                catch (e) {
+                    console.error(`Polygon.Render: failed to resolve extrusion texture for entity ${((_b = entity === null || entity === void 0 ? void 0 : entity.Bruce) === null || _b === void 0 ? void 0 : _b.ID) || "<NONE>"}:`, e);
+                }
+            }
+            const drawsDisplacedSurface = Boolean(extrusionArchive);
+            // The displaced surface IS the entity's fill, drawn as its own primitive at the value's height.
+            // Leaving the flat polygon filled as well shows a second copy of the parcel on the ground under it.
+            const hasFill = (drawsDisplacedSurface ? true
+                : fillType === BModels.Style.EPolygonFillType.Texture
+                    ? Boolean(textureDataUri || frameArchive || cFillColor.alpha > 0)
+                    : cFillColor.alpha > 0);
+            const fillMaterial = drawsDisplacedSurface
+                ? Cesium.Color.WHITE.withAlpha(0)
+                : textureDataUri
+                    ? new Cesium.ImageMaterialProperty({ image: textureDataUri, transparent: true })
+                    : frameArchive
+                        ? Cesium.Color.WHITE.withAlpha(0)
+                        : cFillColor;
             const lineColorTrace = style.lineColor ? BModels.Calculator.TraceGetColor(style.lineColor, entity, params.tags) : { value: null, effective: null };
             const bLineColor = lineColorTrace.value;
             const cLineColor = bLineColor ? ColorToCColor(bLineColor) : Cesium.Color.fromCssColorString("rgba(80, 80, 80, 0.8)");
@@ -39964,7 +40906,9 @@
             const points = BModels.Geometry.ParsePoints(outerRing === null || outerRing === void 0 ? void 0 : outerRing.LinearRing);
             let posses = points.map(x => Cesium.Cartesian3.fromDegrees(EnsureNumber(x.longitude), EnsureNumber(x.latitude), EnsureNumber(x.altitude)));
             BModels.Cartes.CloseRing3(posses);
-            const extrusion = getPolygonExtrusion(entity, params.tags, outerRing, posses, heightRef, style);
+            const extrusion = drawsDisplacedSurface
+                ? { posses, value: undefined, exHeightRef: Cesium.HeightReference.NONE }
+                : getPolygonExtrusion(entity, params.tags, outerRing, posses, heightRef, style);
             posses = extrusion.posses;
             posses = CullDuplicateCPosses(posses);
             if (posses.length < 4) {
@@ -40013,6 +40957,7 @@
                     polygon: {
                         hierarchy: new Cesium.PolygonHierarchy(posses, holePosses.map(x => new Cesium.PolygonHierarchy(x))),
                         material: fillMaterial,
+                        fill: !drawsDisplacedSurface,
                         extrudedHeight: extrusion.value,
                         extrudedHeightReference: extrusion.exHeightRef,
                         shadows: Cesium.ShadowMode.ENABLED,
@@ -40043,6 +40988,12 @@
                 if (!CompareCPolygonHierarchies(oldHierarchy, newHierarchy)) {
                     cEntity.polygon.hierarchy = new Cesium.ConstantProperty(newHierarchy);
                 }
+                // Toggling extrusion styling on an already-rendered entity flips this,
+                // so it has to be reconciled rather than set only at creation.
+                const oldFill = GetCValue(params.viewer, cEntity.polygon.fill);
+                if (oldFill !== !drawsDisplacedSurface) {
+                    cEntity.polygon.fill = new Cesium.ConstantProperty(!drawsDisplacedSurface);
+                }
                 const oldExtrusion = GetCValue(params.viewer, cEntity.polygon.extrudedHeight);
                 if (oldExtrusion != extrusion.value) {
                     cEntity.polygon.extrudedHeight = new Cesium.ConstantProperty(extrusion.value);
@@ -40096,7 +41047,16 @@
             }
             // Must run before any material is baked below: the Animator takes over polygon.material, so a bake
             // has to know whether it is baking over a live animation or over a disposed one's restored material.
-            const animator = syncTextureFrameArchive(cEntity, frameArchive, params.viewer, style.textureColorMask);
+            const animator = syncTextureFrameArchive(cEntity, drawsDisplacedSurface ? null : frameArchive, params.viewer, style.textureColorMask, style.maskTextureBaseline);
+            syncDisplacedSurface({
+                cEntity,
+                extrusionArchive,
+                viewer: params.viewer,
+                style,
+                entity,
+                heightRef,
+                outerRingPosses: posses
+            });
             if (animator) {
                 exports.CesiumEntityStyler.SetDefaultTextureImage({
                     entity: cEntity,
@@ -40156,7 +41116,7 @@
                     }
                 }
                 let borderPosses = posses.map(x => x.clone ? x.clone() : { ...x });
-                let cEntityBorder = (_c = (_b = params.rendered) === null || _b === void 0 ? void 0 : _b._siblingGraphics) === null || _c === void 0 ? void 0 : _c[0];
+                let cEntityBorder = (_d = (_c = params.rendered) === null || _c === void 0 ? void 0 : _c._siblingGraphics) === null || _d === void 0 ? void 0 : _d[0];
                 cEntity._siblingGraphics = [];
                 if (!cEntityBorder || ((!cEntityBorder.polyline && units == "px") ||
                     (!cEntityBorder.corridor && units == "m"))) {
@@ -40406,12 +41366,13 @@
         /**
          * Disposes a cEntity's TextureFrameSeriesAnimator.Animator (if any).
          */
-        function DisposeTextureFrameSeriesAnimator(cEntity) {
+        function DisposeTextureFrameSeriesAnimator(cEntity, viewer) {
             const existing = cEntity === null || cEntity === void 0 ? void 0 : cEntity[TEXTURE_FRAME_SERIES_ANIMATOR_KEY];
             if (existing && !existing.IsDisposed()) {
                 existing.Dispose();
                 cEntity[TEXTURE_FRAME_SERIES_ANIMATOR_KEY] = null;
             }
+            disposeDisplacedSurface(cEntity, viewer);
         }
         EntityRenderEnginePolygon.DisposeTextureFrameSeriesAnimator = DisposeTextureFrameSeriesAnimator;
     })(exports.EntityRenderEnginePolygon || (exports.EntityRenderEnginePolygon = {}));
@@ -40525,6 +41486,145 @@
     // Cache of tinted texture data URIs, keyed by resolved url + color mask, so repeated renders of the
     // same polygon (or multiple polygons sharing a texture) don't refetch/reprocess the same image.
     const _textureCache = new BModels.LRUCache(50);
+    /**
+     * Reconciles the displaced surface (and the animator feeding it) against this render's resolved
+     * extrusion texture, creating, reusing or tearing down as the style demands.
+     * @param params
+     */
+    function syncDisplacedSurface(params) {
+        var _a;
+        const { cEntity, extrusionArchive, viewer, style, entity, heightRef, outerRingPosses } = params;
+        const existingAnimator = cEntity[EXTRUSION_ANIMATOR_KEY];
+        const existingSurface = cEntity[DISPLACED_SURFACE_KEY];
+        // Nothing to draw and nothing left over, which is every polygon that does not use this feature.
+        if (!extrusionArchive && !existingAnimator && !existingSurface) {
+            return;
+        }
+        const reusable = extrusionArchive
+            && existingAnimator
+            && !existingAnimator.IsDisposed()
+            && existingAnimator.GetArchiveUrl() === extrusionArchive.url
+            && existingSurface
+            && !existingSurface.isDestroyed();
+        const placement = surfacePlacement(entity, heightRef);
+        // Whether the surface follows terrain is baked into its ground sampling, so a change there has
+        // to rebuild rather than update in place.
+        if (reusable && existingSurface.GetFollowsGround() === placement.followGround) {
+            existingSurface.SetBaseHeight(placement.baseHeight);
+            existingSurface.SetExaggeration((_a = style.extrusionExaggeration) !== null && _a !== void 0 ? _a : exports.DisplacedSurfacePrimitive.autoExaggeration(existingSurface.GetExtent(), extrusionArchive.metadata.ValueMin, extrusionArchive.metadata.ValueMax));
+            return;
+        }
+        disposeDisplacedSurface(cEntity, viewer);
+        if (!extrusionArchive) {
+            return;
+        }
+        const extent = archiveExtent(extrusionArchive.metadata, outerRingPosses);
+        if (!extent) {
+            console.warn("Polygon.Render: extrusion texture has no usable extent, skipping displaced surface.");
+            return;
+        }
+        // Drives the value canvas only: the surface paints the colour, so the polygon's own material is
+        // left transparent rather than animated underneath it.
+        const animator = new TextureFrameSeriesAnimator.Animator({
+            viewer,
+            entity: cEntity,
+            archiveUrl: extrusionArchive.url,
+            frames: extrusionArchive.metadata.Frames,
+            textureColorMask: style.textureColorMask,
+            driveMaterial: false,
+            produceValueCanvas: true,
+            baselineMask: extrusionArchive.metadata.BaselineMask,
+            // Off-type for the same reason as the fill path: the pinned bruce-models predates the field.
+            maskBaseline: style.maskTextureBaseline
+        });
+        cEntity[EXTRUSION_ANIMATOR_KEY] = animator;
+        const mask = style.textureColorMask;
+        const surface = new exports.DisplacedSurfacePrimitive.Surface({
+            extent,
+            // The grid has to be walked the way the raster was sampled, or the surface skews across the extent.
+            pixelPlacement: extrusionArchive.metadata.PixelPlacement,
+            source: null,
+            baseHeight: placement.baseHeight,
+            followGround: placement.followGround,
+            terrainProvider: viewer && viewer.terrainProvider,
+            valueMin: extrusionArchive.metadata.ValueMin,
+            valueMax: extrusionArchive.metadata.ValueMax,
+            exaggeration: style.extrusionExaggeration,
+            lowColor: mask ? BModels.Color.ColorFromStr(mask.minColor) : null,
+            highColor: mask ? BModels.Color.ColorFromStr(mask.maxColor) : null
+        });
+        surface.BindAnimator(animator);
+        viewer.scene.primitives.add(surface);
+        cEntity[DISPLACED_SURFACE_KEY] = surface;
+    }
+    /**
+     * Turns the polygon's altitude option into the two things the displaced surface needs:
+     * - how high value zero sits.
+     * - whether that is measured from the terrain or from the ellipsoid.
+     * @param entity
+     * @param heightRef
+     */
+    function surfacePlacement(entity, heightRef) {
+        const rawAltitude = BModels.Entity.GetValue({
+            entity,
+            path: ["Bruce", "Location", "altitude"]
+        });
+        const altitude = rawAltitude ? EnsureNumber(rawAltitude) : 0;
+        if (heightRef === Cesium.HeightReference.CLAMP_TO_GROUND) {
+            return { baseHeight: 0, followGround: true };
+        }
+        if (heightRef === Cesium.HeightReference.RELATIVE_TO_GROUND) {
+            return { baseHeight: altitude, followGround: true };
+        }
+        return { baseHeight: altitude, followGround: false };
+    }
+    /**
+     * The archive's own extent when it recorded one, otherwise the polygon's own bounds so archives
+     * generated before the extent was written still render somewhere sensible.
+     * @param metadata
+     * @param posses
+     */
+    function archiveExtent(metadata, posses) {
+        if (metadata.West != null && metadata.East != null && metadata.South != null && metadata.North != null) {
+            return { West: metadata.West, East: metadata.East, South: metadata.South, North: metadata.North };
+        }
+        if (!posses || posses.length === 0) {
+            return null;
+        }
+        const rectangle = Cesium.Rectangle.fromCartesianArray(posses);
+        return {
+            West: Cesium.Math.toDegrees(rectangle.west),
+            East: Cesium.Math.toDegrees(rectangle.east),
+            South: Cesium.Math.toDegrees(rectangle.south),
+            North: Cesium.Math.toDegrees(rectangle.north)
+        };
+    }
+    /**
+     * Tears down the displaced surface and its feeding animator, if this entity has them.
+     * @param cEntity
+     * @param viewer
+     */
+    function disposeDisplacedSurface(cEntity, viewer) {
+        const surface = cEntity === null || cEntity === void 0 ? void 0 : cEntity[DISPLACED_SURFACE_KEY];
+        if (surface) {
+            const viewerAlive = viewer && (typeof viewer.isDestroyed !== "function" || !viewer.isDestroyed());
+            if (viewerAlive && viewer.scene && viewer.scene.primitives) {
+                // Removing from the collection destroys the primitive, releasing its meshes and texture.
+                viewer.scene.primitives.remove(surface);
+            }
+            else if (!surface.isDestroyed()) {
+                surface.destroy();
+            }
+            cEntity[DISPLACED_SURFACE_KEY] = null;
+        }
+        const animator = cEntity === null || cEntity === void 0 ? void 0 : cEntity[EXTRUSION_ANIMATOR_KEY];
+        if (animator && !animator.IsDisposed()) {
+            animator.Dispose();
+        }
+        if (cEntity) {
+            cEntity[EXTRUSION_ANIMATOR_KEY] = null;
+        }
+    }
     /**
      * Reconciles cEntity's TextureFrameSeriesAnimator.Animator (if any) against this render's resolved texture.
      * Called once cEntity is fully created/updated and definitely has a `polygon` graphics.
@@ -40534,7 +41634,7 @@
      * @param viewer
      * @param textureColorMask
      */
-    function syncTextureFrameArchive(cEntity, frameArchive, viewer, textureColorMask) {
+    function syncTextureFrameArchive(cEntity, frameArchive, viewer, textureColorMask, maskTextureBaseline) {
         const existing = cEntity[TEXTURE_FRAME_SERIES_ANIMATOR_KEY];
         if (frameArchive && existing && !existing.IsDisposed() && existing.GetArchiveUrl() === frameArchive.url) {
             return existing;
@@ -40551,7 +41651,9 @@
             entity: cEntity,
             archiveUrl: frameArchive.url,
             frames: frameArchive.metadata.Frames,
-            textureColorMask
+            textureColorMask,
+            baselineMask: frameArchive.metadata.BaselineMask,
+            maskBaseline: maskTextureBaseline
         });
         cEntity[TEXTURE_FRAME_SERIES_ANIMATOR_KEY] = animator;
         return animator;
@@ -40615,8 +41717,15 @@
      * @param params
      */
     async function resolveTexturedFill(params) {
-        const { api, style, entity, tags } = params;
-        const textureValue = style.texture;
+        return resolveTextureValue({ ...params, textureValue: params.style.texture });
+    }
+    /**
+     * Resolves either shape a texture setting can take (a calculated file id/URL, or a search condition)
+     * into a tinted data URI or, when the resolved file is a frame archive, the archive itself.
+     * @param params
+     */
+    async function resolveTextureValue(params) {
+        const { api, style, entity, tags, textureValue } = params;
         if (textureValue && !Array.isArray(textureValue)) {
             return resolveTextureCondition({ api, condition: textureValue });
         }
@@ -41393,7 +42502,7 @@
                     entity._dispose();
                     entity._dispose = null;
                 }
-                exports.EntityRenderEnginePolygon.DisposeTextureFrameSeriesAnimator(entity);
+                exports.EntityRenderEnginePolygon.DisposeTextureFrameSeriesAnimator(entity, viewer);
                 if (entity._parentEntity && !ignoreParent) {
                     doRemove({
                         viewer,
@@ -42141,7 +43250,7 @@
         StyleUtils.ApplyTypeStyle = ApplyTypeStyle;
     })(exports.StyleUtils || (exports.StyleUtils = {}));
 
-    const VERSION = "7.1.3";
+    const VERSION = "7.1.5";
     /**
      * Updates the environment instance used by bruce-cesium to one specified.
      * This can be used to ensure that the instance a parent is referencing is shared between bruce-cesium, bruce-models, and the parent app.