bruce-models 7.1.88 → 7.1.89

package/dist/types/client-file/value-map-reader.d.ts

@@ -0,0 +1,520 @@
+import { Geometry } from "../common/geometry";
+import { BruceApi } from "../api/bruce-api";
+import { ClientFile } from "./client-file";
+import type { ClientFileValueMap } from "./client-file-value-map";
+import { ValueMapGrid } from "./value-map-grid";
+/**
+ * Reads a generated value map: its frames, the values in them, and the shapes those values make.
+ */
+export declare namespace ValueMapReader {
+    interface IRaster {
+        Width: number;
+        Height: number;
+        Data: Uint8Array | Uint8ClampedArray;
+    }
+    /**
+     * Turns one PNG's bytes into its pixels.
+     */
+    type TDecoder = (bytes: Uint8Array) => Promise<IRaster>;
+    /**
+     * Hands back a slice of the archive blob.
+     */
+    type TByteSource = (offset: number, length: number) => Promise<Uint8Array>;
+    interface IField {
+        Width: number;
+        Height: number;
+        Values: Float64Array | null;
+        Covered: Uint8Array;
+    }
+    interface IMask {
+        Width: number;
+        Height: number;
+        Bits: Uint8Array;
+    }
+    interface IReading {
+        Longitude: number;
+        Latitude: number;
+        Frame: number;
+        Time: string | null;
+        Units: string | null;
+        Texel: ValueMapGrid.ITexel | null;
+        Covered: boolean;
+        Value: number | null;
+        SourceValue: number | null;
+    }
+    interface IDetails extends IReading {
+        Attribute: string | null;
+        Label: string | null;
+        Dataset: string | null;
+        Frames: number;
+        Transform: string | null;
+        VerticalDatum: string | null;
+        Tile: {
+            Level: number;
+            TexelMetres: number;
+            ResolutionX: number;
+            ResolutionY: number;
+            West: number;
+            East: number;
+            South: number;
+            North: number;
+        };
+        TileTexel: ValueMapGrid.ITexel | null;
+        ValueMin: number | null;
+        ValueMax: number | null;
+        Shift: number | null;
+        Baseline: boolean;
+    }
+    interface ISummary {
+        Frame: number;
+        Time: string | null;
+        Units: string | null;
+        Texels: number;
+        Covered: number;
+        Peak: number | null;
+        Mean: number | null;
+        SourcePeak: number | null;
+        SourceMean: number | null;
+    }
+    interface IAdded {
+        Frame: number;
+        Time: string | null;
+        NewTexels: number;
+        Shapes: Geometry.IGeometry[];
+        New: IMask;
+        Cumulative: IMask;
+    }
+    const MIN_TEXELS = 8;
+    const SIMPLIFY_TOLERANCE = 0.25;
+    const ONSET_FRACTION = 0.5;
+    const LEVELS = 256;
+    const MAX_COMPOSITE_TEXELS = 2048;
+    const FRAME_CACHE = 16;
+    const TILE_CACHE = 32;
+    const MAX_READ_GAP = 131072;
+    /**
+     * One generated value map, read from its Client File.
+     *
+     *     const map = await ClientFileValueMap.Open({ api, fileId });
+     *     const frame = await map.Frame(0);
+     *     for (const shape of await map.ShapesAbove({ threshold: 1.25 })) { ... }
+     *
+     * Every reading is in the archive's delivered units. Where a transform was applied, ask for the
+     * source values instead to get the customer's own numbers.
+     */
+    interface IReaderParams {
+        file: ClientFile.IFile;
+        bytes: TByteSource;
+        decoder?: TDecoder;
+        maxCompositeTexels?: number;
+        extent?: ClientFileValueMap.IExtent;
+    }
+    class Reader {
+        readonly File: ClientFile.IFile;
+        readonly Metadata: ClientFileValueMap.IMetadata;
+        readonly Tiles: ClientFileValueMap.IBinaryTile[];
+        readonly Grid: ValueMapGrid.Grid;
+        readonly Extent: ClientFileValueMap.IExtent;
+        private readonly decoder;
+        private readonly bytes;
+        private readonly frames;
+        private readonly tileLayers;
+        private readonly statistics;
+        private readonly thresholds;
+        private baseline;
+        private unchanging;
+        constructor(params: IReaderParams);
+        /**
+         * The attribute this value map was generated from.
+         */
+        get Attribute(): string | null;
+        /**
+         * What the attribute is called for a reader, where the source names it.
+         */
+        get Label(): string | null;
+        /**
+         * The dataset the values came from, since one account holds several over the same mesh.
+         */
+        get Dataset(): string | null;
+        /**
+         * The Entity Type Source this was generated from.
+         */
+        get EntityTypeSourceID(): number | null;
+        /**
+         * When the archive was written, which is what tells two generations of it apart.
+         */
+        get Generated(): string | null;
+        get Revision(): number | null;
+        /**
+         * The units a reading is in, where the source states them.
+         */
+        get Units(): string | null;
+        /**
+         * How a frame's number is packed: one channel or two.
+         */
+        get Format(): string;
+        /**
+         * The values a reading out of this value map falls between, in its own units.
+         */
+        get ValueRange(): {
+            Min: number;
+            Max: number;
+        };
+        /**
+         * The values the source's own numbers fall between, or null where nothing was transformed.
+         */
+        get SourceRange(): {
+            Min: number;
+            Max: number;
+        } | null;
+        /**
+         * What the source's own heights are measured from, when the archive says.
+         * A thickness declares none, and an untransformed elevation declares one with no transform.
+         */
+        get VerticalDatum(): string | null;
+        /**
+         * What was applied to the source's numbers to get the delivered ones, empty for nothing.
+         */
+        get Transform(): string;
+        /**
+         * Whether a reading differs from what the source's own data said.
+         */
+        get IsTransformed(): boolean;
+        /**
+         * What the source suggests a picture be ramped over, which is not a bound on the data.
+         */
+        get ColorBarRange(): {
+            Min: number;
+            Max: number;
+        } | null;
+        /**
+         * The largest movement any one texel made over the series.
+         */
+        get MovingRangeMax(): number | null;
+        /**
+         * How many timesteps the generator set out to write.
+         */
+        get RequestedFrames(): number;
+        /**
+         * How many it actually wrote.
+         */
+        get WrittenFrames(): number;
+        /**
+         * Whether the archive holds every timestep that was asked for.
+         */
+        get IsComplete(): boolean;
+        /**
+         * When each frame was sampled. Authoritative, unlike the series increment.
+         */
+        get Times(): string[];
+        /**
+         * How many frames the archive holds.
+         */
+        get Length(): number;
+        /**
+         * Says so when the archive's heights are not on the ellipsoid, or null when they are.
+         */
+        Warning(): string | null;
+        /**
+         * One layer's declaration, or undefined when the archive does not carry it.
+         */
+        Layer(name: string): ClientFileValueMap.ILayer | undefined;
+        /**
+         * One frame's values and a mask of which texels were sampled.
+         */
+        Frame(index?: number, source?: boolean): Promise<IField>;
+        /**
+         * Each texel's lowest value over the series and where that is known, or null.
+         */
+        ValueMin(): Promise<IField | null>;
+        /**
+         * Each texel's highest value over the series and where that is known, or null.
+         */
+        ValueMax(): Promise<IField | null>;
+        /**
+         * The per-texel correction applied to the source's own numbers, or null where none was.
+         *
+         * sourceValue = value - shift, which is what makes the transform reversible per texel rather
+         * than only describable in prose.
+         */
+        ValueShift(): Promise<IField | null>;
+        /**
+         * The texels flagged as permanently at their own minimum, or null when none were published.
+         *
+         * A caller measuring change subtracts these rather than reporting ground that never moved.
+         */
+        Baseline(): Promise<IMask | null>;
+        /**
+         * The texels holding one value for the whole series, or null for a single frame archive.
+         */
+        Unchanging(): Promise<IMask | null>;
+        /**
+         * Every texel a change in the series cannot be read from, or null when there are none.
+         *
+         * The published baseline and the texels measured as unchanging, since neither describes
+         * anything the series does and a caller asking what moved wants both gone.
+         */
+        Ignored(): Promise<IMask | null>;
+        /**
+         * The level the series itself separates on, for a caller who cannot name one.
+         */
+        NaturalThreshold(source?: boolean): Promise<number>;
+        /**
+         * The level to measure against, read off the series when the caller names none.
+         */
+        Resolve(threshold: number | null | undefined, source?: boolean): Promise<number>;
+        /**
+         * The texels in one frame whose value is over a threshold.
+         *
+         * Ask for source to compare against the customer's own numbers, so a level stated against
+         * their data means what they think it means.
+         */
+        MaskAbove(params?: {
+            threshold?: number;
+            frame?: number;
+            excludeBaseline?: boolean;
+            source?: boolean;
+        }): Promise<IMask>;
+        /**
+         * The texels over a threshold in every frame, or null for an archive with no frames.
+         *
+         * Measured rather than read off the first frame, so a tide that is out at the start does
+         * not get counted as ground the event flooded.
+         */
+        AlwaysAbove(params?: {
+            threshold?: number;
+            excludeBaseline?: boolean;
+            source?: boolean;
+        }): Promise<IMask | null>;
+        /**
+         * One frame's mask with anything below the noise floor already removed.
+         *
+         * Built from the components so the floor is applied once, which is what lets two frames be
+         * compared as sets that already agree on what counts.
+         */
+        CoveredMask(params?: {
+            threshold?: number;
+            frame?: number;
+            minTexels?: number;
+            excludeBaseline?: boolean;
+            source?: boolean;
+        }): Promise<IMask>;
+        /**
+         * How many texels are over the threshold in each frame.
+         *
+         * Decoding is local, so the whole series is read without a request and the frames worth
+         * querying can be found rather than guessed at.
+         */
+        Profile(params?: {
+            threshold?: number;
+            minTexels?: number;
+            excludeBaseline?: boolean;
+            source?: boolean;
+        }): Promise<number[]>;
+        /**
+         * The frames that characterise an event: it arriving, its worst, and it passing.
+         *
+         * Read off the series rather than named by the caller, since a frame number that suits one
+         * archive is quietly wrong for the next and finding the worst is usually the question.
+         */
+        FramesOfInterest(params?: {
+            threshold?: number;
+            fraction?: number;
+            excludeBaseline?: boolean;
+            source?: boolean;
+        }): Promise<number[]>;
+        /**
+         * Each area of one frame over a threshold, as a Bruce geometry ready to query with.
+         * Holes are dropped unless asked for.
+         */
+        ShapesAbove(params?: {
+            threshold?: number;
+            frame?: number;
+            minTexels?: number;
+            keepHoles?: boolean;
+            excludeBaseline?: boolean;
+            tolerance?: number;
+            source?: boolean;
+        }): Promise<Geometry.IGeometry[]>;
+        /**
+         * Each area of any mask as a Bruce geometry, for a caller who built the mask itself.
+         */
+        ShapesOf(mask: IMask, params?: {
+            minTexels?: number;
+            keepHoles?: boolean;
+            tolerance?: number;
+        }): Geometry.IGeometry[];
+        /**
+         * One area's outer ring and its holes, as positions.
+         *
+         * The longest ring is the outer one, since a hole is enclosed by what surrounds it. Pass a
+         * tolerance of 0 to keep every traced vertex.
+         */
+        RingsOf(members: ValueMapGrid.ITexel[], tolerance?: number): {
+            Outer: ValueMapGrid.IPoint[];
+            Holes: ValueMapGrid.IPoint[][];
+        };
+        /**
+         * Walks the series in order, reporting only the ground each frame adds.
+         * Most frames add nothing, so onProgress is called for every frame while only the ones that grew come back.
+         */
+        NewAreas(params?: {
+            threshold?: number;
+            minTexels?: number;
+            excludeBaseline?: boolean;
+            tolerance?: number;
+            source?: boolean;
+            onProgress?: (at: {
+                Frame: number;
+                Frames: number;
+                Time: string | null;
+                NewTexels: number;
+                Added: boolean;
+            }) => void;
+        }): Promise<IAdded[]>;
+        /**
+         * The texels an Entity covers, from where its record says it is.
+         *
+         * The raster does not move, so this holds for the whole series and a caller reading every
+         * frame works it out once.
+         *
+         * Ask for geometry to use the Entity's own outline rather than the box around it.
+         */
+        TexelsOf(entity: any, useGeometry?: boolean): ValueMapGrid.ITexel[];
+        /**
+         * Every value a frame holds over a set of texels, skipping the texels it never sampled.
+         *
+         * An unsampled texel decodes to the bottom of the archive's range, which reads as a real
+         * measurement rather than as an absence, so the coverage mask decides what is reported.
+         */
+        ReadingsAt(texels: ValueMapGrid.ITexel[], frame: IField): number[];
+        /**
+         * The highest value a frame holds over a set of texels, or null where it holds nothing.
+         *
+         * The highest rather than the middle one, because something spanning more than one texel is
+         * described by its worst part.
+         */
+        PeakAt(texels: ValueMapGrid.ITexel[], frame?: number, source?: boolean): Promise<number | null>;
+        /**
+         * The average value a frame holds over a set of texels, or null where it holds nothing.
+         * What something spanning several texels experienced overall, as against the worst part.
+         */
+        MeanAt(texels: ValueMapGrid.ITexel[], frame?: number, source?: boolean): Promise<number | null>;
+        /**
+         * How the values over a mask are spread, for a caller reporting on an area.
+         */
+        ValuesAt(mask: IMask, frame: IField): {
+            Texels: number;
+            Peak?: number;
+            Mean?: number;
+            Median?: number;
+        };
+        /**
+         * The finest tile covering a position, or null when it falls outside every one of them.
+         *
+         * Tiles overlap, and the finer one is the better answer, so the last match wins over a list
+         * that is already sorted coarse first.
+         */
+        TileAt(longitude: number, latitude: number): ClientFileValueMap.IBinaryTile | null;
+        /**
+         * One reading at one place, in both the delivered numbers and the source's own.
+         *
+         * Reads the single tile the position falls in rather than compositing the whole grid, which
+         * is what makes charting one point over a long series cheap.
+         */
+        SampleAt(longitude: number, latitude: number, frame?: number): Promise<IReading | null>;
+        /**
+         * Everything the archive knows about one place, for a caller inspecting a single point.
+         */
+        DetailsAt(longitude: number, latitude: number, frame?: number): Promise<IDetails | null>;
+        /**
+         * Every reading at one place over the whole series, in the order the times run.
+         */
+        SeriesAt(longitude: number, latitude: number): Promise<IReading[]>;
+        /**
+         * What one frame holds over an Entity, in both the delivered numbers and the source's own.
+         */
+        SampleOf(entity: any, frame?: number, useGeometry?: boolean): Promise<ISummary>;
+        /**
+         * What every frame holds over one Entity, for a caller charting a record through an event.
+         */
+        SeriesOf(entity: any, useGeometry?: boolean): Promise<ISummary[]>;
+        private identity;
+        private position;
+        private statistic;
+        private composite;
+        private paste;
+        private tileLayer;
+        private tileReading;
+        private tileFlag;
+        private tileSeries;
+        private decodeAll;
+        private packing;
+        private range;
+        private toSource;
+        private missingShift;
+    }
+    /**
+     * A value map read from a Client File.
+     */
+    interface IOpenParams {
+        api?: BruceApi.Api;
+        fileId?: string;
+        file?: ClientFile.IFile;
+        blob?: ArrayBuffer | Uint8Array;
+        bytes?: TByteSource;
+        decoder?: TDecoder;
+        maxCompositeTexels?: number;
+        extent?: ClientFileValueMap.IExtent;
+    }
+    function Open(params: IOpenParams): Promise<Reader>;
+    /**
+     * Where an archive's bytes come from: a blob already held, or ranged reads of the file's URL.
+     */
+    function SourceFor(file: ClientFile.IFile, blob?: ArrayBuffer | Uint8Array, api?: BruceApi.Api): TByteSource;
+    /**
+     * Decodes a PNG where the runtime has an image decoder of its own.
+     *
+     * A browser has one. Node does not, and rather than pull an image library into a client library
+     * that mostly does not decode anything, a caller there passes their own.
+     */
+    const DefaultDecoder: TDecoder;
+    const MIN_RING_POINTS = 4;
+    /**
+     * The disconnected areas in a mask, as 4-connected groups of texels.
+     */
+    function Components(mask: IMask, minTexels?: number): ValueMapGrid.ITexel[][];
+    /**
+     * The closed rings bounding a group of texels, in texel corner coordinates.
+     */
+    function Trace(members: ValueMapGrid.ITexel[]): {
+        X: number;
+        Y: number;
+    }[][];
+    /**
+     * A ring with its texel staircase reduced, by Ramer-Douglas-Peucker.
+     */
+    function Simplify(ring: {
+        X: number;
+        Y: number;
+    }[], tolerance: number): {
+        X: number;
+        Y: number;
+    }[];
+    /**
+     * How many texels a mask holds.
+     */
+    function Count(mask: IMask): number;
+    /**
+     * Two masks merged texel by texel.
+     */
+    function Combine(left: IMask, right: IMask, rule: (a: boolean, b: boolean) => boolean): IMask;
+    /**
+     * A polygon geometry from an outer ring and its holes, ready to query Bruce with.
+     */
+    function Polygon(outer: ValueMapGrid.IPoint[], holes: ValueMapGrid.IPoint[][]): Geometry.IGeometry;
+    /**
+     * An Entity's polygon rings, or nothing when its record carries no outline.
+     */
+    function RingsOfEntity(entity: any): ValueMapGrid.IPoint[][];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "bruce-models",
-    "version": "7.1.88",
+    "version": "7.1.89",
     "description": "",
     "keywords": [],
     "main": "dist/bruce-models.umd.js",