bruce-cesium 7.3.3 → 7.3.5

package/dist/types/rendering/cesium-animated-property.d.ts

@@ -117,11 +117,44 @@ export declare namespace CesiumAnimatedProperty {
         IsDone(): boolean;
         GetValue(): number;
     }
+    interface IAnimateAttitude {
+        pitch: number | null;
+        roll: number | null;
+    }
     interface IAnimateSeriesPos {
         pos3d: Cesium.Cartesian3;
         dateTime: Date;
         heading: number | null;
+        pitch?: number | null;
+        roll?: number | null;
     }
+    const TRAIL_REAL_SECONDS = 20;
+    const TRAIL_MIN_MS: number;
+    const TRAIL_MAX_MS: number;
+    const TRAIL_MAX_POINTS = 500;
+    const TRAIL_MIN_POINTS = 8;
+    /**
+     * Returns how much scene time a trail should cover, for a clock moving at this rate.
+     * @param ratePerSecondMs milliseconds of scene time per real second.
+     * @param realSeconds how much watching the trail should represent.
+     */
+    function TrailSpanFor(ratePerSecondMs: number, realSeconds?: number, minMs?: number, maxMs?: number): number;
+    /**
+     * Returns the positions a movement trail should run through, for a playhead at this time.
+     * @param params
+     */
+    function TrailPositionsFrom(params: {
+        positions: IAnimateSeriesPos[];
+        nowTimeMs: number;
+        ratePerSecondMs: number;
+        currentPos?: Cesium.Cartesian3;
+    }): Cesium.Cartesian3[];
+    /**
+     * Thins a run of positions down to at most maxPoints, keeping the first and last.
+     * @param posses
+     * @param maxPoints
+     */
+    function DecimateSeries(posses: Cesium.Cartesian3[], maxPoints?: number): Cesium.Cartesian3[];
     /**
      * Animates a position from a set of provided positions in time.
      * This will return a position across the provided positions based on the current time.
@@ -165,6 +198,7 @@ export declare namespace CesiumAnimatedProperty {
          * Otherwise returns the Cesium viewer time.
          */
         private getTimeMs;
+        private ratePerSecondMs;
         SetUseRealTime(value: boolean): void;
         AddPosition(pos: IAnimateSeriesPos): void;
         UpdatePitchRoll(pitch: number, roll: number): void;
