bruce-cesium 7.2.4 → 7.2.5

package/dist/bruce-cesium.umd.js

@@ -2883,6 +2883,36 @@
     function ColorToCColor(color) {
         return new Cesium.Color(color.red ? color.red / 255 : 0, color.green ? color.green / 255 : 0, color.blue ? color.blue / 255 : 0, color.alpha);
     }
+    const degreesCache = new WeakMap();
+    /**
+     * Returns a world position's latitude and longitude in degrees, or null when it has none.
+     * @param pos
+     */
+    function CartesianToDegrees(pos) {
+        if (!pos) {
+            return null;
+        }
+        const cached = degreesCache.get(pos);
+        if (cached) {
+            return cached;
+        }
+        let carto;
+        try {
+            carto = Cesium.Cartographic.fromCartesian(pos);
+        }
+        catch {
+            return null;
+        }
+        if (!carto) {
+            return null;
+        }
+        const degrees = {
+            lat: Cesium.Math.toDegrees(carto.latitude),
+            lon: Cesium.Math.toDegrees(carto.longitude)
+        };
+        degreesCache.set(pos, degrees);
+        return degrees;
+    }
     /**
      * Removes duplicate points in a row and returns a new array.
      * Passed array is not mutated.
@@ -10737,41 +10767,107 @@
             return Math.round(minMs + ((maxMs - minMs) * progress));
         }
         HistoricFetchOrder.IntervalFor = IntervalFor;
+        // Upper bounds in metres for the distance bands, nearest first.
+        HistoricFetchOrder.DEFAULT_BANDS = [500, 2000, 10000, 50000];
         /**
-         * Returns the Entities grouped into bands by distance from the camera, nearest band first.
-         *
-         * Bands rather than a true sort, so a small camera move does not reshuffle the whole queue and
-         * restart it. What the user is looking at resolves first either way.
+         * Resolves what to order by from the view monitor, falling back to the camera itself.
          */
