bruce-models 7.1.87 → 7.1.89

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

@@ -0,0 +1,176 @@
+import type { ClientFileValueMap } from "./client-file-value-map";
+/**
+ * Reading what a published value map declares, without decoding a single pixel.
+ */
+export declare namespace ValueMapMetadata {
+    type IMetadata = ClientFileValueMap.IMetadata;
+    type ILayer = ClientFileValueMap.ILayer;
+    type IBinaryTile = ClientFileValueMap.IBinaryTile;
+    type IBinaryRange = ClientFileValueMap.IBinaryRange;
+    type IExtent = ClientFileValueMap.IExtent;
+    export const SUPPORTED_VERSION = 3;
+    export const LAYOUT_TILES = "tiles";
+    export const LAYOUT_SINGLE = "single";
+    export const FORMAT_U8 = "u8";
+    export const FORMAT_RG16 = "rg16";
+    export const FORMAT_MASK = "mask";
+    export const ENCODING_ABSOLUTE = "absolute";
+    export const LAYER_VALUE = "Value";
+    export const LAYER_VALUE_MIN = "ValueMin";
+    export const LAYER_VALUE_MAX = "ValueMax";
+    export const LAYER_BASELINE = "Baseline";
+    export const LAYER_VALUE_SHIFT = "ValueShift";
+    export const NO_DATA = 0;
+    export const DATUM_ELLIPSOIDAL = "WGS84";
+    export const DATUMS_ELLIPSOIDAL: string[];
+    /**
+     * The published block on a Client File record, or undefined when it carries none.
+     */
+    export function Of(file: any): IMetadata | undefined;
+    /**
+     * Whether a record is a value map this library can read.
+     */
+    export function IsReadable(metadata: IMetadata | undefined): boolean;
+    /**
+     * Why an archive cannot be read, or null when it can.
+     *
+     * Returned rather than thrown so a renderer can warn and draw nothing while an analysis caller
+     * turns the same sentence into an error. Both then say the same thing.
+     */
+    export function Unreadable(metadata: IMetadata | undefined): string | null;
+    /**
+     * The tiles coarsest first, which is the order a reader has to composite them in.
+     *
+     * Tiles overlap and the finer one is the better answer, so assigning coarse first leaves the
+     * finest tile holding each texel it covers.
+     */
+    export function TilesOf(metadata: IMetadata | undefined): IBinaryTile[];
+    /**
+     * One layer's declaration, or undefined when the archive does not carry it.
+     */
+    export function LayerOf(metadata: IMetadata | undefined, name: string): ILayer | undefined;
+    /**
+     * The range one layer was quantised between, or null for a mask and for a layer that is absent.
+     *
+     * A statistics layer is encoded over the true data range rather than over the frames' own, so
+     * reading it with the frame range is a plausible wrong answer.
+     */
+    export function LayerRange(metadata: IMetadata | undefined, name: string): {
+        Min: number;
+        Max: number;
+    } | null;
+    /**
+     * The values a reading out of this archive falls between, in its delivered units.
+     */
+    export function ValueRange(metadata: IMetadata | undefined): {
+        Min: number;
+        Max: number;
+    };
+    /**
+     * The values the source's own numbers fall between, or null where nothing was transformed.
+     */
+    export function SourceRange(metadata: IMetadata | undefined): {
+        Min: number;
+        Max: number;
+    } | null;
+    /**
+     * What was applied to the source's numbers to get the delivered ones, empty for nothing.
+     */
+    export function TransformOf(metadata: IMetadata | undefined): string;
+    /**
+     * Whether a delivered reading differs from what the source's own data said.
+     *
+     * Both halves are needed: the transform names what happened, and the ValueShift layer is the
+     * only thing that can undo it per texel.
+     */
+    export function IsTransformed(metadata: IMetadata | undefined): boolean;
+    /**
+     * What a picture should be ramped over where the source suggests one, which is not a bound on the data.
+     */
+    export function ColorBarRange(metadata: IMetadata | undefined): {
+        Min: number;
+        Max: number;
+    } | null;
+    /**
+     * When each frame was sampled. Authoritative, unlike Series.Increment.
+     */
+    export function TimesOf(metadata: IMetadata | undefined): string[];
+    /**
+     * Whether the archive holds every timestep that was asked for.
+     *
+     * A short archive is otherwise indistinguishable from a short series, and the failure it hides
+     * is a skipped timestep in the middle of the event rather than a shorter one.
+     */
+    export function IsComplete(metadata: IMetadata | undefined): boolean;
+    /**
+     * Says so when an archive's heights are not on the ellipsoid they will be drawn against.
+     *
+     * Returned rather than logged, so the renderer keeps its console warning and an analysis caller
+     * can put the same sentence in a report.
+     */
+    export function UnshiftedWarning(metadata: IMetadata | undefined): string | null;
+    /**
+     * Where one tile's copy of a layer sits in the blob, or null when it holds none.
+     *
+     * A per-time layer holds one entry per Series.Times element, and a zero length means the tile
+     * held nothing at that time, so the indices stay aligned with the series.
+     */
+    export function BytesOf(tile: IBinaryTile | undefined, name: string, index?: number): IBinaryRange | null;
+    export const MAX_READ_GAP = 131072;
+    /**
+     * The span of the blob a set of byte ranges covers, or null for an empty set.
+     */
+    export function SpanOf(ranges: (IBinaryRange | null | undefined)[]): IBinaryRange | null;
+    /**
+     * The rectangle the archive's raster covers, or null when the block does not place it.
+     */
+    export function ExtentOf(metadata: IMetadata | undefined): IExtent | null;
+    /**
+     * Whether frames carry a 16 bit value packed across R and G.
+     *
+     * Worth asking by name: taking R alone from a packed frame yields a plausible surface quantised
+     * to 255 steps of the full range rather than an obvious failure.
+     */
+    export function IsPacked(metadata: IMetadata | undefined): boolean;
+    /**
+     * A value in the attribute's own units as the 0 to 1 position a 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 published range is what makes that expressible.
+     */
+    export function Normalise(value: number, range: {
+        Min: number;
+        Max: number;
+    }): number;
+    /**
+     * A 0 to 1 position back in the attribute's own units.
+     */
+    export function Denormalise(position: number, range: {
+        Min: number;
+        Max: number;
+    }): number;
+    /**
+     * The packed number at one texel, straight out of the channels, whatever the format.
+     */
+    export function PackedAt(pixels: Uint8Array | Uint8ClampedArray, at: number, format: string): number;
+    /**
+     * The 0 to 1 reading at one texel, for a caller indexing a ramp rather than reporting a number.
+     */
+    export function NormalisedAt(pixels: Uint8Array | Uint8ClampedArray, at: number, format: string): number;
+    /**
+     * The reads that cover a set of byte ranges, adjacent ones merged and distant ones left apart.
+     *
+     * What stops a caller having to choose between one round trip per entry and one download of
+     * everything between the first entry and the last.
+     */
+    export function PlanReads(ranges: (IBinaryRange | null | undefined)[], maxGap?: number): IBinaryRange[];
+    /**
+     * A packed channel reading as the number it stands for.
+     * value = Min + packed / fullScale * (Max - Min), where packed is R at 8 bits and R * 256 + G at 16.
+     */
+    export function Decode(packed: number, format: string, range: {
+        Min: number;
+        Max: number;
+    }): number;
+    export {};
+}

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[][];
+}