@pirireis/webglobeplugins 0.17.1 → 1.0.2

package/vectorfield/wind/plugin-persistant.ts

@@ -0,0 +1,483 @@
+/**
+ * Author: Toprak Nihat Deniz Ozturk
+ */
+
+import { Globe } from "../../types";
+import { imageToFields } from "./adapters/image-to-fields";
+import ParticlePlugin from "../waveparticles/plugin";
+import { createImageFromBase64 } from "../../util/webglobjectbuilders";
+import { TexturePointSampler } from "../../heatwave/texture-point-sampler";
+import imageToMagnitude, { imageToRadianAngle } from "./imagetovectorfieldandmagnitude";
+import { WindData, LegendData } from "./adapters/types.js";
+import { isBoolean } from "../../util/check/typecheck";
+
+/**
+ * Shader Documentation:
+ * * Vector field escape value
+ * texture2D(u_wind, pos).rg == vec2(0.0, 0.0) is used as escape value.
+ * In sea wind maps, land areas have rg values of 0.0.
+ * The probability of a real particle having rg == vec2(0.0, 0.0) is low.
+ * Must have lowest value in both horizontal and vertical dimensions.
+ */
+
+type WindDataMeta = {
+    width: number;
+    height: number;
+    bbox: number[]; // [minLon, minLat, maxLon, maxLat]
+    flipY?: boolean;
+};
+
+type WindPluginOptions = {
+    fadeOpacity?: number;
+    speedFactor?: number;
+    dropRate?: number;
+    dropRateBump?: number;
+    baseOpacity?: number;
+    wingSize?: number;
+    tailSize?: number;
+    minSpeed?: number;
+    maxSpeed?: number;
+    height?: number;
+    numParticles?: number;
+    legendData?: LegendData;
+};
+
+const windyLegendData: LegendData = {
+    thresholds: [0, 3, 3, 5, 5, 7, 10, 10, 13, 15, 15, 17, 20, 20, 25, 25, 30],
+    values: [
+        "#6271B8",
+        "#6271B8",
+        "#6271B8",
+        "#6271B8",
+        "#3D6EA3",
+        "#4A94AA",
+        "#4A9294",
+        "#4D8E7C",
+        "#4CA44C",
+        "#67A436",
+        "#A28740",
+        "#A26D5C",
+        "#8D3F5C",
+        "#974B91",
+        "#5F64A0",
+        "#5B88A1",
+        "#5B88A1"
+    ]
+};
+
+export default class WindPlugin {
+    public id: string;
+    public globe!: Globe;
+    private gl: WebGL2RenderingContext | null = null;
+    private particlePlugin!: ParticlePlugin;
+    private windMetadata: WindDataMeta;
+    private _legendData: LegendData;
+    private options: WindPluginOptions;
+    private windData: WindData | null;
+    private _height: number;
+    private _speedFactor: number;
+    private _dropRate: number;
+    private texturePointSampler?: TexturePointSampler;
+    private texturePointSamplerAngle?: TexturePointSampler;
+
+    /**
+     * @param id - Plugin identifier
+     * @param windDataMeta - Wind data metadata
+     * @param windDataMeta.width - image width
+     * @param windDataMeta.height - image height
+     * @param windDataMeta.bbox - bounding box [minLon, minLat, maxLon, maxLat]
+     * @param options - Plugin options
+     * @param options.fadeOpacity - how fast the particle trails fade on each frame | between 0 - 1 | default 0.746
+     * @param options.speedFactor - how fast the particles move | between 0 - 1 | default 0.6
+     * @param options.dropRate - how often the particles move to a random place | between 0 - 1 | default 0.007
+     * @param options.dropRateBump - drop rate increase relative to individual particle speed
+     * @param options.baseOpacity - opacity of drawn particle trails | between 0 - 1 | default 1.0
+     * @param options.wingSize - wing size of particle arrow | positive number | default 7.0
+     * @param options.tailSize - tail size of particle arrow | positive number | default 1.0
+     * @param options.minSpeed - minimum speed threshold | positive number | default 0.0
+     * @param options.maxSpeed - maximum speed threshold | positive number | default 1000.0
+     * @param options.height - height of the particles | number | default 0.0
+     * @param options.numParticles - number of particles | positive integer | default 40000
+     * @param options.legendData - legend data for color mapping
+     */
+    constructor(
+        id: string,
+        windDataMeta: WindDataMeta,
+        options: WindPluginOptions = {}
+    ) {
+        this.id = id;
+        this.windMetadata = windDataMeta;
+        this._legendData = options.legendData || windyLegendData;
+
+        this.options = {
+            fadeOpacity: options.fadeOpacity ?? 0.746,
+            speedFactor: options.speedFactor ?? 0.6,
+            dropRate: options.dropRate ?? 0.007,
+            dropRateBump: options.dropRateBump ?? 0.001,
+            baseOpacity: options.baseOpacity ?? 1.0,
+            wingSize: options.wingSize ?? 7.0,
+            tailSize: options.tailSize ?? 1.0,
+            minSpeed: options.minSpeed ?? 0.0,
+            maxSpeed: options.maxSpeed ?? 1000.0,
+            height: options.height ?? 0.0,
+            numParticles: options.numParticles ?? 40000,
+            legendData: this._legendData
+        };
+
+        this.windData = null;
+        this._height = this.options.height!;
+        this._speedFactor = this.options.speedFactor!;
+        this._dropRate = this.options.dropRate!;
+    }
+
+    // Globe plugin init method
+    init(globe: Globe, gl: WebGL2RenderingContext): void {
+        this.globe = globe;
+        this.gl = gl;
+
+        // Initialize the particle plugin with appropriate options
+        const { bbox, width, height, flipY } = this.windMetadata;
+
+        this.particlePlugin = new ParticlePlugin(
+            `${this.id}_particles`,
+            {
+                dataWidth: width,
+                dataHeight: height,
+                fadeOpacity: this.options.fadeOpacity,
+                opacity: this.options.baseOpacity,
+                speed: this._speedFactor,
+                dropRate: this._dropRate,
+                height: this._height,
+                minLon: bbox[0],
+                minLat: bbox[1] < -85 ? -85 : bbox[1],
+                maxLon: bbox[2],
+                maxLat: bbox[3] > 85 ? 85 : bbox[3],
+                particleCount: this.options.numParticles,
+                flipY: flipY ?? true,
+                useColorTexture: false, // TODO: under test.. make it true later
+                useSpeedTexture: true,
+                minSpeedThreshold: this.options.minSpeed,
+                maxSpeedThreshold: this.options.maxSpeed,
+                tailSize: this.options.tailSize!,
+                wingSize: this.options.wingSize!
+            }
+        );
+
+        this.particlePlugin.init(globe, gl);
+        // apply initial speed thresholds from options
+        this.particlePlugin.setSpeedThresholds(this.options.minSpeed!, this.options.maxSpeed!);
+    }
+
+    draw3D(): void {
+        if (this.particlePlugin) {
+            this.particlePlugin.draw3D();
+        }
+    }
+
+    free(): void {
+        if (this.particlePlugin) {
+            this.particlePlugin.free();
+        }
+        if (this.texturePointSampler) {
+            this.texturePointSampler = undefined;
+        }
+        if (this.texturePointSamplerAngle) {
+            this.texturePointSamplerAngle = undefined;
+        }
+    }
+
+    // ===== Wind Data Management =====
+
+    /**
+     * Set wind data from base64 encoded image
+     * @param windData - Wind data object
+     * @param windData.image - base64 encoded image
+     * @param windData.width - image width
+     * @param windData.height - image height
+     * @param windData.uMin - minimum u value
+     * @param windData.vMin - minimum v value
+     * @param windData.uMax - maximum u value
+     * @param windData.vMax - maximum v value
+     * @param windData.bbox - bounding box [minLon, minLat, maxLon, maxLat]
+     */
+    setWindDataWithImageBase64(windData: {
+        image: string;
+        width: number;
+        height: number;
+        uMin: number;
+        vMin: number;
+        uMax: number;
+        vMax: number;
+        bbox?: number[];
+    }): void {
+        const image = createImageFromBase64(windData.image);
+        image.onload = () => {
+            const fullWindData: WindData = {
+                image: image,
+                uMin: windData.uMin,
+                vMin: windData.vMin,
+                uMax: windData.uMax,
+                vMax: windData.vMax
+            };
+            this.setWind(fullWindData);
+        };
+    }
+
+    /**
+     * Set wind data from HTMLImageElement
+     */
+    setWind(windData: WindData): void {
+        this.windData = windData;
+
+        if (!this.particlePlugin) {
+            return;
+        }
+
+        // Convert wind image to vector field, speed field, and color field
+        const { vectorFieldData, speedFieldData, colorFieldData } = imageToFields(
+            windData,
+            this._legendData
+        );
+
+        // Update the particle plugin with the new data
+        this.particlePlugin.setVectorFieldData(vectorFieldData, {
+            dataWidth: windData.image.width,
+            dataHeight: windData.image.height,
+            flipY: this.windMetadata.flipY
+        });
+
+        this.particlePlugin.setSpeedField(speedFieldData);
+        this.particlePlugin.setColorField(colorFieldData);
+
+        // Update texture point samplers if they exist
+        this._setCoorcinatesDataCalculatorData();
+    }
+
+    // ===== Legend and Color Management =====
+
+    /**
+     * Set legend data for color mapping
+     * @param legendData - Legend data object
+     * @param legendData.thresholds - list of speed thresholds
+     * @param legendData.values - list of colors in hex format like #ff0000
+     */
+    setLegend(legendData: LegendData): void {
+        this._legendData = legendData;
+
+        // If wind data is already set, re-process to update colors
+        if (this.windData && this.particlePlugin) {
+            const { vectorFieldData, speedFieldData, colorFieldData } = imageToFields(
+                this.windData,
+                this._legendData
+            );
+            this.particlePlugin.setColorField(colorFieldData);
+        }
+    }
+
+
+    setFlipY(flipY: boolean): void {
+        isBoolean(flipY);
+        this.windMetadata.flipY = flipY;
+        if (this.particlePlugin && this.windData) {
+            this.setWind(this.windData);
+        }
+    }
+
+
+    setDrawTextureMaxPixelOnDimension(value: number): void {
+        if (this.particlePlugin) {
+            this.particlePlugin.setDrawTextureMaxPixelOnDimension(value);
+        }
+    }
+    // ===== Property Setters =====
+
+    set height(value: number) {
+        this._height = value;
+        if (this.particlePlugin) {
+            this.particlePlugin.setHeight(value);
+        }
+    }
+
+    get height(): number {
+        return this._height;
+    }
+
+    set minSpeed(value: number) {
+        this.options.minSpeed = value;
+        if (this.particlePlugin) {
+            this.particlePlugin.setMinSpeedThreshold(value);
+        }
+    }
+
+    get minSpeed(): number {
+        return this.options.minSpeed!;
+    }
+
+    set maxSpeed(value: number) {
+        this.options.maxSpeed = value;
+        if (this.particlePlugin) {
+            this.particlePlugin.setMaxSpeedThreshold(value);
+        }
+    }
+
+    get maxSpeed(): number {
+        return this.options.maxSpeed!;
+    }
+
+    set fadeOpacity(value: number) {
+        this.options.fadeOpacity = value;
+        if (this.particlePlugin) {
+            this.particlePlugin.setFadeOpacity(value);
+        }
+    }
+
+    get fadeOpacity(): number {
+        return this.options.fadeOpacity!;
+    }
+
+    set speedFactor(value: number) {
+        this._speedFactor = value;
+        if (this.particlePlugin) {
+            this.particlePlugin.setParticleSpeed(value);
+        }
+    }
+
+    get speedFactor(): number {
+        return this._speedFactor;
+    }
+
+    set dropRate(value: number) {
+        this._dropRate = value;
+        if (this.particlePlugin) {
+            this.particlePlugin.setDropRate(value);
+        }
+    }
+
+    get dropRate(): number {
+        return this._dropRate;
+    }
+
+    set dropRateBump(value: number) {
+        this.options.dropRateBump = value;
+        // Note: ParticlePlugin doesn't have dropRateBump parameter
+        // This would need to be added to ParticlePlugin if needed
+    }
+
+    get dropRateBump(): number {
+        return this.options.dropRateBump!;
+    }
+
+    set baseOpacity(value: number) {
+        this.options.baseOpacity = value;
+        if (this.particlePlugin) {
+            this.particlePlugin.setOpacity(value);
+        }
+    }
+
+    get baseOpacity(): number {
+        return this.options.baseOpacity!;
+    }
+
+    set numParticles(value: number) {
+        this.options.numParticles = value;
+        if (this.particlePlugin) {
+            this.particlePlugin.setParticleCount(value);
+        }
+    }
+
+    get numParticles(): number {
+        return this.options.numParticles!;
+    }
+
+    /**
+     * Set wing and tail size for particle arrows
+     */
+    setParticleDimensions(tail: number, wing: number): void {
+        this.options.tailSize = tail;
+        this.options.wingSize = wing;
+        if (this.particlePlugin) {
+            this.particlePlugin.setParticleDimensions(tail, wing);
+        }
+    }
+
+    /**
+     * Set particle color (used when not using color field)
+     */
+    setParticleColor(color: number[]): void {
+        if (this.particlePlugin) {
+            this.particlePlugin.setParticleColor(color);
+        }
+    }
+
+    /**
+     * Set bounding box
+     */
+    setBBox(bbox: { minLon: number; minLat: number; maxLon: number; maxLat: number }): void {
+        // rescale
+
+        if (this.particlePlugin) {
+            this.particlePlugin.setBBox({
+                minLon: bbox.minLon,
+                minLat: bbox.minLat < -85 ? -85 : bbox.minLat,
+                maxLon: bbox.maxLon,
+                maxLat: bbox.maxLat > 85 ? 85 : bbox.maxLat
+            });
+        }
+        // Update metadata
+        this.windMetadata.bbox = [bbox.minLon, bbox.minLat, bbox.maxLon, bbox.maxLat];
+    }
+
+    // ===== Texture Point Sampler (for backward compatibility) =====
+
+    /**
+     * Get texture point sampler for magnitude or angle
+     * @param type - 'magnitude' or 'angle'
+     */
+    getTexturePointSampler(type: 'magnitude' | 'angle' = 'magnitude'): TexturePointSampler {
+        if (type === 'magnitude') {
+            if (!this.texturePointSampler) {
+                this._createTexturePointSampler();
+                this._setCoorcinatesDataCalculatorData();
+            }
+            return this.texturePointSampler!;
+        } else if (type === 'angle') {
+            if (!this.texturePointSamplerAngle) {
+                this._createTexturePointSamplerAngle();
+                this._setCoorcinatesDataCalculatorData();
+            }
+            return this.texturePointSamplerAngle!;
+        } else {
+            throw new Error(`WindPlugin.getTexturePointSampler: type must be either 'magnitude' or 'angle'.`);
+        }
+    }
+
+    private _createTexturePointSamplerAngle(): void {
+        const { bbox, width, height } = this.windMetadata;
+        this.texturePointSamplerAngle = new TexturePointSampler(bbox as [number, number, number, number], width, height);
+    }
+
+    private _createTexturePointSampler(): void {
+        const { bbox, width, height } = this.windMetadata;
+        this.texturePointSampler = new TexturePointSampler(bbox as [number, number, number, number], width, height);
+    }
+
+    private _setCoorcinatesDataCalculatorData(): void {
+        if (!this.windData) {
+            return;
+        }
+        const windDataWithDimensions = {
+            ...this.windData,
+            width: this.windData.image.width,
+            height: this.windData.image.height
+        };
+        if (this.texturePointSamplerAngle) {
+            const angle = imageToRadianAngle(windDataWithDimensions as any);
+            this.texturePointSamplerAngle.updateTextureData(0, angle, angle);
+        }
+        if (this.texturePointSampler) {
+            const magnitude = imageToMagnitude(windDataWithDimensions as any);
+            this.texturePointSampler.updateTextureData(0, magnitude, magnitude);
+        }
+    }
+}
+