autumnplot-gl 4.0.0-beta → 4.1.0

package/lib/RawField.d.ts

@@ -1,11 +1,58 @@
 import { Float16Array } from "@petamoriken/float16";
-import { ContourData, TypedArray, WebGLAnyRenderingContext, WindProfile } from "./AutumnTypes";
-import { FieldContourOpts } from "./ContourCreator";
-import { Grid } from "./Grid";
-import { WGLTextureSpec } from "autumn-wgl";
-type TextureDataType<ArrayType> = ArrayType extends Float32Array ? Float32Array : (ArrayType extends Uint8Array ? Uint8Array : Uint16Array);
+import { ContourData, TypedArray, TypedArrayStr, WebGLAnyRenderingContext, WindProfile } from "./AutumnTypes";
+import { FieldContourOpts } from "./ContourCreator.worker";
+import { Grid } from "./grids/Grid";
+import { WGLTexture } from "autumn-wgl";
+import { AutoZoomGrid } from "./grids/AutoZoom";
+type TextureDataType<ArrayType> = ArrayType extends Float32Array ? Float32Array : (ArrayType extends Uint8Array ? Uint8Array : (ArrayType extends Uint32Array ? Uint32Array : (ArrayType extends Int32Array ? Int32Array : (ArrayType extends Int16Array ? Int16Array : Uint16Array))));
+declare abstract class ExpressionScalarField<ArrayType extends TypedArray, GridType extends Grid> {
+    abstract updateTexImageData(gl: WebGLAnyRenderingContext, image_mag_filter: number, fill_textures: Map<string, WGLTexture> | null): Map<string, WGLTexture>;
+    abstract getSamplerIds(): string[];
+    abstract getExpression(): string;
+    abstract renderCPU(): RawScalarField<ArrayType, GridType>;
+    abstract iterateCPU(): Generator<number, void, unknown>;
+    abstract get grid(): GridType;
+    abstract get aryConstructor(): new (...args: any[]) => ArrayType;
+    abstract get dtypes(): TypedArrayStr[];
+    private operand;
+    /**
+     * Multiply this field by another scalar. The computation occurs on the GPU if the resulting field is used in a plot component or on the CPU if
+     *  {@link ComputedScalarField.renderCPU | renderCPU()} is called on the resulting field.
+     * @param other - Scalar to multiply this field by
+     * @returns A `ComputedScalarField` representing the multiplied field
+     */
+    multiply(other: ExpressionScalarField<ArrayType, GridType> | number): ComputedScalarField<ArrayType, GridType>;
+    /**
+     * Divide this field by another scalar. The computation occurs on the GPU if the resulting field is used in a plot component or on the CPU if
+     * {@link ComputedScalarField.renderCPU | renderCPU()} is called on the resulting field.
+     * @param other - Scalar to divide this field by
+     * @returns A `ComputedScalarField` representing the divided field
+     */
+    divide(other: ExpressionScalarField<ArrayType, GridType> | number): ComputedScalarField<ArrayType, GridType>;
+    /**
+     * Add this field to another scalar. The computation occurs on the GPU if the resulting field is used in a plot component or on the CPU if
+     *  {@link ComputedScalarField.renderCPU | renderCPU()} is called on the resulting field.
+     * @param other - Scalar to add to this field
+     * @returns A `ComputedScalarField` representing the added field
+     */
+    add(other: ExpressionScalarField<ArrayType, GridType> | number): ComputedScalarField<ArrayType, GridType>;
+    /**
+     * Subtract another scalar from this field. The computation occurs on the GPU if the resulting field is used in a plot component or on the CPU if
+     *  {@link ComputedScalarField.renderCPU | renderCPU()} is called on the resulting field.
+     * @param other - Scalar to subtract from this field
+     * @returns A `ComputedScalarField` representing the subtracted field
+     */
+    subtract(other: ExpressionScalarField<ArrayType, GridType> | number): ComputedScalarField<ArrayType, GridType>;
+    abstract getThinnedField(thin_fac: number, map_max_zoom: number): this;
+    abstract sampleField(lon: number, lat: number): number;
+    abstract sampleFieldWithCoord(lon: number, lat: number): {
+        sample: number;
+        sample_lon: number;
+        sample_lat: number;
+    };
+}
 /** A class representing a raw 2D field of gridded data, such as height or u wind. */
