bruce-cesium 7.3.8 → 7.3.9

package/dist/bruce-cesium.umd.js

@@ -11027,10 +11027,6 @@
 
     /**
      * How often a historic refresh is worth running, and which Entities it should ask about first.
-     *
-     * A handful of tracked vehicles can afford to re-read on almost every clock tick. Thousands of
-     * parcels cannot, and refreshing them that often was never buying anything since the answer barely
-     * changes between ticks.
      */
     var HistoricFetchOrder;
     (function (HistoricFetchOrder) {
@@ -11075,6 +11071,13 @@
         HistoricFetchOrder.IntervalForClock = IntervalForClock;
         // Upper bounds in metres for the distance bands, nearest first.
         HistoricFetchOrder.DEFAULT_BANDS = [500, 2000, 10000, 50000];
+        // How far outside the visible rectangle something still counts as worth re-reading, share of the view itself.
+        HistoricFetchOrder.REFRESH_MARGIN_FRACTION = 0.5;
+        // A close view still gets a usable buffer, and a distant one does not reach half the account.
+        HistoricFetchOrder.MIN_REFRESH_MARGIN_METRES = 250;
+        HistoricFetchOrder.MAX_REFRESH_MARGIN_METRES = 2000;
+        const METRES_PER_DEGREE_LAT = 111320;
+        const MIN_LAT_COSINE = 0.01;
         /**
          * Resolves what to order by from the view monitor, falling back to the camera itself.
          */
@@ -11155,6 +11158,55 @@
             return grouped.filter(group => group.length > 0);
         }
         HistoricFetchOrder.ByCameraDistanceOf = ByCameraDistanceOf;
+        /**
+         * Returns how far past a visible rectangle a refresh should still reach, in metres.
+         */
+        function RefreshMarginFor(bounds) {
+            if (!bounds) {
+                return HistoricFetchOrder.MIN_REFRESH_MARGIN_METRES;
+            }
+            const latSpan = Math.abs(bounds.north - bounds.south) * METRES_PER_DEGREE_LAT;
+            const cosine = Math.max(MIN_LAT_COSINE, Math.cos(Cesium.Math.toRadians((bounds.north + bounds.south) / 2)));
+            const lonDegrees = bounds.west > bounds.east
+                ? (bounds.east + 360) - bounds.west
+                : bounds.east - bounds.west;
+            const lonSpan = Math.abs(lonDegrees) * METRES_PER_DEGREE_LAT * cosine;
+            const span = Math.min(latSpan, lonSpan);
+            if (!(span > 0)) {
+                return HistoricFetchOrder.MIN_REFRESH_MARGIN_METRES;
+            }
+            return Math.min(HistoricFetchOrder.MAX_REFRESH_MARGIN_METRES, Math.max(HistoricFetchOrder.MIN_REFRESH_MARGIN_METRES, span * HistoricFetchOrder.REFRESH_MARGIN_FRACTION));
+        }
+        HistoricFetchOrder.RefreshMarginFor = RefreshMarginFor;
+        /**
+         * Returns the rectangle grown outwards by a margin in metres.
+         */
+        function GrowBounds(bounds, metres) {
+            if (!bounds || !(metres > 0)) {
+                return bounds;
+            }
+            const dLat = metres / METRES_PER_DEGREE_LAT;
+            const north = Math.min(90, bounds.north + dLat);
+            const south = Math.max(-90, bounds.south - dLat);
+            const cosine = Math.cos(Cesium.Math.toRadians((bounds.north + bounds.south) / 2));
+            if (cosine < MIN_LAT_COSINE) {
+                return { north, south, west: -180, east: 180 };
+            }
+            const dLon = metres / (METRES_PER_DEGREE_LAT * cosine);
+            const straddles = bounds.west > bounds.east;
+            const gap = straddles ? bounds.west - bounds.east : 360 - (bounds.east - bounds.west);
+            if (gap <= dLon * 2) {
+                return { north, south, west: -180, east: 180 };
+            }
+            return { north, south, west: wrapLongitude(bounds.west - dLon), east: wrapLongitude(bounds.east + dLon) };
+        }
+        HistoricFetchOrder.GrowBounds = GrowBounds;
+        /*
+         * Returns a longitude folded back into the range the bounds are expressed in.
+         */
+        function wrapLongitude(lon) {
+            return (((lon + 180) % 360) + 360) % 360 - 180;
+        }
         /*
          * Returns whether a world position sits inside a ground rectangle given in degrees.
          */
@@ -11163,17 +11215,22 @@
             if (!degrees) {
                 return false;
             }
-            const { lat, lon } = degrees;
+            return InDegreeBounds(degrees.lat, degrees.lon, bounds);
+        }
+        HistoricFetchOrder.InBounds = InBounds;
+        /*
+         * The same test for a caller that already holds the degrees and should not pay to resolve them from a world position again.
+         */
+        function InDegreeBounds(lat, lon, bounds) {
             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;
+        HistoricFetchOrder.InDegreeBounds = InDegreeBounds;
         /*
          * Returns an Entity's world position, or null when it has none to place it by.
          */
@@ -14559,6 +14616,19 @@
             // 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();
+            // IDs a historic read has actually answered with a record, rather than falling back to a stub.
+            // A refresh serves these before the ones that have never produced anything.
+            this.everFound = new Set();
+            // Every known Entity bucketed by the ground cell its position falls in, so a refresh can ask
+            // what the view reaches instead of walking the whole set. Built as IDs arrive.
+            this.cells = new Map();
+            // IDs the position source could not place yet. They are always refreshed.
+            this.unplaced = new Set();
+            // The IDs the last decision found inside the view, so a camera move can queue the difference
+            // rather than re-requesting everything it already asked about.
+            this.lastInView = new Set();
+            // Unsubscribes the view monitor listener that queues what the camera has moved onto.
+            this.monitorRemoval = null;
             // Indicates a tick is active.
             // When true, we won't bother calling onTick again.
             this.runningTick = false;
@@ -14609,6 +14679,16 @@
             }
             this.historic = historic;
             this.expandSources = expandSources;
