@aeroswarm/weather-layer 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,56 @@
-# 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.
+
+## 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,137 @@
+import { AnimationState } from '@aeroswarm/weather';
+export { M as MapLike, 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;
+};
+
+/** 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;
+
+export { type CloudFeatureLayer, type CloudFieldOptions, type CloudLayer3D, type CloudLayerOptions, type CloudModel, type CloudPuff3D, type RiaCloudDeps, advanceCloudField, buildCloudField, clamp, createCloudLayer3D, gustPulse, lightningInterval, makeCloudSpriteUrl, offsetToLonLat, particleSpeed, rainCount, screenVector, seededRandom, windParticleCount };