bruce-cesium 7.2.9 → 7.3.1

package/dist/bruce-cesium.es5.js

@@ -1,6 +1,6 @@
 import * as Cesium from 'cesium';
-import { Cartographic, ColorMaterialProperty, Entity, Color, ConstantProperty, CallbackProperty, Primitive, Cesium3DTileFeature, DistanceDisplayCondition, ShaderSource, Cartesian3, Math as Math$1, Ellipsoid, Transforms, Matrix4, Geometry, GeometryAttribute, ComponentDatatype, PrimitiveType, BoundingSphere, GeometryPipeline, sampleTerrain, Texture, PixelFormat, Sampler, TextureWrap, TextureMinificationFilter, TextureMagnificationFilter, VertexArray, BufferUsage, ShaderProgram, RenderState, BlendingState, DrawCommand, Pass, Cartesian2, JulianDate, Quaternion, HeadingPitchRoll, HeightReference, ColorBlendMode, ShadowMode, ClassificationType, Model, ArcType, CornerType, ConstantPositionProperty, ImageMaterialProperty, PolygonHierarchy, PolylineGraphics, Rectangle, HorizontalOrigin, VerticalOrigin, SceneTransforms, NearFarScalar, Matrix3, KmlDataSource, GeoJsonDataSource, SceneMode, Ion, IonResource, Cesium3DTileStyle, HeadingPitchRange, Cesium3DTileColorBlendMode, EllipsoidTerrainProvider, IonImageryProvider, createWorldImagery, createWorldImageryAsync, BingMapsImageryProvider, BingMapsStyle, MapboxImageryProvider, MapboxStyleImageryProvider, ArcGisMapServerImageryProvider, OpenStreetMapImageryProvider, UrlTemplateImageryProvider, GridImageryProvider, GeographicTilingScheme, ImageryLayer, TileMapServiceImageryProvider, CesiumTerrainProvider, Cesium3DTileset, Intersect, OrthographicFrustum, EasingFunction, EllipsoidGeodesic, sampleTerrainMostDetailed, defined, ModelGraphics, PolygonGraphics, CorridorGraphics, PointGraphics, BillboardGraphics, EllipseGraphics, PolylineDashMaterialProperty, PolygonPipeline, CustomDataSource, GeometryInstance, CesiumInspector, ClockRange, DynamicEnvironmentMapManager, ScreenSpaceEventHandler, ScreenSpaceEventType, Fullscreen, CzmlDataSource } from 'cesium';
-import { Cartes, Entity as Entity$1, ProjectViewTile, ENVIRONMENT, Calculator, ClientFile, EntityLod, EntityTag, EntityType, LRUCache, ObjectUtils, Style, Carto, Geometry as Geometry$1, Bounds, ClientFileValueMap, Color as Color$1, Api, MenuItem, ProjectView, ProjectViewBookmark, Tileset, ZoomControl, BruceEvent, EntityCoords, DelayQueue, DataLab, EntityRelation, BruceApi, AccountConcept, RecordChangeFeed, EntitySource, ProgramKey, ProjectViewLegacyTile, Camera, Account, AccountLimits, Session, UrlUtils, EntityAttachment, EntityAttachmentType, EntityAttribute, MathUtils, ProjectViewBookmarkGroup, EntityRelationType, EntityHistoricData } from 'bruce-models';
+import { Cartographic, Entity, DistanceDisplayCondition, ColorMaterialProperty, Color, Math as Math$1, Cartesian3, JulianDate, Quaternion, Transforms, HeadingPitchRoll, Matrix4, ConstantProperty, CallbackProperty, Primitive, Cesium3DTileFeature, ShaderSource, Ellipsoid, Geometry, GeometryAttribute, ComponentDatatype, PrimitiveType, BoundingSphere, GeometryPipeline, sampleTerrain, Texture, PixelFormat, Sampler, TextureWrap, TextureMinificationFilter, TextureMagnificationFilter, VertexArray, BufferUsage, ShaderProgram, RenderState, BlendingState, DrawCommand, Pass, Cartesian2, Cartesian4, HeightReference, ColorBlendMode, ShadowMode, ClassificationType, Model, ArcType, CornerType, ConstantPositionProperty, HorizontalOrigin, VerticalOrigin, ImageMaterialProperty, PolygonHierarchy, PolylineGraphics, Rectangle, SceneTransforms, NearFarScalar, Matrix3, KmlDataSource, GeoJsonDataSource, SceneMode, Cesium3DTileStyle, HeadingPitchRange, Ion, IonResource, Cesium3DTileColorBlendMode, Cesium3DTileset, OrthographicFrustum, EasingFunction, EllipsoidTerrainProvider, IonImageryProvider, createWorldImagery, createWorldImageryAsync, BingMapsImageryProvider, BingMapsStyle, MapboxImageryProvider, MapboxStyleImageryProvider, ArcGisMapServerImageryProvider, OpenStreetMapImageryProvider, UrlTemplateImageryProvider, GridImageryProvider, GeographicTilingScheme, ImageryLayer, TileMapServiceImageryProvider, CesiumTerrainProvider, Intersect, ModelGraphics, PolygonGraphics, CorridorGraphics, PointGraphics, BillboardGraphics, EllipseGraphics, PolylineDashMaterialProperty, EllipsoidGeodesic, sampleTerrainMostDetailed, defined, PolygonPipeline, CesiumInspector, ClockRange, DynamicEnvironmentMapManager, CustomDataSource, GeometryInstance, ScreenSpaceEventHandler, ScreenSpaceEventType, Fullscreen, CzmlDataSource } from 'cesium';
+import { Cartes, Entity as Entity$1, ProjectViewTile, ENVIRONMENT, Calculator, ClientFile, EntityLod, EntityTag, EntityType, LRUCache, ObjectUtils, Style, Carto, Geometry as Geometry$1, Api, MenuItem, ProjectView, ProjectViewBookmark, Tileset, ZoomControl, ClientFileValueMap, Color as Color$1, Bounds, BruceEvent, EntityCoords, DelayQueue, DataLab, AccountConcept, RecordChangeFeed, BruceApi, EntityRelation, EntitySource, Camera, ProgramKey, ProjectViewLegacyTile, Account, AccountLimits, Session, UrlUtils, ProjectViewBookmarkGroup, EntityAttachment, EntityAttachmentType, EntityAttribute, MathUtils, EntityRelationType, EntityHistoricData } from 'bruce-models';
 
 /**
  * Ensures a number is returned from a given value.
@@ -6591,7 +6591,7 @@ function shouldCullEntity(viewer, cEntity) {
     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 = Cartesian3.distance(camera.position, adjustedSphere.center);
+    const cameraDistance = Cartesian3.distance(camera.positionWC, adjustedSphere.center);
     if (cameraDistance > TERRAIN_SKIP_DISTANCE) {
         adjustedSphere.radius += TERRAIN_SKIP_RADIUS_PAD;
     }
@@ -6604,7 +6604,8 @@ function shouldCullEntity(viewer, cEntity) {
         }
         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 !== Intersect.INSIDE && visibility !== Intersect.INTERSECTING;
 }
@@ -6631,14 +6632,14 @@ function shouldRecheck(viewer) {
         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;
@@ -6647,14 +6648,14 @@ function shouldRecheck(viewer) {
     const tilesLoadingDiff = lastRecheck.tilesLoading != viewer.scene.globe.tilesLoaded;
     let recheck = tilesLoadingDiff;
     if (!recheck) {
-        const posDiff = Cartesian3.magnitude(Cartesian3.subtract(position, camera.position, new Cartesian3()));
-        const dirDiff = Cartesian3.magnitude(Cartesian3.subtract(direction, camera.direction, new Cartesian3()));
+        const posDiff = Cartesian3.magnitude(Cartesian3.subtract(position, camera.positionWC, new Cartesian3()));
+        const dirDiff = Cartesian3.magnitude(Cartesian3.subtract(direction, camera.directionWC, new 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
         };
     }
@@ -6707,7 +6708,9 @@ function cullTilesets(register) {
         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;
@@ -42488,6 +42491,17 @@ var DisplacedSurfacePrimitive;
     // 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 };
@@ -42510,6 +42524,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;
@@ -42539,6 +42566,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.
  *
@@ -42558,8 +42625,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
@@ -42572,8 +42647,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.
@@ -42808,6 +42889,147 @@ void main() {
         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;
@@ -42826,6 +43048,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;
@@ -42838,7 +43068,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;
@@ -42861,6 +43093,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.
@@ -42899,6 +43222,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) {
@@ -42943,6 +43268,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;
         }
         /*
@@ -42975,24 +43308,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 = 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 = Math$1.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 = Cartographic.fromDegrees(Math$1.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 Texture({
+                    context,
+                    pixelFormat: 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 Sampler({
+                        wrapS: TextureWrap.CLAMP_TO_EDGE,
+                        wrapT: 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 Texture({
+                context,
+                pixelFormat: PixelFormat.RGBA,
+                source: {
+                    width: size,
+                    height: size,
+                    arrayBufferView: this.maskGroundPixels || packHeights([{ height: 0 }])
+                },
+                flipY: false,
+                sampler: new Sampler({
+                    wrapS: TextureWrap.CLAMP_TO_EDGE,
+                    wrapT: TextureWrap.CLAMP_TO_EDGE,
+                    // Nearest, because the shader interpolates decoded heights itself.
+                    minificationFilter: TextureMinificationFilter.NEAREST,
+                    magnificationFilter: 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.
@@ -43004,10 +43436,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 Texture({
                 context,
                 pixelFormat: PixelFormat.RGBA,
@@ -43216,6 +43646,28 @@ void main() {
                         u_groundWeight: () => (self.followGround && self.groundPixels ? 1 : 0),
                         u_groundRange: () => new Cartesian2(GROUND_MIN_METRES, GROUND_MAX_METRES),
                         u_groundSize: () => new 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 Cartesian2(self.maskGroundPixels ? MASK_GROUND_SAMPLES_PER_SIDE : 1, self.maskGroundPixels ? MASK_GROUND_SAMPLES_PER_SIDE : 1),
+                        u_extentDegrees: () => new Cartesian4(self.extent.West, self.extent.East, self.extent.North, self.extent.South),
+                        u_maskGroundDegrees: () => {
+                            const box = self.maskGroundBox || self.extent;
+                            return new 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,
@@ -43852,6 +44304,34 @@ var EntityRenderEnginePolygon;
         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).
      */
@@ -45914,7 +46394,7 @@ var StyleUtils;
     StyleUtils.ApplyTypeStyle = ApplyTypeStyle;
 })(StyleUtils || (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.