bruce-cesium 7.2.1 → 7.2.3

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 {
     /**
@@ -23,35 +23,263 @@ export declare namespace TextureFrameSeriesAnimator {
         ResolutionX?: number;
         ResolutionY?: number;
         PixelPlacement?: string;
-        BaselineFaces?: number;
+        ExtremesValueMin?: number;
+        ExtremesValueMax?: number;
+        Times?: string[];
+        Tiles?: ITileEntry[];
+        Format?: string;
+        Encoding?: string;
+        Units?: string;
+        SourceVerticalDatum?: string;
+        Transform?: string;
+        SourceUnits?: string;
+        SourceValueMin?: number;
+        SourceValueMax?: number;
+    }
+    /**
+     * 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: IFrameEntry[];
+        Floor?: {
+            ByteOffset: number;
+            ByteLength: number;
+        };
+        Ceiling?: {
+            ByteOffset: number;
+            ByteLength: number;
+        };
         BaselineMask?: {
             ByteOffset: number;
             ByteLength: number;
         };
-        BaselineValueMin?: number;
-        BaselineValueMax?: number;
     }
+    const LAYOUT_TILES = "tiles";
+    const SUPPORTED_VERSION = 3;
+    /**
+     * A value map as the generator publishes it: what the numbers are, how they are packed, where
+     * they are, and which per-texel layers exist.
+     */
+    interface IValueMapMetadata {
+        Version?: number;
+        Identity?: {
+            BruceSourceID?: number;
+            EntityTypeSourceID?: number;
+            EntityTypeID?: string;
+            Attribute?: string;
+            Label?: string;
+            Dataset?: string;
+            Generated?: string;
+            Revision?: number;
+        };
+        Series?: {
+            Start?: string;
+            End?: string;
+            Increment?: string;
+            Requested?: number;
+            Written?: number;
+            Complete?: boolean;
+            Times?: string[];
+        };
+        Value?: {
+            Units?: string;
+            Encoding?: string;
+            Format?: string;
+            Min?: number;
+            Max?: number;
+        };
+        ValueSource?: {
+            Units?: string;
+            Min?: number;
+            Max?: number;
+            VerticalDatum?: string;
+            Transform?: string;
+        };
+        Layers?: {
+            Name: string;
+            Format?: string;
+            PerTime?: boolean;
+            Min?: number;
+            Max?: number;
+        }[];
+        Geometry?: {
+            CRS?: string;
+            SourceCRS?: string;
+            West?: number;
+            East?: number;
+            South?: number;
+            North?: number;
+            PixelPlacement?: string;
+            ExtentCovers?: string;
+            Layout?: string;
+            TileTexels?: number;
+            ResolutionX?: number;
+            ResolutionY?: number;
+        };
+        Stats?: {
+            MovingRangeMax?: number;
+            BaselineCells?: number;
+            Baseline?: {
+                Min?: number;
+                Max?: number;
+            };
+        };
+        Hints?: {
+            ColorBarMin?: number;
+            ColorBarMax?: number;
+        };
+        Tiles?: IValueMapTile[];
+    }
+    interface IValueMapTile {
+        Level: number;
+        X: number;
+        Y: number;
+        West: number;
+        East: number;
+        South: number;
+        North: number;
+        TexelMetres: number;
+        ResolutionX: number;
+        ResolutionY: number;
+        Layers?: {
+            [name: string]: {
+                Bytes: IByteRange;
+            } | {
+                Bytes: IByteRange;
+            }[];
+        };
+    }
+    interface IByteRange {
+        Offset: number;
+        Length: number;
+    }
+    const FORMAT_U8 = "u8";
+    const FORMAT_RG16 = "rg16";
+    const ENCODING_ABSOLUTE = "absolute";
+    const LAYER_VALUE = "Value";
+    const LAYER_VALUE_MIN = "ValueMin";
+    const LAYER_VALUE_MAX = "ValueMax";
+    const LAYER_BASELINE = "Baseline";
+    const LAYER_VALUE_SHIFT = "ValueShift";
+    /**
+     * Turns a published value map into the flat shape this renderer works in, or null when it cannot be drawn.
+     * @param published the archive's Data.generation
+     */
+    function Adapt(published: IValueMapMetadata | undefined): IFrameArchiveMetadata | null;
+    /**
+     * How to turn a delivered value into the number the source published, or null when the archive
+     * does not say enough to do it.
+     * @param metadata the archive's Data.generation
+     */
+    function SourceMap(metadata: IFrameArchiveMetadata | undefined): {
+        scale: number;
+        offset: number;
+    } | null;
+    /**
+     * A delivered value in the source's own terms, or unchanged when it cannot be turned back.
+     * @param map from SourceMap(), null when the archive does not say enough
+     */
+    function ToSource(map: {
+        scale: number;
+        offset: number;
+    } | null, value: number): number;
+    /**
+     * Whether the archive's frames carry a 16 bit value packed across R and G.
+     *
+     * Every consumer that reads a texel has to ask: taking R alone from a packed frame yields a
+     * plausible surface quantised to 255 steps of the full range rather than an obvious failure.
+     * @param metadata the archive's Data.generation
+     */
+    function IsPackedValue(metadata: IFrameArchiveMetadata | undefined): boolean;
+    /**
+     * The normalised 0 to 1 value at a texel, from whichever format the archive packed it in.
+     * @param metadata the archive's Data.generation
+     * @param pixels untinted RGBA value pixels
+     * @param at index of the texel's red channel
+     */
+    function NormalisedAt(metadata: IFrameArchiveMetadata | undefined, pixels: Uint8ClampedArray, at: number): number;
+    const DATUM_ELLIPSOIDAL = "WGS84";
+    /**
+     * Whether the values are heights against a vertical datum rather than a thickness.
+     *
+     * A thickness rises from wherever the polygon sits and a height already knows where it belongs, so
+     * this is what decides whether the polygon's own altitude may be added underneath it.
+     * @param metadata the archive's Data.generation
+     */
+    function IsDatumHeight(metadata: IFrameArchiveMetadata | undefined): boolean;
+    /**
+     * The archive's tiles, which Adapt() guarantees are present.
+     * @param metadata the archive's Data.generation
+     */
+    function TilesOf(metadata: IFrameArchiveMetadata | undefined): ITileEntry[];
+    /**
+     * 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;
     /**
      * 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.
-     * @param data ClientFile.Data (the `IFile.Data` field), as returned by ClientFile.Get().
+     * @param data ClientFile.Data
      */
     function IsFrameArchiveMetadata(data: any): data is {
-        generation: IFrameArchiveMetadata;
+        generation: IValueMapMetadata;
     };
+    /**
+     * 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;
-        baselineMask?: {
-            ByteOffset: number;
-            ByteLength: number;
-        };
+        drapeExtent?: IExtent;
         maskBaseline?: boolean;
     }
     class Animator {
@@ -88,11 +316,20 @@ 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 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 +337,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 +348,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.
@@ -127,15 +372,36 @@ export declare namespace TextureFrameSeriesAnimator {
         private nearestUncachedFrame;
         private pumpFetchQueue;
         private fetchAndTint;
-        /**
-         * Decodes one frame's raw PNG bytes (as returned by a Range GET) and applies the grayscale color mask.
-         */
-        protected decodeAndTint(buffer: ArrayBuffer): Promise<{
+        protected composeTiles(tiles: ITileEntry[], idx: number, buffer: ArrayBuffer, spanStart: number): Promise<{
             pixels: Uint8ClampedArray;
             width: number;
             height: number;
             valuePixels?: Uint8ClampedArray;
         }>;
+        private compositeExtent;
+        private compositeSize;
+        protected tint(imageData: ImageData): {
+            pixels: Uint8ClampedArray;
+            width: number;
+            height: number;
+            valuePixels?: Uint8ClampedArray;
+        };
+        private writeInto;
+        /**
+         * 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;
         /**
          * Fetches and decodes the archive's static baseline mask, at most once.
          */

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

@@ -0,0 +1,161 @@
+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;
+    /**
+     * One cell's numbers as a label should print them, or null where the texture has no data there.
+     * @param params at is the index of the cell's red channel. sourceMap is derived from the metadata
+     * when omitted, which a caller reading many cells should hoist rather than repeat.
+     */
+    function ReadingAt(params: {
+        metadata?: TextureFrameSeriesAnimator.IFrameArchiveMetadata;
+        source: ImageData;
+        floor?: ImageData | null;
+        ceiling?: ImageData | null;
+        at: number;
+        sourceMap?: {
+            scale: number;
+            offset: number;
+        } | null;
+    }): IReading | null;
+    /**
+     * The unit a label's value line should name, or undefined when the archive states none.
+     * @param metadata the archive's Data.generation
+     */
+    function LabelUnits(metadata?: TextureFrameSeriesAnimator.IFrameArchiveMetadata): string | undefined;
+    /**
+     * 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 sourceMap;
+        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.3",
   "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.80",
     "tslib": "^2.4.1"
   }
 }