react-native-cesium 1.1.0 → 1.2.1

package/README.md

@@ -397,6 +397,22 @@ Avoid assuming **main-thread-only** vs **JS-thread-only** labels beyond the abov
 - You may **mix** the two: calling `setCamera` updates position and HPR but leaves the last view-correction target unchanged, so a calibration quaternion set earlier continues to apply until you change it with `setCameraQuaternion`.
 - Prefer **`setCameraQuaternion`** on frames where you need to drive both the globe camera and the correction together so the native target stays consistent.
 
+#### 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.
+
+| 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. |
+| `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. |
+| `verticalFovDeg` | Applied directly (not smoothed). |
+
+You don't have to do anything special to take advantage of this — the smoother already runs, it's the same code path whether your driver is a Reanimated worklet at 60 Hz, a `setInterval` push at 10 Hz, or a 1 Hz GPS subscription. Just call `setCamera` whenever you have a new value.
+
+If the smoothing ever feels off for your data source, the relevant constants live in [`cpp/engine/EngineTunables.hpp`](cpp/engine/EngineTunables.hpp) (`kSmoothPositionAlpha`, `kSmoothPositionTauMin`, `kSmoothPositionTauMax`, `kPosSnapThroughDeg`, `kEwmaIntervalAlpha`, plus the per-DoF `kSmooth*` rates).
+
 ### `CesiumMetrics`
 
 | Field | Type | Description                                                                                                                                 |

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,7 +244,23 @@ 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);
+  auto smooth = reactnativecesium::CameraSmoother::step(
+      cur, tgt, dt, target_.recentIntervalSec());
+
+  // ── 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.
@@ -539,5 +560,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,6 +2,7 @@
 
 #include "EngineTunables.hpp"
 
+#include <algorithm>
 #include <cmath>
 
 namespace reactnativecesium {
@@ -23,15 +24,40 @@ 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) {
+    const CameraParams& current, const CameraParams& target, double dt,
+    double recentIntervalSec) {
   CameraParams next = current;
 
-  // lat/lon: copied directly — pan gestures must feel instant.
-  next.latitude  = target.latitude;
-  next.longitude = target.longitude;
+  // ── 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);
+  }
 
   const double aAlt   = 1.0 - std::exp(-tunables::kSmoothAltitude * dt);
   const double aHdg   = 1.0 - std::exp(-tunables::kSmoothHeading  * dt);
@@ -50,6 +76,11 @@ 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

@@ -7,9 +7,13 @@ namespace reactnativecesium {
 // Stateless helper. Given a current camera state and a target camera state,
 // returns the next camera state for a frame of duration `dt` seconds.
 //
-// Per-DoF smoothing rules (matching the previous platform-specific code):
-//   - lat / lon: copied directly from target (no smoothing — pan must feel
-//     instant on touch).
+// 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.
 //   - 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
@@ -18,7 +22,8 @@ class CameraSmoother {
 public:
   static CameraParams step(const CameraParams& current,
                            const CameraParams& target,
-                           double dt);
+                           double dt,
+                           double recentIntervalSec);
 };
 
 } // namespace reactnativecesium

package/cpp/engine/CameraTargetState.cpp

@@ -25,4 +25,25 @@ 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

@@ -4,6 +4,7 @@
 #include "GlobeCamera.hpp"
 
 #include <atomic>
+#include <chrono>
 #include <mutex>
 
 namespace reactnativecesium {
@@ -31,6 +32,7 @@ public:
       std::lock_guard<std::mutex> g(mutex_);
       target_ = target;
     }
+    noteUpdateCadence();
     dirty_.store(true, std::memory_order_release);
     forceRender_.store(true, std::memory_order_release);
   }
@@ -47,6 +49,7 @@ public:
       target_.pitch     = pitch;
       target_.roll      = roll;
     }
+    noteUpdateCadence();
     dirty_.store(true, std::memory_order_release);
     forceRender_.store(true, std::memory_order_release);
   }
@@ -56,6 +59,7 @@ public:
       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);
   }
@@ -87,11 +91,31 @@ 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};
 };
 
 } // 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/cpp/engine/EngineTunables.hpp

@@ -53,6 +53,21 @@ inline constexpr double kEpsAltitudeMeters  = 0.1;
 inline constexpr double kEpsAngleDeg        = 0.05;
 inline constexpr double kEpsQuatDot         = 1e-8;
 
+// Lat/lon are smoothed adaptively: τ = clamp(α · ewmaInterval, τmin, τmax),
+// then per frame we apply 1 - exp(-dt/τ). α<1 means the camera converges
+// before the next sample lands. With ~60 Hz gestures the EWMA interval is
+// ~16 ms ⇒ τ at the floor (5 ms) ⇒ ≤1-frame trail (indistinguishable from
+// the previous snap). With a 1 Hz GPS feed τ ≈ 450 ms ⇒ ~95 % converged
+// before the next sample arrives, removing the per-second teleport.
+inline constexpr double kSmoothPositionAlpha   = 0.45;
+inline constexpr double kSmoothPositionTauMin  = 0.005;
+inline constexpr double kSmoothPositionTauMax  = 0.6;
+// Genuine teleports (e.g. setCamera(NewYork) → setCamera(Tokyo)) skip the
+// smoother — easing across the planet over 600 ms looks worse than a snap.
+inline constexpr double kPosSnapThroughDeg     = 0.5;
+// EWMA mixing factor for the inter-arrival interval of setCamera calls.
+inline constexpr double kEwmaIntervalAlpha     = 0.3;
+
 // Metrics throttle: emit telemetry every N rendered frames.
 inline constexpr int kMetricsEmitEveryFrames = 20;
 

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,7 +277,25 @@
 
     const auto cur    = _engine->camera().getParams();
     const auto tgt    = _target.snapshot();
-    const auto smooth = reactnativecesium::CameraSmoother::step(cur, tgt, dt);
+    auto smooth = reactnativecesium::CameraSmoother::step(
+        cur, tgt, dt, _target.recentIntervalSec());
+
+    // ── 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.1.0",
+  "version": "1.2.1",
   "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
 }