+            if (this.historic) {
+                // Anything already known was taken in before the index was being built, so it is filed
+                // a bounded number at a time from here rather than in one pass now.
+                for (const entityId of this.allEIds) {
+                    this.unplaced.add(entityId);
+                }
+            }
+            else {
+                this.clearIndex();
+            }
             if (this.historic) {
                 // 4 ticks per second.
                 // The fastest data we are working with is 5 times per second.
@@ -14660,6 +14740,8 @@
             this.lastOrderFocus = null;
             this.allEIds.clear();
             this.lastFoundDateTimes.clear();
+            this.everFound.clear();
+            this.clearIndex();
             this.lastDateTime = null;
         }
         ReQueueAll() {
@@ -14670,22 +14752,193 @@
             this.eIdQueued = new Set(this.eIdQueue);
             this.priorityCount = 0;
             this.lastOrderFocus = null;
+            this.clearIndex();
         }
         /**
-         * 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.
+         * 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;
+            this.cells.clear();
+            this.lastInView.clear();
+            for (const entityId of this.allEIds) {
+                this.unplaced.add(entityId);
+            }
         }
         /**
-         * 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.
+         * 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) {
+            var _a;
+            (_a = this.monitorRemoval) === null || _a === void 0 ? void 0 : _a.call(this);
+            this.monitorRemoval = null;
             this.monitor = monitor;
             this.lastOrderFocus = null;
+            if (!monitor) {
+                return;
+            }
+            this.monitorRemoval = monitor.Updated().Subscribe(() => {
+                this.admitNewlyInView();
+            });
+        }
+        /*
+         * Queues whatever the camera has moved onto since the last decision.
+         */
+        admitNewlyInView() {
+            if (this.disposed || !this.historic) {
+                return;
+            }
+            const inView = this.decideInView();
+            if (!inView) {
+                return;
+            }
+            const admit = [];
+            for (const entityId of inView) {
+                if (!this.lastInView.has(entityId)) {
+                    admit.push(entityId);
+                }
+            }
+            this.lastInView = new Set(inView);
+            if (admit.length) {
+                this.Queue(admit);
+            }
+        }
+        /*
+         * Returns the IDs a refresh should ask about, or null when the view cannot say and the answer has to be everything.
+         */
+        decideInView() {
+            if (!this.historic || !this.positionOf || !this.monitor) {
+                return null;
+            }
+            const area = this.refreshArea();
+            if (!area) {
+                return null;
+            }
+            const inView = [];
+            for (const key of this.candidateCellKeys(area)) {
+                const cell = this.cells.get(key);
+                if (!cell) {
+                    continue;
+                }
+                for (let i = 0; i < cell.ids.length; i++) {
+                    if (HistoricFetchOrder.InDegreeBounds(cell.lats[i], cell.lons[i], area)) {
+                        inView.push(cell.ids[i]);
+                    }
+                }
+            }
+            // Anything the source cannot place yet is asked about rather than quietly dropped.
+            for (const entityId of this.unplaced) {
+                inView.push(entityId);
+            }
+            return inView;
+        }
+        /*
+         * Returns the cell keys a rectangle can reach.
+         */
+        candidateCellKeys(area) {
+            const size = EntityGatherer.CELL_DEGREES;
+            const southCell = Math.floor(area.south / size);
+            const northCell = Math.floor(area.north / size);
+            const spans = (area.west > area.east ? [
+                {
+                    from: Math.floor(area.west / size),
+                    to: Math.floor(180 / size)
+                },
+                {
+                    from: Math.floor(-180 / size),
+                    to: Math.floor(area.east / size)
+                }
+            ] :
+                [{
+                        from: Math.floor(area.west / size),
+                        to: Math.floor(area.east / size)
+                    }]);
+            let width = 0;
+            for (const span of spans) {
+                width += (span.to - span.from) + 1;
+            }
+            const wanted = ((northCell - southCell) + 1) * width;
+            if (!(wanted > 0) || wanted > this.cells.size) {
+                return Array.from(this.cells.keys());
+            }
+            const keys = [];
+            for (let lat = southCell; lat <= northCell; lat++) {
+                for (const span of spans) {
+                    for (let lon = span.from; lon <= span.to; lon++) {
+                        keys.push(lat + ":" + lon);
+                    }
+                }
+            }
+            return keys;
+        }
+        /*
+         * Files an Entity in the cell its position falls in.
+         */
+        place(entityId) {
+            const degrees = this.degreesOf(entityId);
+            if (!degrees) {
+                this.unplaced.add(entityId);
+                return;
+            }
+            const size = EntityGatherer.CELL_DEGREES;
+            const key = Math.floor(degrees.lat / size) + ":" + Math.floor(degrees.lon / size);
+            let cell = this.cells.get(key);
+            if (!cell) {
+                cell = { ids: [], lats: [], lons: [] };
+                this.cells.set(key, cell);
+            }
+            cell.ids.push(entityId);
+            cell.lats.push(degrees.lat);
+            cell.lons.push(degrees.lon);
+            this.unplaced.delete(entityId);
+        }
+        /*
+         * Retries a bounded number of the Entities the source could not place before, so a late baked
+         * position joins the index without any one tick paying for all of them.
+         */
+        placeStragglers() {
+            if (!this.unplaced.size || !this.positionOf) {
+                return;
+            }
+            let budget = EntityGatherer.PLACE_BATCH;
+            for (const entityId of this.unplaced) {
+                if (budget-- <= 0) {
+                    return;
+                }
+                this.place(entityId);
+            }
+        }
+        clearIndex() {
+            this.cells.clear();
+            this.unplaced.clear();
+            this.lastInView.clear();
+        }
+        /*
+         * Returns where an Entity sits in degrees, or null when the source cannot place it.
+         */
+        degreesOf(entityId) {
+            let pos = null;
+            try {
+                pos = this.positionOf ? this.positionOf(entityId) : null;
+            }
+            catch {
+                pos = null;
+            }
+            return pos ? CartesianToDegrees(pos) : null;
+        }
+        /*
+         * Returns the visible rectangle plus the margin a refresh still reaches into,
+         * or null when the view cannot say, which is what leaves every Entity in.
+         */
+        refreshArea() {
+            const focus = HistoricFetchOrder.FocusFrom({ viewer: this.viewer, monitor: this.monitor });
+            if (!(focus === null || focus === void 0 ? void 0 : focus.bounds)) {
+                return null;
+            }
+            return HistoricFetchOrder.GrowBounds(focus.bounds, HistoricFetchOrder.RefreshMarginFor(focus.bounds));
         }
         /**
          * Re-bands the pending queue so the nearest Entities are requested first.
@@ -14698,8 +14951,6 @@
             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;
@@ -14746,26 +14997,47 @@
             });
             const ordered = [];
             for (const band of banded) {
+                // Within a band, the ones a read has answered for go first.
+                // A building that has never produced a record is the one least likely to start now, so it waits.
+                const withData = [];
+                const withoutData = [];
                 for (const entityId of band) {
+                    (this.everFound.has(entityId) ? withData : withoutData).push(entityId);
+                }
+                for (const entityId of withData) {
+                    ordered.push(entityId);
+                }
+                for (const entityId of withoutData) {
                     ordered.push(entityId);
                 }
             }
             return ordered;
         }
+        /*
+         * Takes an ID into the known set, filing it in the index the first time it is seen.
+         */
+        remember(entityId) {
+            if (this.allEIds.has(entityId)) {
+                return;
+            }
+            this.allEIds.add(entityId);
+            // Only a historic refresh reads the index, so nothing else pays to build it.
+            if (this.historic) {
+                this.place(entityId);
+            }
+        }
         Queue(entityIds, topOfQueue = false) {
             if (this.disposed || !(entityIds === null || entityIds === void 0 ? void 0 : entityIds.length)) {
                 return;
             }
             let changes = 0;
             if (topOfQueue) {
-                // Walked back to front so a repeated ID keeps the position of its last occurrence, then
-                // laid down in that order, which is where inserting one at a time leaves them.
                 const toFront = [];
                 const promoting = new Set();
                 let anyAlreadyQueued = false;
                 for (let i = entityIds.length - 1; i >= 0; i--) {
                     const eId = entityIds[i];
-                    this.allEIds.add(eId);
+                    this.remember(eId);
                     if (promoting.has(eId)) {
                         continue;
                     }
@@ -14801,7 +15073,7 @@
             else {
                 for (let i = 0; i < entityIds.length; i++) {
                     const eId = entityIds[i];
-                    this.allEIds.add(eId);
+                    this.remember(eId);
                     if (this.eIdQueued.has(eId)) {
                         continue;
                     }
@@ -14816,19 +15088,22 @@
             this.onTick(false);
         }
         Dispose() {
+            var _a;
             if (this.disposed) {
                 return;
             }
             this.disposed = true;
+            (_a = this.monitorRemoval) === null || _a === void 0 ? void 0 : _a.call(this);
+            this.monitorRemoval = null;
             this.hDisposals.forEach((d) => d());
             this.hDisposals = [];
-            // A tick still awaiting a response resumes after this, and anything left here would have it
-            // ask for the whole set again on the way out.
             this.eIdQueue = [];
             this.eIdQueued.clear();
             this.priorityCount = 0;
             this.allEIds.clear();
             this.lastFoundDateTimes.clear();
+            this.everFound.clear();
+            this.clearIndex();
             this.entityDataOverrides.clear();
         }
         checkRange(force) {
@@ -14852,6 +15127,7 @@
             this.lastDateTime = rTime;
             (async () => {
                 this.runningTick = true;
+                this.placeStragglers();
                 let rerun = false;
                 try {
                     const handleResponse = async (requestedBatch, entities) => {
@@ -14864,6 +15140,13 @@
                                 foundById.set(entityId, entity);
                             }
                         }
+                        if (this.historic) {
+                            for (const entityId of requestedBatch || []) {
+                                if (foundById.has(entityId)) {
+                                    this.everFound.add(entityId);
+                                }
+                            }
+                        }
                         for (const entityId of requestedBatch || []) {
                             const override = this.entityDataOverrides.get(entityId);
                             if (override) {
@@ -14992,15 +15275,16 @@
                             this._onQueueProgress.Trigger(100);
                         }
                     }
-                    // Now run through all IDs that we've seen and request them.
+                    // Now run through the IDs we've seen that the view still reaches, and request them.
                     // We'll skip those that we just requested.
-                    let allEIds = Array.from(this.allEIds);
+                    const inView = this.decideInView();
+                    this.lastInView = inView ? new Set(inView) : new Set();
+                    let allEIds = inView || Array.from(this.allEIds);
                     if (requestedIds.size) {
                         allEIds = allEIds.filter((eId) => !requestedIds.has(eId));
                     }
                     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.
+                        // The near ones are resolved first out of whatever the view still reaches.
                         allEIds = this.bandIds(allEIds);
                         while (allEIds.length && !this.disposed && !this.eIdQueue.length) {
                             if (this.historic && this.lastDateTime !== rTime) {
@@ -15039,6 +15323,11 @@
     }
     // Below this the whole queue clears in one or two requests, so ordering it buys nothing.
     EntityGatherer.MIN_ORDER_QUEUE = 500;
+    // Side of the ground cells Entities are bucketed into, in degrees.
+    // About a kilometre, so a view covers a handful of them rather than hundreds.
+    EntityGatherer.CELL_DEGREES = 0.01;
+    // How many Entities one tick will try to place in the index.
+    EntityGatherer.PLACE_BATCH = 20000;
     // 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;
@@ -47784,7 +48073,7 @@ void main() {
         StyleUtils.ApplyTypeStyle = ApplyTypeStyle;
     })(exports.StyleUtils || (exports.StyleUtils = {}));
 
-    const VERSION = "7.3.8";
+    const VERSION = "7.3.9";
     /**
      * 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.