react-native-cesium 1.2.0 → 1.2.2

package/README.md

@@ -399,11 +399,11 @@ Avoid assuming **main-thread-only** vs **JS-thread-only** labels beyond the abov
 
 #### Smoothing of incoming camera updates
 
-Every value you pass to `setCamera` / `setCameraQuaternion` is treated as a **demand** target — what you would *like* the camera to be — rather than a per-frame command. The native render thread runs an exponential filter every frame that converges the displayed camera onto your demand target, which means a coarse 1 Hz position feed (e.g. external GPS) does **not** teleport the view once a second. Instead it eases between samples.
+Every value you pass to `setCamera` / `setCameraQuaternion` is treated as a **demand** target — what you would *like* the camera to be — rather than a per-frame command. The native render thread interpolates the displayed camera toward your demand target every frame, which means a coarse 1 Hz position feed (e.g. external GPS) does **not** teleport the view once a second. Instead it moves at constant speed — exactly like looking out the window of the vehicle being tracked.
 
 | DoF | Smoothing |
 | --- | --- |
-| `latitude` / `longitude` | **Adaptive** exponential filter. Time constant `τ = clamp(α · ewmaInterval, τmin, τmax)` where `ewmaInterval` tracks the cadence of your `setCamera` calls. ~60 Hz gestures collapse `τ` to the floor (≤1 frame of trail, indistinguishable from the previous "snap" behaviour); ~1 Hz GPS feeds expand `τ` so each sample is ~95 % converged before the next arrives. Cross-planet jumps (Δ > ~0.5°) bypass the smoother and snap, so a deliberate teleport stays instant. Antimeridian crossings always rotate the short way. |
+| `latitude` / `longitude` | **Linear interpolation** at constant speed between position fixes. When a new lat/lon arrives, the native engine records the previous target as the "from" position and linearly lerps toward the new target over the EWMA inter-arrival interval (e.g. a 1 Hz GPS feed gives a 1 s travel time, so the camera moves at exactly the vehicle's speed between fixes). At 60 Hz gestures the interval collapses to ~16 ms making the interpolation indistinguishable from an instant snap. Cross-planet jumps (Δ > ~0.5°) bypass interpolation so deliberate teleports remain instant. Antimeridian crossings always rotate the short way. |
 | `altitude` | Exponential, fixed `τ ≈ 40 ms`. |
 | `heading` / `pitch` / `roll` | Exponential on the shortest-arc angular delta, fixed `τ ≈ 20–33 ms`. |
 | `viewCorrection` (quaternion) | SLERP-based exponential, fixed `τ ≈ 20 ms`, hemisphere-corrected so it always takes the short rotation. |

package/android/src/main/cpp/CesiumBridgeAndroid.cpp

@@ -2,6 +2,7 @@
 
 #include "engine/CameraSmoother.hpp"
 #include "engine/EngineTunables.hpp"
+#include "engine/GeoidConverter.hpp"
 #include "vulkan/VulkanBackend.h"
 
 #include <android/native_window_jni.h>
@@ -198,6 +199,10 @@ void CesiumBridgeAndroid::setTaskProcessorThreads(int32_t v) {
   // initialize().
   config_.taskProcessorThreads = std::max(0, v);
 }
+void CesiumBridgeAndroid::setMinAltitudeAboveTerrain(float v) {
+  config_.minAltitudeAboveTerrain = std::max(0.0f, v);
+  if (initialized_) applyEngineConfig();
+}
 
 void CesiumBridgeAndroid::markNeedsRender() { target_.requestForceRender(); }
 
@@ -239,8 +244,22 @@ void CesiumBridgeAndroid::renderFrame(double dt) {
 
   const auto cur    = engine_->camera().getParams();
   const auto tgt    = target_.snapshot();
-  const auto smooth = reactnativecesium::CameraSmoother::step(
-      cur, tgt, dt, target_.recentIntervalSec());
+  auto smooth = reactnativecesium::CameraSmoother::step(cur, tgt, dt);
+
+  // ── Terrain floor clamp ───────────────────────────────────────────────
+  const float minAbove = engine_->getConfig().minAltitudeAboveTerrain;
+  if (minAbove > 0.0f) {
+    const double geoidOffset =
+        reactnativecesium::mslToEllipsoidMeters(smooth.latitude, smooth.longitude, 0.0);
+    const double camEllipsoid =
+        reactnativecesium::mslToEllipsoidMeters(smooth.latitude, smooth.longitude, smooth.altitude);
+    const double minEllipsoid =
+        static_cast<double>(engine_->terrainFloorEllipsoidMeters()) + minAbove;
+    if (camEllipsoid < minEllipsoid) {
+      smooth.altitude = minEllipsoid - geoidOffset;
+    }
+  }
+
   engine_->camera().setParams(smooth);
 
   // If we converged, clear the dirty flag so the next idle vsync can early-out.
@@ -540,5 +559,9 @@ JNIEXPORT void JNICALL
 Java_com_margelo_nitro_reactnativecesium_CesiumBridgeJNI_nativeSetTaskProcessorThreads(JNIEnv*, jobject, jlong ptr, jint v) {
   getBridge(ptr)->setTaskProcessorThreads(v);
 }
+JNIEXPORT void JNICALL
+Java_com_margelo_nitro_reactnativecesium_CesiumBridgeJNI_nativeSetMinAltitudeAboveTerrain(JNIEnv*, jobject, jlong ptr, jfloat v) {
+  getBridge(ptr)->setMinAltitudeAboveTerrain(v);
+}
 
 } // extern "C"

package/android/src/main/cpp/CesiumBridgeAndroid.h

@@ -52,6 +52,7 @@ struct CesiumBridgeAndroid {
   void setLodTransitionLength(double v);
   void setSqliteCacheMaxRows(int32_t v);
   void setTaskProcessorThreads(int32_t v);
+  void setMinAltitudeAboveTerrain(float v);
 
   void markNeedsRender();
   bool shouldRenderNextFrame();

package/android/src/main/java/com/margelo/nitro/reactnativecesium/CesiumBridgeJNI.kt

@@ -82,6 +82,7 @@ class CesiumBridgeJNI {
   fun setLodTransitionLength(v: Double) = nativeSetLodTransitionLength(nativePtr, v)
   fun setSqliteCacheMaxRows(v: Int) = nativeSetSqliteCacheMaxRows(nativePtr, v)
   fun setTaskProcessorThreads(v: Int) = nativeSetTaskProcessorThreads(nativePtr, v)
+  fun setMinAltitudeAboveTerrain(v: Float) = nativeSetMinAltitudeAboveTerrain(nativePtr, v)
 
   private external fun nativeCreate(): Long
   private external fun nativeInit(ptr: Long, surface: Surface, w: Int, h: Int, cacheDir: String, cacertPath: String)
@@ -144,4 +145,5 @@ class CesiumBridgeJNI {
   private external fun nativeSetLodTransitionLength(ptr: Long, v: Double)
   private external fun nativeSetSqliteCacheMaxRows(ptr: Long, v: Int)
   private external fun nativeSetTaskProcessorThreads(ptr: Long, v: Int)
+  private external fun nativeSetMinAltitudeAboveTerrain(ptr: Long, v: Float)
 }

package/android/src/main/java/com/margelo/nitro/reactnativecesium/HybridCesiumView.kt

@@ -120,6 +120,8 @@ class HybridCesiumView(private val appContext: Context) : HybridCesiumViewSpec()
     set(value) { field = value; if (value != null) postToRender { bridge?.setSqliteCacheMaxRows(value.toInt()) } }
   override var taskProcessorThreads: Double? = null
     set(value) { field = value; if (value != null) postToRender { bridge?.setTaskProcessorThreads(value.toInt()) } }
+  override var minAltitudeAboveTerrain: Double? = null
+    set(value) { field = value; if (value != null) postToRender { bridge?.setMinAltitudeAboveTerrain(value.toFloat()) } }
 
   override var onMetrics: ((metrics: CesiumMetrics) -> Unit)? = null
 
@@ -476,6 +478,7 @@ class HybridCesiumView(private val appContext: Context) : HybridCesiumViewSpec()
     lodTransitionLength?.let { b.setLodTransitionLength(it) }
     sqliteCacheMaxRows?.let { b.setSqliteCacheMaxRows(it.toInt()) }
     taskProcessorThreads?.let { b.setTaskProcessorThreads(it.toInt()) }
+    minAltitudeAboveTerrain?.let { b.setMinAltitudeAboveTerrain(it.toFloat()) }
   }
 
   /**

package/cpp/engine/CameraSmoother.cpp

@@ -2,7 +2,6 @@
 
 #include "EngineTunables.hpp"
 
-#include <algorithm>
 #include <cmath>
 
 namespace reactnativecesium {
@@ -24,40 +23,18 @@ inline double quatDotAbs(const glm::dquat& a, const glm::dquat& b) {
   return std::abs(glm::dot(glm::normalize(a), glm::normalize(b)));
 }
 
-inline double wrapLonDeltaDeg(double a, double b) {
-  return std::fmod(b - a + 540.0, 360.0) - 180.0;
-}
-
 } // namespace
 
 CameraParams CameraSmoother::step(
-    const CameraParams& current, const CameraParams& target, double dt,
-    double recentIntervalSec) {
+    const CameraParams& current, const CameraParams& target, double dt) {
   CameraParams next = current;
 
-  // ── lat/lon: adaptive exponential smoothing ─────────────────────────────
-  // τ scales with the cadence of incoming setCamera calls so gestures feel
-  // instant (τ at the floor) while sparse GPS-rate updates ease across each
-  // interval (τ near the ceiling).
-  const double tau  = std::clamp(
-      tunables::kSmoothPositionAlpha * recentIntervalSec,
-      tunables::kSmoothPositionTauMin,
-      tunables::kSmoothPositionTauMax);
-  const double aPos = 1.0 - std::exp(-dt / tau);
-
-  const double dLat = target.latitude - current.latitude;
-  const double dLon = wrapLonDeltaDeg(current.longitude, target.longitude);
-  const bool snapThrough =
-      std::abs(dLat) > tunables::kPosSnapThroughDeg ||
-      std::abs(dLon) > tunables::kPosSnapThroughDeg;
-
-  if (snapThrough) {
-    next.latitude  = target.latitude;
-    next.longitude = target.longitude;
-  } else {
-    next.latitude  = current.latitude + aPos * dLat;
-    next.longitude = lerpAngleDeg(current.longitude, target.longitude, aPos);
-  }
+  // lat/lon: snap directly to the target.
+  // CameraTargetState::snapshot() already produces a linearly-interpolated
+  // position that advances at constant speed between position fixes, so
+  // snapping here gives smooth, constant-velocity motion with no ease-in/out.
+  next.latitude  = target.latitude;
+  next.longitude = target.longitude;
 
   const double aAlt   = 1.0 - std::exp(-tunables::kSmoothAltitude * dt);
   const double aHdg   = 1.0 - std::exp(-tunables::kSmoothHeading  * dt);
@@ -76,11 +53,6 @@ CameraParams CameraSmoother::step(
   next.viewCorrection = glm::normalize(glm::slerp(cq, tq, aViewQ));
 
   // Eventually-exact convergence: snap once the residual is sub-epsilon.
-  if (std::abs(target.latitude - next.latitude) <= tunables::kEpsLatLon)
-    next.latitude = target.latitude;
-  if (std::abs(wrapLonDeltaDeg(next.longitude, target.longitude))
-        <= tunables::kEpsLatLon)
-    next.longitude = target.longitude;
   if (std::abs(target.altitude - next.altitude) <= tunables::kEpsAltitudeMeters)
     next.altitude = target.altitude;
   if (angleDeltaAbsDeg(next.heading, target.heading) <= tunables::kEpsAngleDeg)

package/cpp/engine/CameraSmoother.hpp

@@ -8,12 +8,9 @@ namespace reactnativecesium {
 // returns the next camera state for a frame of duration `dt` seconds.
 //
 // Per-DoF smoothing rules:
-//   - lat / lon: adaptive exponential smoothing `1 - exp(-dt/τ)` where
-//     τ = clamp(α · recentIntervalSec, τmin, τmax). High update rates (60 Hz
-//     gestures) drive τ to the floor so the camera tracks the finger without
-//     perceptible lag; sparse updates (1 Hz GPS) widen τ so each sample
-//     interpolates smoothly across its interval. Snap-through guard for
-//     genuine teleports keeps cross-planet `setCamera` jumps instant.
+//   - lat / lon: snapped directly to target. The target itself is already a
+//     linearly-interpolated position produced by CameraTargetState::snapshot(),
+//     so snapping here gives constant-velocity motion between position fixes.
 //   - altitude / heading / pitch / roll / viewCorrection: exponential decay
 //     `1 - exp(-k * dt)` per DoF with k taken from EngineTunables.
 //   - When the delta drops below the matching epsilon, the value is snapped
@@ -22,8 +19,7 @@ class CameraSmoother {
 public:
   static CameraParams step(const CameraParams& current,
                            const CameraParams& target,
-                           double dt,
-                           double recentIntervalSec);
+                           double dt);
 };
 
 } // namespace reactnativecesium

package/cpp/engine/CameraTargetState.cpp

@@ -1,18 +1,130 @@
 #include "CameraTargetState.hpp"
 
+#include <algorithm>
 #include <cmath>
 
 namespace reactnativecesium {
 
 namespace {
+
 inline double angleDeltaAbsDeg(double a, double b) {
   return std::abs(std::fmod(b - a + 540.0, 360.0) - 180.0);
 }
+
 inline double quatDotAbs(const glm::dquat& a, const glm::dquat& b) {
   return std::abs(glm::dot(glm::normalize(a), glm::normalize(b)));
 }
+
+// Shortest signed angular delta for longitude, wrapped to [-180, 180].
+inline double lonDeltaDeg(double from, double to) {
+  return std::fmod(to - from + 540.0, 360.0) - 180.0;
+}
+
 } // namespace
 
+// ── Public writers ────────────────────────────────────────────────────────────
+
+void CameraTargetState::setAll(const CameraParams& target) {
+  {
+    std::lock_guard<std::mutex> g(mutex_);
+    target_ = target;
+    // Deliberately do NOT touch interpolation state: setAll is engine-init only
+    // and the first frame must snap to the requested position immediately.
+  }
+  dirty_.store(true, std::memory_order_release);
+  forceRender_.store(true, std::memory_order_release);
+}
+
+void CameraTargetState::setHpr(double lat, double lon, double alt,
+                                double heading, double pitch, double roll) {
+  {
+    std::lock_guard<std::mutex> g(mutex_);
+
+    const bool posChanged =
+        std::abs(lat - target_.latitude)  > tunables::kEpsLatLon ||
+        std::abs(lon - target_.longitude) > tunables::kEpsLatLon;
+
+    if (posChanged) {
+      const auto now = std::chrono::steady_clock::now();
+
+      if (!hasInterpolation_) {
+        // First runtime lat/lon update: seed posFrom = destination so that
+        // lerp(dest, dest, t) = dest for all t — clean snap, no startup glide.
+        posFromLat_       = lat;
+        posFromLon_       = lon;
+        ewmaIntervalSec_  = tunables::kSmoothPositionTauMax / tunables::kSmoothPositionAlpha;
+        posUpdateTime_    = now;
+        hasInterpolation_ = true;
+      } else {
+        // Subsequent update: record where we're moving FROM (the previous
+        // target), update the EWMA interval, and reset the clock.
+        posFromLat_ = target_.latitude;
+        posFromLon_ = target_.longitude;
+
+        const double dt = std::chrono::duration<double>(now - posUpdateTime_).count();
+        if (dt > 0.0) {
+          ewmaIntervalSec_ = ewmaIntervalSec_ +
+              tunables::kEwmaIntervalAlpha * (dt - ewmaIntervalSec_);
+        }
+        posUpdateTime_ = now;
+      }
+    }
+
+    target_.latitude  = lat;
+    target_.longitude = lon;
+    target_.altitude  = alt;
+    target_.heading   = heading;
+    target_.pitch     = pitch;
+    target_.roll      = roll;
+  }
+  dirty_.store(true, std::memory_order_release);
+  forceRender_.store(true, std::memory_order_release);
+}
+
+void CameraTargetState::setViewCorrection(const glm::dquat& q) {
+  {
+    std::lock_guard<std::mutex> g(mutex_);
+    target_.viewCorrection = q;
+    // Position cadence intentionally NOT updated — viewCorrection changes
+    // carry no lat/lon information and must not affect the interpolation window.
+  }
+  dirty_.store(true, std::memory_order_release);
+  forceRender_.store(true, std::memory_order_release);
+}
+
+// ── Snapshot (render-thread read) ─────────────────────────────────────────────
+
+CameraParams CameraTargetState::snapshot() const {
+  const auto now = std::chrono::steady_clock::now();
+  std::lock_guard<std::mutex> g(mutex_);
+
+  CameraParams result = target_;
+
+  if (hasInterpolation_ && ewmaIntervalSec_ > 0.0) {
+    const double dLat = target_.latitude - posFromLat_;
+    const double dLon = lonDeltaDeg(posFromLon_, target_.longitude);
+
+    // Snap-through guard: genuine teleports (setCamera(NewYork → Tokyo)) bypass
+    // the interpolation so they remain instant rather than gliding across the planet.
+    const bool snapThrough =
+        std::abs(dLat) > tunables::kPosSnapThroughDeg ||
+        std::abs(dLon) > tunables::kPosSnapThroughDeg;
+
+    if (!snapThrough) {
+      const double elapsed =
+          std::chrono::duration<double>(now - posUpdateTime_).count();
+      const double t = std::min(elapsed / ewmaIntervalSec_, 1.0);
+
+      result.latitude  = posFromLat_ + t * dLat;
+      result.longitude = posFromLon_ + t * dLon;
+    }
+  }
+
+  return result;
+}
+
+// ── Epsilon check (shared) ────────────────────────────────────────────────────
+
 bool CameraTargetState::deltaExceedsEpsilon(
     const CameraParams& a, const CameraParams& b) {
   return std::abs(a.latitude  - b.latitude)  > tunables::kEpsLatLon
@@ -25,25 +137,4 @@ bool CameraTargetState::deltaExceedsEpsilon(
              > tunables::kEpsQuatDot;
 }
 
-void CameraTargetState::noteUpdateCadence() noexcept {
-  const auto now = std::chrono::steady_clock::now();
-  if (!hasLastUpdate_) {
-    // Seed the EWMA with τmax so the first sample after a quiet period uses
-    // the full smoothing budget rather than the floor (5 ms ≈ snap).
-    ewmaIntervalSec_.store(tunables::kSmoothPositionTauMax / tunables::kSmoothPositionAlpha,
-                           std::memory_order_release);
-    lastUpdateTime_ = now;
-    hasLastUpdate_  = true;
-    return;
-  }
-
-  const double dt = std::chrono::duration<double>(now - lastUpdateTime_).count();
-  lastUpdateTime_ = now;
-  if (dt <= 0.0) return; // back-to-back writes from the same frame: ignore.
-
-  const double prev = ewmaIntervalSec_.load(std::memory_order_relaxed);
-  const double next = prev + tunables::kEwmaIntervalAlpha * (dt - prev);
-  ewmaIntervalSec_.store(next, std::memory_order_release);
-}
-
 } // namespace reactnativecesium

package/cpp/engine/CameraTargetState.hpp

@@ -21,54 +21,43 @@ namespace reactnativecesium {
 //
 // `dirty_` and `forceRender_` are independent atomic flags so the read side can
 // poll without taking the lock when the camera has not moved.
+//
+// Lat/lon interpolation
+// ─────────────────────
+// When setHpr is called with a new lat/lon, `posFrom` (old target) and
+// `posUpdateTime` are recorded inside the mutex. snapshot() then linearly
+// interpolates posFrom → target over `ewmaIntervalSec` (EWMA of inter-arrival
+// times). This produces constant-velocity motion between position fixes —
+// realistic for any vehicle/GPS source — without any changes to the public API.
+//
+// Special cases handled in snapshot():
+//   - t >= 1 : camera has reached the target, returns target_ directly.
+//   - Snap-through guard: deltas > kPosSnapThroughDeg bypass interpolation so
+//     deliberate teleports (setCamera(NewYork → Tokyo)) remain instant.
+//   - First setHpr for a given lat/lon: posFrom is set to the *destination*
+//     so lerp(dest, dest, t) = dest — no startup glide.
+//   - setAll (initialisation only): does not touch interpolation state; always
+//     snaps directly.
 class CameraTargetState {
 public:
   CameraTargetState() = default;
 
-  // Replace the entire target (does not touch viewCorrection if you want to
-  // preserve it — use setHpr instead).
-  void setAll(const CameraParams& target) {
-    {
-      std::lock_guard<std::mutex> g(mutex_);
-      target_ = target;
-    }
-    noteUpdateCadence();
-    dirty_.store(true, std::memory_order_release);
-    forceRender_.store(true, std::memory_order_release);
-  }
+  // Replace the entire target. Used only for engine initialisation; does NOT
+  // update position-interpolation state so the first rendered frame snaps.
+  void setAll(const CameraParams& target);
 
   // Update lat/lon/alt + heading/pitch/roll, leaving viewCorrection unchanged.
+  // When lat/lon actually changes, updates the linear-interpolation bookkeeping.
   void setHpr(double lat, double lon, double alt,
-              double heading, double pitch, double roll) {
-    {
-      std::lock_guard<std::mutex> g(mutex_);
-      target_.latitude  = lat;
-      target_.longitude = lon;
-      target_.altitude  = alt;
-      target_.heading   = heading;
-      target_.pitch     = pitch;
-      target_.roll      = roll;
-    }
-    noteUpdateCadence();
-    dirty_.store(true, std::memory_order_release);
-    forceRender_.store(true, std::memory_order_release);
-  }
+              double heading, double pitch, double roll);
 
-  void setViewCorrection(const glm::dquat& q) {
-    {
-      std::lock_guard<std::mutex> g(mutex_);
-      target_.viewCorrection = q;
-    }
-    noteUpdateCadence();
-    dirty_.store(true, std::memory_order_release);
-    forceRender_.store(true, std::memory_order_release);
-  }
+  void setViewCorrection(const glm::dquat& q);
 
-  // Snapshot the demand target (read side; one mutex per frame).
-  CameraParams snapshot() const {
-    std::lock_guard<std::mutex> g(mutex_);
-    return target_;
-  }
+  // Snapshot the demand target for this render frame.  Lat/lon are linearly
+  // interpolated between the previous target (posFrom) and the current target
+  // over the EWMA inter-arrival interval.  All other DoFs are returned as-is
+  // (the smoother handles their exponential curves).
+  CameraParams snapshot() const;
 
   // Lightweight, lock-free check used by the render thread to decide whether
   // it should bother taking a full snapshot at all.
@@ -91,31 +80,24 @@ public:
   // whether to render this frame.
   static bool deltaExceedsEpsilon(const CameraParams& a, const CameraParams& b);
 
-  // EWMA of the inter-arrival interval (seconds) of demand updates. Used by
-  // CameraSmoother to scale the lat/lon time constant: high update rate ⇒
-  // tiny τ (snappy gestures); low update rate ⇒ larger τ (smooth GPS catch-up).
-  // Lock-free read on the render-thread hot path.
-  double recentIntervalSec() const noexcept {
-    return ewmaIntervalSec_.load(std::memory_order_acquire);
-  }
-
 private:
-  // Folds the time since the previous demand update into ewmaIntervalSec_.
-  // Called under (or after) the target_ mutex; the EWMA itself is atomic so
-  // the read side never blocks. Writes are uncontended (only JS-thread).
-  void noteUpdateCadence() noexcept;
-
   mutable std::mutex mutex_;
   CameraParams target_;
   std::atomic<bool> dirty_{false};
   std::atomic<bool> forceRender_{true};
 
-  // Cadence tracker. lastUpdateTime_ is only touched on the writer (JS)
-  // thread, so it does not need synchronisation; ewmaIntervalSec_ is read
-  // by the render thread without taking the mutex.
-  std::chrono::steady_clock::time_point lastUpdateTime_{};
-  bool                                  hasLastUpdate_{false};
-  std::atomic<double>                   ewmaIntervalSec_{0.0};
+  // ── Lat/lon linear interpolation state (all protected by mutex_) ──────────
+  // posFromLat_/posFromLon_: the target position when the last update arrived
+  //   (i.e. where we are smoothly moving FROM).
+  // posUpdateTime_:          wall-clock time of the last lat/lon change.
+  // ewmaIntervalSec_:        EWMA of inter-arrival times of lat/lon changes.
+  // hasInterpolation_:       true once we have valid posFrom + posUpdateTime
+  //                          data (false until the second distinct lat/lon value).
+  double                                 posFromLat_{0.0};
+  double                                 posFromLon_{0.0};
+  std::chrono::steady_clock::time_point  posUpdateTime_{};
+  double                                 ewmaIntervalSec_{0.0};
+  bool                                   hasInterpolation_{false};
 };
 
 } // namespace reactnativecesium

package/cpp/engine/CesiumEngine.cpp

@@ -455,6 +455,16 @@ void CesiumEngine::updateFrame(double w, double h, FrameResult& result) {
     }
   }
 
+  // ── Terrain floor tracking (for minAltitudeAboveTerrain clamp) ───────────
+  // Computed once before the tile loop and updated per-tile inside it.
+  // Only active when the feature is enabled to avoid any overhead otherwise.
+  const bool trackTerrainFloor = (config_.minAltitudeAboveTerrain > 0.0f);
+  const CameraParams camParams  = trackTerrainFloor ? camera_.getParams() : CameraParams{};
+  const double camLatRad = glm::radians(camParams.latitude);
+  const double camLonRad = glm::radians(camParams.longitude);
+  float  bestTerrainFloor = terrainFloorEllipsoidM_; // carry previous value if no tile matches
+  double bestTerrainDist  = std::numeric_limits<double>::max();
+
   for (const auto& tile : updateResult.tilesToRenderThisFrame) {
     if (!tile) continue;
 
@@ -478,6 +488,24 @@ void CesiumEngine::updateFrame(double w, double h, FrameResult& result) {
           static_cast<float>(rect.getSouth()),
           static_cast<float>(rect.getEast()),
           static_cast<float>(rect.getNorth()));
+
+      // ── Terrain floor: find nearest vertex to camera nadir ────────────
+      if (trackTerrainFloor &&
+          rect.contains(CesiumGeospatial::Cartographic(camLonRad, camLatRad, 0.0))) {
+        for (const auto& prim : res->primitives) {
+          if (prim.altitudes.empty() || prim.localPositions.empty()) continue;
+          const size_t vertexCount = prim.localPositions.size();
+          for (size_t vi = 0; vi < vertexCount; ++vi) {
+            const glm::dvec3 vECEF =
+                glm::dvec3(prim.localPositions[vi]) + prim.rtcCenter;
+            const double dist = glm::length(vECEF - cameraPos);
+            if (dist < bestTerrainDist) {
+              bestTerrainDist  = dist;
+              bestTerrainFloor = prim.altitudes[vi];
+            }
+          }
+        }
+      }
     }
 
     for (const auto& prim : res->primitives) {
@@ -553,6 +581,10 @@ void CesiumEngine::updateFrame(double w, double h, FrameResult& result) {
   result.cameraLon     = params.longitude;
   result.cameraAlt     = params.altitude;
 
+  if (trackTerrainFloor) {
+    terrainFloorEllipsoidM_ = bestTerrainFloor;
+  }
+
   lifecycle_.advanceFrame();
 }
 

package/cpp/engine/CesiumEngine.hpp

@@ -78,6 +78,11 @@ struct EngineConfig {
   // 0 means "auto-detect" via std::thread::hardware_concurrency() clamped to
   // [2, 8]. Override only for benchmarking / regression testing.
   int32_t taskProcessorThreads = 0;
+
+  // ── Camera constraints ───────────────────────────────────────────────
+  // Minimum altitude above the loaded terrain surface (metres MSL).
+  // 0 = no constraint (default). Typical use: 2.0 to prevent going underground.
+  float minAltitudeAboveTerrain = 0.0f;
 };
 
 class CesiumEngine {
@@ -112,6 +117,13 @@ public:
   bool tilesetReady() const { return tileset_ != nullptr; }
   int64_t currentImageryAssetId() const { return currentImageryAssetId_; }
 
+  const EngineConfig& getConfig() const { return config_; }
+
+  // Ellipsoid height (metres) of the terrain vertex nearest to the camera nadir,
+  // updated each frame from the loaded tile mesh. 0.0 until the first terrain
+  // tile covering the camera position has been rendered.
+  float terrainFloorEllipsoidMeters() const { return terrainFloorEllipsoidM_; }
+
 private:
   void createTileset();
   void destroyTileset();
@@ -149,6 +161,10 @@ private:
   GlobeCamera          camera_;
   TileLifecycleManager lifecycle_;
 
+  // Ellipsoid height of the terrain surface at the camera nadir, updated each
+  // frame. Initialised to 0 (sea level) until a terrain tile is first loaded.
+  float terrainFloorEllipsoidM_ = 0.0f;
+
   // Pre-computed fallback ellipsoid geometry (ECEF, absolute).
   std::vector<glm::dvec3> ellipsoidPositions_;
   std::vector<uint32_t>   ellipsoidIndices_;

package/ios/CesiumBridge.h

@@ -61,6 +61,7 @@ NS_ASSUME_NONNULL_BEGIN
 - (void)setLodTransitionLength:(double)v;
 - (void)setSqliteCacheMaxRows:(int32_t)v;
 - (void)setTaskProcessorThreads:(int32_t)v;
+- (void)setMinAltitudeAboveTerrain:(float)v;
 
 /// Throttled metrics consumed by the Swift hybrid view.
 @property (nonatomic, readonly) double metricsFps;

package/ios/CesiumBridge.mm

@@ -5,6 +5,7 @@
 #include "engine/CameraTargetState.hpp"
 #include "engine/CesiumEngine.hpp"
 #include "engine/EngineTunables.hpp"
+#include "engine/GeoidConverter.hpp"
 #include "engine/MetricsAggregator.hpp"
 #include "metal/MetalBackend.h"
 
@@ -237,6 +238,11 @@
 - (void)setTaskProcessorThreads:(int32_t)v {
   _config.taskProcessorThreads = std::max<int32_t>(0, v);
 }
+- (void)setMinAltitudeAboveTerrain:(float)v {
+  _config.minAltitudeAboveTerrain = std::max(0.0f, v);
+  if (_engine) _engine->updateConfig(_config);
+  _target.requestForceRender();
+}
 
 - (void)setMsaaSampleCount:(int)samples {
   if (_metalBackend) _metalBackend->setMsaaSampleCount(samples);
@@ -271,8 +277,24 @@
 
     const auto cur    = _engine->camera().getParams();
     const auto tgt    = _target.snapshot();
-    const auto smooth = reactnativecesium::CameraSmoother::step(
-        cur, tgt, dt, _target.recentIntervalSec());
+    auto smooth = reactnativecesium::CameraSmoother::step(cur, tgt, dt);
+
+    // ── Terrain floor clamp ───────────────────────────────────────────────
+    // Uses terrain floor from the previous frame (one-frame lag is
+    // imperceptible at 60 fps). Skipped when minAltitudeAboveTerrain == 0.
+    const float minAbove = _engine->getConfig().minAltitudeAboveTerrain;
+    if (minAbove > 0.0f) {
+      const double geoidOffset =
+          reactnativecesium::mslToEllipsoidMeters(smooth.latitude, smooth.longitude, 0.0);
+      const double camEllipsoid =
+          reactnativecesium::mslToEllipsoidMeters(smooth.latitude, smooth.longitude, smooth.altitude);
+      const double minEllipsoid =
+          static_cast<double>(_engine->terrainFloorEllipsoidMeters()) + minAbove;
+      if (camEllipsoid < minEllipsoid) {
+        smooth.altitude = minEllipsoid - geoidOffset;
+      }
+    }
+
     _engine->camera().setParams(smooth);
 
     if (!reactnativecesium::CameraTargetState::deltaExceedsEpsilon(smooth, tgt)) {

package/ios/HybridCesiumView.swift

@@ -101,6 +101,9 @@ class HybridCesiumView: HybridCesiumViewSpec {
   var taskProcessorThreads: Double? {
     didSet { if let v = taskProcessorThreads { postToRender { [weak self] in self?.bridge?.setTaskProcessorThreads(Int32(v)) } } }
   }
+  var minAltitudeAboveTerrain: Double? {
+    didSet { if let v = minAltitudeAboveTerrain { postToRender { [weak self] in self?.bridge?.setMinAltitudeAboveTerrain(Float(v)) } } }
+  }
 
   // MARK: - Render-thread dispatch helper
 
@@ -319,6 +322,7 @@ class HybridCesiumView: HybridCesiumViewSpec {
     if let v = lodTransitionLength { bridge?.setLodTransitionLength(v) }
     if let v = sqliteCacheMaxRows { bridge?.setSqliteCacheMaxRows(Int32(v)) }
     if let v = taskProcessorThreads { bridge?.setTaskProcessorThreads(Int32(v)) }
+    if let v = minAltitudeAboveTerrain { bridge?.setMinAltitudeAboveTerrain(Float(v)) }
   }
 
   /// Pushes camera state into native bridge only when values changed.

package/lib/typescript/src/specs/cesium-view.nitro.d.ts

@@ -67,6 +67,13 @@ export interface CesiumViewProps extends HybridViewProps {
     sqliteCacheMaxRows?: number;
     /** Worker thread count. 0 = auto (hardware_concurrency-1, clamped 2..8). */
     taskProcessorThreads?: number;
+    /**
+     * Minimum altitude above the loaded terrain surface, in metres MSL.
+     * Default 0 (no constraint). Set to e.g. 2 to prevent the camera from going underground.
+     * The clamp is applied every frame in native, based on the altitude of the nearest
+     * terrain mesh vertex to the camera nadir.
+     */
+    minAltitudeAboveTerrain?: number;
     onMetrics?: (metrics: CesiumMetrics) => void;
 }
 export interface CesiumViewMethods extends HybridViewMethods {

package/lib/typescript/src/specs/cesium-view.nitro.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cesium-view.nitro.d.ts","sourceRoot":"","sources":["../../../../src/specs/cesium-view.nitro.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,UAAU,EACV,eAAe,EACf,iBAAiB,EAClB,MAAM,4BAA4B,CAAA;AAEnC,6EAA6E;AAC7E,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,cAAc,EAAE,MAAM,CAAA;CACvB;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;CACV;AAED,iEAAiE;AACjE,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAA;IACX,aAAa,EAAE,MAAM,CAAA;IACrB,YAAY,EAAE,MAAM,CAAA;IACpB,YAAY,EAAE,MAAM,CAAA;IACpB,kBAAkB,EAAE,OAAO,CAAA;IAC3B,+DAA+D;IAC/D,aAAa,EAAE,OAAO,CAAA;IACtB,YAAY,EAAE,OAAO,CAAA;IACrB,gBAAgB,EAAE,MAAM,CAAA;CACzB;AAED,MAAM,WAAW,eAAgB,SAAQ,eAAe;IACtD,cAAc,EAAE,MAAM,CAAA;IACtB,UAAU,EAAE,MAAM,CAAA;IAClB,4EAA4E;IAC5E,aAAa,EAAE,WAAW,CAAA;IAC1B,cAAc,EAAE,OAAO,CAAA;IACvB,uBAAuB,EAAE,MAAM,CAAA;IAC/B,4BAA4B,EAAE,MAAM,CAAA;IACpC,sBAAsB,EAAE,MAAM,CAAA;IAC9B,6CAA6C;IAC7C,eAAe,EAAE,MAAM,CAAA;IACvB,iBAAiB,EAAE,MAAM,CAAA;IAGzB,8DAA8D;IAC9D,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,mGAAmG;IACnG,gBAAgB,CAAC,EAAE,OAAO,CAAA;IAC1B,mEAAmE;IACnE,eAAe,CAAC,EAAE,OAAO,CAAA;IACzB,gFAAgF;IAChF,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,oEAAoE;IACpE,eAAe,CAAC,EAAE,OAAO,CAAA;IACzB,6DAA6D;IAC7D,gBAAgB,CAAC,EAAE,OAAO,CAAA;IAC1B,2EAA2E;IAC3E,6BAA6B,CAAC,EAAE,OAAO,CAAA;IACvC,4FAA4F;IAC5F,sBAAsB,CAAC,EAAE,MAAM,CAAA;IAC/B,8EAA8E;IAC9E,yBAAyB,CAAC,EAAE,OAAO,CAAA;IACnC,mDAAmD;IACnD,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAC5B,mDAAmD;IACnD,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B,4EAA4E;IAC5E,oBAAoB,CAAC,EAAE,MAAM,CAAA;IAE7B,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,IAAI,CAAA;CAC7C;AAED,MAAM,WAAW,iBAAkB,SAAQ,iBAAiB;IAC1D,+CAA+C;IAC/C,cAAc,IAAI,OAAO,CAAC,WAAW,CAAC,CAAA;IACtC;;;OAGG;IACH,SAAS,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,CAAA;IACpC;;;OAGG;IACH,mBAAmB,CAAC,MAAM,EAAE,WAAW,EAAE,cAAc,EAAE,UAAU,GAAG,IAAI,CAAA;IAC1E,4FAA4F;IAC5F,iBAAiB,IAAI,OAAO,CAAC,UAAU,CAAC,CAAA;CACzC;AAED,MAAM,MAAM,UAAU,GAAG,UAAU,CAAC,eAAe,EAAE,iBAAiB,CAAC,CAAA"}
+{"version":3,"file":"cesium-view.nitro.d.ts","sourceRoot":"","sources":["../../../../src/specs/cesium-view.nitro.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,UAAU,EACV,eAAe,EACf,iBAAiB,EAClB,MAAM,4BAA4B,CAAA;AAEnC,6EAA6E;AAC7E,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,cAAc,EAAE,MAAM,CAAA;CACvB;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;CACV;AAED,iEAAiE;AACjE,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAA;IACX,aAAa,EAAE,MAAM,CAAA;IACrB,YAAY,EAAE,MAAM,CAAA;IACpB,YAAY,EAAE,MAAM,CAAA;IACpB,kBAAkB,EAAE,OAAO,CAAA;IAC3B,+DAA+D;IAC/D,aAAa,EAAE,OAAO,CAAA;IACtB,YAAY,EAAE,OAAO,CAAA;IACrB,gBAAgB,EAAE,MAAM,CAAA;CACzB;AAED,MAAM,WAAW,eAAgB,SAAQ,eAAe;IACtD,cAAc,EAAE,MAAM,CAAA;IACtB,UAAU,EAAE,MAAM,CAAA;IAClB,4EAA4E;IAC5E,aAAa,EAAE,WAAW,CAAA;IAC1B,cAAc,EAAE,OAAO,CAAA;IACvB,uBAAuB,EAAE,MAAM,CAAA;IAC/B,4BAA4B,EAAE,MAAM,CAAA;IACpC,sBAAsB,EAAE,MAAM,CAAA;IAC9B,6CAA6C;IAC7C,eAAe,EAAE,MAAM,CAAA;IACvB,iBAAiB,EAAE,MAAM,CAAA;IAGzB,8DAA8D;IAC9D,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,mGAAmG;IACnG,gBAAgB,CAAC,EAAE,OAAO,CAAA;IAC1B,mEAAmE;IACnE,eAAe,CAAC,EAAE,OAAO,CAAA;IACzB,gFAAgF;IAChF,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,oEAAoE;IACpE,eAAe,CAAC,EAAE,OAAO,CAAA;IACzB,6DAA6D;IAC7D,gBAAgB,CAAC,EAAE,OAAO,CAAA;IAC1B,2EAA2E;IAC3E,6BAA6B,CAAC,EAAE,OAAO,CAAA;IACvC,4FAA4F;IAC5F,sBAAsB,CAAC,EAAE,MAAM,CAAA;IAC/B,8EAA8E;IAC9E,yBAAyB,CAAC,EAAE,OAAO,CAAA;IACnC,mDAAmD;IACnD,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAC5B,mDAAmD;IACnD,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B,4EAA4E;IAC5E,oBAAoB,CAAC,EAAE,MAAM,CAAA;IAC7B;;;;;OAKG;IACH,uBAAuB,CAAC,EAAE,MAAM,CAAA;IAEhC,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,IAAI,CAAA;CAC7C;AAED,MAAM,WAAW,iBAAkB,SAAQ,iBAAiB;IAC1D,+CAA+C;IAC/C,cAAc,IAAI,OAAO,CAAC,WAAW,CAAC,CAAA;IACtC;;;OAGG;IACH,SAAS,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,CAAA;IACpC;;;OAGG;IACH,mBAAmB,CAAC,MAAM,EAAE,WAAW,EAAE,cAAc,EAAE,UAAU,GAAG,IAAI,CAAA;IAC1E,4FAA4F;IAC5F,iBAAiB,IAAI,OAAO,CAAC,UAAU,CAAC,CAAA;CACzC;AAED,MAAM,MAAM,UAAU,GAAG,UAAU,CAAC,eAAe,EAAE,iBAAiB,CAAC,CAAA"}

package/nitrogen/generated/android/c++/JHybridCesiumViewSpec.cpp

@@ -247,6 +247,15 @@ namespace margelo::nitro::reactnativecesium {
     static const auto method = _javaPart->javaClassStatic()->getMethod<void(jni::alias_ref<jni::JDouble> /* taskProcessorThreads */)>("setTaskProcessorThreads");
     method(_javaPart, taskProcessorThreads.has_value() ? jni::JDouble::valueOf(taskProcessorThreads.value()) : nullptr);
   }
+  std::optional<double> JHybridCesiumViewSpec::getMinAltitudeAboveTerrain() {
+    static const auto method = _javaPart->javaClassStatic()->getMethod<jni::local_ref<jni::JDouble>()>("getMinAltitudeAboveTerrain");
+    auto __result = method(_javaPart);
+    return __result != nullptr ? std::make_optional(__result->value()) : std::nullopt;
+  }
+  void JHybridCesiumViewSpec::setMinAltitudeAboveTerrain(std::optional<double> minAltitudeAboveTerrain) {
+    static const auto method = _javaPart->javaClassStatic()->getMethod<void(jni::alias_ref<jni::JDouble> /* minAltitudeAboveTerrain */)>("setMinAltitudeAboveTerrain");
+    method(_javaPart, minAltitudeAboveTerrain.has_value() ? jni::JDouble::valueOf(minAltitudeAboveTerrain.value()) : nullptr);
+  }
   std::optional<std::function<void(const CesiumMetrics& /* metrics */)>> JHybridCesiumViewSpec::getOnMetrics() {
     static const auto method = _javaPart->javaClassStatic()->getMethod<jni::local_ref<JFunc_void_CesiumMetrics::javaobject>()>("getOnMetrics_cxx");
     auto __result = method(_javaPart);

package/nitrogen/generated/android/c++/JHybridCesiumViewSpec.hpp

@@ -92,6 +92,8 @@ namespace margelo::nitro::reactnativecesium {
     void setSqliteCacheMaxRows(std::optional<double> sqliteCacheMaxRows) override;
     std::optional<double> getTaskProcessorThreads() override;
     void setTaskProcessorThreads(std::optional<double> taskProcessorThreads) override;
+    std::optional<double> getMinAltitudeAboveTerrain() override;
+    void setMinAltitudeAboveTerrain(std::optional<double> minAltitudeAboveTerrain) override;
     std::optional<std::function<void(const CesiumMetrics& /* metrics */)>> getOnMetrics() override;
     void setOnMetrics(const std::optional<std::function<void(const CesiumMetrics& /* metrics */)>>& onMetrics) override;
 

package/nitrogen/generated/android/c++/views/JHybridCesiumViewStateUpdater.cpp

@@ -121,6 +121,10 @@ void JHybridCesiumViewStateUpdater::updateViewProps(jni::alias_ref<jni::JClass>
     hybridView->setTaskProcessorThreads(props->taskProcessorThreads.value);
     props->taskProcessorThreads.isDirty = false;
   }
+  if (props->minAltitudeAboveTerrain.isDirty) {
+    hybridView->setMinAltitudeAboveTerrain(props->minAltitudeAboveTerrain.value);
+    props->minAltitudeAboveTerrain.isDirty = false;
+  }
   if (props->onMetrics.isDirty) {
     hybridView->setOnMetrics(props->onMetrics.value);
     props->onMetrics.isDirty = false;

package/nitrogen/generated/android/kotlin/com/margelo/nitro/reactnativecesium/HybridCesiumViewSpec.kt

@@ -153,6 +153,12 @@ abstract class HybridCesiumViewSpec: HybridView() {
   @set:Keep
   abstract var taskProcessorThreads: Double?
   
+  @get:DoNotStrip
+  @get:Keep
+  @set:DoNotStrip
+  @set:Keep
+  abstract var minAltitudeAboveTerrain: Double?
+  
   abstract var onMetrics: ((metrics: CesiumMetrics) -> Unit)?
   
   private var onMetrics_cxx: Func_void_CesiumMetrics?

package/nitrogen/generated/ios/c++/HybridCesiumViewSpecSwift.hpp

@@ -212,6 +212,13 @@ namespace margelo::nitro::reactnativecesium {
     inline void setTaskProcessorThreads(std::optional<double> taskProcessorThreads) noexcept override {
       _swiftPart.setTaskProcessorThreads(taskProcessorThreads);
     }
+    inline std::optional<double> getMinAltitudeAboveTerrain() noexcept override {
+      auto __result = _swiftPart.getMinAltitudeAboveTerrain();
+      return __result;
+    }
+    inline void setMinAltitudeAboveTerrain(std::optional<double> minAltitudeAboveTerrain) noexcept override {
+      _swiftPart.setMinAltitudeAboveTerrain(minAltitudeAboveTerrain);
+    }
     inline std::optional<std::function<void(const CesiumMetrics& /* metrics */)>> getOnMetrics() noexcept override {
       auto __result = _swiftPart.getOnMetrics();
       return __result;

package/nitrogen/generated/ios/c++/views/HybridCesiumViewComponent.mm

@@ -184,6 +184,11 @@ using namespace margelo::nitro::reactnativecesium::views;
     swiftPart.setTaskProcessorThreads(newViewProps.taskProcessorThreads.value);
     newViewProps.taskProcessorThreads.isDirty = false;
   }
+  // minAltitudeAboveTerrain: optional
+  if (newViewProps.minAltitudeAboveTerrain.isDirty) {
+    swiftPart.setMinAltitudeAboveTerrain(newViewProps.minAltitudeAboveTerrain.value);
+    newViewProps.minAltitudeAboveTerrain.isDirty = false;
+  }
   // onMetrics: optional
   if (newViewProps.onMetrics.isDirty) {
     swiftPart.setOnMetrics(newViewProps.onMetrics.value);

package/nitrogen/generated/ios/swift/HybridCesiumViewSpec.swift

@@ -31,6 +31,7 @@ public protocol HybridCesiumViewSpec_protocol: HybridObject, HybridView {
   var lodTransitionLength: Double? { get set }
   var sqliteCacheMaxRows: Double? { get set }
   var taskProcessorThreads: Double? { get set }
+  var minAltitudeAboveTerrain: Double? { get set }
   var onMetrics: ((_ metrics: CesiumMetrics) -> Void)? { get set }
 
   // Methods

package/nitrogen/generated/ios/swift/HybridCesiumViewSpec_cxx.swift

@@ -508,6 +508,30 @@ open class HybridCesiumViewSpec_cxx {
     }
   }
   
+  public final var minAltitudeAboveTerrain: bridge.std__optional_double_ {
+    @inline(__always)
+    get {
+      return { () -> bridge.std__optional_double_ in
+        if let __unwrappedValue = self.__implementation.minAltitudeAboveTerrain {
+          return bridge.create_std__optional_double_(__unwrappedValue)
+        } else {
+          return .init()
+        }
+      }()
+    }
+    @inline(__always)
+    set {
+      self.__implementation.minAltitudeAboveTerrain = { () -> Double? in
+        if bridge.has_value_std__optional_double_(newValue) {
+          let __unwrapped = bridge.get_std__optional_double_(newValue)
+          return __unwrapped
+        } else {
+          return nil
+        }
+      }()
+    }
+  }
+  
   public final var onMetrics: bridge.std__optional_std__function_void_const_CesiumMetrics_____metrics______ {
     @inline(__always)
     get {

package/nitrogen/generated/shared/c++/HybridCesiumViewSpec.cpp

@@ -56,6 +56,8 @@ namespace margelo::nitro::reactnativecesium {
       prototype.registerHybridSetter("sqliteCacheMaxRows", &HybridCesiumViewSpec::setSqliteCacheMaxRows);
       prototype.registerHybridGetter("taskProcessorThreads", &HybridCesiumViewSpec::getTaskProcessorThreads);
       prototype.registerHybridSetter("taskProcessorThreads", &HybridCesiumViewSpec::setTaskProcessorThreads);
+      prototype.registerHybridGetter("minAltitudeAboveTerrain", &HybridCesiumViewSpec::getMinAltitudeAboveTerrain);
+      prototype.registerHybridSetter("minAltitudeAboveTerrain", &HybridCesiumViewSpec::setMinAltitudeAboveTerrain);
       prototype.registerHybridGetter("onMetrics", &HybridCesiumViewSpec::getOnMetrics);
       prototype.registerHybridSetter("onMetrics", &HybridCesiumViewSpec::setOnMetrics);
       prototype.registerHybridMethod("getCameraState", &HybridCesiumViewSpec::getCameraState);

package/nitrogen/generated/shared/c++/HybridCesiumViewSpec.hpp

@@ -97,6 +97,8 @@ namespace margelo::nitro::reactnativecesium {
       virtual void setSqliteCacheMaxRows(std::optional<double> sqliteCacheMaxRows) = 0;
       virtual std::optional<double> getTaskProcessorThreads() = 0;
       virtual void setTaskProcessorThreads(std::optional<double> taskProcessorThreads) = 0;
+      virtual std::optional<double> getMinAltitudeAboveTerrain() = 0;
+      virtual void setMinAltitudeAboveTerrain(std::optional<double> minAltitudeAboveTerrain) = 0;
       virtual std::optional<std::function<void(const CesiumMetrics& /* metrics */)>> getOnMetrics() = 0;
       virtual void setOnMetrics(const std::optional<std::function<void(const CesiumMetrics& /* metrics */)>>& onMetrics) = 0;
 

package/nitrogen/generated/shared/c++/views/HybridCesiumViewComponent.cpp

@@ -236,6 +236,16 @@ namespace margelo::nitro::reactnativecesium::views {
         throw std::runtime_error(std::string("CesiumView.taskProcessorThreads: ") + exc.what());
       }
     }()),
+    minAltitudeAboveTerrain([&]() -> CachedProp<std::optional<double>> {
+      try {
+        const react::RawValue* rawValue = rawProps.at("minAltitudeAboveTerrain", nullptr, nullptr);
+        if (rawValue == nullptr) return sourceProps.minAltitudeAboveTerrain;
+        const auto& [runtime, value] = (std::pair<jsi::Runtime*, jsi::Value>)*rawValue;
+        return CachedProp<std::optional<double>>::fromRawValue(*runtime, value, sourceProps.minAltitudeAboveTerrain);
+      } catch (const std::exception& exc) {
+        throw std::runtime_error(std::string("CesiumView.minAltitudeAboveTerrain: ") + exc.what());
+      }
+    }()),
     onMetrics([&]() -> CachedProp<std::optional<std::function<void(const CesiumMetrics& /* metrics */)>>> {
       try {
         const react::RawValue* rawValue = rawProps.at("onMetrics", nullptr, nullptr);
@@ -280,6 +290,7 @@ namespace margelo::nitro::reactnativecesium::views {
       case hashString("lodTransitionLength"): return true;
       case hashString("sqliteCacheMaxRows"): return true;
       case hashString("taskProcessorThreads"): return true;
+      case hashString("minAltitudeAboveTerrain"): return true;
       case hashString("onMetrics"): return true;
       case hashString("hybridRef"): return true;
       default: return false;

package/nitrogen/generated/shared/c++/views/HybridCesiumViewComponent.hpp

@@ -65,6 +65,7 @@ namespace margelo::nitro::reactnativecesium::views {
     CachedProp<std::optional<double>> lodTransitionLength;
     CachedProp<std::optional<double>> sqliteCacheMaxRows;
     CachedProp<std::optional<double>> taskProcessorThreads;
+    CachedProp<std::optional<double>> minAltitudeAboveTerrain;
     CachedProp<std::optional<std::function<void(const CesiumMetrics& /* metrics */)>>> onMetrics;
     CachedProp<std::optional<std::function<void(const std::shared_ptr<HybridCesiumViewSpec>& /* ref */)>>> hybridRef;
 

package/nitrogen/generated/shared/json/CesiumViewConfig.json

@@ -25,6 +25,7 @@
     "lodTransitionLength": true,
     "sqliteCacheMaxRows": true,
     "taskProcessorThreads": true,
+    "minAltitudeAboveTerrain": true,
     "onMetrics": true,
     "hybridRef": true
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-cesium",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "description": "Experimental Cesium rendering for React Native via Nitro (iOS/Metal today; Android planned)",
   "main": "./lib/commonjs/index.js",
   "module": "./lib/module/index.js",

package/scripts/cesium/clone.mjs

@@ -6,13 +6,13 @@ import { execFileSync } from 'node:child_process'
 import { existsSync, mkdirSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
+import { CESIUM_NATIVE_REF as ref } from './config.mjs'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
 const root = join(__dirname, '..', '..')
 const vendor = join(root, 'vendor')
 const dest = join(vendor, 'cesium-native')
 const repo = 'https://github.com/CesiumGS/cesium-native.git'
-const ref = 'v0.60.0'
 
 function run(cmd, args, opts = {}) {
   execFileSync(cmd, args, { stdio: 'inherit', ...opts })

package/scripts/cesium/config.mjs

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+/**
+ * Shared configuration for Cesium Native build scripts.
+ * Update CESIUM_NATIVE_REF here when bumping the pinned cesium-native version.
+ */
+
+/** Git tag of CesiumGS/cesium-native to clone and build. */
+export const CESIUM_NATIVE_REF = 'v0.60.0'

package/scripts/cesium/ensure-native.mjs

@@ -1,20 +1,30 @@
 #!/usr/bin/env node
 /**
- * If Cesium Native vendor output is missing for the requested platform(s), run
- * `npm|yarn run update` then `CESIUM_BUILD_ONLY=… npm|yarn run build`.
+ * Ensure Cesium Native vendor output is present and built for the pinned ref.
  *
- * Invoked from CocoaPods (podspec prepare_command) and Android Gradle (preBuild).
+ * Fast-path (in order):
+ *   1. Vendor dir already exists and was built for the current ref → nothing to do.
+ *   2. Global cache (~/.cache/react-native-cesium/<ref>/<platform>/) has a matching
+ *      build → restore from cache without recompiling.
+ *   3. Otherwise → clone source and build, then populate the global cache.
  *
- * Opt out (CI without toolchains): REACT_NATIVE_CESIUM_SKIP_NATIVE_BUILD=1 — fails fast if artifacts are still missing.
+ * Invoked from CocoaPods (react_native_cesium_ensure_native in Podfile pre_install)
+ * and Android Gradle (preBuild task).
+ *
+ * Opt out (CI without toolchains): REACT_NATIVE_CESIUM_SKIP_NATIVE_BUILD=1 —
+ * fails fast if artifacts are still missing.
  */
 import { spawnSync } from 'node:child_process'
-import { existsSync } from 'node:fs'
+import { cpSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
 import { dirname, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
+import { CESIUM_NATIVE_REF } from './config.mjs'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
 const root = resolve(join(__dirname, '..', '..'))
 
+// Marker files whose existence confirms a successful build.
 const MARKER_IOS = join(root, 'vendor', 'ios', 'CesiumNative.xcframework', 'Info.plist')
 const MARKER_ANDROID = join(
   root,
@@ -26,6 +36,100 @@ const MARKER_ANDROID = join(
   'cesium-nativeConfig.cmake'
 )
 
+// Stamp files that record which cesium-native ref the vendor dir was built from.
+const REF_STAMP_IOS = join(root, 'vendor', 'ios', '.cesium-native-ref')
+const REF_STAMP_ANDROID = join(root, 'vendor', 'android', '.cesium-native-ref')
+
+// ─── Global cache ────────────────────────────────────────────────────────────
+// Keyed by cesium-native ref so builds for different versions coexist.
+// Survives node_modules being cleared between pod installs.
+
+function globalCacheBase() {
+  const xdg = process.env.XDG_CACHE_HOME?.trim()
+  return xdg
+    ? join(xdg, 'react-native-cesium')
+    : join(homedir(), '.cache', 'react-native-cesium')
+}
+
+function cacheDir(platform, ref) {
+  return join(globalCacheBase(), ref, platform)
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function readStamp(stampPath) {
+  try {
+    return readFileSync(stampPath, 'utf8').trim()
+  } catch {
+    return null
+  }
+}
+
+function isStale(markerPath, stampPath, ref) {
+  if (!existsSync(markerPath)) return true
+  const built = readStamp(stampPath)
+  if (built !== ref) {
+    console.log(
+      `react-native-cesium: vendor built for ${built ?? 'unknown ref'}, current ref is ${ref} — will refresh.`
+    )
+    return true
+  }
+  return false
+}
+
+/**
+ * Try to restore a platform's vendor dir from the global cache.
+ * Returns true if the cache hit and the restore succeeded.
+ */
+function tryRestoreFromCache(platform, ref, vendorDir, stampPath, markerPath) {
+  const src = cacheDir(platform, ref)
+  if (!existsSync(src)) return false
+
+  console.log(
+    `react-native-cesium: cache hit for ${platform} ${ref} — restoring from ${src} (skipping build)`
+  )
+  try {
+    rmSync(vendorDir, { recursive: true, force: true })
+    mkdirSync(vendorDir, { recursive: true })
+    cpSync(src, vendorDir, { recursive: true })
+    // Ensure stamp is present even if the cached dir predates stamp support.
+    writeFileSync(stampPath, ref)
+    if (!existsSync(markerPath)) {
+      console.warn(
+        `react-native-cesium: cache restore for ${platform} ${ref} succeeded but marker is missing: ${markerPath}\n` +
+          'The cache entry may be corrupt; delete it and retry:\n' +
+          `  rm -rf "${src}"`
+      )
+      return false
+    }
+    return true
+  } catch (e) {
+    console.warn(
+      `react-native-cesium: cache restore failed (${e.message}) — will rebuild.`
+    )
+    return false
+  }
+}
+
+/** Populate the global cache from a freshly built vendor dir. */
+function saveToCache(platform, ref, vendorDir) {
+  const dst = cacheDir(platform, ref)
+  try {
+    rmSync(dst, { recursive: true, force: true })
+    mkdirSync(dst, { recursive: true })
+    cpSync(vendorDir, dst, { recursive: true })
+    console.log(
+      `react-native-cesium: saved ${platform} ${ref} build to cache (${dst})`
+    )
+  } catch (e) {
+    console.warn(
+      `react-native-cesium: could not write to cache (${e.message}) — build succeeded but next run may rebuild.`
+    )
+  }
+}
+
+// ─── Script runner ───────────────────────────────────────────────────────────
+
 function parseArgs(argv) {
   const want = { ios: false, android: false }
   for (const a of argv) {
@@ -46,7 +150,7 @@ function useYarn() {
 function runScript(name, extraEnv) {
   const yarn = useYarn()
   const cmd = yarn ? 'yarn' : 'npm'
-  const args = yarn ? ['run', name] : ['run', name]
+  const args = ['run', name]
   const env = { ...process.env, ...extraEnv }
   const r = spawnSync(cmd, args, { cwd: root, env, stdio: 'inherit' })
   if (r.error) {
@@ -59,48 +163,88 @@ function runScript(name, extraEnv) {
   }
 }
 
+// ─── Main ────────────────────────────────────────────────────────────────────
+
 function main() {
   const skip = process.env.REACT_NATIVE_CESIUM_SKIP_NATIVE_BUILD === '1'
   const want = parseArgs(process.argv.slice(2))
+  const ref = CESIUM_NATIVE_REF
+
+  const vendorIos = join(root, 'vendor', 'ios')
+  const vendorAndroid = join(root, 'vendor', 'android')
 
-  const needIos = want.ios && !existsSync(MARKER_IOS)
-  const needAndroid = want.android && !existsSync(MARKER_ANDROID)
+  let needIos = want.ios && isStale(MARKER_IOS, REF_STAMP_IOS, ref)
+  let needAndroid = want.android && isStale(MARKER_ANDROID, REF_STAMP_ANDROID, ref)
 
   if (!needIos && !needAndroid) {
+    // Vendor is already up to date. Back-fill the global cache if it is missing so
+    // that future runs (after node_modules is cleared) can restore without rebuilding.
+    if (want.ios && !existsSync(cacheDir('ios', ref))) {
+      saveToCache('ios', ref, vendorIos)
+    }
+    if (want.android && !existsSync(cacheDir('android', ref))) {
+      saveToCache('android', ref, vendorAndroid)
+    }
     return
   }
 
   if (skip) {
+    const missing = [
+      needIos && `  iOS:     ${MARKER_IOS}`,
+      needAndroid && `  Android: ${MARKER_ANDROID}`,
+    ]
+      .filter(Boolean)
+      .join('\n')
     console.error(
-      'react-native-cesium: Cesium Native vendor output is missing, but REACT_NATIVE_CESIUM_SKIP_NATIVE_BUILD=1.\n' +
+      'react-native-cesium: Cesium Native vendor output is missing or stale, but REACT_NATIVE_CESIUM_SKIP_NATIVE_BUILD=1.\n' +
         'Build the native libraries on a machine with the required toolchains, or unset the variable and retry.\n' +
-        `Expected iOS: ${MARKER_IOS}\n` +
-        `Expected Android: ${MARKER_ANDROID}\n` +
-        'See the package README (Build Cesium Native locally).'
+        missing +
+        '\nSee the package README (Build Cesium Native locally).'
     )
     process.exit(1)
   }
 
   if (needIos && process.platform !== 'darwin') {
     console.error(
-      'react-native-cesium: iOS Cesium Native output is missing; building it requires macOS with Xcode.\n' +
+      'react-native-cesium: iOS Cesium Native output is missing or stale; building it requires macOS with Xcode.\n' +
         `Expected: ${MARKER_IOS}`
     )
     process.exit(1)
   }
 
+  // Fast path: restore from global cache if available.
+  if (needIos && tryRestoreFromCache('ios', ref, vendorIos, REF_STAMP_IOS, MARKER_IOS)) {
+    needIos = false
+  }
+  if (
+    needAndroid &&
+    tryRestoreFromCache('android', ref, vendorAndroid, REF_STAMP_ANDROID, MARKER_ANDROID)
+  ) {
+    needAndroid = false
+  }
+
+  if (!needIos && !needAndroid) return
+
+  // Clone cesium-native source if not already present.
   if (!existsSync(join(root, 'vendor', 'cesium-native'))) {
     console.log('react-native-cesium: running package update (clone Cesium Native / vcpkg prep)…')
     runScript('update', {})
   }
 
-  if (needIos && !existsSync(MARKER_IOS)) {
+  if (needIos) {
     console.log('react-native-cesium: building Cesium Native for iOS (this can take a long time)…')
     runScript('build', { CESIUM_BUILD_ONLY: 'ios' })
+    writeFileSync(REF_STAMP_IOS, ref)
+    saveToCache('ios', ref, vendorIos)
   }
-  if (needAndroid && !existsSync(MARKER_ANDROID)) {
-    console.log('react-native-cesium: building Cesium Native for Android (this can take a long time)…')
+
+  if (needAndroid) {
+    console.log(
+      'react-native-cesium: building Cesium Native for Android (this can take a long time)…'
+    )
     runScript('build', { CESIUM_BUILD_ONLY: 'android' })
+    writeFileSync(REF_STAMP_ANDROID, ref)
+    saveToCache('android', ref, vendorAndroid)
   }
 
   if (needIos && !existsSync(MARKER_IOS)) {
@@ -108,7 +252,9 @@ function main() {
     process.exit(1)
   }
   if (needAndroid && !existsSync(MARKER_ANDROID)) {
-    console.error(`react-native-cesium: Android build finished but marker missing: ${MARKER_ANDROID}`)
+    console.error(
+      `react-native-cesium: Android build finished but marker missing: ${MARKER_ANDROID}`
+    )
     process.exit(1)
   }
 }

package/src/specs/cesium-view.nitro.ts

@@ -77,6 +77,13 @@ export interface CesiumViewProps extends HybridViewProps {
   sqliteCacheMaxRows?: number
   /** Worker thread count. 0 = auto (hardware_concurrency-1, clamped 2..8). */
   taskProcessorThreads?: number
+  /**
+   * Minimum altitude above the loaded terrain surface, in metres MSL.
+   * Default 0 (no constraint). Set to e.g. 2 to prevent the camera from going underground.
+   * The clamp is applied every frame in native, based on the altitude of the nearest
+   * terrain mesh vertex to the camera nadir.
+   */
+  minAltitudeAboveTerrain?: number
 
   onMetrics?: (metrics: CesiumMetrics) => void
 }