bruce-cesium 7.2.2 → 7.2.3

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

@@ -23,34 +23,19 @@ export declare namespace TextureFrameSeriesAnimator {
         ResolutionX?: number;
         ResolutionY?: number;
         PixelPlacement?: string;
-        BaselineFaces?: number;
-        BaselineMask?: {
-            ByteOffset: number;
-            ByteLength: number;
-        };
-        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;
+        Format?: string;
+        Encoding?: string;
+        Units?: string;
+        SourceVerticalDatum?: string;
+        Transform?: string;
+        SourceUnits?: string;
+        SourceValueMin?: number;
+        SourceValueMax?: number;
     }
-    const QUANTITY_THICKNESS = "thickness";
-    const QUANTITY_ELEVATION = "elevation";
     /**
      * One tile of an adaptive pyramid.
      *
@@ -68,10 +53,7 @@ export declare namespace TextureFrameSeriesAnimator {
         TexelMetres: number;
         ResolutionX: number;
         ResolutionY: number;
-        Frames: {
-            ByteOffset: number;
-            ByteLength: number;
-        }[];
+        Frames: IFrameEntry[];
         Floor?: {
             ByteOffset: number;
             ByteLength: number;
@@ -86,53 +68,179 @@ export declare namespace TextureFrameSeriesAnimator {
         };
     }
     const LAYOUT_TILES = "tiles";
+    const SUPPORTED_VERSION = 3;
     /**
-     * The generator that produced an archive, for telling a stale one from a current one.
+     * 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.
      *
-     * 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.
+     * 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 GeneratorVersion(metadata: IFrameArchiveMetadata | undefined): number;
+    function IsPackedValue(metadata: IFrameArchiveMetadata | undefined): boolean;
     /**
-     * Whether an archive is an adaptive pyramid rather than one raster.
+     * 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 IsTiledLayout(metadata: IFrameArchiveMetadata | undefined): boolean;
-    const MEASURE_ABSOLUTE = "absolute";
-    const MEASURE_ANOMALY = "anomaly";
+    function NormalisedAt(metadata: IFrameArchiveMetadata | undefined, pixels: Uint8ClampedArray, at: number): number;
+    const DATUM_ELLIPSOIDAL = "WGS84";
     /**
-     * Turns a value in the attribute's own units into the 0 to 1 position the ramp is indexed by.
+     * Whether the values are heights against a vertical datum rather than a thickness.
      *
-     * 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.
+     * 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
-     * @param value in the attribute's units
      */
-    function NormalisePosition(metadata: IFrameArchiveMetadata | undefined, value: number): number;
+    function IsDatumHeight(metadata: IFrameArchiveMetadata | undefined): boolean;
     /**
-     * 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.
+     * The archive's tiles, which Adapt() guarantees are present.
      * @param metadata the archive's Data.generation
      */
-    function IsAnomalyMeasure(metadata: IFrameArchiveMetadata | undefined): boolean;
+    function TilesOf(metadata: IFrameArchiveMetadata | undefined): ITileEntry[];
     /**
-     * How much the value moves anywhere in the series, in source units.
+     * Turns a value in the attribute's own units into the 0 to 1 position the ramp is indexed by.
      *
-     * 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.
+     * 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 MovingRange(metadata: IFrameArchiveMetadata | undefined): number | undefined;
+    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.
@@ -172,10 +280,6 @@ export declare namespace TextureFrameSeriesAnimator {
         driveMaterial?: boolean;
         produceValueCanvas?: boolean;
         drapeExtent?: IExtent;
-        baselineMask?: {
-            ByteOffset: number;
-            ByteLength: number;
-        };
         maskBaseline?: boolean;
     }
     class Animator {
@@ -219,8 +323,7 @@ export declare namespace TextureFrameSeriesAnimator {
         private readonly produceValueCanvas;
         private readonly metadata?;
         private readonly drapeExtent?;
-        private readonly tiles?;
-        private scratch;
+        private readonly tiles;
         private readonly valueCanvas;
         private valueDims;
         private presentVersion;
@@ -269,16 +372,12 @@ 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 composeTiles;
         private compositeExtent;
         private compositeSize;
         protected tint(imageData: ImageData): {
@@ -288,7 +387,6 @@ export declare namespace TextureFrameSeriesAnimator {
             valuePixels?: Uint8ClampedArray;
         };
         private writeInto;
-        private sourceRect;
         /**
          * The archive's per-cell floor and ceiling rasters, once EnsureExtremes has resolved.
          */
@@ -304,9 +402,6 @@ export declare namespace TextureFrameSeriesAnimator {
         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

@@ -65,6 +65,27 @@ export declare namespace TextureValueLabels {
         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
@@ -84,6 +105,7 @@ export declare namespace TextureValueLabels {
         private readonly settings;
         private extent;
         private metadata?;
+        private sourceMap;
         private tiles?;
         private clipRing?;
         private source;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bruce-cesium",
-  "version": "7.2.2",
+  "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.78",
+    "bruce-models": "^7.1.80",
     "tslib": "^2.4.1"
   }
 }