@@ -185,6 +219,11 @@ export declare namespace CesiumAnimatedProperty {
          */
         private updateRealTimePosition;
         GetSeries(): Cesium.Cartesian3[];
+        /**
+         * Returns the heading carried by the last record at or before the playhead, in degrees, or
+         * null when no record in range names one.
+         */
+        GetHeadingDegrees(): number | null;
         GetOrient(): Cesium.Quaternion;
         GetCurrentVelocity(): Cesium.Cartesian3;
         SupplementSeries(newSeries: IAnimateSeriesPos[]): void;
@@ -192,11 +231,20 @@ export declare namespace CesiumAnimatedProperty {
         HasPositionForDateTime(dateTime: Date): boolean;
         GetPositionCount(): number;
     }
+    /**
+     * Returns a position at the height its graphic is actually drawn at.
+     * Respecting the height ref means it is pointing the right way when we orient based on movement.
+     * @param viewer
+     * @param pos3d
+     * @param heightRef
+     */
+    function GetDrawnHeightPos3d(viewer: Cesium.Viewer, pos3d: Cesium.Cartesian3, heightRef: Cesium.HeightReference): Cesium.Cartesian3 | null;
     function GetSeriesPossesForHistoricEntity(viewer: Cesium.Viewer, dataHeightRef: Cesium.HeightReference, heightRef: Cesium.HeightReference, historic: EntityHistoricData.IData[]): CesiumAnimatedProperty.IAnimateSeriesPos[];
     class AnimateTPositionSeries {
         private viewer;
         private positions;
         private onUpdate;
+        private lastCalcAttitude;
         private onDone?;
         private onRangeChangeCallback?;
         private lastCalcTime;
@@ -212,7 +260,7 @@ export declare namespace CesiumAnimatedProperty {
         constructor(params: {
             viewer: Cesium.Viewer;
             posses: IAnimateSeriesPos[];
-            onUpdate: (position: Cesium.Cartesian3, heading: number | null) => void;
+            onUpdate: (position: Cesium.Cartesian3, heading: number | null, attitude?: IAnimateAttitude) => void;
             onDone?: () => void;
             onRangeChange?: () => void;
         });
@@ -229,6 +277,11 @@ export declare namespace CesiumAnimatedProperty {
             minDate: Date | null;
             maxDate: Date | null;
         };
+        /**
+         * Returns the positions a movement trail through this series should run through.
+         * The same window an Entity's own trail uses, so a root trail matches one drawn per Entity.
+         */
+        GetSeries(): Cesium.Cartesian3[];
         /**
          * Trigger the onRangeChange callback to request more data.
          */
@@ -237,6 +290,7 @@ export declare namespace CesiumAnimatedProperty {
          * Stop the animation and call the onDone callback if provided.
          */
         stop(): void;
+        private attitudeAt;
         private update;
         private interpolatePos3dOverTime;
         private easeInOutQuad;

package/dist/types/rendering/entity-render-engine.d.ts

@@ -1,5 +1,5 @@
 import * as Cesium from "cesium";
-import { Entity, BruceApi, ZoomControl, IDictionary, EntityHistoricData } from "bruce-models";
+import { Entity, BruceApi, ZoomControl, IDictionary, EntityHistoricData, EntityTag } from "bruce-models";
 import { RenderManager } from "./render-managers/render-manager";
 import { VisualsRegister } from "./visuals-register";
 import { EntityRenderEnginePoint } from "./entity-render-engine-point";
@@ -141,6 +141,38 @@ export declare namespace EntityRenderEngine {
         const Render: typeof EntityRenderEngineModel3d.Render;
         const RenderGroup: typeof EntityRenderEngineModel3d.RenderGroup;
     }
+    /**
+     * Returns what a style's altitude option means as a Cesium height reference.
+     * @param style any style section carrying an altitudeOption, eg. modelStyle or polylineStyle.
+     * @param defaultRef what to use when the style names no option.
+     */
+    function GetHeightRef(style: any, defaultRef?: Cesium.HeightReference): Cesium.HeightReference;
+    /**
+     * Folds a height reference onto what a Cesium polyline can actually express.
+     * A polyline carries a clampToGround flag and nothing else, so relative to ground has no
+     * meaning there and the configured option falls back the way the polyline engine has always
+     * read it, as an absolute height.
+     * @param heightRef what the style asked for
+     */
+    function GetHeightRefPolyline(heightRef: Cesium.HeightReference): Cesium.HeightReference;
+    /**
+     * How a movement trail should be drawn, or null when it should not be drawn at all.
+     */
+    interface ITrackStyle {
+        color: Cesium.Color;
+        width: number;
+    }
+    const TRACK_DEFAULT_WIDTH = 2;
+    const TRACK_DEFAULT_COLOR = "rgba(255, 193, 7, 0.8)";
+    /**
+     * Resolves a movement trail's colour, width and height reference from the polyline style.
+     * @param params
+     */
+    function GetTrackStyle(params: {
+        entity: Entity.IEntity;
+        style: any;
+        tags?: EntityTag.ITag[];
+    }): ITrackStyle | null;
     /**
      * @param min
      * @param max

package/dist/types/rendering/menu-item-manager.d.ts

@@ -50,6 +50,7 @@ export declare namespace MenuItemManager {
          */
         ClearSeriesSegments(itemId: string): void;
         private sharedGetters;
+        private sharedHistoric;
         private sharedMonitor;
         private tilesetInitQueue;
         get Monitor(): CesiumViewMonitor.Monitor;

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

@@ -17,6 +17,12 @@ export declare namespace HistoricFetchOrder {
      * 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 cadence for a set of this size on a clock running at this rate.
+     * @param entityCount
+     * @param multiplier the viewer clock's, ie. scene seconds per real second
+     */
+    function IntervalForClock(entityCount: number, multiplier: number): number;
     const DEFAULT_BANDS: number[];
     /**
      * Where the user is actually looking, which is not the same as where the camera is.

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

@@ -0,0 +1,115 @@
+import { Entity, IDictionary } from "bruce-models";
+/**
+ * The shared read path for Entities whose position comes from the clock.
+ */
+export declare namespace SharedHistoricGetters {
+    const DEFAULT_MIN_INTERVAL_MS = 250;
+    const DEFAULT_FRESH_MS = 200;
+    const DEFAULT_MAX_INTERVAL_MS = 3000;
+    const IDLE_DOUBLINGS = 6;
+    const FEED_MAX_INTERVAL_MS = 15000;
+    /**
+     * What one manager wants: these Entities, as at this instant.
+     */
+    interface IAsk {
+        subscriberId: string;
+        entityIds: string[];
+        at: number;
+        force?: boolean;
+    }
+    function SignatureOf(entity: Entity.IEntity): string;
+    /**
+     * Reads a set of Entities at an instant.
+     */
+    type Read = (entityIds: string[], at: number) => Promise<Entity.IEntity[]>;
+    /**
+     * One read path, shared by every manager reading the same Entities the same way.
+     */
+    class Lane {
+        private params;
+        private pending;
+        private inFlight;
+        private lastSentAt;
+        private pumpTimeout;
+        private pumpScheduled;
+        private disposed;
+        private held;
+        private heldSignatures;
+        private idleReads;
+        private heldInternalIds;
+        private feedRemoval;
+        private feedWired;
+        constructor(params: {
+            read: Read;
+            getMinIntervalMs?: () => number;
+            freshMs?: number;
+            maxIntervalMs?: number;
+            signatureOf?: (entity: Entity.IEntity) => string;
+            subscribeToChanges?: (onChanged: (rangeString: string) => void) => (() => void) | null;
+            isFeedConnected?: () => boolean;
+            now?: () => number;
+        });
+        /**
+         * Asks for these Entities at this instant, resolving with them however the lane gets there:
+         * from the held answer, from a read already about to happen, or from one this ask starts.
+         */
+        Request(ask: IAsk): Promise<Entity.IEntity[]>;
+        /**
+         * Forgets a subscriber, for a manager that has been disposed while it was waiting.
+         */
+        Drop(subscriberId: string): void;
+        /**
+         * Tells the lane that records it holds have changed, so its next read happens on the caller's
+         * cadence rather than behind whatever backoff a quiet spell had earned.
+         */
+        NotifyChanged(): void;
+        /**
+         * The same, for a feed event naming Entity internal ids as ranges.
+         * @param rangeString as reported by the record change feed.
+         */
+        NotifyChangedRange(rangeString: string): void;
+        Dispose(): void;
+        /**
+         * How many reads in a row have come back unchanged, which is what the wait is scaled by.
+         */
+        get IdleReads(): number;
+        /**
+         * The wait the lane would apply before its next read,
+         * ie. the caller's cadence after however far the idle backoff has widened it.
+         */
+        get IntervalMs(): number;
+        /**
+         * What the lane is currently holding, for a caller that wants it without asking for a read.
+         */
+        get Held(): {
+            at: number;
+            byId: IDictionary<Entity.IEntity>;
+        };
+        private intervalNow;
+        private freshAnswerFor;
+        private wireFeed;
+        private schedulePump;
+        private pump;
+    }
+    /**
+     * The lanes in play, keyed so that two managers reading the same Entities the same way land on the same one.
+     */
+    class Cache {
+        private lanes;
+        /**
+         * Returns the lane for this endpoint and attribute key, creating it on first use.
+         * @param params
+         */
+        GetOrCreateLane(params: {
+            baseUrl: string;
+            attrKey?: string;
+            read: Read;
+            getMinIntervalMs?: () => number;
+            freshMs?: number;
+            maxIntervalMs?: number;
+            subscribeToChanges?: (onChanged: (rangeString: string) => void) => (() => void) | null;
+            isFeedConnected?: () => boolean;
+        }): Lane;
+        Dispose(): void;
+    }
+}

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

@@ -3,6 +3,7 @@ import * as Cesium from "cesium";
 import { CesiumViewMonitor } from "../../../viewer/cesium-view-monitor";
 import { VisualsRegister } from "../../visuals-register";
 import { RenderManager } from "../render-manager";
+import { SharedHistoricGetters } from "../common/shared-getters-historic";
 /**
  * Render manager for rendering an array of entity ids.
  * This will render them in batches to avoid overloading the viewer.
@@ -30,12 +31,15 @@ export declare namespace EntitiesIdsRenderManager {
         private renderQueue;
         private renderQueueForceFlags;
         private reRenderState;
+        private sharedHistoric;
+        private historicLane;
         constructor(params: {
             viewer: Cesium.Viewer;
             register: VisualsRegister.Register;
             apiGetter: BruceApi.IGetter;
             monitor: CesiumViewMonitor.Monitor;
             item: MenuItem.Item.IEntityIds;
+            sharedHistoric?: SharedHistoricGetters.Cache;
         });
         Init(params?: {
             item?: MenuItem.Item.IEntityIds;
@@ -52,6 +56,7 @@ export declare namespace EntitiesIdsRenderManager {
             zoomControl?: ZoomControl.IItem[];
             queueRerender?: boolean;
         }): void;
+        private getHistoricLane;
         private onGetterUpdate;
         private renderEntities;
         /**

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

@@ -111,6 +111,11 @@ export declare namespace EntitiesRenderManager {
         private gatherHistoric;
         private doRenderAsIndividuals;
         get HandoffKey(): string | null;
+        /**
+         * Returns whether this item needs its historic records fetched.
+         * @param item
+         */
+        static NeedsHistoricRecords(item: MenuItem.Item.IEntities): boolean;
         static GetHandoffKey(item: MenuItem.Item.IEntities): string | null;
         /**
          * Everything about a menu item that changes how its entities are drawn, as a comparable string.

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

@@ -31,6 +31,13 @@ export declare namespace AssemblyRenderManager {
         private modelSpace;
         get ModelSpace(): boolean;
         private rootId;
+        private rootPos3d;
+        private rootHeading;
+        private children;
+        private trackEntity;
+        private viewerDateTimeChangeRemoval;
+        private historicGatherer;
+        private historicAnimation;
         constructor(params: {
             viewer: Cesium.Viewer;
             register: VisualsRegister.Register;
@@ -38,6 +45,39 @@ export declare namespace AssemblyRenderManager {
             item: MenuItem.Item.IAssembly;
             modelSpace?: boolean;
         });
+        /**
+         * Returns whether this Assembly's root moves over time.
+         * @param item
+         */
+        static IsHistoric(item: MenuItem.Item.IAssembly): boolean;
+        /**
+         * Returns what a record's altitude means for this item, from its style's altitude option.
+         * @param item
+         */
+        static GetRecordHeightRef(item: MenuItem.Item.IAssembly): Cesium.HeightReference;
+        private static rootFrame;
+        /**
+         * Returns where a child sits relative to its root, which is what stays true as the root moves.
+         * @param rootPos3d
+         * @param headingDegrees
+         * @param childPos3d
+         */
+        static ChildOffsetIn(rootPos3d: Cesium.Cartesian3, headingDegrees: number, childPos3d: Cesium.Cartesian3): Cesium.Cartesian3;
+        /**
+         * Returns where a child sits in the world, for a root at this position and heading.
+         * @param rootPos3d
+         * @param headingDegrees
+         * @param offset
+         */
+        static ChildPositionFrom(rootPos3d: Cesium.Cartesian3, headingDegrees: number, offset: Cesium.Cartesian3): Cesium.Cartesian3;
+        /**
+         * Moves the whole Assembly to a new root position, without refetching any of its children.
+         * @param params
+         */
+        ApplyRootPosition(params: {
+            pos3d: Cesium.Cartesian3;
+            heading?: number;
+        }): void;
         Init(): void;
         /**
          * Processes given entity IDs and renders them in the viewer.
@@ -45,6 +85,8 @@ export declare namespace AssemblyRenderManager {
          * @returns
          */
         private processEntityIds;
+        private viewerDateTimeSub;
+        private applyRootTrack;
         Dispose(): void;
         ReRender(params: {
             entityIds?: string[];

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

@@ -1,5 +1,6 @@
-import { ApiGetters, BruceEvent, Entity, MenuItem } from "bruce-models";
+import { ApiGetters, BruceEvent, Entity, EntityCoords, EntityHistoricData, MenuItem } from "bruce-models";
 import * as Cesium from "cesium";
+import { CesiumAnimatedProperty } from "../../cesium-animated-property";
 import { TilesetRenderEngine } from "../../tileset-render-engine";
 import { VisualsRegister } from '../../visuals-register';
 import { RenderManager } from "../render-manager";
@@ -48,9 +49,9 @@ export declare namespace TilesetCadRenderManager {
         private somethingIsolatedDateTime;
         private loadedCesiumEntities;
         private viewerDateTimeChangeRemoval;
-        private historicPossesInitialLoaded;
         private historicAnimation;
         private historicGatherer;
+        private trackEntity;
         private historicPossesLoadingProm;
         private featureQueue;
         private featureQueueStates;
@@ -69,6 +70,45 @@ export declare namespace TilesetCadRenderManager {
         Init(): void;
         private onCTilesetLoad;
         get HandoffKey(): string | null;
+        private accountIdForRecords;
+        private applyRootTrack;
+        /**
+         * Returns whether this item's historic heading gets the half-turn correction.
+         * See CodeLogicExceptions.ASSEMBLY_HISTORIC_HEADING_FLIP.
+         * @param accountId whose records are being rendered
+         */
+        static FlipsHistoricHeading(accountId: string): boolean;
+        /**
+         * Returns what a record's altitude means for this item, from its style's altitude option.
+         * @param item
+         */
+        static GetRecordHeightRef(item: MenuItem.Item.ICadTileset): Cesium.HeightReference;
+        /**
+         * Turns the root Entity's historic records into the positions the tileset moves along.
+         * @param params
+         */
+        static HistoricPossesFor(params: {
+            viewer: Cesium.Viewer;
+            item: MenuItem.Item.ICadTileset;
+            records: EntityHistoricData.IData[];
+        }): CesiumAnimatedProperty.IAnimateSeriesPos[];
+        /**
+         * Returns the tileset coordinates that place it at a root Entity's own recorded position.
+         * @param entity
+         */
+        static CoordsFromHistoricEntity(entity: Entity.IEntity): EntityCoords.IEntityCoords;
+        /**
+         * Returns the tileset coordinates for a root at this position and attitude.
+         * @param params
+         */
+        static CoordsFromHistoricPos3d(params: {
+            rootId: string;
+            pos3d: Cesium.Cartesian3;
+            heading: number;
+            pitch?: number;
+            roll?: number;
+            cTileset?: TilesetRenderEngine.ITilesetExt;
+        }): EntityCoords.IEntityCoords;
         static GetHandoffKey(item: MenuItem.Item.ICadTileset, modelSpace?: boolean): string | null;
         PrepareHandoff(): RenderManager.IHandoffPayload | null;
         AdoptHandoff(payload: RenderManager.IHandoffPayload): void;

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

@@ -15,6 +15,10 @@ export declare namespace DrawingUtils {
     }): {
         point: Cesium.Cartesian3;
     };
+    /**
+     * Empties the sampled terrain heights. For a terrain provider swap, or a test.
+     */
+    function ClearSampledTerrain(): void;
     /**
      * Returns terrain height from current viewer's provider.
      * On error or flat terrain, it will return 0.
@@ -30,6 +34,36 @@ export declare namespace DrawingUtils {
         height: number;
         error?: any;
     }>;
+    const TERRAIN_CELL_SIZE = 400;
+    const TERRAIN_CELL_SIZE_FINE = 50;
+    const TERRAIN_CELL_MAX_SPREAD = 25;
+    /**
+     * Returns the terrain height under a position, from the terrain as it is currently loaded.
+     *
+     * NaN when the terrain tile has not loaded yet and nothing cached covers the area, so a caller can
+     * tell "no answer" from "sea level".
+     *
+     * @param params terrainId identifies the terrain the cache is keyed against.
+     */
+    function GetTerrainOffset(params: {
+        viewer: Cesium.Viewer;
+        pos3d: Cesium.Cartesian3;
+        terrainId: string | number | null | undefined;
+    }): number;
+    /**
+     * Returns where a position is actually drawn, as an absolute height.
+     * @param params
+     */
+    function GetDrawnPos3d(params: {
+        viewer: Cesium.Viewer;
+        heightRef: Cesium.HeightReference;
+        pos3d: Cesium.Cartesian3;
+        terrainId: string | number | null | undefined;
+    }): Cesium.Cartesian3 | null;
+    /**
+     * Empties the terrain height cache. For a terrain provider swap, or a test.
+     */
+    function ClearTerrainCache(): void;
     function EnsurePosHeight(params: {
         pos3d: Cesium.Cartesian3;
         viewer: Cesium.Viewer;

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

@@ -33,6 +33,11 @@ export declare namespace ViewUtils {
     }): {
         terrain: ProjectViewTile.IBookmarkTerrain;
     };
+    /**
+     * Returns the identity a terrain height cache should be keyed against, or null for terrain with no heights to sample.
+     * @param viewer
+     */
+    function GetTerrainCacheId(viewer: Cesium.Viewer): string | number | null | undefined;
     function SetTerrainWireframeStatus(params: {
         viewer: Cesium.Viewer;
         status: boolean;

package/package.json

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