bruce-cesium 7.0.2 → 7.0.3

package/dist/types/internal/cesium-utils.d.ts

@@ -2,6 +2,69 @@ import { Color } from "bruce-models";
 import * as Cesium from "cesium";
 export declare function OnNextCRender(viewer: Cesium.Viewer, callback: () => void): void;
 export declare function GetCValue<T>(viewer: Cesium.Viewer, obj: Cesium.Property | any): T;
+export declare function MarkCCollectionOwned(collection: Cesium.EntityCollection): void;
+export declare function IsCCollectionOwned(collection: Cesium.EntityCollection): boolean;
+/**
+ * Runs a bulk collection mutation with every given collection's events suspended, so Cesium raises one
+ * collectionChanged per collection for the whole pass instead of one per entity.
+ *
+ * Takes a set of collections rather than assuming `viewer.entities`, because managed visuals live in their menu
+ * item's own data source: suspending the wrong collection silently does nothing.
+ * @param collections Duplicates and empty entries are ignored.
+ * @param run
+ */
+export declare function WithSuspendedCCollections<T>(collections: Iterable<Cesium.EntityCollection>, run: () => T): T;
+/**
+ * Returns the collection a graphic belongs to, falling back to the viewer's own when it has never been added.
+ * @param viewer
+ * @param entity
+ */
+export declare function GetCEntityCollection(viewer: Cesium.Viewer, entity: any): Cesium.EntityCollection;
+/**
+ * Returns whether a graphic is currently in the scene, looking in whichever collection owns it.
+ * @param viewer
+ * @param entity
+ */
+export declare function IsCEntityInScene(viewer: Cesium.Viewer, entity: any): boolean;
+/**
+ * Removes a graphic from whichever collection owns it. Returns whether it removed anything.
+ * @param viewer
+ * @param entity
+ */
+export declare function RemoveCEntityFromScene(viewer: Cesium.Viewer, entity: any): boolean;
+/**
+ * Adds a graphic back into whichever collection owns it, or the viewer's if it has no owner yet.
+ * @param viewer
+ * @param entity
+ */
+export declare function AddCEntityToScene(viewer: Cesium.Viewer, entity: any, fallbackCollection?: Cesium.EntityCollection): boolean;
+/**
+ * Returns whether toggling `show` on these graphics is safe, rather than having to add/remove them from the
+ * entity collection to hide them.
+ *
+ * Toggling show is far cheaper than re-adding the graphic to the viewer however a Cesium bug means we can't always use it.
+ * See: https://github.com/CesiumGS/cesium/issues/9370
+ * @param parts The graphic and any sibling graphics, eg. from EntityUtils.GatherEntity.
+ */
+export declare function CanToggleShowSafely(parts: any[]): boolean;
+/**
+ * Returns if two resolved Cesium property values are equal, using the value's own equals() when it has one.
+ * @param a
+ * @param b
+ */
+export declare function AreCValuesEqual(a: any, b: any): boolean;
+/**
+ * Wraps a value in a ConstantProperty and assigns it to a graphic's property, but only when the resolved
+ * value actually differs. Returns whether it assigned.
+ * @param params
+ */
+export declare function SetCPropIfChanged<T>(params: {
+    viewer: Cesium.Viewer;
+    graphic: any;
+    property: string;
+    value: T;
+    compare?: (oldValue: T, newValue: T) => boolean;
+}): boolean;
 export declare function ColorToCColor(color: Color.IColor): Cesium.Color;
 /**
  * Removes duplicate points in a row and returns a new array.

package/dist/types/internal/js-utils.d.ts

@@ -6,3 +6,13 @@
  * @returns
  */
 export declare function EnsureNumber(value: any, defaultNum?: number): number;
+/**
+ * Returns an entity's own name when it is good enough to use as-is, or null when it has to be resolved properly.
+ * @param entity
+ */
+export declare function GetUsableEntityName(entity: any): string;
+/**
+ * Returns whether a name is a real one rather than empty or a placeholder.
+ * @param name
+ */
+export declare function IsUsableEntityName(name: any): boolean;

package/dist/types/rendering/cesium-animated-in-out.d.ts