-        function ByCameraDistance(params) {
+        function FocusFrom(params) {
             var _a;
-            const { viewer, entities } = params;
-            const bands = params.bands || [500, 2000, 10000, 50000];
-            if (!(entities === null || entities === void 0 ? void 0 : entities.length)) {
+            const { viewer, monitor } = params;
+            let origin = null;
+            let bounds = null;
+            try {
+                // Null whenever the view has no ground intersection, eg. a camera aimed at the sky.
+                const target = monitor === null || monitor === void 0 ? void 0 : monitor.GetTarget();
+                if (target && isFinite(target.latitude) && isFinite(target.longitude)) {
+                    origin = Cesium.Cartesian3.fromDegrees(target.longitude, target.latitude);
+                }
+                bounds = (monitor === null || monitor === void 0 ? void 0 : monitor.GetBounds()) || null;
+            }
+            catch {
+                origin = null;
+                bounds = null;
+            }
+            if (!origin) {
+                origin = (_a = viewer === null || viewer === void 0 ? void 0 : viewer.camera) === null || _a === void 0 ? void 0 : _a.position;
+            }
+            if (!origin) {
+                return null;
+            }
+            return bounds ? { origin, bounds } : { origin };
+        }
+        HistoricFetchOrder.FocusFrom = FocusFrom;
+        /**
+         * Returns the Entities grouped nearest first, on screen ahead of off screen.
+         */
+        function ByCameraDistance(params) {
+            const { viewer, entities, monitor } = params;
+            return ByCameraDistanceOf({
+                focus: FocusFrom({ viewer, monitor }),
+                items: entities,
+                posOf: (entity) => SafePos(entity, viewer),
+                bands: params.bands
+            });
+        }
+        HistoricFetchOrder.ByCameraDistance = ByCameraDistance;
+        /**
+         * Bands anything that can name its own world position, on the same bounds as the Entity form.
+         */
+        function ByCameraDistanceOf(params) {
+            const { focus, items, posOf } = params;
+            const bands = params.bands || HistoricFetchOrder.DEFAULT_BANDS;
+            if (!(items === null || items === void 0 ? void 0 : items.length)) {
                 return [];
             }
-            const cameraPos = (_a = viewer === null || viewer === void 0 ? void 0 : viewer.camera) === null || _a === void 0 ? void 0 : _a.position;
-            if (!cameraPos) {
-                return [entities];
+            if (!(focus === null || focus === void 0 ? void 0 : focus.origin)) {
+                return [items];
+            }
+            // One band past the named bounds, for everything beyond the last of them. Then the same
+            // again for what is off screen, so nothing visible waits behind something that is not.
+            const perTier = bands.length + 1;
+            const offScreenTier = focus.bounds ? perTier : 0;
+            const placeless = offScreenTier + perTier;
+            const grouped = [];
+            for (let i = 0; i <= placeless; i++) {
+                grouped.push([]);
             }
-            // One band past the named bounds, for everything beyond the last of them.
-            const banded = bands.map(() => []).concat([[]]);
-            for (const entity of entities) {
-                const pos = SafePos(entity, viewer);
+            for (const item of items) {
+                // An item with no position falls to the last group rather than blocking the near ones.
+                const pos = posOf(item);
                 if (!pos) {
-                    banded[banded.length - 1].push(entity);
+                    grouped[placeless].push(item);
                     continue;
                 }
-                const distance = Cesium.Cartesian3.distance(cameraPos, pos);
-                let index = bands.findIndex(bound => distance <= bound);
-                if (index < 0) {
-                    index = banded.length - 1;
+                const distance = Cesium.Cartesian3.distance(focus.origin, pos);
+                let band = bands.findIndex(bound => distance <= bound);
+                if (band < 0) {
+                    band = bands.length;
                 }
-                banded[index].push(entity);
+                grouped[(focus.bounds && !InBounds(pos, focus.bounds)) ? offScreenTier + band : band].push(item);
             }
-            return banded.filter(band => band.length > 0);
+            return grouped.filter(group => group.length > 0);
         }
-        HistoricFetchOrder.ByCameraDistance = ByCameraDistance;
+        HistoricFetchOrder.ByCameraDistanceOf = ByCameraDistanceOf;
+        /*
+         * Returns whether a world position sits inside a ground rectangle given in degrees.
+         */
+        function InBounds(pos, bounds) {
+            const degrees = CartesianToDegrees(pos);
+            if (!degrees) {
+                return false;
+            }
+            const { lat, lon } = degrees;
+            if (lat < bounds.south || lat > bounds.north) {
+                return false;
+            }
+            // A view straddling the antimeridian reports west east of east, so the span is the outside.
+            if (bounds.west > bounds.east) {
+                return lon >= bounds.west || lon <= bounds.east;
+            }
+            return lon >= bounds.west && lon <= bounds.east;
+        }
+        HistoricFetchOrder.InBounds = InBounds;
         /*
          * Returns an Entity's world position, or null when it has none to place it by.
          */
@@ -11089,7 +11185,7 @@
             }
             if (plan.detail) {
                 const bands = entities.length > HistoricFetchOrder.SMALL_SET
-                    ? HistoricFetchOrder.ByCameraDistance({ viewer, entities })
+                    ? HistoricFetchOrder.ByCameraDistance({ viewer, entities, monitor: this.params.monitor })
                     : [entities];
                 for (const range of this.cache.MissingRanges(plan.detail.start, plan.detail.stop)) {
                     if (this.disposed) {
@@ -11253,6 +11349,7 @@
                 this.onSeriesDiscovered = onSeriesDiscovered;
                 this.historicGatherer = new HistoricGatherer({
                     viewer: this.viewer,
+                    monitor: this.monitor,
                     getApi: () => this.apiGetter.getApi(),
                     getAttrKey: () => { var _a; return (_a = this.item.BruceEntity) === null || _a === void 0 ? void 0 : _a.historicAttrKey; },
                     // A second either side, to take in records sitting exactly on the boundary.
@@ -13358,6 +13455,7 @@
                 this.visualsManager = visualsManager;
                 this.historicGatherer = new HistoricGatherer({
                     viewer: this.viewer,
+                    monitor: this.monitor,
                     getApi: () => this.apiGetter.getApi(),
                     getAttrKey: () => { var _a; return (_a = this.item.BruceEntity) === null || _a === void 0 ? void 0 : _a.historicAttrKey; },
                     // Padding either side of a requested range, for clock desync between us and the server.
@@ -13992,6 +14090,16 @@
             this.lastFoundDateTimes = new Map();
             // ID of Entity IDs that need to be requested.
             this.eIdQueue = [];
+            // Resolves where an Entity sits without reading its record, when the caller can say.
+            // Unset leaves the queue in insertion order, which is what sources that bake no coordinates get.
+            this.positionOf = null;
+            // How many IDs at the front of the queue were explicitly asked for first.
+            // Camera ordering leaves those alone, since an explicit re-render outranks proximity.
+            this.priorityCount = 0;
+            // View focus the queue was last banded from.
+            this.lastOrderFocus = null;
+            // Reports what the camera is aimed at, rather than only where it sits.
+            this.monitor = null;
             // All IDs that have ever been queued.
             // When nothing is in queue, we'll re-request the existing IDs based on timeline changes.
             this.allEIds = new Set();
@@ -14091,6 +14199,8 @@
                 return;
             }
             this.eIdQueue = [];
+            this.priorityCount = 0;
+            this.lastOrderFocus = null;
             this.allEIds.clear();
             this.lastFoundDateTimes.clear();
             this.lastDateTime = null;
@@ -14100,6 +14210,89 @@
                 return;
             }
             this.eIdQueue = Array.from(this.allEIds);
+            this.priorityCount = 0;
+            this.lastOrderFocus = null;
+        }
+        /**
+         * Supplies a lookup from Entity ID to world position, letting the queue resolve what the camera
+         * is nearest first. Sources that cannot answer should not call this, and are served in order.
+         */
+        SetPositionSource(positionOf) {
+            this.positionOf = positionOf;
+            this.lastOrderFocus = null;
+        }
+        /**
+         * Supplies the view monitor, so the order follows the ground the camera is aimed at and prefers
+         * what is on screen. Without one the ordering falls back to distance from the camera itself.
+         */
+        SetViewMonitor(monitor) {
+            this.monitor = monitor;
+            this.lastOrderFocus = null;
+        }
+        /**
+         * Re-bands the pending queue so the nearest Entities are requested first.
+         */
+        orderQueueByCamera() {
+            if (!this.positionOf || this.eIdQueue.length < EntityGatherer.MIN_ORDER_QUEUE) {
+                return;
+            }
+            const focus = HistoricFetchOrder.FocusFrom({ viewer: this.viewer, monitor: this.monitor });
+            if (!focus) {
+                return;
+            }
+            // Re-banding on every batch would cost a full pass per request for no change in the answer.
+            // Measured on the focus, so panning across the ground counts even when the eye barely moves.
+            if (this.lastOrderFocus && !EntityGatherer.boundsChanged(this.lastOrderFocus, focus) &&
+                Cesium.Cartesian3.distance(this.lastOrderFocus.origin, focus.origin) < EntityGatherer.REORDER_MOVE_METRES) {
+                return;
+            }
+            this.lastOrderFocus = focus;
+            const priority = this.priorityCount > 0 ? this.eIdQueue.slice(0, this.priorityCount) : [];
+            const rest = this.priorityCount > 0 ? this.eIdQueue.slice(this.priorityCount) : this.eIdQueue;
+            if (!rest.length) {
+                return;
+            }
+            this.eIdQueue = priority.concat(this.bandIds(rest, focus));
+        }
+        /*
+         * Returns whether the visible rectangle differs enough to change what counts as on screen.
+         */
+        static boundsChanged(a, b) {
+            if (!a.bounds || !b.bounds) {
+                return Boolean(a.bounds) !== Boolean(b.bounds);
+            }
+            return (a.bounds.north !== b.bounds.north ||
+                a.bounds.south !== b.bounds.south ||
+                a.bounds.east !== b.bounds.east ||
+                a.bounds.west !== b.bounds.west);
+        }
+        /*
+         * Returns the IDs reordered nearest band first, or unchanged when there is nothing to order by.
+         */
+        bandIds(entityIds, focus) {
+            const from = focus || HistoricFetchOrder.FocusFrom({ viewer: this.viewer, monitor: this.monitor });
+            if (!this.positionOf || !from || !entityIds.length) {
+                return entityIds;
+            }
+            const banded = HistoricFetchOrder.ByCameraDistanceOf({
+                focus: from,
+                items: entityIds,
+                posOf: (entityId) => {
+                    try {
+                        return this.positionOf(entityId);
+                    }
+                    catch {
+                        return null;
+                    }
+                }
+            });
+            const ordered = [];
+            for (const band of banded) {
+                for (const entityId of band) {
+                    ordered.push(entityId);
+                }
+            }
+            return ordered;
         }
         Queue(entityIds, topOfQueue = false) {
             if (this.disposed || !(entityIds === null || entityIds === void 0 ? void 0 : entityIds.length)) {
@@ -14113,8 +14306,12 @@
                     // If we want it to be at the top of the queue, remove it from the queue first.
                     if (index !== -1) {
                         this.eIdQueue.splice(index, 1);
+                        if (index < this.priorityCount) {
+                            this.priorityCount -= 1;
+                        }
                     }
                     this.eIdQueue.unshift(eId);
+                    this.priorityCount += 1;
                     changes += 1;
                 }
                 else if (index === -1) {
@@ -14265,7 +14462,9 @@
                             if (this.historic && this.lastDateTime !== rTime) {
                                 break;
                             }
+                            this.orderQueueByCamera();
                             const batch = this.eIdQueue.splice(0, QUEUE_BATCH_SIZE);
+                            this.priorityCount = Math.max(0, this.priorityCount - batch.length);
                             const { entities } = await BModels.Entity.GetListByIds({
                                 entityIds: batch,
                                 historicPoint: this.historic ? rTime : null,
@@ -14298,6 +14497,9 @@
                         allEIds = allEIds.filter((eId) => requestedIds.indexOf(eId) === -1);
                     }
                     if (allEIds.length) {
+                        // A historic tick re-reads the whole set, so the near ones are worth resolving
+                        // first here even more than in the queue above.
+                        allEIds = this.bandIds(allEIds);
                         while (allEIds.length && !this.disposed && !this.eIdQueue.length) {
                             if (this.historic && this.lastDateTime !== rTime) {
                                 break;
@@ -14331,6 +14533,11 @@
             })();
         }
     }
+    // Below this the whole queue clears in one or two requests, so ordering it buys nothing.
+    EntityGatherer.MIN_ORDER_QUEUE = 500;
+    // How far the point being looked at has to move before the queue is worth re-banding, in metres.
+    // Under the nearest band's width, so a move that could change what is nearest still triggers one.
+    EntityGatherer.REORDER_MOVE_METRES = 250;
 
     // ND-1641. BOOKMARKS - (DEMO) View does not match bookmark.
     // We have some evil hard-coded style mappings that need to be fixed.
@@ -14454,7 +14661,8 @@
         }
         Init(params) {
             var _a, _b;
-            let { viewer, api, cTileset, fallbackStyleId, styleMapping, expandSources, menuItemId, register, scenario, historic, applyStyles } = params;
+            let { viewer, api, cTileset, fallbackStyleId, styleMapping, expandSources, menuItemId, register, scenario, historic, applyStyles, monitor } = params;
+            this.monitor = monitor;
             this.viewer = viewer;
             this.api = api;
             this.cTileset = cTileset;
@@ -14510,6 +14718,14 @@
                     }
                 }
             });
+            // Only Entities Sets bake coordinates into their features, so for any other source this
+            // resolves nothing and the gather stays in insertion order.
+            this.entityGatherer.SetViewMonitor(this.monitor);
+            this.entityGatherer.SetPositionSource((entityId) => {
+                var _a;
+                const visual = (_a = this.getEntityRego(entityId)) === null || _a === void 0 ? void 0 : _a.visual;
+                return (visual === null || visual === void 0 ? void 0 : visual._bakedPos) || null;
+            });
             this.loaded = true;
             this.loadStyles();
             const feed = (_b = this.api) === null || _b === void 0 ? void 0 : _b.RecordChangeFeed;
@@ -19721,7 +19937,8 @@
                 // Saves having to do a case-insensitive lookup every time.
                 this.featurePropCache = new Map();
                 this.featurePropsChecked = 0;
-                const { viewer, register: visualsManager, getters: apiGetter, item, initQueue } = params;
+                const { viewer, register: visualsManager, getters: apiGetter, item, initQueue, monitor } = params;
+                this.monitor = monitor;
                 this.viewer = viewer;
                 this.getters = apiGetter;
                 this.item = item;
@@ -19830,7 +20047,8 @@
                                         menuItemId: this.item.id,
                                         register: this.visualsManager,
                                         historic: Manager.IsHistoric(this.item),
-                                        applyStyles: Boolean(this.item.ApplyStyles)
+                                        applyStyles: Boolean(this.item.ApplyStyles),
+                                        monitor: this.monitor
                                     });
                                 }
                                 this.onCTilesetLoad();
@@ -19990,6 +20208,16 @@
                     else if (lowered === "internalid") {
                         this.featurePropCache.set("internalId", prop);
                     }
+                    else if (lowered === "latitude") {
+                        this.featurePropCache.set("latitude", prop);
+                    }
+                    else if (lowered === "longitude") {
+                        this.featurePropCache.set("longitude", prop);
+                    }
+                    // b3dm names the baked height TerrainHeight, the glTF metadata table calls it Altitude.
+                    else if (lowered === "terrainheight" || lowered === "altitude") {
+                        this.featurePropCache.set("height", prop);
+                    }
                 }
             }
             Dispose() {
@@ -20144,7 +20372,8 @@
                         menuItemId: this.item.id,
                         register: this.visualsManager,
                         historic: Manager.IsHistoric(this.item),
-                        applyStyles: Boolean(this.item.ApplyStyles)
+                        applyStyles: Boolean(this.item.ApplyStyles),
+                        monitor: this.monitor
                     });
                     this.queueHandoffRestyle(this.visualsManager.GetRegos({ menuItemId: this.item.id }));
                 }
