bruce-cesium 7.2.1 → 7.2.2

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

@@ -1,4 +1,4 @@
-import { Style } from "bruce-models";
+import { Calculator, Style } from "bruce-models";
 import * as Cesium from "cesium";
 export declare namespace TextureFrameSeriesAnimator {
     /**
@@ -30,7 +30,102 @@ export declare namespace TextureFrameSeriesAnimator {
         };
         BaselineValueMin?: number;
         BaselineValueMax?: number;
+        Measure?: string;
+        AnomalyMax?: number;
+        Floor?: {
+            ByteOffset: number;
+            ByteLength: number;
+        };
+        Ceiling?: {
+            ByteOffset: number;
+            ByteLength: number;
+        };
+        ExtremesValueMin?: number;
+        ExtremesValueMax?: number;
+        Layout?: string;
+        TileTexels?: number;
+        Times?: string[];
+        Tiles?: ITileEntry[];
+        GeneratorVersion?: number;
+        Quantity?: string;
     }
+    const QUANTITY_THICKNESS = "thickness";
+    const QUANTITY_ELEVATION = "elevation";
+    /**
+     * One tile of an adaptive pyramid.
+     *
+     * TexelMetres is the ground size of one of its texels, which is what lets a viewer see where the
+     * model actually has detail rather than presenting one resolution as if it were uniform.
+     */
+    interface ITileEntry {
+        Level: number;
+        X: number;
+        Y: number;
+        West: number;
+        East: number;
+        South: number;
+        North: number;
+        TexelMetres: number;
+        ResolutionX: number;
+        ResolutionY: number;
+        Frames: {
+            ByteOffset: number;
+            ByteLength: number;
+        }[];
+        Floor?: {
+            ByteOffset: number;
+            ByteLength: number;
+        };
+        Ceiling?: {
+            ByteOffset: number;
+            ByteLength: number;
+        };
+        BaselineMask?: {
+            ByteOffset: number;
+            ByteLength: number;
+        };
+    }
+    const LAYOUT_TILES = "tiles";
+    /**
+     * The generator that produced an archive, for telling a stale one from a current one.
+     *
+     * Read the version rather than sniffing for fields: an archive can legitimately omit Tiles or
+     * GeoidSeparation and still be current, so their absence says nothing about its age.
+     * @param metadata the archive's Data.generation
+     */
+    function GeneratorVersion(metadata: IFrameArchiveMetadata | undefined): number;
+    /**
+     * Whether an archive is an adaptive pyramid rather than one raster.
+     * @param metadata the archive's Data.generation
+     */
+    function IsTiledLayout(metadata: IFrameArchiveMetadata | undefined): boolean;
+    const MEASURE_ABSOLUTE = "absolute";
+    const MEASURE_ANOMALY = "anomaly";
+    /**
+     * Turns a value in the attribute's own units into the 0 to 1 position the ramp is indexed by.
+     *
+     * Stops are authored in real units, since "hide anything under 0.1 m" is the sentence a user
+     * actually has, and the archive's own published range is what makes that expressible.
+     * @param metadata the archive's Data.generation
+     * @param value in the attribute's units
+     */
+    function NormalisePosition(metadata: IFrameArchiveMetadata | undefined, value: number): number;
+    /**
+     * Whether the frames are a departure from each cell's own normal rather than a raw reading.
+     *
+     * Worth asking before labelling anything: the two measures need different words for the same
+     * number, and calling an anomaly "water depth" is a worse error than the coarse ramp it replaced.
+     * @param metadata the archive's Data.generation
+     */
+    function IsAnomalyMeasure(metadata: IFrameArchiveMetadata | undefined): boolean;
+    /**
+     * How much the value moves anywhere in the series, in source units.
+     *
+     * Falls back to the published range, which is the right answer for an anomaly archive (its range
+     * IS the movement) and the only available one for an archive predating AnomalyMax.
+     * @param metadata the archive's Data.generation
+     */
+    function MovingRange(metadata: IFrameArchiveMetadata | undefined): number | undefined;
     /**
      * Detects whether a ClientFile's `Data.generation` metadata describes a frame archive rather than a single static image,
      * so a caller can decide whether to construct an Animator or fall back to the existing static-texture path.
@@ -39,15 +134,44 @@ export declare namespace TextureFrameSeriesAnimator {
     function IsFrameArchiveMetadata(data: any): data is {
         generation: IFrameArchiveMetadata;
     };
+    /**
+     * Structural copies of the style shapes this consumes.
+     */
+    interface IExtent {
+        West: number;
+        East: number;
+        South: number;
+        North: number;
+    }
+    interface ICellBorder {
+        color: Calculator.IField[];
+        width: Calculator.IField[];
+    }
+    interface IRampPoint {
+        position: number;
+        color: string;
+    }
+    function AppearanceSignature(options: {
+        valueCanvas?: boolean;
+        drape?: IExtent;
+        textureColorMask?: Style.ITextureColorMask;
+        cellBorder?: ICellBorder;
+        cellTexels?: number;
+        maskBaseline?: boolean;
+    }): string;
     interface IOptions {
         viewer: Cesium.Viewer;
         entity: Cesium.Entity;
         archiveUrl: string;
         frames: IFrameEntry[];
         textureColorMask?: Style.ITextureColorMask;
+        cellBorder?: ICellBorder;
+        cellTexels?: number;
+        metadata?: IFrameArchiveMetadata;
         crossfadeMs?: number;
         driveMaterial?: boolean;
         produceValueCanvas?: boolean;
+        drapeExtent?: IExtent;
         baselineMask?: {
             ByteOffset: number;
             ByteLength: number;
@@ -88,11 +212,21 @@ export declare namespace TextureFrameSeriesAnimator {
         private readonly pool;
         private poolIdx;
         private readonly imageProperty;
+        private readonly appearance;
+        private readonly rampStops;
+        private readonly cellBorder;
         private readonly driveMaterial;
         private readonly produceValueCanvas;
+        private readonly metadata?;
+        private readonly drapeExtent?;
+        private readonly tiles?;
+        private scratch;
         private readonly valueCanvas;
         private valueDims;
         private presentVersion;
+        private extremesLoad;
+        private floorPixels;
+        private ceilingPixels;
         constructor(options: IOptions);
         /**
          * Explicit teardown: stops driving the entity's material, abandons any in-flight/pending fetch (results are simply ignored when they land),
@@ -100,6 +234,7 @@ export declare namespace TextureFrameSeriesAnimator {
          */
         Dispose(): void;
         IsDisposed(): boolean;
+        GetAppearanceSignature(): string;
         /**
          * The archive URL this instance was constructed with,
          * lets a caller re-rendering the same entity tell whether an existing instance is already correct, without reaching into private state.
@@ -110,6 +245,13 @@ export declare namespace TextureFrameSeriesAnimator {
          * material (eg: re-tinting for opacity/selection) without detaching the animation.
          */
         GetImageProperty(): Cesium.CallbackProperty;
+        /**
+         * The presented frame's TINTED pixels, where alpha is what the ramp actually painted.
+         *
+         * Distinct from the value canvas, whose alpha only says a texel has data. A cell can hold a
+         * reading and still be painted nothing, which is exactly what a hidden floor band does.
+         */
+        GetDisplayedPixels(): Uint8ClampedArray | null;
         /**
          * The untinted canvas carrying the presented frame's value in RGB and its coverage in alpha,
          * or null unless the instance was constructed with produceValueCanvas.
@@ -136,6 +278,35 @@ export declare namespace TextureFrameSeriesAnimator {
             height: number;
             valuePixels?: Uint8ClampedArray;
         }>;
+        private composeTiles;
+        private compositeExtent;
+        private compositeSize;
+        protected tint(imageData: ImageData): {
+            pixels: Uint8ClampedArray;
+            width: number;
+            height: number;
+            valuePixels?: Uint8ClampedArray;
+        };
+        private writeInto;
+        private sourceRect;
+        /**
+         * The archive's per-cell floor and ceiling rasters, once EnsureExtremes has resolved.
+         */
+        GetExtremes(): {
+            floor: ImageData | null;
+            ceiling: ImageData | null;
+        };
+        /**
+         * Fetches and decodes the floor and ceiling rasters, at most once.
+         */
+        EnsureExtremes(): Promise<void>;
+        private loadTiledBaselineMask;
+        private loadTiledExtremes;
+        private tileRect;
+        private decodeSlices;
+        private loadImageAt;
+        private remap;
+        private loadImageDataAt;
         /**
          * Fetches and decodes the archive's static baseline mask, at most once.
          */

package/dist/types/rendering/texture-value-labels.d.ts

@@ -0,0 +1,139 @@
+import * as Cesium from "cesium";
+import { TextureFrameSeriesAnimator } from "./texture-frame-series-animator";
+/**
+ * Prints a value texture's own numbers over the cells they belong to.
+ */
+export declare namespace TextureValueLabels {
+    /**
+     * A structural copy of the style shape, for the same reason the animator keeps one: a host app
+     * may be on an older published bruce-models than the one that introduced it.
+     */
+    interface ISettings {
+        minCellPixels?: number;
+        minSpacingPixels?: number;
+        maxLabels?: number;
+        decimals?: number;
+        parts?: ("value" | "floor" | "ceiling")[];
+        gridColor?: string;
+        gridWidthPixels?: number;
+        minGridCellPixels?: number;
+    }
+    /**
+     * One tile's footprint and cell count, for drawing a grid at the tile's own resolution.
+     */
+    interface ITileGrid {
+        West: number;
+        East: number;
+        South: number;
+        North: number;
+        ResolutionX: number;
+        ResolutionY: number;
+    }
+    interface IExtent {
+        West: number;
+        East: number;
+        South: number;
+        North: number;
+    }
+    interface IOptions {
+        viewer: Cesium.Viewer;
+        extent: IExtent;
+        settings?: ISettings;
+        metadata?: TextureFrameSeriesAnimator.IFrameArchiveMetadata;
+        tiles?: ITileGrid[];
+        clipRing?: {
+            lon: number;
+            lat: number;
+        }[];
+    }
+    /**
+     * One cell's numbers, in the attribute's own units.
+     */
+    interface IReading {
+        value: number;
+        floor?: number;
+        ceiling?: number;
+    }
+    /**
+     * A clip outline from a projected ring, or null when the ring cannot be drawn.
+     * @param projected one entry per ring vertex, null where the vertex has no window coordinate
+     */
+    function ClipOutline(projected: ({
+        x: number;
+        y: number;
+    } | null)[]): {
+        x: number;
+        y: number;
+    }[] | null;
+    /**
+     * How many cells apart labels should sit, as a power of two.
+     * @param options cellPixels is one cell's size on screen, held is the stride already in use
+     */
+    function ChooseLabelStride(options: {
+        cellPixels: number;
+        visibleCols: number;
+        visibleRows: number;
+        maxLabels: number;
+        minSpacingPixels: number;
+        held?: number;
+    }): number;
+    class Labels {
+        private readonly viewer;
+        private readonly canvas;
+        private readonly ctx;
+        private readonly settings;
+        private extent;
+        private metadata?;
+        private tiles?;
+        private clipRing?;
+        private source;
+        private painted;
+        private floor;
+        private ceiling;
+        private disposed;
+        private drawn;
+        private stride;
+        constructor(options: IOptions);
+        SetExtent(extent: IExtent): void;
+        /**
+         * The current frame's decoded values, as the animator's value canvas already provides them.
+         * @param source value pixels, one texel per cell
+         */
+        SetSource(source: ImageData | null): void;
+        /**
+         * The tinted pixels of the same frame, so the grid can skip cells the ramp painted nothing in.
+         * @param painted RGBA of the presented frame, or null to fall back to coverage alone
+         */
+        SetPainted(painted: Uint8ClampedArray | null): void;
+        /**
+         * The archive's per-cell extremes, when it publishes them. Without these a label can still
+         * print the current reading, just not the range behind it.
+         */
+        SetExtremes(floor: ImageData | null, ceiling: ImageData | null): void;
+        GetDrawnCount(): number;
+        Clear(): void;
+        Dispose(): void;
+        /**
+         * Redraws every visible label. Cheap enough to call per rendered frame, because the cell
+         * count it considers is bounded by the view rather than by the texture.
+         */
+        Render(): void;
+        private drawGrid;
+        private applyRingClip;
+        private tileCellOutline;
+        private drawTileGrid;
+        private groundAtScreenCentre;
+        private coveredAt;
+        private isCovered;
+        private widestLabel;
+        private cellOutline;
+        private drawLabel;
+        private readNear;
+        private paintedAt;
+        private readAt;
+        private lonAt;
+        private latAt;
+        private visibleTexels;
+        private project;
+    }
+}

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

@@ -438,6 +438,7 @@ export declare namespace VisualsRegister {
             requestRender?: boolean;
             source?: EUpdateSource;
             lazy?: boolean;
+            keepVisual?: Visual;
             onComplete?: () => void;
         }): void;
         /**

package/package.json

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