@@ -1,5 +1,10 @@
 import * as Cesium from "cesium";
 export declare namespace CesiumAnimatedInOut {
+    /**
+     * Runs any removals already queued for this viewer immediately, instead of waiting for the next render.
+     * For teardown paths that need the scene emptied synchronously.
+     */
+    function FlushPendingRemovals(viewer: Cesium.Viewer): void;
     /**
      * Animates an Entity out of the scene.
      * Removes it from the scene at the end of the animation.

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

@@ -23,12 +23,14 @@ export declare namespace EntityRenderEngineModel3d {
         maxDistance?: number;
         minDistance?: number;
         rendered?: EntityRenderEngine.ICesiumEntityExt;
+        offline?: boolean;
         fullStyle?: Style.IEntitySettings;
     }
     /**
      * Params for rendering a group of 3D model entities.
      */
     interface IGroupParams {
+        offline?: boolean;
         rendered?: Map<string, EntityRenderEngine.ICesiumEntityExt>;
         apiGetter: BruceApi.IGetter;
         menuItemId: string;

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

@@ -23,12 +23,14 @@ export declare namespace EntityRenderEnginePoint {
         maxDistance?: number;
         minDistance?: number;
         rendered?: EntityRenderEngine.ICesiumEntityExt;
+        offline?: boolean;
         fullStyle?: Style.IEntitySettings;
     }
     /**
      * Params for rendering a group of point Entities.
      */
     interface IGroupParams {
+        offline?: boolean;
         rendered?: Map<string, EntityRenderEngine.ICesiumEntityExt>;
         apiGetter: BruceApi.IGetter;
         menuItemId: string;

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

@@ -6,6 +6,7 @@ import { ISeriesSegment } from "../internal/series-segment";
 export declare namespace EntityRenderEnginePolygon {
     interface IParams {
         rendered?: EntityRenderEngine.ICesiumEntityExt;
+        offline?: boolean;
         api?: BruceApi.Api;
         style: Style.IPolygonSettings;
         entity: Entity.IEntity;
@@ -17,6 +18,7 @@ export declare namespace EntityRenderEnginePolygon {
         onSeriesDiscovered?: (segment: ISeriesSegment) => void;
     }
     interface IGroupParams {
+        offline?: boolean;
         apiGetter: BruceApi.IGetter;
         menuItemId: string;
         onSeriesDiscovered?: (segment: ISeriesSegment) => void;

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

@@ -11,6 +11,7 @@ export declare namespace EntityRenderEnginePolyline {
      */
     interface IParams {
         rendered?: EntityRenderEngine.ICesiumEntityExt;
+        offline?: boolean;
         style: Style.IPolylineSettings;
         entity: Entity.IEntity;
         tags: EntityTag.ITag[];
@@ -22,6 +23,7 @@ export declare namespace EntityRenderEnginePolyline {
      * Params for rendering a group of polyline Entities.
      */
     interface IGroupParams {
+        offline?: boolean;
         apiGetter: BruceApi.IGetter;
         menuItemId: string;
         entities: Entity.IEntity[];

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

@@ -1,5 +1,6 @@
 import * as Cesium from "cesium";
 import { Entity, BruceApi, ZoomControl, IDictionary, EntityHistoricData } from "bruce-models";
+import { RenderManager } from "./render-managers/render-manager";
 import { VisualsRegister } from "./visuals-register";
 import { EntityRenderEnginePoint } from "./entity-render-engine-point";
 import { EntityRenderEngineModel3d } from "./entity-render-engine-model3d";
@@ -36,11 +37,24 @@ export declare namespace StyleEffective {
     function MatchesFilter(effective: string | null | undefined, filter: string | null | undefined): boolean;
 }
 export declare namespace EntityRenderEngine {
+    /**
+     * Identifies the zoom band a graphic was last rendered for, covering everything in that band which
+     * changes how the entity is drawn. Used to decide whether a re-render is needed at all.
+     *
+     * Deliberately NOT the reuse key: most of a band's identity is plain graphics properties that can be
+     * patched onto the existing graphic, so see GetGraphicShapeId for that decision.
+     */
     function GetRenderGroupId(zoomItem: ZoomControl.IItem): string;
+    /**
+     * Identifies the kind of Cesium graphic a zoom item + entity resolves to, ignoring anything that is merely a property on it.
+     */
+    function GetGraphicShapeId(zoomItem: ZoomControl.IItem, entity: Entity.IEntity): string;
     interface ICesiumEntityExt extends Cesium.Entity {
         _siblingGraphics?: Cesium.Entity[];
         _parentEntity?: Cesium.Entity;
         _renderGroup?: string;
+        _graphicShape?: string;
+        _bandCheck?: RenderManager.IBandCheck;
         _noEdit?: boolean;
         _noSelect?: boolean;
         styleId?: number;
@@ -81,6 +95,7 @@ export declare namespace EntityRenderEngine {
         entitiesHistoric?: IDictionary<EntityHistoricData.IData[]>;
         entityHistoricDrawTrack?: boolean;
         force?: boolean;
+        offline?: boolean;
         optimizeGeometry?: boolean;
         optimizeMinPoints?: number;
         optimizeTolerance?: number;
@@ -131,7 +146,8 @@ export declare namespace EntityRenderEngine {
      * @param max
      * @param meterSize size of "thing" in meters, eg polyline is 0.5 meters width. If size is provided we can potentially cull it earlier.
      * @param isPolygon
+     * @param fitMeterSize overall extent of the "thing" in meters, eg a parcel's bounding-box diagonal. If provided we keep it visible far enough out to actually fit on screen.
      * @returns
      */
-    function GetDisplayCondition(min: number, max: number, meterSize?: number, isPolygon?: boolean): Cesium.DistanceDisplayCondition;
+    function GetDisplayCondition(min: number, max: number, meterSize?: number, isPolygon?: boolean, fitMeterSize?: number): Cesium.DistanceDisplayCondition;
 }

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

@@ -91,6 +91,12 @@ export declare namespace MenuItemManager {
         private isHandoffCapable;
         private computeHandoffKey;
         private tryClaimHandoffPayload;
+        /**
+         * Moves any series segments recorded for one menu item over to another, for a claimed hand-off.
+         * The adopting manager may legitimately skip re-rendering (nothing to restyle), and segments are only
+         * ever reported from inside a render, so without this the claiming item would end up with none.
+         */
+        private transferSeriesSegments;
         FlushPendingHandoffs(): void;
         GetEnabledItemIds(): string[];
         GetEnabledItem(id: string): IRenderedItem;

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

@@ -40,6 +40,12 @@ export declare namespace DataLabRenderManager {
         private attachGetter;
         private unsetGetter;
         private setEntityCheckQueue;
+        /**
+         * Narrows a camera-driven check to the entities whose zoom band could actually have changed, so a pan or
+         * zoom stops re-requesting the whole rendered set. See RenderManager.CouldBandHaveChanged.
+         * @param ids
+         */
+        private filterPossibleBandChanges;
         private preventCurrentCheckApiRefresh;
         Dispose(): void;
         private doDispose;
@@ -61,6 +67,11 @@ export declare namespace DataLabRenderManager {
         private doRenderDataLabEntities;
         get HandoffKey(): string | null;
         static GetHandoffKey(item: MenuItem.Item.IDataLab): string | null;
+        /**
+         * Everything about this menu item that changes how its entities are drawn, as a comparable string.
+         * The hand-off key is only the query id, so this is what catches a styling difference between two items sharing that query.
+         */
+        static GetRenderSignature(item: MenuItem.Item.IDataLab): string;
         PrepareHandoff(): RenderManager.IHandoffPayload | null;
         AdoptHandoff(payload: RenderManager.IHandoffPayload): void;
     }

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

@@ -80,6 +80,11 @@ export declare namespace EntitiesRenderManager {
             zoomControl?: ZoomControl.IItem[];
             queueRerender?: boolean;
         }): void;
+        /**
+         * Narrows a camera-driven check to the entities whose zoom band could actually have changed.
+         * @param ids
+         */
+        private filterPossibleBandChanges;
         private doEntityCheck;
         private distributeForRender;
         private renderEntities;
@@ -102,6 +107,13 @@ export declare namespace EntitiesRenderManager {
         private doRenderAsIndividuals;
         get HandoffKey(): string | null;
         static GetHandoffKey(item: MenuItem.Item.IEntities): string | null;
+        /**
+         * Everything about a menu item that changes how its entities are drawn, as a comparable string.
+         * Two items with the same signature produce identical graphics, so a hand-off between them needs no
+         * re-render (and so no re-fetch of entity data the hand-off just avoided requesting).
+         * A false mismatch only costs the optimization, so key ordering inside an inline Style is not normalized.
+         */
+        static GetRenderSignature(item: MenuItem.Item.IEntities): string;
         PrepareHandoff(): RenderManager.IHandoffPayload | null;
         AdoptHandoff(payload: RenderManager.IHandoffPayload): void;
     }

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

@@ -46,15 +46,48 @@ export declare namespace RenderManager {
          */
         AdoptHandoff(payload: IHandoffPayload): void;
     }
+    /**
+     * What a zoom-item resolution measured, so a later pass can tell whether the answer could have changed
+     * without redoing it. See IBandCheck on a rendered graphic.
+     */
+    interface IZoomItemResolution {
+        distance?: number;
+        cameraPos?: Cesium.Cartesian3;
+    }
     function DetermineZoomItem(params: {
         viewer: Cesium.Viewer;
         entity: Entity.IEntity;
         zoomControl: ZoomControl.IItem[];
+        out?: IZoomItemResolution;
     }): ZoomControl.IItem;
+    /**
+     * Returns whether an entity could have moved into a different zoom band since its graphic was rendered,
+     * given where the camera is now.
+     *
+     * Answers true whenever it cannot prove otherwise, so a caller may safely skip only on a false.
+     */
+    function CouldBandHaveChanged(params: {
+        viewer: Cesium.Viewer;
+        bandCheck: IBandCheck;
+    }): boolean;
+    /**
+     * What a graphic's zoom band was resolved from, recorded so a camera move can be tested against it
+     * without re-measuring the entity (which would need its geometry, ie. another fetch).
+     */
+    interface IBandCheck extends IZoomItemResolution {
+        min?: number;
+        max?: number;
+    }
     function GetZoomControlFromDistance(params: {
         zoomControl: ZoomControl.IItem[];
         distance: number;
     }): ZoomControl.IItem;
+    /**
+     * Everything in a zoom control that changes how an entity is drawn, as a comparable string.
+     * Used to tell whether two menu items would produce identical graphics (see a manager's GetRenderSignature).
+     * A false mismatch only costs an optimization, so key ordering inside an inline Style is not normalized.
+     */
+    function GetZoomControlSignature(zoomControl: ZoomControl.IItem[]): string;
     function GetZoomMinMax(params: {
         zoomControl: ZoomControl.IItem[];
     }): number[];

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

@@ -2,6 +2,7 @@ import { ApiGetters, MenuItem } from "bruce-models";
 import { RenderManager } from "../render-manager";
 import * as Cesium from "cesium";
 import { TilesetArbRenderManager } from "./tileset-arb-render-manager";
+import { VisualsRegister } from "../../visuals-register";
 export declare namespace TilesetPointcloudRenderManager {
     class Manager implements RenderManager.IManager, RenderManager.IHandoffCapableManager, RenderManager.IHandoffReceiver {
         private viewer;
@@ -12,11 +13,13 @@ export declare namespace TilesetPointcloudRenderManager {
         private cTileset;
         get Tileset(): Cesium.Cesium3DTileset;
         private initQueue;
+        private visualsManager;
         constructor(params: {
             viewer: Cesium.Viewer;
             getters: ApiGetters;
             item: MenuItem.Item.IPointcloud;
             initQueue?: TilesetArbRenderManager.IInitQueue;
+            register?: VisualsRegister.Register;
         });
         Init(): void;
         private onCTilesetLoad;

package/dist/types/rendering/texture-frame-series-animator.d.ts

@@ -71,6 +71,11 @@ export declare namespace TextureFrameSeriesAnimator {
          * lets a caller re-rendering the same entity tell whether an existing instance is already correct, without reaching into private state.
          */
         GetArchiveUrl(): string;
+        /**
+         * The property this instance presents frames through, for a caller that needs to rebuild the entity's
+         * material (eg: re-tinting for opacity/selection) without detaching the animation.
+         */
+        GetImageProperty(): Cesium.CallbackProperty;
         private onClockTick;
         private findFrameIndex;
         private swapToFrame;

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

@@ -54,7 +54,19 @@ export declare namespace TilesetRenderEngine {
         _bruceSettings?: ISettingsParams;
         _bruceDateRange?: IDateRange;
     }
+    /**
+     * Just enough of the visuals register to hand a tileset over, declared structurally so this engine does not have
+     * to import the register (which imports back into the rendering engines).
+     */
+    interface ITilesetSink {
+        AddTileset(params: {
+            tileset: Cesium.Cesium3DTileset;
+            menuItemId?: string;
+        }): void;
+    }
     interface IParams {
+        register?: ITilesetSink;
+        menuItemId?: string;
         loadUrl?: string;
         accountId: string;
         apiGetter: BruceApi.IGetter;
@@ -93,6 +105,8 @@ export declare namespace TilesetRenderEngine {
         loadUrl?: string;
         viaCdn?: boolean;
         noMemoryLimit?: boolean;
+        register?: ITilesetSink;
+        menuItemId?: string;
         backFaceCulling?: boolean;
     }): Promise<Cesium.Cesium3DTileset>;
     class Styler extends TilesetStyler {

package/dist/types/rendering/visual-register-culler.d.ts

@@ -13,6 +13,13 @@ export declare namespace VisualRegisterCuller {
     function Monitor(params: {
         register: VisualsRegister.Register;
     }): (params: IMonitorDispose) => void;
+    /**
+     * Runs the tileset visibility pass immediately, rather than waiting for the next cull cycle.
+     * Exposed so the behaviour is directly assertable, and for a caller that needs it applied now.
+     * @param register
+     */
+    function CullTilesets(register: VisualsRegister.Register): void;
+    function IsCullingIgnored(viewer: Cesium.Viewer, rego: VisualsRegister.IVisualRego): boolean;
     function IsCulled(viewer: Cesium.Viewer, rego: VisualsRegister.IVisualRego, visual: VisualsRegister.Visual): any;
     function MarkShouldRecheck(viewer: Cesium.Viewer): void;
 }

package/dist/types/rendering/visuals-register.d.ts

@@ -1,10 +1,20 @@
 import { ApiGetters, BruceEvent, Cartes, Entity, EntityRelation, IDictionary, MenuItem, ProjectViewBookmark } from "bruce-models";
 import * as Cesium from "cesium";
+import { IShowGate } from "../internal/cesium-show-gate";
 /**
  * Manages a registry of all Bruce visuals being rendered by menu items.
  */
 export declare namespace VisualsRegister {
     type Visual = Cesium.Entity | Cesium.Primitive | Cesium.Cesium3DTileFeature;
+    /**
+     * A Cesium tileset the register knows about, tracked separately from regos.
+     */
+    interface ITilesetRego {
+        tileset: Cesium.Cesium3DTileset;
+        menuItemId?: string;
+        gate?: IShowGate;
+        culled?: boolean;
+    }
     interface IVisualRego {
         canEdit: boolean;
         entityId: string;
@@ -101,6 +111,33 @@ export declare namespace VisualsRegister {
             viewer: Cesium.Viewer;
             apiGetters?: ApiGetters;
         });
+        private menuItemSources;
+        private sourceOrderDirty;
+        /**
+         * Returns the collection a menu item's visuals belong in, creating its data source on first use.
+         * Returns null when there is nothing to key off, leaving the caller on the viewer's own collection.
+         * @param menuItemId
+         */
+        private ensureMenuItemCollection;
+        /**
+         * Notes the highest zIndex seen for a menu item, since that is what its data source has to sort by.
+         * zIndex orders geometry within a data source but not between them, so a whole layer stacks by the
+         * highest value anything in it asked for.
+         * @param menuItemId
+         * @param visual
+         */
+        private trackSourceZIndex;
+        /**
+         * Re-stacks the menu item data sources so a higher zIndex sits above a lower one.
+         */
+        private applySourceOrder;
+        /**
+         * Drops a menu item's data source once nothing is registered under it any more.
+         * @param menuItemId
+         */
+        private releaseMenuItemCollection;
+        /** Every collection a bulk pass over this register's visuals could mutate. */
+        private allSceneCollections;
         private indexMenuItemEntity;
         private unindexMenuItemEntityIfAbsent;
         private markLazyExclusion;
@@ -412,9 +449,36 @@ export declare namespace VisualsRegister {
         }): {
             regos: IVisualRego[];
         };
+        private tilesets;
+        /**
+         * Registers a tileset so the register can decide when it is worth drawing.
+         * @param params
+         */
+        AddTileset(params: {
+            tileset: Cesium.Cesium3DTileset;
+            menuItemId?: string;
+        }): void;
+        /**
+         * Stops tracking a tileset and hands its show flag back to its owner.
+         * @param tileset
+         */
+        RemoveTileset(tileset: Cesium.Cesium3DTileset): void;
+        /**
+         * Stops tracking every tileset belonging to a menu item.
+         * @param menuItemId
+         */
+        RemoveTilesetsByMenuItem(menuItemId: string): void;
+        /**
+         * Every tileset currently tracked.
+         */
+        GetTilesets(): ITilesetRego[];
         /**
-         * Returns all registered entity ids.
+         * Suppresses or restores a tileset.
+         * Returns whether its effective visibility changed, so a caller can skip requesting a render when nothing did.
+         * @param tileset
+         * @param culled
          */
+        SetTilesetCulled(tileset: Cesium.Cesium3DTileset, culled: boolean): boolean;
         GetEntityIds(): string[];
         /**
          * Marks regos corresponding to given entity ids as stale.

package/dist/types/utils/cesium-entity-styler.d.ts

@@ -30,6 +30,7 @@ export declare namespace CesiumEntityStyler {
         entity: VisualsRegister.Visual;
         color: Cesium.Color;
         override?: boolean;
+        includeSiblings?: boolean;
         requestRender?: boolean;
     }): void;
     function SetDefaultTextureImage(params: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bruce-cesium",
-  "version": "7.0.2",
+  "version": "7.0.3",
   "description": "",
   "keywords": [],
   "main": "dist/bruce-cesium.umd.js",