@@ -20187,6 +20416,45 @@
                     }
                 }, 10);
             }
+            /*
+             * Reads a numeric feature property, returning null for anything that is not one.
+             */
+            static readNumber(feature, prop) {
+                const raw = feature.getProperty(prop);
+                // Coercing straight to a number would turn null, undefined and "" into a valid zero,
+                // which for a coordinate is a real place off the coast of Africa.
+                if (raw == null || raw === "" || typeof raw === "boolean") {
+                    return null;
+                }
+                const value = +raw;
+                return isFinite(value) ? value : null;
+            }
+            /*
+             * Returns the world position an Entities Set bakes into each feature, or null when it has none.
+             */
+            readBakedPos(feature) {
+                const latProp = this.featurePropCache.get("latitude");
+                const lonProp = this.featurePropCache.get("longitude");
+                if (!latProp || !lonProp) {
+                    return null;
+                }
+                try {
+                    const lat = Manager.readNumber(feature, latProp);
+                    const lon = Manager.readNumber(feature, lonProp);
+                    // Degrees, per the batch table the generator writes. The range check doubles as a
+                    // guard against a source that bakes radians, which would otherwise read as valid.
+                    if (lat == null || lon == null || Math.abs(lat) > 90 || Math.abs(lon) > 180) {
+                        return null;
+                    }
+                    // A height that will not read is worth losing, the position it belongs to is not.
+                    const heightProp = this.featurePropCache.get("height");
+                    const height = heightProp ? Manager.readNumber(feature, heightProp) : 0;
+                    return Cesium.Cartesian3.fromDegrees(lon, lat, height !== null && height !== void 0 ? height : 0);
+                }
+                catch {
+                    return null;
+                }
+            }
             mapTilesetFeature(feature) {
                 var _a, _b, _c;
                 this.evaluateFeatureProps(feature);
@@ -20267,6 +20535,12 @@
                         rego.internalId = parsed;
                     }
                 }
