react-native-mapsforge-vtm-ext-grib 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jhotadhari
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,118 @@
+# react-native-mapsforge-vtm-ext-grib
+
+Weather GRIB overlay extension for [`react-native-mapsforge-vtm`](https://github.com/jhotadhari/react-native-mapsforge-vtm).
+Renders gridded weather data (wind, temperature, pressure, precipitation, waves) as colored overlays on offline vector maps.
+
+**Android only** — matches the platform scope of the parent library.
+
+## Quick Start
+
+```tsx
+import { MapContainer, LayerMapsforge } from 'react-native-mapsforge-vtm';
+import { WeatherOverlay } from 'react-native-mapsforge-vtm-ext-grib';
+
+<MapContainer>
+  <LayerMapsforge mapFile="/sdcard/maps/germany.map" />
+  <WeatherOverlay
+    dataUrl="https://weather.example.com/forecast.json"
+    parameter="WIND"
+    timeIndex={0}
+    colorMap="wind"
+    opacity={0.7}
+  />
+</MapContainer>
+```
+
+## Features (Phase 1 — Static Overlay)
+
+- Colored grid overlay from pre-processed JSON weather data
+- 6 built-in color ramps: `temperature`, `wind`, `pressure`, `rainfall`, `waves`, `grayscale`
+- Per-pixel bilinear interpolation from the source grid
+- Zoom-level bounds (`zoomMin`/`zoomMax`, `enabledZoomMin`/`enabledZoomMax`)
+- Layer opacity control
+- Time step selection
+
+## JSON Data Format
+
+The `dataUrl` should point to a JSON file with this structure:
+
+```json
+{
+  "parameter": "WIND",
+  "unit": "m/s",
+  "timeSteps": [
+    {
+      "validTime": "2026-07-03T00:00:00Z",
+      "minLat": 47.0,
+      "maxLat": 55.0,
+      "minLng": 5.0,
+      "maxLng": 16.0,
+      "ni": 44,
+      "nj": 32,
+      "values": [0.5, 1.2, null, 3.1, ...]
+    }
+  ]
+}
+```
+
+- `values` is a row-major array of length `ni * nj`. `null` entries represent missing data (rendered as transparent).
+- `ni`: number of grid points in the longitude direction.
+- `nj`: number of grid points in the latitude direction.
+
+Use [`@weacast/grib2json`](https://www.npmjs.com/package/@weacast/grib2json) for server-side GRIB→JSON conversion. On-device GRIB parsing (via JGribX) is planned for Phase 5.
+
+## Installation
+
+```sh
+yarn add react-native-mapsforge-vtm-ext-grib
+```
+
+This library has a **peer dependency** on `react-native-mapsforge-vtm` and `react-native-reanimated`.
+
+## Example app
+
+```sh
+# Clone and install:
+git clone https://github.com/jhotadhari/react-native-mapsforge-vtm-ext-grib
+cd react-native-mapsforge-vtm-ext-grib
+yarn install
+
+# Development (with yalc-linked react-native-mapsforge-vtm):
+cd example && yalc link react-native-mapsforge-vtm && cd ..
+yarn example android
+
+# Serve sample weather data for the example:
+cd example/data && python3 -m http.server 8000
+```
+
+## Documentation
+
+- [Extending react-native-mapsforge-vtm](https://github.com/jhotadhari/react-native-mapsforge-vtm/blob/main/docs/advanced/extending.md) — extension architecture guide
+- [ext-plan skill](https://github.com/jhotadhari/react-native-mapsforge-vtm/blob/main/.claude/skills/ext-plan.md) — interactive scaffolding command
+
+## Architecture
+
+`WeatherOverlay` creates a custom vtm `TileSource` (`WeatherTileSource`) that renders weather grid data into bitmap tiles on demand. The tile source is backed by a `BitmapTileLayer` — the same layer type used for OSM raster tiles and hillshading in the parent library.
+
+```
+WeatherGridData (in-memory)
+    → WeatherTileSource (extends TileSource)
+        → WeatherTileDataSource (implements ITileDataSource)
+            → query() → bitmap → setTileImage()
+                → BitmapTileLayer
+```
+
+## Roadmap
+
+| Phase | Feature | Status |
+|---|---|---|
+| 1 | Static colored overlay (tile-based) | ✅ Current |
+| 2 | Smooth time animation (dual-layer crossfade) | Planned |
+| 3 | Custom vtm Layer (GPU interpolation + particles) | Planned |
+| 4 | Wind barbs, isobars, cursor readout | Planned |
+| 5 | On-device GRIB parsing (JGribX + jj2000) | Planned |
+| 6 | Polish, performance, reanimated bearing/tilt | Planned |
+
+## License
+
+MIT

package/android/CMakeLists.txt

@@ -0,0 +1,13 @@
+# Wrapper CMakeLists.txt for react-native-mapsforge-vtm-ext-grib.
+#
+# Discovered by React Native autolinking at the android/ module root.
+# Pulls in the codegen-generated TurboModule JNI from generated/jni/.
+#
+# Structure mirrors the parent library (react-native-mapsforge-vtm):
+# the wrapper is discovered by autolinking and delegates to the
+# generated JNI subdirectory.
+cmake_minimum_required(VERSION 3.16)
+
+# Codegen-generated TurboModule JNI.
+add_subdirectory("${CMAKE_CURRENT_SOURCE_DIR}/generated/jni/"
+                 extgrib_codegen_build)

package/android/build.gradle

@@ -0,0 +1,108 @@
+buildscript {
+  ext.getExtOrDefault = {name ->
+    return rootProject.ext.has(name) ? rootProject.ext.get(name) : project.properties['MapsforgeVtmExtGrib_' + name]
+  }
+
+  repositories {
+    google()
+    mavenCentral()
+  }
+
+  dependencies {
+    classpath "com.android.tools.build:gradle:8.12.0"
+    classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:${getExtOrDefault('kotlinVersion')}"
+  }
+}
+
+apply plugin: "com.android.library"
+apply plugin: "kotlin-android"
+apply plugin: "com.facebook.react"
+
+def getExtOrIntegerDefault(name) {
+  return rootProject.ext.has(name) ? rootProject.ext.get(name) : (project.properties["MapsforgeVtmExtGrib_" + name]).toInteger()
+}
+
+def supportsNamespace() {
+  def parsed = com.android.Version.ANDROID_GRADLE_PLUGIN_VERSION.tokenize('.')
+  def major = parsed[0].toInteger()
+  def minor = parsed[1].toInteger()
+  return (major == 7 && minor >= 3) || major >= 8
+}
+
+android {
+  if (supportsNamespace()) {
+    namespace "com.jhotadhari.reactnative.mapsforge.vtm.ext.grib"
+
+    sourceSets {
+      main {
+        manifest.srcFile "src/main/AndroidManifestNew.xml"
+      }
+    }
+  }
+
+  compileSdkVersion getExtOrIntegerDefault("compileSdkVersion")
+
+  defaultConfig {
+    minSdkVersion getExtOrIntegerDefault("minSdkVersion")
+    targetSdkVersion getExtOrIntegerDefault("targetSdkVersion")
+  }
+
+  buildFeatures {
+    buildConfig true
+  }
+
+  buildTypes {
+    release {
+      minifyEnabled false
+    }
+  }
+
+  lintOptions {
+    disable "GradleCompatible"
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_1_8
+    targetCompatibility JavaVersion.VERSION_1_8
+  }
+
+  sourceSets {
+    main {
+      java.srcDirs += [
+        "generated/java",
+        "generated/jni"
+      ]
+    }
+  }
+}
+
+repositories {
+  mavenCentral()
+  google()
+}
+
+def kotlin_version = getExtOrDefault("kotlinVersion")
+
+dependencies {
+  implementation "com.facebook.react:react-android"
+  implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
+
+  // Parent library — provides Utils, LayerHelper, LayerZoomBoundsHelper,
+  // and the extension-point hooks (MapHandleContext, useLayerOrder,
+  // useNativeLayerLifecycle).
+  compileOnly project(':react-native-mapsforge-vtm')
+
+  // vtm — same version as the main library
+  implementation 'com.github.mapsforge.vtm:vtm:0.29.0'
+  implementation 'com.github.mapsforge.vtm:vtm-android:0.29.0'
+  runtimeOnly 'com.github.mapsforge.vtm:vtm-android:0.29.0:natives-armeabi-v7a'
+  runtimeOnly 'com.github.mapsforge.vtm:vtm-android:0.29.0:natives-arm64-v8a'
+  runtimeOnly 'com.github.mapsforge.vtm:vtm-android:0.29.0:natives-x86'
+  runtimeOnly 'com.github.mapsforge.vtm:vtm-android:0.29.0:natives-x86_64'
+}
+
+react {
+  jsRootDir = file("../src/")
+  libraryName = "MapsforgeVtmExtGrib"
+  codegenJavaPackageName = "com.jhotadhari.reactnative.mapsforge.vtm.ext.grib"
+}

package/android/generated/java/com/jhotadhari/reactnative/mapsforge/vtm/ext/grib/NativeWeatherOverlaySpec.java

@@ -0,0 +1,95 @@
+
+/**
+ * This code was generated by [react-native-codegen](https://www.npmjs.com/package/react-native-codegen).
+ *
+ * Do not edit this file as changes may cause incorrect behavior and will be lost
+ * once the code is regenerated.
+ *
+ * @generated by codegen project: GenerateModuleJavaSpec.js
+ *
+ * @nolint
+ */
+
+package com.jhotadhari.reactnative.mapsforge.vtm.ext.grib;
+
+import com.facebook.proguard.annotations.DoNotStrip;
+import com.facebook.react.bridge.Promise;
+import com.facebook.react.bridge.ReactApplicationContext;
+import com.facebook.react.bridge.ReactContextBaseJavaModule;
+import com.facebook.react.bridge.ReactMethod;
+import com.facebook.react.bridge.ReadableMap;
+import com.facebook.react.common.build.ReactBuildConfig;
+import com.facebook.react.turbomodule.core.interfaces.TurboModule;
+import java.util.Arrays;
+import java.util.HashSet;
+import java.util.Map;
+import java.util.Set;
+import javax.annotation.Nonnull;
+import javax.annotation.Nullable;
+
+public abstract class NativeWeatherOverlaySpec extends ReactContextBaseJavaModule implements TurboModule {
+  public static final String NAME = "WeatherOverlay";
+
+  public NativeWeatherOverlaySpec(ReactApplicationContext reactContext) {
+    super(reactContext);
+  }
+
+  @Override
+  public @Nonnull String getName() {
+    return NAME;
+  }
+
+  protected abstract Map<String, Object> getTypedExportedConstants();
+
+  @Override
+  @DoNotStrip
+  public final @Nullable Map<String, Object> getConstants() {
+    Map<String, Object> constants = getTypedExportedConstants();
+    if (ReactBuildConfig.DEBUG || ReactBuildConfig.IS_INTERNAL_BUILD) {
+      Set<String> obligatoryFlowConstants = new HashSet<>();
+      Set<String> optionalFlowConstants = new HashSet<>(Arrays.asList(
+          "colorMap",
+          "dataUrl",
+          "enabledZoomMax",
+          "enabledZoomMin",
+          "opacity",
+          "parameter",
+          "timeIndex",
+          "zoomMax",
+          "zoomMin"
+      ));
+      Set<String> undeclaredConstants = new HashSet<>(constants.keySet());
+      undeclaredConstants.removeAll(obligatoryFlowConstants);
+      undeclaredConstants.removeAll(optionalFlowConstants);
+      if (!undeclaredConstants.isEmpty()) {
+        throw new IllegalStateException(String.format("Native Module Flow doesn't declare constants: %s", undeclaredConstants));
+      }
+      undeclaredConstants = obligatoryFlowConstants;
+      undeclaredConstants.removeAll(constants.keySet());
+      if (!undeclaredConstants.isEmpty()) {
+        throw new IllegalStateException(String.format("Native Module doesn't fill in constants: %s", undeclaredConstants));
+      }
+    }
+    return constants;
+  }
+
+  @ReactMethod
+  @DoNotStrip
+  public abstract void createLayer(ReadableMap params, Promise promise);
+
+  @ReactMethod
+  @DoNotStrip
+  public abstract void removeLayer(ReadableMap params, Promise promise);
+
+  @ReactMethod
+  @DoNotStrip
+  public abstract void updateEnabledZoomMinMax(ReadableMap params, Promise promise);
+
+  @ReactMethod
+  @DoNotStrip
+  public abstract void setOpacity(ReadableMap params, Promise promise);
+
+  @ReactMethod
+  @DoNotStrip
+  public abstract void setTimeIndex(ReadableMap params, Promise promise);
+}

package/android/generated/jni/CMakeLists.txt

@@ -0,0 +1,28 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+
+cmake_minimum_required(VERSION 3.13)
+set(CMAKE_VERBOSE_MAKEFILE on)
+
+file(GLOB react_codegen_SRCS CONFIGURE_DEPENDS *.cpp react/renderer/components/RNMapsforgeVtmExtGribSpec/*.cpp)
+
+add_library(
+  react_codegen_RNMapsforgeVtmExtGribSpec
+  OBJECT
+  ${react_codegen_SRCS}
+)
+
+target_include_directories(react_codegen_RNMapsforgeVtmExtGribSpec PUBLIC . react/renderer/components/RNMapsforgeVtmExtGribSpec)
+
+target_link_libraries(
+  react_codegen_RNMapsforgeVtmExtGribSpec
+  fbjni
+  jsi
+  # We need to link different libraries based on whether we are building rncore or not, that's necessary
+  # because we want to break a circular dependency between react_codegen_rncore and reactnative
+  reactnative
+)
+
+target_compile_reactnative_options(react_codegen_RNMapsforgeVtmExtGribSpec PRIVATE)

package/android/generated/jni/RNMapsforgeVtmExtGribSpec-generated.cpp

@@ -0,0 +1,62 @@
+
+/**
+ * This code was generated by [react-native-codegen](https://www.npmjs.com/package/react-native-codegen).
+ *
+ * Do not edit this file as changes may cause incorrect behavior and will be lost
+ * once the code is regenerated.
+ *
+ * @generated by codegen project: GenerateModuleJniCpp.js
+ */
+
+#include "RNMapsforgeVtmExtGribSpec.h"
+
+namespace facebook::react {
+
+static facebook::jsi::Value __hostFunction_NativeWeatherOverlaySpecJSI_getConstants(facebook::jsi::Runtime& rt, TurboModule &turboModule, const facebook::jsi::Value* args, size_t count) {
+  static jmethodID cachedMethodId = nullptr;
+  return static_cast<JavaTurboModule &>(turboModule).invokeJavaMethod(rt, ObjectKind, "getConstants", "()Ljava/util/Map;", args, count, cachedMethodId);
+}
+
+static facebook::jsi::Value __hostFunction_NativeWeatherOverlaySpecJSI_createLayer(facebook::jsi::Runtime& rt, TurboModule &turboModule, const facebook::jsi::Value* args, size_t count) {
+  static jmethodID cachedMethodId = nullptr;
+  return static_cast<JavaTurboModule &>(turboModule).invokeJavaMethod(rt, PromiseKind, "createLayer", "(Lcom/facebook/react/bridge/ReadableMap;Lcom/facebook/react/bridge/Promise;)V", args, count, cachedMethodId);
+}
+
+static facebook::jsi::Value __hostFunction_NativeWeatherOverlaySpecJSI_removeLayer(facebook::jsi::Runtime& rt, TurboModule &turboModule, const facebook::jsi::Value* args, size_t count) {
+  static jmethodID cachedMethodId = nullptr;
+  return static_cast<JavaTurboModule &>(turboModule).invokeJavaMethod(rt, PromiseKind, "removeLayer", "(Lcom/facebook/react/bridge/ReadableMap;Lcom/facebook/react/bridge/Promise;)V", args, count, cachedMethodId);
+}
+
+static facebook::jsi::Value __hostFunction_NativeWeatherOverlaySpecJSI_updateEnabledZoomMinMax(facebook::jsi::Runtime& rt, TurboModule &turboModule, const facebook::jsi::Value* args, size_t count) {
+  static jmethodID cachedMethodId = nullptr;
+  return static_cast<JavaTurboModule &>(turboModule).invokeJavaMethod(rt, PromiseKind, "updateEnabledZoomMinMax", "(Lcom/facebook/react/bridge/ReadableMap;Lcom/facebook/react/bridge/Promise;)V", args, count, cachedMethodId);
+}
+
+static facebook::jsi::Value __hostFunction_NativeWeatherOverlaySpecJSI_setOpacity(facebook::jsi::Runtime& rt, TurboModule &turboModule, const facebook::jsi::Value* args, size_t count) {
+  static jmethodID cachedMethodId = nullptr;
+  return static_cast<JavaTurboModule &>(turboModule).invokeJavaMethod(rt, PromiseKind, "setOpacity", "(Lcom/facebook/react/bridge/ReadableMap;Lcom/facebook/react/bridge/Promise;)V", args, count, cachedMethodId);
+}
+
+static facebook::jsi::Value __hostFunction_NativeWeatherOverlaySpecJSI_setTimeIndex(facebook::jsi::Runtime& rt, TurboModule &turboModule, const facebook::jsi::Value* args, size_t count) {
+  static jmethodID cachedMethodId = nullptr;
+  return static_cast<JavaTurboModule &>(turboModule).invokeJavaMethod(rt, PromiseKind, "setTimeIndex", "(Lcom/facebook/react/bridge/ReadableMap;Lcom/facebook/react/bridge/Promise;)V", args, count, cachedMethodId);
+}
+
+NativeWeatherOverlaySpecJSI::NativeWeatherOverlaySpecJSI(const JavaTurboModule::InitParams &params)
+  : JavaTurboModule(params) {
+  methodMap_["getConstants"] = MethodMetadata {0, __hostFunction_NativeWeatherOverlaySpecJSI_getConstants};
+  methodMap_["createLayer"] = MethodMetadata {1, __hostFunction_NativeWeatherOverlaySpecJSI_createLayer};
+  methodMap_["removeLayer"] = MethodMetadata {1, __hostFunction_NativeWeatherOverlaySpecJSI_removeLayer};
+  methodMap_["updateEnabledZoomMinMax"] = MethodMetadata {1, __hostFunction_NativeWeatherOverlaySpecJSI_updateEnabledZoomMinMax};
+  methodMap_["setOpacity"] = MethodMetadata {1, __hostFunction_NativeWeatherOverlaySpecJSI_setOpacity};
+  methodMap_["setTimeIndex"] = MethodMetadata {1, __hostFunction_NativeWeatherOverlaySpecJSI_setTimeIndex};
+}
+
+std::shared_ptr<TurboModule> RNMapsforgeVtmExtGribSpec_ModuleProvider(const std::string &moduleName, const JavaTurboModule::InitParams &params) {
+  if (moduleName == "WeatherOverlay") {
+    return std::make_shared<NativeWeatherOverlaySpecJSI>(params);
+  }
+  return nullptr;
+}
+
+} // namespace facebook::react

package/android/generated/jni/RNMapsforgeVtmExtGribSpec.h

@@ -0,0 +1,31 @@
+
+/**
+ * This code was generated by [react-native-codegen](https://www.npmjs.com/package/react-native-codegen).
+ *
+ * Do not edit this file as changes may cause incorrect behavior and will be lost
+ * once the code is regenerated.
+ *
+ * @generated by codegen project: GenerateModuleJniH.js
+ */
+
+#pragma once
+
+#include <ReactCommon/JavaTurboModule.h>
+#include <ReactCommon/TurboModule.h>
+#include <jsi/jsi.h>
+
+namespace facebook::react {
+
+/**
+ * JNI C++ class for module 'NativeWeatherOverlay'
+ */
+class JSI_EXPORT NativeWeatherOverlaySpecJSI : public JavaTurboModule {
+public:
+  NativeWeatherOverlaySpecJSI(const JavaTurboModule::InitParams &params);
+};
+
+
+JSI_EXPORT
+std::shared_ptr<TurboModule> RNMapsforgeVtmExtGribSpec_ModuleProvider(const std::string &moduleName, const JavaTurboModule::InitParams &params);
+
+} // namespace facebook::react