@aeroswarm/weather-layer 0.0.0-stage → 0.1.2

package/README.md

@@ -1,3 +1,77 @@
-# Temporary Holding Version
+# @aeroswarm/weather-layer
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Animated weather on a LuciadRIA map: wind particles, clouds, rain/snow, fog and lightning. It takes
+the `AnimationState` produced by [`@aeroswarm/weather`](../../server/weather) (decoded METAR/SPECI/TAF)
+and draws it. No network access.
+
+## A. Flat overlay (2D and 3D)
+
+```ts
+import { animationSnapshot } from "@aeroswarm/weather";
+import { createWeatherOverlay } from "@aeroswarm/weather-layer";
+
+const overlay = createWeatherOverlay(map);          // transparent canvases on map.domNode
+const snapshot = animationSnapshot({ observation: metar, forecast: taf });
+if (snapshot) overlay.setState(snapshot.state);
+
+overlay.setVisible(false);                           // toggle from your layer panel
+overlay.setOpacity(0.8);
+overlay.destroy();
+```
+
+React:
+
+```tsx
+import { useWeatherOverlay } from "@aeroswarm/weather-layer/react";
+
+useWeatherOverlay(map, snapshot?.state, { visible, opacity });
+```
+
+Wind direction follows the map rotation (`mapScreenOffset`; override with `getScreenOffset`).
+The overlay is a canvas above the map, so it is not part of `map.layerTree`: wire its `visible` and
+`opacity` to your own layer panel. Honours `prefers-reduced-motion` (draws a still frame).
+
+## B. 3D clouds at real altitude
+
+```ts
+import { FeatureLayer } from "@mid/ria/view/feature/FeatureLayer";
+import { createCloudLayer3D } from "@aeroswarm/weather-layer";
+
+const clouds = createCloudLayer3D(
+  { reference, Feature, FeatureModel, MemoryStore, FeatureLayer, FeaturePainter, createPoint },
+  { center: { lat: -7.3798, lon: 112.7869 }, elevationM: 3 },
+);
+map.layerTree.addChild(clouds.layer);
+clouds.setState(snapshot.state);
+```
+
+Cloud height = aerodrome elevation + cloud base above ground level (METAR reports AGL). Sprites are
+sized in metres, so they scale with zoom and perspective. Drawn only when the map is 3D
+(`EPSG:4978`) unless `only3D: false`. The RIA classes are passed in so this package never bundles
+its own copy of RIA.
+
+## C. Windy-style fields (flow particles + colour maps)
+
+Wind particles that follow a gridded wind field, coloured by speed, plus colour maps for cloud cover,
+rain or temperature. The grid can come from anywhere (see `@aeroswarm/weather`: `windGridFromStations`
+for several METARs, `parseGrib2Json`, `parseGridJson`, `stationWindsFromModelPoints`).
+
+```ts
+import { createFieldOverlay, createRiaUnproject, PRECIPITATION_RAMP } from "@aeroswarm/weather-layer";
+
+const unproject = createRiaUnproject(map, { wgs84, createPoint, createTransformation });
+const overlay = createFieldOverlay(map, { unproject });
+
+overlay.setWind(windGrid);                                  // particles
+overlay.setScalar(cloudGrid);                                // cloud cover (default ramp)
+overlay.setScalar(rainGrid, PRECIPITATION_RAMP);             // or rain, temperature, ...
+```
+
+The field is mapped onto a screen grid whenever the map moves (throttled), so the particles read a
+small array instead of projecting every particle on every frame. Points that are not on the map (3D:
+off the globe) have no wind.
+
+## Limits
+
+METAR and TAF describe one point (the aerodrome). The animation is a representation around the
+airport, not the real position of clouds or rain. There is no terrain or land mask yet.

package/dist/index.d.ts