+                // Stamped on the feature the properties came from, so a sibling keeps its own position
+                // and nothing has to be cleaned up when the tile unloads.
+                const bakedPos = this.readBakedPos(feature);
+                if (bakedPos) {
+                    feature._bakedPos = bakedPos;
+                }
                 this.loadedCesiumEntities[rego.entityId] = rego;
                 this.visualsManager.AddRego({
                     rego,
@@ -24131,6 +24405,7 @@
                                 viewer: this.viewer,
                                 register: this.visualsRegister,
                                 getters: this.getters,
+                                monitor: this.sharedMonitor,
                                 item: params.item,
                                 initQueue: this.tilesetInitQueue
                             });
@@ -40886,9 +41161,11 @@
                     return;
                 }
                 let next = -1;
+                let isTarget = false;
                 if (this.pendingIndex !== -1) {
                     next = this.pendingIndex;
                     this.pendingIndex = -1;
+                    isTarget = true;
                 }
                 else {
                     next = this.nearestUncachedFrame();
@@ -40897,7 +41174,7 @@
                     return;
                 }
                 this.inFlightIndex = next;
-                this.fetchAndTint(next)
+                this.fetchAndTint(next, isTarget)
                     .catch(() => {
                     // Eating it.
                 })
@@ -40908,7 +41185,7 @@
                     }
                 });
             }
