bruce-cesium 7.2.9 → 7.3.1

package/dist/bruce-cesium.umd.js

@@ -6575,7 +6575,7 @@
         const adjustedSphere = boundingSphere.sphere.clone();
         // Terrain only matters here because it moves the sphere onto the ground.
         // Far enough away that a plausible ground height is a rounding error against the viewing distance, sampling it is wasted work.
-        const cameraDistance = Cesium.Cartesian3.distance(camera.position, adjustedSphere.center);
+        const cameraDistance = Cesium.Cartesian3.distance(camera.positionWC, adjustedSphere.center);
         if (cameraDistance > TERRAIN_SKIP_DISTANCE) {
             adjustedSphere.radius += TERRAIN_SKIP_RADIUS_PAD;
         }
@@ -6588,7 +6588,8 @@
             }
             adjustedSphere.center = grounded;
         }
-        const cullingVolume = camera.frustum.computeCullingVolume(camera.position, camera.direction, camera.up);
+        // Camera vectors are frame relative while a reference frame is set (the compass orbits via lookAt).
+        const cullingVolume = camera.frustum.computeCullingVolume(camera.positionWC, camera.directionWC, camera.upWC);
         const visibility = cullingVolume.computeVisibility(adjustedSphere);
         return visibility !== Cesium.Intersect.INSIDE && visibility !== Cesium.Intersect.INTERSECTING;
     }
@@ -6615,14 +6616,14 @@
             return true;
         }
         const camera = viewer.scene.camera;
