bruce-cesium 7.1.9 → 7.2.1

package/dist/types/rendering/render-managers/common/historic-utils.d.ts

@@ -0,0 +1,159 @@
+import * as Cesium from "cesium";
+import { BruceApi, Entity, EntityHistoricData, IDictionary } from "bruce-models";
+/**
+ * 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.
+ */
+export declare namespace HistoricFetchOrder {
+    const MIN_INTERVAL_MS = 250;
+    const MAX_INTERVAL_MS = 10000;
+    const SMALL_SET = 30;
+    const LARGE_SET = 5000;
+    /**
+     * Returns how long to wait between historic refreshes for a set of this size.
+     */
+    function IntervalFor(entityCount: number, minMs?: number, maxMs?: number): number;
+    /**
+     * 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.
+     */
+    function ByCameraDistance(params: {
+        viewer: Cesium.Viewer;
+        entities: Entity.IEntity[];
+        bands?: number[];
+    }): Entity.IEntity[][];
+}
+/**
+ * Decides what slice of history is worth fetching for the clock as it is currently moving.
+ */
+export declare namespace HistoricFetchPlan {
+    interface ITrajectory {
+        direction: -1 | 0 | 1;
+        ratePerSecondMs: number;
+    }
+    interface IRange {
+        start: number;
+        stop: number;
+    }
+    interface IPlan {
+        detail: IRange | null;
+        coarse: (IRange & {
+            sample: number;
+        }) | null;
+    }
+    const DEFAULT_LEAD_SECONDS = 10;
+    const DEFAULT_MIN_DETAIL_MS: number;
+    const DEFAULT_MAX_DETAIL_MS: number;
+    const DEFAULT_SAMPLE = 200;
+    function DetailSpanFor(trajectory: ITrajectory, leadSeconds: number, minMs: number, maxMs: number): number;
+    /**
+     * Returns the detail window and the coarse pass for the clock as it stands.
+     */
+    function Plan(params: {
+        currentTime: number;
+        windowStart: number;
+        windowStop: number;
+        trajectory: ITrajectory;
+        leadSeconds?: number;
+        minDetailMs?: number;
+        maxDetailMs?: number;
+        sample?: number;
+    }): IPlan;
+    /**
+     * Tracks which way the clock is moving and how fast, from the times it is observed at.
+     * Playback and a user dragging the timeline both look the same here, which is the point.
+     */
+    class TrajectoryTracker {
+        private smoothing;
+        private lastTime;
+        private lastObservedAt;
+        private direction;
+        private ratePerSecondMs;
+        constructor(smoothing?: number);
+        /**
+         * Records where the clock is now. observedAt is the wall clock, in milliseconds.
+         */
+        Observe(sceneTime: number, observedAt: number): void;
+        Get(): ITrajectory;
+        Reset(): void;
+    }
+}
+/**
+ * Tracks which time ranges of historic data have already been requested, and the records they
+ * returned, so moving the clock only fetches the part that is genuinely new.
+ *
+ * Coverage is tracked by the ranges that were asked for, not by the timestamps that came back. A
+ * window holding no records is still covered, otherwise an empty stretch is re-requested forever.
+ */
+export declare class HistoricRangeCache {
+    private mergeToleranceMs;
+    private held;
+    private heldCoarse;
+    private records;
+    constructor(mergeToleranceMs?: number);
+    /**
+     * Returns the parts of the window that have not been requested yet.
+     */
+    MissingRanges(start: number, stop: number): {
+        start: number;
+        stop: number;
+    }[];
+    /**
+     * Marks a range as requested and merges the records it returned into what is already held.
+     */
+    Absorb(start: number, stop: number, recordsByIds: IDictionary<EntityHistoricData.IData[]>, coarse?: boolean): void;
+    GetRecords(): IDictionary<EntityHistoricData.IData[]>;
+    /**
+     * Returns whether the window is already covered in full.
+     */
+    Covers(start: number, stop: number): boolean;
+    /**
+     * Returns whether a sampled pass already describes the window.
+     */
+    CoversCoarse(start: number, stop: number): boolean;
+    Clear(): void;
+    private mergeAdjacent;
+}
+/**
+ * Pulls historic records for the visible clock range: what to ask for, in what order, and what has
+ * already been asked for.
+ */
+export declare class HistoricGatherer {
+    private params;
+    static readonly LIVE_TAIL_MS = 15000;
+    private cache;
+    private trajectory;
+    private inFlight;
+    private disposed;
+    constructor(params: {
+        viewer: Cesium.Viewer;
+        getApi: () => BruceApi.Api;
+        getAttrKey: () => string;
+        sample?: number;
+        onRecords?: (recordsByIds: IDictionary<EntityHistoricData.IData[]>) => void;
+        paddingMs?: number;
+        liveTailMs?: number;
+    });
+    get Records(): IDictionary<EntityHistoricData.IData[]>;
+    Clear(): void;
+    Dispose(): void;
+    /**
+     * Returns how long to wait between refreshes for a set of this size.
+     */
+    IntervalFor(entityCount: number): number;
+    /**
+     * Fetches whatever the current clock range needs that is not already held.
+     * Returns whether anything was requested, alongside every record held for these Entities.
+     */
+    Gather(entities: Entity.IEntity[]): Promise<{
+        fetched: boolean;
+        recordsByIds: IDictionary<EntityHistoricData.IData[]>;
+    }>;
+    private holdTo;
+    private request;
+}