@@ -0,0 +1,312 @@
+import { AnimationState, ScalarGrid, WindGrid } from '@aeroswarm/weather';
+import { M as MapLike } from './overlay-U9My4PH5.js';
+export { W as WeatherOverlay, a as WeatherOverlayOptions, b as WeatherRenderer, c as WeatherRendererOptions, d as WeatherTheme, e as createWeatherOverlay, m as mapScreenOffset } from './overlay-U9My4PH5.js';
+
+/**
+ * Kelas dan fungsi LuciadRIA yang dipakai layer awan. Diberikan oleh pemakai (injeksi) supaya package
+ * ini tidak punya dependensi ke RIA dan memakai salinan RIA milik aplikasi yang sama dengan petanya.
+ */
+interface RiaCloudDeps {
+    /** Referensi EPSG:4326, mis. `getReference("EPSG:4326")`. */
+    reference: unknown;
+    Feature: new (shape: unknown, properties: Record<string, unknown>, id?: string) => unknown;
+    FeatureModel: new (store: unknown, options: {
+        reference: unknown;
+    }) => CloudModel;
+    MemoryStore: new () => unknown;
+    FeatureLayer: new (model: CloudModel, options: Record<string, unknown>) => CloudFeatureLayer;
+    FeaturePainter: new () => CloudPainter;
+    createPoint: (reference: unknown, coordinates: number[]) => unknown;
+}
+interface CloudModel {
+    put(feature: unknown): unknown;
+    remove(id: string): unknown;
+}
+interface CloudFeatureLayer {
+    visible: boolean;
+}
+interface CloudPainter {
+    getDetailLevelScales?: () => number[];
+    paintBody: (geoCanvas: {
+        drawIcon(shape: unknown, style: Record<string, unknown>): void;
+    }, feature: {
+        properties: Record<string, unknown>;
+    }, shape: unknown, layer: unknown, map: {
+        reference: {
+            identifier: string;
+        };
+    }) => void;
+}
+interface CloudLayerOptions {
+    /** Pusat sebaran awan (bandara). */
+    center: {
+        lat: number;
+        lon: number;
+    };
+    /** Elevasi bandara (m di atas laut), ditambahkan ke tinggi dasar awan AGL. Bawaan 0. */
+    elevationM?: number;
+    radiusM?: number;
+    /** Awan hanya digambar di peta 3D (EPSG:4978). Bawaan true. */
+    only3D?: boolean;
+    /** Percepatan gerak awan. Bawaan 12. */
+    timeScale?: number;
+    /** Selang pembaruan posisi (ms). Bawaan 500. */
+    updateIntervalMs?: number;
+    id?: string;
+}
+interface CloudLayer3D {
+    readonly layer: CloudFeatureLayer;
+    /** Ganti kondisi cuaca: awan dibangun ulang dari lapisan awan METAR/TAF. */
+    setState(state: AnimationState): void;
+    setVisible(visible: boolean): void;
+    destroy(): void;
+}
+/** Sprite gumpalan awan sebagai data URL (gradien radial lembut). */
+declare function makeCloudSpriteUrl(): string;
+/**
+ * Layer RIA berisi gumpalan awan di ketinggian sebenarnya (elevasi bandara + tinggi dasar AGL),
+ * berukuran dalam meter sehingga ikut zoom dan perspektif 3D. Tambahkan ke peta dengan
+ * `map.layerTree.addChild(cloud.layer)`.
+ */
+declare function createCloudLayer3D(ria: RiaCloudDeps, options: CloudLayerOptions): CloudLayer3D;
+
+/** Satu gumpalan awan di sekitar bandara, dalam meter dari titik pusat. */
+interface CloudPuff3D {
+    id: string;
+    eastM: number;
+    northM: number;
+    /** Ketinggian di atas permukaan laut (m): elevasi bandara + tinggi dasar awan (AGL). */
+    altM: number;
+    sizeM: number;
+    opacity: number;
+    convective: boolean;
+}
+interface CloudFieldOptions {
+    /** Radius sebaran awan dari bandara (m). Bawaan 12.000. */
+    radiusM?: number;
+    /** Elevasi bandara (m di atas laut). METAR memberi tinggi awan AGL, jadi ini ditambahkan. */
+    elevationM?: number;
+    /** Biji acak supaya letak awan konsisten antar render. */
+    seed?: number;
+}
+/** Pembangkit acak kecil (mulberry32) agar medan awan deterministik. */
+declare function seededRandom(seed: number): () => number;
+/**
+ * Sebar gumpalan awan di sekitar bandara dari lapisan awan METAR/TAF. Banyaknya menurut tutupan,
+ * ketinggiannya = elevasi bandara + tinggi dasar (AGL). Awan konvektif lebih besar dan lebih padat.
+ */
+declare function buildCloudField(state: AnimationState, options?: CloudFieldOptions): CloudPuff3D[];
+/**
+ * Geser awan searah angin (`toDeg`, derajat dari utara). `timeScale` mempercepat gerak supaya
+ * terlihat (1 = kecepatan nyata, yang nyaris tidak terlihat dari ketinggian peta). Awan yang
+ * keluar dari radius muncul lagi di sisi seberang.
+ */
+declare function advanceCloudField(field: readonly CloudPuff3D[], wind: {
+    toDeg: number | null;
+    speedKt: number;
+}, dtSeconds: number, options?: {
+    radiusM?: number;
+    timeScale?: number;
+}): CloudPuff3D[];
+/** Titik lat/lon dari selisih meter timur/utara terhadap pusat (pendekatan datar, cukup untuk ~20 km). */
+declare function offsetToLonLat(centerLat: number, centerLon: number, eastM: number, northM: number): {
+    lat: number;
+    lon: number;
+};
+
+/** Warna: [nilai, merah, hijau, biru, alfa 0-1]. Nilai harus naik. */
+type RampStop = readonly [number, number, number, number, number?];
+type Rgba = readonly [number, number, number, number];
+/** Warna di `value` dengan interpolasi linear antar titik; di luar rentang dipakai titik ujung. */
+declare function rampColor(stops: readonly RampStop[], value: number): Rgba;
+declare const rgbaCss: ([r, g, b, a]: Rgba, alpha?: number) => string;
+/** Kecepatan angin (m/s): dari biru dingin (tenang) ke merah (kencang), seperti peta angin umum. */
+declare const WIND_RAMP: readonly RampStop[];
+/** Tutupan awan (%): bening ke putih keabu-abuan. */
+declare const CLOUD_RAMP: readonly RampStop[];
+/** Curah hujan (mm/jam). */
+declare const PRECIPITATION_RAMP: readonly RampStop[];
+/** Suhu (°C). */
+declare const TEMPERATURE_RAMP: readonly RampStop[];
+
+/** Titik layar (piksel) ke koordinat geografis; null bila di luar peta (mis. di luar bola bumi). */
+type Unproject = (x: number, y: number) => {
+    lon: number;
+    lat: number;
+} | null;
+/** Angin yang sudah dipetakan ke kisi layar: satu vektor arah layar dan kecepatan per sel. */
+interface ScreenWindField {
+    cols: number;
+    rows: number;
+    cell: number;
+    /** Vektor satuan arah gerak di layar (x kanan, y bawah). */
+    dx: Float32Array;
+    dy: Float32Array;
+    /** Kecepatan (m/s); NaN = tanpa data. */
+    speed: Float32Array;
+}
+interface ScreenScalarField {
+    cols: number;
+    rows: number;
+    cell: number;
+    values: Float32Array;
+}
+/**
+ * Ubah grid angin geografis menjadi kisi layar. Dilakukan sekali tiap peta bergerak, supaya partikel
+ * tinggal membaca kisi (tanpa memproyeksikan ulang tiap partikel tiap frame).
+ */
+declare function buildScreenWindField(grid: WindGrid, width: number, height: number, unproject: Unproject, screenOffsetDeg: number, cell?: number): ScreenWindField;
+declare function buildScreenScalarField(grid: ScalarGrid, width: number, height: number, unproject: Unproject, cell?: number): ScreenScalarField;
+/** Angin di titik layar (x, y) dari kisi; null di luar kisi atau tanpa data. */
+declare function windAt(field: ScreenWindField, x: number, y: number): {
+    dx: number;
+    dy: number;
+    speed: number;
+} | null;
+
+interface FieldOverlayOptions {
+    /** Titik layar ke lon/lat; lihat `createRiaUnproject`. */
+    unproject: Unproject;
+    zIndex?: number;
+    maxFps?: number;
+    pixelsPerMs?: number;
+    getScreenOffset?: (map: MapLike) => number;
+}
+interface FieldOverlay {
+    /** Aliran partikel angin dari grid; null untuk menghapus. */
+    setWind(grid: WindGrid | null): void;
+    /** Peta warna dari grid skalar (awan, hujan, suhu); null untuk menghapus. */
+    setScalar(grid: ScalarGrid | null, ramp?: readonly RampStop[]): void;
+    setVisible(visible: boolean): void;
+    setOpacity(opacity: number): void;
+    destroy(): void;
+}
+/**
+ * Overlay medan cuaca ala Windy di atas peta: peta warna (di bawah) dan aliran partikel angin (di
+ * atas). Medan dipetakan ulang ke layar tiap peta bergerak (dibatasi ~10 kali per detik).
+ */
+declare function createFieldOverlay(map: MapLike, options: FieldOverlayOptions): FieldOverlay;
+
+interface FlowRendererOptions {
+    container: HTMLElement;
+    unproject: Unproject;
+    zIndex?: number;
+    maxFps?: number;
+    /** Piksel per detik untuk tiap m/s angin. Bawaan 9. */
+    pixelsPerMs?: number;
+    /** Jumlah partikel maksimum. Bawaan 3000. */
+    maxParticles?: number;
+    reducedMotion?: boolean;
+}
+/**
+ * Aliran angin ala Windy: partikel bergerak mengikuti medan angin dari grid, berwarna menurut
+ * kecepatan, dengan ekor yang memudar. Medan dipetakan ke kisi layar sekali tiap peta bergerak.
+ */
+declare class FlowRenderer {
+    private readonly options;
+    private readonly canvas;
+    private readonly ctx;
+    private grid;
+    private field;
+    private particles;
+    private width;
+    private height;
+    private dpr;
+    private offset;
+    private raf;
+    private running;
+    private last;
+    private accumulated;
+    private readonly frameInterval;
+    private readonly reduceMotion;
+    constructor(options: FlowRendererOptions);
+    setWind(grid: WindGrid | null): void;
+    setScreenOffset(degrees: number): void;
+    /** Dipanggil saat peta bergerak/zoom: petakan ulang medan ke layar. */
+    refreshField(): void;
+    resize(): void;
+    setVisible(visible: boolean): void;
+    setOpacity(opacity: number): void;
+    start(): void;
+    stop(): void;
+    destroy(): void;
+    private spawn;
+    private step;
+}
+
+/** Hitungan murni untuk renderer: tanpa DOM supaya mudah dites. */
+/**
+ * Vektor gerak di layar (x ke kanan, y ke bawah) untuk arah `toDeg` (derajat dari utara, searah jarum
+ * jam). `screenOffsetDeg` = putaran peta: arah di layar = arah geografis + offset.
+ */
+declare function screenVector(toDeg: number, screenOffsetDeg?: number): {
+    x: number;
+    y: number;
+};
+declare const clamp: (value: number, min?: number, max?: number) => number;
+/** Jumlah partikel angin menurut luas layar, dibatasi `max`. */
+declare function windParticleCount(width: number, height: number, max?: number): number;
+/** Jumlah garis hujan yang digambar dari `pool` tetes, menurut intensitas 0-1. */
+declare function rainCount(pool: number, intensity: number): number;
+/** Kecepatan visual partikel (px/detik) dari kecepatan angin (kt) dan hembusan sesaat. */
+declare function particleSpeed(speedKt: number, gustKt?: number): number;
+/** Hembusan sesaat (kt tambahan) yang berdenyut halus sesuai `gustiness` 0-1. */
+declare function gustPulse(gustiness: number, timeMs: number): number;
+/** Selang antar kilat (ms) dari laju kilat per menit, dengan sedikit acak (`random` 0-1). */
+declare function lightningInterval(perMinute: number, random: number): number;
+
+/** Bagian RIA yang dipakai `createRiaUnproject`; diberikan oleh aplikasi (injeksi). */
+interface RiaUnprojectDeps {
+    /** `getReference("EPSG:4326")`. */
+    wgs84: unknown;
+    createPoint: (reference: unknown, coordinates: number[]) => unknown;
+    createTransformation: (source: unknown, destination: unknown) => {
+        transform(point: unknown): {
+            x: number;
+            y: number;
+        };
+    };
+}
+interface UnprojectableMap {
+    readonly reference: unknown;
+    readonly viewToMapTransformation: {
+        transform(point: unknown): unknown;
+    };
+}
+/**
+ * Fungsi titik layar -> lon/lat untuk peta RIA 2D maupun 3D. Mengembalikan null untuk titik yang tidak
+ * jatuh pada peta (di 3D: di luar bola bumi), jadi aliran partikel berhenti di sana.
+ */
+declare function createRiaUnproject(map: UnprojectableMap, deps: RiaUnprojectDeps): Unproject;
+
+interface ScalarRendererOptions {
+    container: HTMLElement;
+    unproject: Unproject;
+    ramp?: readonly RampStop[];
+    zIndex?: number;
+}
+/**
+ * Peta warna dari grid skalar (tutupan awan, hujan, suhu): tiap sel layar diwarnai dari nilai grid,
+ * digambar halus. Digambar ulang hanya saat grid atau peta berubah, bukan tiap frame.
+ */
+declare class ScalarRenderer {
+    private readonly options;
+    private readonly canvas;
+    private readonly ctx;
+    private readonly small;
+    private grid;
+    private ramp;
+    private width;
+    private height;
+    private dpr;
+    constructor(options: ScalarRendererOptions);
+    setGrid(grid: ScalarGrid | null, ramp?: readonly RampStop[]): void;
+    resize(): void;
+    /** Gambar ulang setelah peta bergerak atau di-zoom. */
+    draw(): void;
+    setVisible(visible: boolean): void;
+    setOpacity(opacity: number): void;
+    destroy(): void;
+}
+
+export { CLOUD_RAMP, type CloudFeatureLayer, type CloudFieldOptions, type CloudLayer3D, type CloudLayerOptions, type CloudModel, type CloudPuff3D, type FieldOverlay, type FieldOverlayOptions, FlowRenderer, type FlowRendererOptions, MapLike, PRECIPITATION_RAMP, type RampStop, type Rgba, type RiaCloudDeps, type RiaUnprojectDeps, ScalarRenderer, type ScalarRendererOptions, type ScreenScalarField, type ScreenWindField, TEMPERATURE_RAMP, type Unproject, WIND_RAMP, advanceCloudField, buildCloudField, buildScreenScalarField, buildScreenWindField, clamp, createCloudLayer3D, createFieldOverlay, createRiaUnproject, gustPulse, lightningInterval, makeCloudSpriteUrl, offsetToLonLat, particleSpeed, rainCount, rampColor, rgbaCss, screenVector, seededRandom, windAt, windParticleCount };