-        if (!((_a = camera === null || camera === void 0 ? void 0 : camera.position) === null || _a === void 0 ? void 0 : _a.x)) {
+        if (!((_a = camera === null || camera === void 0 ? void 0 : camera.positionWC) === null || _a === void 0 ? void 0 : _a.x)) {
             return false;
         }
         const lastRecheck = camera[LAST_RECHECK_KEY];
         if (!lastRecheck) {
             camera[LAST_RECHECK_KEY] = {
-                position: camera.position.clone(),
-                direction: camera.direction.clone(),
+                position: camera.positionWC.clone(),
+                direction: camera.directionWC.clone(),
                 tilesLoading: viewer.scene.globe.tilesLoaded
             };
             return true;
@@ -6631,14 +6632,14 @@
         const tilesLoadingDiff = lastRecheck.tilesLoading != viewer.scene.globe.tilesLoaded;
         let recheck = tilesLoadingDiff;
         if (!recheck) {
-            const posDiff = Cesium.Cartesian3.magnitude(Cesium.Cartesian3.subtract(position, camera.position, new Cesium.Cartesian3()));
-            const dirDiff = Cesium.Cartesian3.magnitude(Cesium.Cartesian3.subtract(direction, camera.direction, new Cesium.Cartesian3()));
+            const posDiff = Cesium.Cartesian3.magnitude(Cesium.Cartesian3.subtract(position, camera.positionWC, new Cesium.Cartesian3()));
+            const dirDiff = Cesium.Cartesian3.magnitude(Cesium.Cartesian3.subtract(direction, camera.directionWC, new Cesium.Cartesian3()));
             recheck = posDiff > 100 || dirDiff > 0.01;
         }
         if (recheck) {
             camera[LAST_RECHECK_KEY] = {
-                position: camera.position.clone(),
-                direction: camera.direction.clone(),
+                position: camera.positionWC.clone(),
+                direction: camera.directionWC.clone(),
                 tilesLoading: viewer.scene.globe.tilesLoaded
             };
         }
@@ -6691,7 +6692,9 @@
             return;
         }
         const camera = viewer.scene.camera;
-        const cullingVolume = camera.frustum.computeCullingVolume(camera.position, camera.direction, camera.up);
+        // Camera vectors are frame relative while a reference frame is set (the compass orbits via lookAt).
+        // These spheres are world space, so only the world coordinate vectors compare against them correctly.
+        const cullingVolume = camera.frustum.computeCullingVolume(camera.positionWC, camera.directionWC, camera.upWC);
         let changed = false;
         for (const rego of tilesets) {
             const tileset = rego.tileset;
@@ -42366,6 +42369,17 @@
         // 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.
+        // Ground samples across the clearance regions rather than the whole extent.
+        const MASK_GROUND_SAMPLES_PER_SIDE = 128;
+        // Finest and coarsest terrain level a clearance raster is sampled at, and how many terrain tiles it is allowed to pull.
+        const MASK_GROUND_LEVEL_MAX = 13;
+        const MASK_GROUND_LEVEL_MIN = 8;
+        const MASK_GROUND_TILE_BUDGET = 64;
+        // Longest side of the rasterised region mask. The mask decides whether a texel is held up, so it
+        // wants to be finer than the value raster it is compared against.
+        const MASK_TEXTURE_MAX_SIDE = 1024;
+        // Stands in for "no floor" and "no clearance", far below anything the sheet can reach.
+        const NO_LIMIT_METRES = -1e6;
         const GROUND_MIN_METRES = -1000;
         const GROUND_MAX_METRES = 9000;
         const DEFAULT_LOW_COLOR = { red: 255, green: 255, blue: 255, alpha: 0.12 };
@@ -42388,6 +42402,19 @@ uniform float u_skirtDepth;
 uniform float u_groundWeight;
 uniform vec2 u_groundRange;
 uniform vec2 u_groundSize;
+uniform sampler2D u_maskTexture;
+uniform sampler2D u_maskGroundTexture;
+uniform float u_maskWeight;
+uniform float u_maskGroundWeight;
+uniform float u_maskFill;
+uniform float u_maskFillValue;
+uniform float u_maskClearance;
+uniform float u_maskFloor;
+uniform vec2 u_maskGroundSize;
+// West, East, North, South in degrees, for the surface and for the sampled region box.
+uniform vec4 u_extentDegrees;
+uniform vec4 u_maskGroundDegrees;
+uniform float u_coverageCutoffVertex;
 
 out vec2 v_st;
 out float v_value;
@@ -42417,6 +42444,46 @@ float sampleGround(vec2 uv) {
     return mix(mix(h00, h10, f.x), mix(h01, h11, f.x), f.y);
 }
 
+/*
+ * Height of the terrain under a point of the surface, read from the region's own ground raster.
+ *
+ * Sampled over the regions rather than over the whole extent, so the raster is fine enough for a
+ * clearance test to mean something.
+ */
+float sampleMaskGround(vec2 uv) {
+    float longitude = mix(u_extentDegrees.x, u_extentDegrees.y, uv.x);
+    float latitude = mix(u_extentDegrees.z, u_extentDegrees.w, uv.y);
+    vec2 inBox = vec2(
+        (longitude - u_maskGroundDegrees.x) / max(u_maskGroundDegrees.y - u_maskGroundDegrees.x, 1e-9),
+        (u_maskGroundDegrees.z - latitude) / max(u_maskGroundDegrees.z - u_maskGroundDegrees.w, 1e-9));
+    vec2 clamped = clamp(inBox, vec2(0.0), vec2(1.0));
+    vec2 texel = 1.0 / u_maskGroundSize;
+    vec2 coord = clamped * u_maskGroundSize - 0.5;
+    vec2 base = floor(coord);
+    vec2 f = coord - base;
+    vec2 origin = (base + 0.5) * texel;
+    vec4 t00 = texture(u_maskGroundTexture, origin);
+    vec4 t10 = texture(u_maskGroundTexture, origin + vec2(texel.x, 0.0));
+    vec4 t01 = texture(u_maskGroundTexture, origin + vec2(0.0, texel.y));
+    vec4 t11 = texture(u_maskGroundTexture, origin + texel);
+    // One unknown corner makes the interpolation meaningless, so the whole point is treated as
+    // unsampled and answers low enough that no clearance built on it can win.
+    float known = min(min(t00.a, t10.a), min(t01.a, t11.a));
+    if (known < 0.5) {
+        return u_groundRange.x;
+    }
+    vec3 p00 = t00.rgb * 255.0;
+    vec3 p10 = t10.rgb * 255.0;
+    vec3 p01 = t01.rgb * 255.0;
+    vec3 p11 = t11.rgb * 255.0;
+    vec3 weights = vec3(65536.0, 256.0, 1.0);
+    float h00 = u_groundRange.x + dot(p00, weights) / 16777215.0 * (u_groundRange.y - u_groundRange.x);
+    float h10 = u_groundRange.x + dot(p10, weights) / 16777215.0 * (u_groundRange.y - u_groundRange.x);
+    float h01 = u_groundRange.x + dot(p01, weights) / 16777215.0 * (u_groundRange.y - u_groundRange.x);
+    float h11 = u_groundRange.x + dot(p11, weights) / 16777215.0 * (u_groundRange.y - u_groundRange.x);
+    return mix(mix(h00, h10, f.x), mix(h01, h11, f.x), f.y);
+}
+
 /*
  * The texel's normalised value, whichever way the archive packed it.
  *
@@ -42436,8 +42503,16 @@ float decodeValue(vec4 texel) {
 void main() {
     vec4 texel = texture(u_valueTexture, st);
     v_st = st;
-    v_value = decodeValue(texel);
-    v_coverage = texel.a;
+
+    // Inside a region the scene knows is water, a texel with no value still has to paint, or the
+    // hole the region exists to close is still a hole.
+    // The value it paints is the shallowest the ramp is not transparent at.
+    float inMask = u_maskWeight * texture(u_maskTexture, st).a;
+    float hasData = step(u_coverageCutoffVertex, texel.a);
+    float raw = decodeValue(texel);
+    float filled = mix(u_maskFillValue, max(raw, u_maskFillValue), hasData);
+    v_value = mix(raw, filled, inMask * u_maskFill);
+    v_coverage = max(texel.a, inMask * u_maskFill);
 
     // Exaggeration stretches the span above the archive's minimum rather than the height itself. On an
     // elevation the height is measured from the ellipsoid, tens of metres from any of the data, so
@@ -42450,8 +42525,14 @@ void main() {
 
     // Coverage scales the displacement only where it is measured from the terrain, because there a
     // zero means the surface sits on the ground.
-    float coverageScale = mix(1.0, texel.a, u_groundWeight);
-    float displacement = u_baseHeight + ground + metres * coverageScale - skirt * u_skirtDepth;
+    float coverageScale = mix(1.0, v_coverage, u_groundWeight);
+    float placed = u_baseHeight + ground + metres * coverageScale;
+
+    // Held above whichever is higher, the region's own floor or the terrain under it plus a margin.
+    // Only inside the region: lifting the whole sheet would raise it over dry land as well.
+    float held = max(u_maskFloor, sampleMaskGround(st) * u_maskGroundWeight + u_maskClearance);
+    float lifted = mix(placed, max(placed, held), step(0.5, inMask));
+    float displacement = lifted - 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.
@@ -42686,6 +42767,147 @@ void main() {
             Cesium.GeometryPipeline.encodeAttribute(geometry, "position", "position3DHigh", "position3DLow");
             return geometry;
         }
+        /*
+         * Where the ramp first paints something, as a normalised value.
+         *
+         * A style with a hidden floor is transparent over its lowest band, so filling a gap at zero would
+         * fill it with nothing. This is the lowest value that actually shows.
+         */
+        function firstOpaqueStop(ramp) {
+            const stops = ramp.length / 4;
+            for (let i = 0; i < stops; i++) {
+                if (ramp[i * 4 + 3] > 0) {
+                    return stops > 1 ? i / (stops - 1) : 0;
+                }
+            }
+            return 0;
+        }
+        /*
+         * Rasterises the clearance regions into a mask over the surface's extent, alpha inside.
+         *
+         * Drawn north row first, matching the value raster's own row order, so one set of texture
+         * coordinates indexes both.
+         */
+        function rasteriseMask(extent, regions) {
+            const spanX = extent.East - extent.West;
+            const spanY = extent.North - extent.South;
+            if (!(spanX > 0) || !(spanY > 0) || !regions.length) {
+                return null;
+            }
+            // No document at all off the page, and the regions are still worth holding: the mask can be
+            // rasterised the next time they are set, and until then the surface simply lifts nothing.
+            if (typeof document === "undefined") {
+                return null;
+            }
+            const wide = spanX >= spanY;
+            const width = wide ? MASK_TEXTURE_MAX_SIDE : Math.max(1, Math.round(MASK_TEXTURE_MAX_SIDE * spanX / spanY));
+            const height = wide ? Math.max(1, Math.round(MASK_TEXTURE_MAX_SIDE * spanY / spanX)) : MASK_TEXTURE_MAX_SIDE;
+            const canvas = document.createElement("canvas");
+            canvas.width = width;
+            canvas.height = height;
+            const ctx = canvas.getContext("2d", { willReadFrequently: true });
+            if (!ctx) {
+                return null;
+            }
+            ctx.clearRect(0, 0, width, height);
+            ctx.fillStyle = "#ffffff";
+            for (const region of regions) {
+                const rings = region.rings || [];
+                if (!rings.length) {
+                    continue;
+                }
+                ctx.beginPath();
+                for (const ring of rings) {
+                    for (let i = 0; i + 1 < ring.length; i += 2) {
+                        const x = (ring[i] - extent.West) / spanX * width;
+                        const y = (extent.North - ring[i + 1]) / spanY * height;
+                        if (i === 0) {
+                            ctx.moveTo(x, y);
+                        }
+                        else {
+                            ctx.lineTo(x, y);
+                        }
+                    }
+                    ctx.closePath();
+                }
+                // Even odd, so a ring inside a ring is a hole without the caller having to wind them.
+                ctx.fill("evenodd");
+            }
+            return { width, height, data: new Uint8Array(ctx.getImageData(0, 0, width, height).data.buffer.slice(0)) };
+        }
+        /*
+         * The box every region fits inside, clipped to the surface, so the ground under them can be
+         * sampled without sampling the whole extent.
+         */
+        function boxOf(extent, regions) {
+            let west = Infinity;
+            let east = -Infinity;
+            let south = Infinity;
+            let north = -Infinity;
+            for (const region of regions) {
+                for (const ring of region.rings || []) {
+                    for (let i = 0; i + 1 < ring.length; i += 2) {
+                        west = Math.min(west, ring[i]);
+                        east = Math.max(east, ring[i]);
+                        south = Math.min(south, ring[i + 1]);
+                        north = Math.max(north, ring[i + 1]);
+                    }
+                }
+            }
+            if (!isFinite(west) || !isFinite(south)) {
+                return null;
+            }
+            return {
+                West: Math.max(west, extent.West),
+                East: Math.min(east, extent.East),
+                South: Math.max(south, extent.South),
+                North: Math.min(north, extent.North)
+            };
+        }
+        /*
+         * Packs sampled terrain heights into a texture's RGB, three bytes a height.
+         *
+         * A height needs more than eight bits to be useful and the surface reads it in the vertex shader,
+         * where float textures are not guaranteed, so it goes in as a fixed point integer.
+         */
+        function packHeights(sampled) {
+            const pixels = new Uint8Array(sampled.length * 4);
+            const span = GROUND_MAX_METRES - GROUND_MIN_METRES;
+            for (let i = 0; i < sampled.length; i++) {
+                const height = sampled[i] ? sampled[i].height : undefined;
+                const known = typeof height === "number" && isFinite(height);
+                const clamped = Math.min(GROUND_MAX_METRES, Math.max(GROUND_MIN_METRES, known ? height : 0));
+                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] = known ? 255 : 0;
+            }
+            return pixels;
+        }
+        /*
+         * The finest terrain level a box can be sampled at inside the tile budget.
+         *
+         * Asked of the provider's own tiling scheme where it offers one, since a terrain set is free to
+         * tile the world differently from the default two by one.
+         */
+        function groundLevelFor(box, provider) {
+            const scheme = provider && provider.tilingScheme;
+            for (let level = MASK_GROUND_LEVEL_MAX; level > MASK_GROUND_LEVEL_MIN; level--) {
+                const across = scheme && typeof scheme.getNumberOfXTilesAtLevel === "function"
+                    ? scheme.getNumberOfXTilesAtLevel(level)
+                    : Math.pow(2, level + 1);
+                const down = scheme && typeof scheme.getNumberOfYTilesAtLevel === "function"
+                    ? scheme.getNumberOfYTilesAtLevel(level)
+                    : Math.pow(2, level);
+                const tiles = Math.ceil((box.East - box.West) / (360 / across) + 1)
+                    * Math.ceil((box.North - box.South) / (180 / down) + 1);
+                if (tiles <= MASK_GROUND_TILE_BUDGET) {
+                    return level;
+                }
+            }
+            return MASK_GROUND_LEVEL_MIN;
+        }
         class Surface {
             constructor(options, hasCoverage) {
                 var _a, _b, _c, _d;
@@ -42704,6 +42926,14 @@ void main() {
                 this.groundTexture = null;
                 this.groundPixels = null;
                 this.groundRequested = false;
+                this.groundClearance = null;
+                this.maskTexture = null;
+                this.maskPixels = null;
+                this.maskGroundTexture = null;
+                this.maskGroundPixels = null;
+                this.maskGroundBox = null;
+                this.maskGroundRequested = false;
+                this.maskGroundLevel = 0;
                 this.followGround = Boolean(options.followGround);
                 this.terrainProvider = options.terrainProvider || null;
                 this.extent = options.extent;
@@ -42716,7 +42946,9 @@ void main() {
                 this.pixelPlacement = options.pixelPlacement;
                 this.tileSkirts = Boolean(options.tileSkirts);
                 this.rampPixels = RampLookup(options.rampStops || null, options.lowColor || DEFAULT_LOW_COLOR, options.highColor || DEFAULT_HIGH_COLOR);
+                this.maskFillValue = firstOpaqueStop(this.rampPixels);
                 this.tiles = buildTiles(hasCoverage);
+                this.SetGroundClearance(options.groundClearance || null);
             }
             GetFollowsGround() {
                 return this.followGround;
@@ -42739,6 +42971,97 @@ void main() {
             SetBaseHeight(baseHeight) {
                 this.baseHeight = baseHeight;
             }
+            GetGroundClearance() {
+                return this.groundClearance;
+            }
+            /*
+             * The terrain level the clearance regions were sampled at, once they have been.
+             *
+             * Worth reading rather than assuming: the level is chosen from how big the regions are, so a
+             * region covering a whole sound gets a coarser test than a hand drawn harbour does.
+             */
+            GetGroundClearanceLevel() {
+                return this.maskGroundLevel;
+            }
+            /*
+             * What the clearance regions were measured against, once they have been.
+             * The heights are read out of whatever the terrain stores, and a terrain referenced to sea
+             * level reads a geoid apart from an archive delivering ellipsoidal metres.
+             */
+            GetGroundClearanceStats() {
+                if (!this.maskGroundPixels) {
+                    return null;
+                }
+                const span = GROUND_MAX_METRES - GROUND_MIN_METRES;
+                let min = Infinity;
+                let max = -Infinity;
+                let samples = 0;
+                for (let i = 0; i < this.maskGroundPixels.length / 4; i++) {
+                    if (!this.maskGroundPixels[i * 4 + 3]) {
+                        continue;
+                    }
+                    const packed = (this.maskGroundPixels[i * 4] << 16)
+                        + (this.maskGroundPixels[i * 4 + 1] << 8) + this.maskGroundPixels[i * 4 + 2];
+                    const height = GROUND_MIN_METRES + (packed / 16777215) * span;
+                    min = Math.min(min, height);
+                    max = Math.max(max, height);
+                    samples++;
+                }
+                if (!samples) {
+                    return null;
+                }
+                return { level: this.maskGroundLevel, min, max, samples };
+            }
+            /*
+             * The real world range the texture's 0 to 1 maps onto, so a caller can compare it against what
+             * the terrain says without having kept its own copy.
+             */
+            GetValueRange() {
+                return { min: this.valueMin, max: this.valueMax };
+            }
+            /*
+             * Takes a different terrain to measure against.
+             * The clearance raster is sampled once and cached, so a scene that swaps its terrain would
+             * otherwise keep holding the sheet above heights read from the terrain it used to have.
+             */
+            SetTerrainProvider(provider) {
+                if (provider === this.terrainProvider) {
+                    return;
+                }
+                this.terrainProvider = provider;
+                this.groundPixels = null;
+                this.groundRequested = false;
+                this.maskGroundPixels = null;
+                this.maskGroundRequested = false;
+                this.maskGroundLevel = 0;
+            }
+            /*
+             * Takes a new set of clearance regions, or drops them.
+             * The mask is rasterised here rather than on the render thread, and the ground under the
+             * regions is re-requested, so a plugin can hand over regions the moment it has them.
+             */
+            SetGroundClearance(clearance) {
+                this.groundClearance = clearance && clearance.regions && clearance.regions.length
+                    ? clearance
+                    : null;
+                this.maskPixels = this.groundClearance
+                    ? rasteriseMask(this.extent, this.groundClearance.regions)
+                    : null;
+                if (this.maskTexture) {
+                    this.maskTexture.destroy();
+                    this.maskTexture = null;
+                }
+                this.maskGroundPixels = null;
+                this.maskGroundRequested = false;
+                this.maskGroundLevel = 0;
+                this.maskGroundBox = this.groundClearance
+                    ? boxOf(this.extent, this.groundClearance.regions)
+                    : null;
+                if (this.maskGroundTexture) {
+                    this.maskGroundTexture.destroy();
+                    this.maskGroundTexture = null;
+                }
+            }
             /**
              * Feeds the surface from an animated frame series.
              * Height and colour advance with the clock without the caller having to push each frame in.
@@ -42777,6 +43100,8 @@ void main() {
                 this.syncRampTexture(context);
                 this.requestGround();
                 this.syncGroundTexture(context);
+                this.requestMaskGround();
+                this.syncMaskTextures(context);
                 // A tile needs one mesh before it has a bounding sphere to measure against.
                 for (const tile of this.tiles) {
                     if (!tile.centre) {
@@ -42821,6 +43146,14 @@ void main() {
                     this.groundTexture.destroy();
                     this.groundTexture = null;
                 }
+                if (this.maskTexture) {
+                    this.maskTexture.destroy();
+                    this.maskTexture = null;
+                }
+                if (this.maskGroundTexture) {
+                    this.maskGroundTexture.destroy();
+                    this.maskGroundTexture = null;
+                }
                 return undefined;
             }
             /*
@@ -42853,24 +43186,123 @@ void main() {
                     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;
+                    this.groundPixels = packHeights(sampled);
                 })
                     .catch(() => {
                     // Terrain that cannot be sampled leaves the surface on the ellipsoid, which is
                     // where a clamped polygon sat before this existed.
                 });
             }
+            /*
+             * Samples the terrain under the clearance regions.
+             *
+             * Its own raster rather than the surface's, because the surface extent here is two degrees
+             * wide and the region is a few kilometres, and a clearance test needs the finer one.
+             */
+            requestMaskGround() {
+                if (this.maskGroundRequested || !this.groundClearance || !this.maskGroundBox) {
+                    return;
+                }
+                if (!(this.groundClearance.clearance > NO_LIMIT_METRES / 2)) {
+                    return;
+                }
+                this.maskGroundRequested = true;
+                const sampler = Cesium.sampleTerrain;
+                if (!this.terrainProvider || typeof sampler !== "function") {
+                    return;
+                }
+                const box = this.maskGroundBox;
+                const level = groundLevelFor(box, this.terrainProvider);
+                this.maskGroundLevel = level;
+                const total = MASK_GROUND_SAMPLES_PER_SIDE * MASK_GROUND_SAMPLES_PER_SIDE;
+                const scheme = this.terrainProvider.tilingScheme;
+                const asked = [];
+                // Which slot in the raster each asked-for position belongs to, since the ones the terrain
+                // does not cover are never asked for at all.
+                const slots = [];
+                for (let row = 0; row < MASK_GROUND_SAMPLES_PER_SIDE; row++) {
+                    const fy = row / (MASK_GROUND_SAMPLES_PER_SIDE - 1);
+                    const latitude = Cesium.Math.lerp(box.North, box.South, fy);
+                    for (let col = 0; col < MASK_GROUND_SAMPLES_PER_SIDE; col++) {
+                        const fx = col / (MASK_GROUND_SAMPLES_PER_SIDE - 1);
+                        const at = Cesium.Cartographic.fromDegrees(Cesium.Math.lerp(box.West, box.East, fx), latitude);
+                        // An imported terrain covers a survey area, so asking outside it answers 404 and
+                        // fills the console with failures for points that were never going to have a height.
+                        if (scheme && typeof this.terrainProvider.getTileDataAvailable === "function") {
+                            const tile = scheme.positionToTileXY(at, level);
+                            if (!tile || this.terrainProvider.getTileDataAvailable(tile.x, tile.y, level) === false) {
+                                continue;
+                            }
+                        }
+                        asked.push(at);
+                        slots.push(row * MASK_GROUND_SAMPLES_PER_SIDE + col);
+                    }
+                }
+                if (!asked.length) {
+                    return;
+                }
+                Promise.resolve(sampler(this.terrainProvider, level, asked))
+                    .then((sampled) => {
+                    if (this.destroyed || !sampled) {
+                        return;
+                    }
+                    const spread = new Array(total).fill(undefined);
+                    for (let i = 0; i < slots.length; i++) {
+                        spread[slots[i]] = sampled[i];
+                    }
+                    this.maskGroundPixels = packHeights(spread);
+                })
+                    .catch(() => {
+                    // Unsampled terrain leaves only the region's own floor to hold the sheet up,
+                    // which is the behaviour a region with no clearance already has.
+                });
+            }
+            /*
+             * Uploads the region mask and the ground under it, with a one texel stand-in until they land
+             * so the shader always has something bound.
+             */
+            syncMaskTextures(context) {
+                if (!this.maskTexture) {
+                    const held = this.maskPixels;
+                    this.maskTexture = new Cesium.Texture({
+                        context,
+                        pixelFormat: Cesium.PixelFormat.RGBA,
+                        source: held
+                            ? { width: held.width, height: held.height, arrayBufferView: held.data }
+                            : { width: 1, height: 1, arrayBufferView: new Uint8Array([0, 0, 0, 0]) },
+                        flipY: false,
+                        sampler: new Cesium.Sampler({
+                            wrapS: Cesium.TextureWrap.CLAMP_TO_EDGE,
+                            wrapT: Cesium.TextureWrap.CLAMP_TO_EDGE
+                        })
+                    });
+                }
+                if (this.maskGroundTexture && (!this.maskGroundPixels
+                    || this.maskGroundTexture.width === MASK_GROUND_SAMPLES_PER_SIDE)) {
+                    return;
+                }
+                if (this.maskGroundTexture) {
+                    this.maskGroundTexture.destroy();
+                }
+                const size = this.maskGroundPixels ? MASK_GROUND_SAMPLES_PER_SIDE : 1;
+                this.maskGroundTexture = new Cesium.Texture({
+                    context,
+                    pixelFormat: Cesium.PixelFormat.RGBA,
+                    source: {
+                        width: size,
+                        height: size,
+                        arrayBufferView: this.maskGroundPixels || packHeights([{ height: 0 }])
+                    },
+                    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
+                    })
+                });
+            }
             /*
              * 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.
@@ -42882,10 +43314,8 @@ void main() {
                 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]);
+                const arrayBufferView = this.groundPixels || packHeights([{ height: 0 }]);
                 this.groundTexture = new Cesium.Texture({
                     context,
                     pixelFormat: Cesium.PixelFormat.RGBA,
@@ -43094,6 +43524,28 @@ void main() {
                             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_maskTexture: () => self.maskTexture,
+                            u_maskGroundTexture: () => self.maskGroundTexture,
+                            u_maskWeight: () => (self.groundClearance && self.maskPixels ? 1 : 0),
+                            u_maskGroundWeight: () => (self.maskGroundPixels ? 1 : 0),
+                            u_maskFill: () => (self.groundClearance && self.groundClearance.fillGaps ? 1 : 0),
+                            u_maskFillValue: () => self.maskFillValue,
+                            u_maskClearance: () => (self.groundClearance
+                                && typeof self.groundClearance.clearance === "number"
+                                && self.maskGroundPixels
+                                ? self.groundClearance.clearance
+                                : NO_LIMIT_METRES),
+                            u_maskFloor: () => (self.groundClearance
+                                && typeof self.groundClearance.floor === "number"
+                                ? self.groundClearance.floor
+                                : NO_LIMIT_METRES),
+                            u_maskGroundSize: () => new Cesium.Cartesian2(self.maskGroundPixels ? MASK_GROUND_SAMPLES_PER_SIDE : 1, self.maskGroundPixels ? MASK_GROUND_SAMPLES_PER_SIDE : 1),
+                            u_extentDegrees: () => new Cesium.Cartesian4(self.extent.West, self.extent.East, self.extent.North, self.extent.South),
+                            u_maskGroundDegrees: () => {
+                                const box = self.maskGroundBox || self.extent;
+                                return new Cesium.Cartesian4(box.West, box.East, box.North, box.South);
+                            },
+                            u_coverageCutoffVertex: () => COVERAGE_CUTOFF,
                             u_metresPerTexel: () => self.metresPerTexel(),
                             u_valueMin: () => self.valueMin,
                             u_valueRange: () => self.valueMax - self.valueMin,
@@ -43729,6 +44181,34 @@ void main() {
             return cEntities;
         }
         EntityRenderEnginePolygon.RenderGroup = RenderGroup;
+        /**
+         * The displaced surface a cEntity is drawing, if it is drawing one.
+         *
+         * Exposed so a background plugin can hand a rendered polygon the water regions it is supposed to
+         * stay above without having to know where the surface is kept.
+         * @param cEntity
+         */
+        function GetDisplacedSurface(cEntity) {
+            return (cEntity === null || cEntity === void 0 ? void 0 : cEntity[DISPLACED_SURFACE_KEY]) || null;
+        }
+        EntityRenderEnginePolygon.GetDisplacedSurface = GetDisplacedSurface;
+        /**
+         * Hands every rendered polygon in a set the regions its sheet must stay above.
+         * @param cEntities
+         * @param clearance Pass null to drop the regions again.
+         */
+        function SetGroundClearance(cEntities, clearance) {
+            let touched = 0;
+            for (const cEntity of cEntities || []) {
+                const surface = GetDisplacedSurface(cEntity);
+                if (surface) {
+                    surface.SetGroundClearance(clearance);
+                    touched++;
+                }
+            }
+            return touched;
+        }
+        EntityRenderEnginePolygon.SetGroundClearance = SetGroundClearance;
         /**
          * Disposes a cEntity's TextureFrameSeriesAnimator.Animator (if any).
          */
@@ -45776,7 +46256,7 @@ void main() {
         StyleUtils.ApplyTypeStyle = ApplyTypeStyle;
     })(exports.StyleUtils || (exports.StyleUtils = {}));
 
-    const VERSION = "7.2.9";
+    const VERSION = "7.3.1";
     /**
      * 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.