package/dist/types/rendering/render-managers/entities/entities-ids-render-manager.d.ts

@@ -25,6 +25,7 @@ export declare namespace EntitiesIdsRenderManager {
         get ZoomControl(): ZoomControl.IItem[];
         private viewerDateTimeChangeRemoval;
         private entitiesHistoric;
+        private historicGatherer;
         private renderQueueActive;
         private renderQueue;
         private renderQueueForceFlags;

package/dist/types/rendering/render-managers/entities/entities-render-manager.d.ts

@@ -38,6 +38,7 @@ export declare namespace EntitiesRenderManager {
         private clustering;
         private sources;
         private reRenderState;
+        private historicGatherer;
         private useGeojson;
         private zoomControl;
         private scenario;
@@ -104,6 +105,10 @@ export declare namespace EntitiesRenderManager {
          */
         private renderAsIndividualsChain;
         private renderAsIndividuals;
+        /**
+         * Returns the historic records to interpolate between, fetching only what is not already held.
+         */
+        private gatherHistoric;
         private doRenderAsIndividuals;
         get HandoffKey(): string | null;
         static GetHandoffKey(item: MenuItem.Item.IEntities): string | null;

package/dist/types/rendering/render-managers/tilesets/tileset-cad-render-manager.d.ts

@@ -49,6 +49,7 @@ export declare namespace TilesetCadRenderManager {
         private viewerDateTimeChangeRemoval;
         private historicPossesInitialLoaded;
         private historicAnimation;
+        private historicGatherer;
         private historicPossesLoadingProm;
         private featureQueue;
         private featureQueueStates;

package/dist/types/rendering/render-managers/tilesets/tileset-entities-render-manager.d.ts

@@ -63,6 +63,8 @@ export declare namespace TilesetEntitiesRenderManager {
         private doDispose;
         private onCTilesetLoad;
         get HandoffKey(): string | null;
+        static IsHistoric(item: MenuItem.Item.IEntitiesTileset): boolean;
+        static NeedsStyler(item: MenuItem.Item.IEntitiesTileset): boolean;
         static GetHandoffKey(item: MenuItem.Item.IEntitiesTileset): string | null;
         PrepareHandoff(): RenderManager.IHandoffPayload | null;
         AdoptHandoff(payload: RenderManager.IHandoffPayload): void;

package/dist/types/rendering/tileset-styler.d.ts

@@ -29,6 +29,7 @@ export declare class TilesetStyler {
     private scenario;
     private expandSources;
     private historic;
+    private applyStyles;
     private entityGatherer;
     private reRenderState;
     private shouldUpdateRegoStates;
@@ -52,6 +53,7 @@ export declare class TilesetStyler {
         menuItemId?: string;
         scenario?: number | string;
         historic?: boolean;
+        applyStyles?: boolean;
     }): void;
     /**
      * Updates style mapping and fallback style.

package/dist/types/utils/view-utils.d.ts

@@ -7,9 +7,11 @@ export declare const CESIUM_TIMELINE_LIVE_PADDING_KEY = "_nextspace_timeline_liv
 export declare const CESIUM_TIMELINE_INTERVAL_KEY = "_nextspace_timeline_interval";
 export declare const CESIUM_MODEL_SPACE_KEY = "_nextspace_model_space";
 export declare const DEFAULT_LIVE_PADDING_SECONDS: number;
-export declare const DEFAULT_BRIGHTNESS_SHIFT = 0.2;
-export declare const DEFAULT_LIGHT_INTENSITY = 3;
+export declare const DEFAULT_BRIGHTNESS_SHIFT = 0;
+export declare const DEFAULT_LIGHT_INTENSITY = 2;
 export declare const LIGHTING_SETTINGS_VERSION = 2;
+export declare const LIGHT_INTENSITY_COMPENSATION = 1.2;
+export declare const MAX_COMPENSATED_LIGHT_INTENSITY = 3;
 export declare namespace ViewUtils {
     function GatherLegacyMapTiles(params: {
         viewer: Cesium.Viewer;
@@ -103,19 +105,40 @@ export declare namespace ViewUtils {
      * @param shift -1 to 1, where 0 or less leaves CesiumJS's own defaults alone.
      */
     function ApplyDefaultBrightness(viewer: Cesium.Viewer, shift?: number): void;
+    /**
+     * Options applied to the environment based lighting of every tileset and model this library creates.
+     * Null leaves CesiumJS's own defaults in place.
+     * @param options eg { enabled: false } to switch the lighting off, or { saturation: 0 } to keep the
+     * lift without the ground bounce tinting untextured geometry.
+     */
+    function SetDefaultEnvironmentMapOptions(options: any): void;
+    /**
+     * Whether the host app's CesiumJS is a build that shades models darker than the ones these bookmarks were set up against.
+     * DynamicEnvironmentMapManager arrived with that change, so its presence marks
+     */
+    function GetDefaultEnvironmentMapOptions(engineShadesDarker?: boolean): any;
+    /**
+     * The lighting options every tileset and model this library creates is built with.
+     * Spread into the construction options, since both are read once when a primitive is made.
+     */
+    function DefaultLightingProps(engineShadesDarker?: boolean): any;
+    /**
+     * ImageBasedLighting applied to every tileset and model this library creates. Null, the default,
+     * leaves CesiumJS's own in place.
+     * @param imageBasedLighting a Cesium.ImageBasedLighting, shared across primitives.
+     */
+    function SetDefaultImageBasedLighting(imageBasedLighting: any): void;
+    function GetDefaultImageBasedLighting(): any;
+    function EngineShadesModelsDarker(): boolean;
     /**
      * Resolves the sun colour and intensity to apply for a bookmark's lighting settings.
      * @param lighting the bookmark's lighting settings, or null when it carries none.
      * @returns the colour and intensity to put on the scene light.
      */
-    function ResolveLightSettings(lighting: any): {
+    function ResolveLightSettings(lighting: any, engineShadesDarker?: boolean): {
         color: Cesium.Color;
         intensity: number;
     };
-    /**
-     * Options handed to every tileset and model this library creates.
-     */
-    function DefaultEnvironmentMapOptions(): any;
     function SetGlobeDetails(params: {
         viewer: Cesium.Viewer;
         hidden?: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bruce-cesium",
-  "version": "7.1.9",
+  "version": "7.2.1",
   "description": "",
   "keywords": [],
   "main": "dist/bruce-cesium.umd.js",
@@ -83,7 +83,7 @@
     "typescript": "^5.0.4"
   },
   "dependencies": {
-    "bruce-models": "^7.1.72",
+    "bruce-models": "^7.1.75",
     "tslib": "^2.4.1"
   }
 }