-declare class RawScalarField<ArrayType extends TypedArray, GridType extends Grid> {
+declare class RawScalarField<ArrayType extends TypedArray, GridType extends Grid> extends ExpressionScalarField<ArrayType, GridType> {
     readonly grid: GridType;
     readonly data: ArrayType;
     private readonly contour_cache;
@@ -16,8 +63,17 @@ declare class RawScalarField<ArrayType extends TypedArray, GridType extends Grid
      */
     constructor(grid: GridType, data: ArrayType);
     /** @internal */
+    get aryConstructor(): new (...args: any[]) => ArrayType;
+    /** @internal */
+    get dtypes(): TypedArrayStr[];
+    /** @internal */
     private getTextureData;
-    getWGLTextureSpec(gl: WebGLAnyRenderingContext, image_mag_filter: number): WGLTextureSpec;
+    private getWGLTextureSpec;
+    updateTexImageData(gl: WebGLAnyRenderingContext, image_mag_filter: number, fill_textures: Map<string, WGLTexture> | null): Map<string, WGLTexture>;
+    /** @internal */
+    getSamplerIds(): string[];
+    /** @internal */
+    getExpression(): string;
     /**
      * Get contour data as an object with each contour level being a separate property.
      * @param opts - Options for doing the contouring
@@ -25,7 +81,7 @@ declare class RawScalarField<ArrayType extends TypedArray, GridType extends Grid
      */
     getContours(opts: FieldContourOpts): Promise<ContourData>;
     /**
-     * Create a new field by aggregating a number of fields using a specific function
+     * Create a new field by aggregating a number of fields using a specific function. This computation occurs on the CPU.
      * @param func - A function that will be applied each element of the field. It should take the same number of arguments as fields you have and return a single number.
      * @param args - The RawScalarFields to aggregate
      * @returns a new gridded field
@@ -34,9 +90,82 @@ declare class RawScalarField<ArrayType extends TypedArray, GridType extends Grid
      * wind_speed_field = RawScalarField.aggreateFields(Math.hypot, u_field, v_field);
      */
     static aggregateFields<ArrayType extends TypedArray, GridType extends Grid>(func: (...args: number[]) => number, ...args: RawScalarField<ArrayType, GridType>[]): RawScalarField<ArrayType, GridType>;
+    /**
+     * Run computations on a scalar field on the CPU (for a `RawScalarField`, this is a no-op). The function blocks the main thread, so avoid calling it if possible.
+     * @returns The computed grid in a `RawScalarField`
+     */
+    renderCPU(): RawScalarField<ArrayType, GridType>;
+    /** @internal */
+    iterateCPU(): Generator<number, void, unknown>;
+    /** @internal */
+    getThinnedField(thin_fac: number, map_max_zoom: number): this;
+    /**
+     * Sample this field at a given latitude and longitude.
+     * @param lon - Longitude of the sample in degrees east
+     * @param lat - Latitude of the sample in degrees north
+     * @returns The value of the nearest grid point along with the grid point latitude and longitude, or NaNs if the point is outside the grid.
+     */
+    sampleFieldWithCoord(lon: number, lat: number): {
+        sample: number;
+        sample_lon: number;
+        sample_lat: number;
+    };
+    /**
+     * Sample this field at a given latitude and longitude.
+     * @param lon - Longitude of the sample in degrees east
+     * @param lat - Latitude of the sample in degrees north
+     * @returns The value of the nearest grid point, or NaN if the point is outside the grid.
+     */
+    sampleField(lon: number, lat: number): number;
+}
+declare class ComputedScalarField<ArrayType extends TypedArray, GridType extends Grid> extends ExpressionScalarField<ArrayType, GridType> {
+    private readonly raw_fields;
+    private readonly expression;
+    private readonly cpu_func;
+    constructor(raw_fields: ExpressionScalarField<ArrayType, GridType>[], expression: string, cpu_func: (...arg: number[]) => number);
+    /** @internal */
+    get grid(): GridType;
+    /** @internal */
+    get aryConstructor(): new (...args: any[]) => ArrayType;
+    /** @internal */
+    get dtypes(): TypedArrayStr[];
+    /** @internal */
+    updateTexImageData(gl: WebGLAnyRenderingContext, image_mag_filter: number, fill_textures: Map<string, WGLTexture> | null): Map<string, WGLTexture>;
+    /** @internal */
+    getSamplerIds(): string[];
+    /** @internal */
+    getExpression(): string;
+    /** @internal */
+    getThinnedField(thin_fac: number, map_max_zoom: number): this;
+    /**
+     * Sample this field at a given latitude and longitude.
+     * @param lon - Longitude of the sample in degrees east
+     * @param lat - Latitude of the sample in degrees north
+     * @returns The value of the nearest grid point along with the grid point latitude and longitude, or NaNs if the point is outside the grid.
+     */
+    sampleFieldWithCoord(lon: number, lat: number): {
+        sample: number;
+        sample_lon: number;
+        sample_lat: number;
+    };
+    /**
+     * Sample this field at a given latitude and longitude.
+     * @param lon - Longitude of the sample in degrees east
+     * @param lat - Latitude of the sample in degrees north
+     * @returns The value of the nearest grid point, or NaN if the point is outside the grid.
+     */
     sampleField(lon: number, lat: number): number;
+    /**
+     * Run computations on a scalar field on the CPU. The function blocks the main thread, so avoid calling it if possible.
+     * @returns The computed grid in a `RawScalarField`
+     */
+    renderCPU(): RawScalarField<ArrayType, GridType>;
+    /** @internal */
+    iterateCPU(): Generator<number, void, unknown>;
 }
+/** The basis vectors for vector fields (i.e, whether vectors a relative to Earth or the grid) */
 type VectorRelativeTo = 'earth' | 'grid';
+/** Options for {@link RawVectorField}s */
 interface RawVectorFieldOptions {
     /**
      * Whether the vectors are relative to the grid ('grid') or Earth ('earth')
@@ -44,33 +173,100 @@ interface RawVectorFieldOptions {
      */
     relative_to?: VectorRelativeTo;
 }
-/** A class representing a 2D gridded field of vectors */
-declare class RawVectorField<ArrayType extends TypedArray, GridType extends Grid> {
-    readonly u: RawScalarField<ArrayType, GridType>;
-    readonly v: RawScalarField<ArrayType, GridType>;
+declare abstract class ExpressionVectorField<ArrayType extends TypedArray, GridType extends AutoZoomGrid> {
+    protected readonly u: ExpressionScalarField<ArrayType, GridType>;
+    protected readonly v: ExpressionScalarField<ArrayType, GridType>;
     readonly relative_to: VectorRelativeTo;
+    constructor(u: ExpressionScalarField<ArrayType, GridType>, v: ExpressionScalarField<ArrayType, GridType>, opts?: RawVectorFieldOptions);
+    private operandScalar;
+    private operandVector;
     /**
-     * Create a vector field.
-     * @param grid - The grid on which the vector components are defined
-     * @param u    - The u (east/west) component of the vectors, which should be given as a 1D array in row-major order, with the first element being at the lower-left corner of the grid
-     * @param v    - The v (north/south) component of the vectors, which should be given as a 1D array in row-major order, with the first element being at the lower-left corner of the grid
-     * @param opts - Options for creating the vector field.
+     * Multiply this vector field by a scalar. The multiplication occurs on the GPU if the resulting field is used in a plot component.
+     * @param other - Scalar to multiply by. Can be either a number or a scalar field.
+     * @returns A `ComputedVectorField` representing the multiplied vector field
      */
-    constructor(grid: GridType, u: ArrayType, v: ArrayType, opts?: RawVectorFieldOptions);
+    multiply(other: ExpressionScalarField<ArrayType, GridType> | number): ComputedVectorField<ArrayType, GridType>;
+    /**
+     * Divide this vector field by a scalar. The division occurs on the GPU if the resulting field is used in a plot component.
+     * @param other - Scalar to divide by. Can be either a number or a scalar field.
+     * @returns A `ComputedVectorField` representing the divided vector field
+     */
+    divide(other: ExpressionScalarField<ArrayType, GridType> | number): ComputedVectorField<ArrayType, GridType>;
+    /**
+     * Add this vector field to another vector field. The addition occurs on the GPU if the resulting field is used in a plot component.
+     * @param other Vector field to add.
+     * @returns A `ComputedVectorField` representing the added vector field
+     */
+    add(other: ExpressionVectorField<ArrayType, GridType>): ComputedVectorField<ArrayType, GridType>;
+    /**
+     * Subtract another vector field from this vector field. The subtraction occurs on the GPU if the resulting field is used in a plot component.
+     * @param other Vector field to subtract.
+     * @returns A `ComputedVectorField` representing the subtracted vector field
+     */
+    subtract(other: ExpressionVectorField<ArrayType, GridType>): ComputedVectorField<ArrayType, GridType>;
     /** @internal */
-    private getTextureData;
-    getWGLTextureSpecs(gl: WebGLAnyRenderingContext, mag_filter: number): {
-        u: WGLTextureSpec;
-        v: WGLTextureSpec;
+    updateTexImageData(gl: WebGLAnyRenderingContext, image_mag_filter: number, fill_textures: {
+        u: Map<string, WGLTexture>;
+        v: Map<string, WGLTexture>;
+    } | null): {
+        u: Map<string, WGLTexture>;
+        v: Map<string, WGLTexture>;
     };
+    /**
+     * Get the magnitude of the vector field as a scalar field. The magnitude calculation occurs on the GPU if this field is used in a plot component.
+     * @returns A `ComputedScalarField` representing the subtracted vector field
+     */
+    magnitude(): ComputedScalarField<ArrayType, GridType>;
     /** @internal */
-    getThinnedField(thin_fac: number, map_max_zoom: number): RawVectorField<ArrayType, Grid>;
+    getThinnedField(thin_fac: number, map_max_zoom: number): ComputedVectorField<ArrayType, GridType>;
     /** @internal */
     get grid(): GridType;
+    /**
+     * Sample this field at a given latitude and longitude.
+     * @param lon - Longitude of the sample in degrees east
+     * @param lat - Latitude of the sample in degrees north
+     * @returns A tuple containing the [`bearing`, `magnitude`] of the vector field at the nearest grid point. The bearing is given as degrees from north, increasing clockwise.
+     *  If the point is outside the grid, it returns [NaN, NaN] instead.
+     */
     sampleField(lon: number, lat: number): [number, number];
+    /** @internal */
+    getSamplerIds(): {
+        u: string[];
+        v: string[];
+    };
+    /** @internal */
+    getExpressions(): {
+        u: string;
+        v: string;
+    };
+}
+/** A class representing a 2D gridded field of vectors */
+declare class RawVectorField<ArrayType extends TypedArray, GridType extends AutoZoomGrid> extends ExpressionVectorField<ArrayType, GridType> {
+    private readonly u_ary;
+    private readonly v_ary;
+    /**
+     * Create a vector field.
+     * @param grid - The grid on which the vector components are defined
+     * @param u_ary - The u (east/west) component of the vectors, which should be given as a 1D array in row-major order, with the first element being at the lower-left corner of the grid
+     * @param v_ary - The v (north/south) component of the vectors, which should be given as a 1D array in row-major order, with the first element being at the lower-left corner of the grid
+     * @param opts - Options for creating the vector field.
+     */
+    constructor(grid: GridType, u_ary: ArrayType, v_ary: ArrayType, opts?: RawVectorFieldOptions);
+    /** @internal */
+    getSamplerIds(): {
+        u: string[];
+        v: string[];
+    };
+    /** @internal */
+    getExpressions(): {
+        u: string;
+        v: string;
+    };
+}
+declare class ComputedVectorField<ArrayType extends TypedArray, GridType extends AutoZoomGrid> extends ExpressionVectorField<ArrayType, GridType> {
 }
 /** A class grid of wind profiles */
-declare class RawProfileField<GridType extends Grid> {
+declare class RawProfileField<GridType extends AutoZoomGrid> {
     readonly profiles: WindProfile[];
     readonly grid: GridType;
     /**
@@ -97,7 +293,7 @@ declare class RawProfileField<GridType extends Grid> {
  */
 type ObsRawData<ObsFieldName extends string> = Record<ObsFieldName, string | number | [number, number] | null>;
 /** Raw observation data, given as a list of objects */
-declare class RawObsField<GridType extends Grid, ObsFieldName extends string> {
+declare class RawObsField<GridType extends AutoZoomGrid, ObsFieldName extends string> {
     readonly grid: GridType;
     readonly data: ObsRawData<ObsFieldName>[];
     /**
@@ -122,5 +318,5 @@ declare class RawObsField<GridType extends Grid, ObsFieldName extends string> {
      */
     getVector(key: ObsFieldName): RawVectorField<Float16Array, GridType>;
 }
-export { RawScalarField, RawVectorField, RawProfileField, RawObsField };
-export type { RawVectorFieldOptions, VectorRelativeTo, TextureDataType, ObsRawData };
+export { RawScalarField, ComputedScalarField, RawVectorField, ComputedVectorField, RawProfileField, RawObsField };
+export type { ExpressionScalarField, RawVectorFieldOptions, ExpressionVectorField, VectorRelativeTo, TextureDataType, ObsRawData };