-            async fetchAndTint(idx) {
+            async fetchAndTint(idx, isTarget = true) {
                 const tiles = this.tiles;
                 // Every tile's frame for one timestep sits contiguously, because the generator writes
                 // frame major. So a tiled frame is still ONE range request, not one per tile.
@@ -40940,10 +41217,25 @@
                 this.frameCache[idx] = decoded.pixels;
                 this.frameDims[idx] = { width: decoded.width, height: decoded.height };
                 this.valueCache[idx] = decoded.valuePixels || null;
-                if (idx === this.currentFrameIndex) {
+                if (this.shouldPresent(idx, isTarget)) {
                     this.beginCrossfadeTo(idx);
                 }
             }
+            /*
+             * Whether a frame that has just decoded is worth putting on screen.
+             */
+            shouldPresent(idx, isTarget) {
+                if (idx === this.currentFrameIndex) {
+                    return true;
+                }
+                // A prefetch is for a frame nobody asked to see, so it stays in the cache.
+                if (!isTarget) {
+                    return false;
+                }
+                // Dragging the timeline retargets faster than a frame can be fetched, so the frame that
+                // lands is rarely the one now under the playhead.
+                return !this.frameCache[this.currentFrameIndex];
+            }
             /*
              * Draws every tile of one frame into a single raster covering the drape extent.
              */
@@ -45481,7 +45773,7 @@ void main() {
         StyleUtils.ApplyTypeStyle = ApplyTypeStyle;
     })(exports.StyleUtils || (exports.StyleUtils = {}));
 
-    const VERSION = "7.2.4";
+    const VERSION = "7.2.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.