react-native-cesium 1.2.18 → 1.2.20

package/README.md

@@ -184,7 +184,7 @@ npm run build --prefix node_modules/react-native-cesium
 
 **Yarn/npm workspaces:** if `react-native-cesium` is a workspace package in your monorepo, use your tool’s workspace runner, e.g. `yarn workspace react-native-cesium run update` (exact syntax depends on your workspace layout).
 
-- `update` checks out **Cesium Native `v0.59.0`** into `vendor/cesium-native` under the package (next to its other files; typically ignored in app repos).
+- `update` checks out **Cesium Native `v0.65.0`** into `vendor/cesium-native` under the package (next to its other files; typically ignored in app repos).
 - `build` runs `scripts/cesium/build.mjs` (**CMake**, **vcpkg** under `vendor/vcpkg` unless **`VCPKG_ROOT`** is set, **Ninja** on macOS) and writes **`vendor/ios/CesiumNative.xcframework`** and/or **`vendor/android`** depending on **`CESIUM_BUILD_ONLY`**.
 
 Then install pods (iOS):
@@ -294,6 +294,7 @@ When you pass a callback ref to `CesiumView`, wrap it with `callback(...)` from
 
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
+| `altitudeDatum` | `"msl"` \| `"ellipsoid"` | `"msl"` | Vertical datum of every public altitude: `initialCamera`, `setAltitude`, `teleport`, and the altitude returned by `getActualCamera`, `getDemandCamera`, and `onActualCamera`. `"msl"` is metres above mean sea level. `"ellipsoid"` is WGS84 ellipsoidal height (Android `Location.getAltitude()`). Ellipsoidal heights are converted to mean sea level with EGM96 before the camera integrator, and converted back on read. Switching the prop does not move the camera: later reads use the new unit, and the next altitude or position write is interpreted in that unit. Leave this at `"msl"` for gesture and scripted altitudes. Use `"ellipsoid"` for a GPS ellipsoidal height, and call `setPosition` and `setAltitude` one after the other on the same thread. |
 | `onMetrics` | `(metrics: CesiumMetrics) => void` | `undefined` | Receives throttled runtime stats and credits text. |
 
 **Optional performance / quality knobs**
@@ -348,7 +349,7 @@ type CameraState = {
 | --- | --- |------------------------------|-------------------------------------------------------------------------------------------------------|
 | `latitude` | `number` | `-90..90`                    | Camera latitude in degrees.                                                                           |
 | `longitude` | `number` | `-180..180`                  | Camera longitude in degrees.                                                                          |
-| `altitude` | `number` | Meters above sea level (MSL) | Camera height in meters.                                                                              |
+| `altitude` | `number` | Metres | Camera height. Mean sea level unless `altitudeDatum` is `"ellipsoid"`, in which case this is WGS84 ellipsoidal height. Writes and reads use the same unit. |
 | `heading` | `number` | Degrees                      | Compass direction the camera faces. Example: `0` faces north, `90` faces east.                        |
 | `pitch` | `number` | Degrees                      | Tilt angle. Negative values look downward toward terrain; positive values tilt up toward horizon/sky. |
 | `roll` | `number` | Degrees                      | Bank/rotation around forward axis. Positive right bank, negative left bank.                           |
@@ -385,15 +386,15 @@ Each axis (position, altitude, heading, attitude, viewCorrection, verticalFov) h
 
 | Method | Signature | Description |
 | --- | --- | --- |
-| `setPosition` | `(latitude: number, longitude: number) => void` | New geographic position **demand** (degrees). Each call stamps the measurement with the native steady-clock time of arrival and runs one α-β update against the predicted state at that instant. Latitude is clamped to ±90 on extrapolation; longitude is continuous (no wrap normalisation) so shortest-arc residual maths stays correct across the antimeridian. |
-| `setAltitude` | `(altitudeMeters: number) => void` | New altitude demand (metres MSL). |
+| `setPosition` | `(latitude: number, longitude: number) => void` | New geographic position **demand** (degrees). Each call stamps the measurement with the native steady-clock time of arrival and runs one α-β update against the predicted state at that instant. Latitude is clamped to ±90 on extrapolation; longitude is continuous (no wrap normalisation) so shortest-arc residual maths stays correct across the antimeridian. When `altitudeDatum` is `"ellipsoid"`, a horizontal move keeps the demanded ellipsoidal height and recomputes mean sea level at the new point. `"msl"` leaves altitude unchanged. |
+| `setAltitude` | `(altitudeMeters: number) => void` | New altitude demand, in metres. Mean sea level unless `altitudeDatum` is `"ellipsoid"`, in which case it is WGS84 height and is converted to mean sea level before the integrator. A later read reports the same sample back in this unit. |
 | `setHeading` | `(headingDeg: number) => void` | New heading demand (degrees; `0` = north, increasing clockwise). The integrator computes the shortest-arc residual, so feeding it `359 → 1` rotates 2° clockwise, not 358° counter-clockwise. |
 | `setAttitude` | `(pitchDeg: number, rollDeg: number) => void` | New pitch and roll demand (degrees). Bundled because almost every IMU emits them together — but you can pass the previous value for either axis if only one of them has changed. |
 | `setViewCorrection` | `(q: Quaternion) => void` | New camera-space rotation applied **after** HPR. SLERPed toward the latest demand each frame. Use for boresight calibration, screen-fixed HUD alignment, etc. Non-unit values are normalised on the native side. |
 | `setVerticalFov` | `(deg: number) => void` | New vertical FOV demand (degrees). Clamped to `20..100` on the native side. |
-| `teleport` | `(camera: CameraState) => void` | Hard scene jump — atomically resets every DoF (value, velocity, demand) to `camera`. Bypasses the integrator entirely. Use for `Fly to coordinate` actions or seeding from saved state. |
-| `getActualCamera` | `() => Promise<CameraState>` | Most recently rendered camera (post-integration). This is what the user is currently looking at and what a HUD overlay should mirror. Differs from `getDemandCamera()` while a glide is in progress or when the terrain-floor clamp has raised the altitude. |
-| `getDemandCamera` | `() => Promise<CameraState>` | What the consumer last asked for (per-DoF demand). Useful for diagnostics, or for showing the requested camera alongside the rendered one. |
+| `teleport` | `(camera: CameraState) => void` | Hard scene jump — atomically resets every DoF (value, velocity, demand) to `camera`. Bypasses the integrator entirely. Use for `Fly to coordinate` actions or seeding from saved state. `camera.altitude` uses the unit selected by `altitudeDatum`. |
+| `getActualCamera` | `() => Promise<CameraState>` | Most recently rendered camera (post-integration). This is what the user is currently looking at and what a HUD overlay should mirror. Differs from `getDemandCamera()` while a glide is in progress or when the terrain-floor clamp has raised the altitude. Altitude is in the unit selected by `altitudeDatum`. |
+| `getDemandCamera` | `() => Promise<CameraState>` | What the consumer last asked for (per-DoF demand). Useful for diagnostics, or for showing the requested camera alongside the rendered one. Altitude is in the unit selected by `altitudeDatum`. |
 | `getViewCorrection` | `() => Promise<Quaternion>` | Current view-correction quaternion (smoothed toward the latest demand). Identity (`w=1, x=y=z=0`) if you have never called `setViewCorrection`. |
 
 #### Threading: setters vs getters
@@ -415,7 +416,7 @@ Avoid assuming **main-thread-only** vs **JS-thread-only** labels beyond the abov
 
 The integrator tracks two camera states simultaneously:
 
-- **Demand** — what the consumer asked for, exactly as it was passed to the setters. `getDemandCamera()` returns this.
+- **Demand** — what the consumer asked for. `getDemandCamera()` returns this, with altitude in the unit selected by `altitudeDatum`.
 - **Actual** — what the integrator extrapolated to and what was passed to the GPU on the last frame. `getActualCamera()` returns this.
 
 For a steady GPS feed with no terrain clamp the two values converge within a few frames. They diverge when:
@@ -461,6 +462,8 @@ imuSubscription.on('attitude', (att) => {
 })
 ```
 
+`fix.altitudeMsl` matches the default `altitudeDatum="msl"`. Android `Location.getAltitude()` is a WGS84 ellipsoidal height: set `altitudeDatum="ellipsoid"` and pass that value to `setAltitude` instead. Call `setPosition` and `setAltitude` one after the other on the same thread so the geoid is applied at that fix.
+
 Each setter is synchronous, takes the integrator's mutex briefly, and is safe to call at any rate from any thread.
 
 ### `CesiumMetrics`

package/android/CMakeLists.txt

@@ -151,6 +151,7 @@ target_link_libraries(
         CesiumGltf
         CesiumGltfReader
         CesiumGltfContent
+        CesiumImage
         CesiumGeospatial
         CesiumGeometry
         CesiumAsync

package/android/build.gradle

@@ -5,7 +5,7 @@ buildscript {
   }
 
   dependencies {
-    classpath "com.android.tools.build:gradle:8.8.0"
+    classpath "com.android.tools.build:gradle:9.2.1"
   }
 }
 

package/android/gradle.properties

@@ -1,5 +1,5 @@
-ReactNativeCesium_kotlinVersion=2.1.20
-ReactNativeCesium_minSdkVersion=23
-ReactNativeCesium_targetSdkVersion=35
-ReactNativeCesium_compileSdkVersion=34
+ReactNativeCesium_kotlinVersion=2.2.0
+ReactNativeCesium_minSdkVersion=24
+ReactNativeCesium_targetSdkVersion=36
+ReactNativeCesium_compileSdkVersion=37
 ReactNativeCesium_ndkVersion=27.1.12297006

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

@@ -2,6 +2,7 @@
 
 #include "engine/EngineTunables.hpp"
 #include "engine/GeoidConverter.hpp"
+#include "engine/TerrainFloor.hpp"
 #include "vulkan/VulkanBackend.h"
 
 #include <android/native_window_jni.h>
@@ -149,13 +150,34 @@ void CesiumBridgeAndroid::updateImageryAssetId(int64_t assetId) {
 
 void CesiumBridgeAndroid::setPosition(double lat, double lon) {
   if (!initialized_ || !integrator_) return;
+  const bool ellipsoid =
+      altitudeIsEllipsoid_.load(std::memory_order_acquire);
+  double adjustedMsl = 0.0;
+  bool adjustAltitude = false;
+  if (ellipsoid) {
+    const auto demand = integrator_->getDemand();
+    adjustedMsl = reactnativecesium::mslAfterHorizontalMove(
+        demand.latitude, demand.longitude, demand.altitude, lat, lon);
+    adjustAltitude = std::abs(adjustedMsl - demand.altitude) >
+                     reactnativecesium::kHorizontalMoveMslEpsilonMeters;
+  }
   integrator_->setPosition(lat, lon);
+  if (adjustAltitude) {
+    integrator_->setAltitude(adjustedMsl);
+  }
   forceRender_.store(true, std::memory_order_release);
 }
 
+void CesiumBridgeAndroid::setAltitudeDatumEllipsoid(bool ellipsoid) {
+  altitudeIsEllipsoid_.store(ellipsoid, std::memory_order_release);
+}
+
 void CesiumBridgeAndroid::setAltitude(double alt) {
   if (!initialized_ || !integrator_) return;
-  integrator_->setAltitude(alt);
+  const auto demand = integrator_->getDemand();
+  integrator_->setAltitude(reactnativecesium::demandAltitudeToMslMeters(
+      demand.latitude, demand.longitude, alt,
+      altitudeIsEllipsoid_.load(std::memory_order_acquire)));
   forceRender_.store(true, std::memory_order_release);
 }
 
@@ -184,13 +206,15 @@ void CesiumBridgeAndroid::teleport(double lat, double lon, double alt,
   reactnativecesium::CameraParams p;
   p.latitude       = lat;
   p.longitude      = lon;
-  p.altitude       = alt;
+  p.altitude       = reactnativecesium::demandAltitudeToMslMeters(
+      lat, lon, alt, altitudeIsEllipsoid_.load(std::memory_order_acquire));
   p.heading        = heading;
   p.pitch          = pitch;
   p.roll           = roll;
   p.verticalFov    = vfov;
   p.viewCorrection = integrator_->getActual().viewCorrection;
   integrator_->teleport(p);
+  reactnativecesium::noteTerrainSlew(*integrator_, terrainLead_);
   engine_->camera().setParams(p);
   forceRender_.store(true, std::memory_order_release);
 }
@@ -309,20 +333,9 @@ void CesiumBridgeAndroid::renderFrame(double nowSeconds) {
   // The integrator owns its own clock — see CameraIntegrator::step().
   // `nowSeconds` is still used below for the metrics-only dt EMA.
   auto actual = integrator_->step();
-
-  // ── Terrain floor clamp ───────────────────────────────────────────────
-  const float minAbove = engine_->getConfig().minAltitudeAboveTerrain;
-  if (minAbove > 0.0f && engine_->terrainFloorKnown()) {
-    const double geoidN =
-        reactnativecesium::mslToEllipsoidMeters(actual.latitude, actual.longitude, 0.0);
-    const double floorMsl =
-        static_cast<double>(engine_->terrainFloorEllipsoidMeters()) - geoidN;
-    const double minMsl = floorMsl + static_cast<double>(minAbove);
-    if (actual.altitude < minMsl) {
-      integrator_->clampActualAltitude(minMsl);
-      actual.altitude = minMsl;
-    }
-  }
+  actual = reactnativecesium::applyTerrainFloor(
+      *engine_, *integrator_, actual, terrainLead_,
+      static_cast<double>(engine_->getConfig().minAltitudeAboveTerrain));
 
   engine_->camera().setParams(actual);
 
@@ -348,7 +361,11 @@ double CesiumBridgeAndroid::readActualLongitude() {
   return integrator_ ? integrator_->getActual().longitude : 0.0;
 }
 double CesiumBridgeAndroid::readActualAltitude() {
-  return integrator_ ? integrator_->getActual().altitude : 0.0;
+  if (!integrator_) return 0.0;
+  const auto actual = integrator_->getActual();
+  return reactnativecesium::mslToDemandAltitudeMeters(
+      actual.latitude, actual.longitude, actual.altitude,
+      altitudeIsEllipsoid_.load(std::memory_order_acquire));
 }
 double CesiumBridgeAndroid::readActualHeading() {
   return integrator_ ? integrator_->getActual().heading : 0.0;
@@ -372,7 +389,11 @@ double CesiumBridgeAndroid::readDemandLongitude() {
   return integrator_ ? integrator_->getDemand().longitude : 0.0;
 }
 double CesiumBridgeAndroid::readDemandAltitude() {
-  return integrator_ ? integrator_->getDemand().altitude : 0.0;
+  if (!integrator_) return 0.0;
+  const auto demand = integrator_->getDemand();
+  return reactnativecesium::mslToDemandAltitudeMeters(
+      demand.latitude, demand.longitude, demand.altitude,
+      altitudeIsEllipsoid_.load(std::memory_order_acquire));
 }
 double CesiumBridgeAndroid::readDemandHeading() {
   return integrator_ ? integrator_->getDemand().heading : 0.0;
@@ -463,6 +484,11 @@ Java_com_margelo_nitro_reactnativecesium_CesiumBridgeJNI_nativeSetPosition(
   getBridge(ptr)->setPosition(lat, lon);
 }
 JNIEXPORT void JNICALL
+Java_com_margelo_nitro_reactnativecesium_CesiumBridgeJNI_nativeSetAltitudeDatumEllipsoid(
+    JNIEnv*, jobject, jlong ptr, jboolean ellipsoid) {
+  getBridge(ptr)->setAltitudeDatumEllipsoid(ellipsoid == JNI_TRUE);
+}
+JNIEXPORT void JNICALL
 Java_com_margelo_nitro_reactnativecesium_CesiumBridgeJNI_nativeSetAltitude(
     JNIEnv*, jobject, jlong ptr, jdouble alt) {
   getBridge(ptr)->setAltitude(alt);

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

@@ -8,6 +8,7 @@
 #include "engine/CameraIntegrator.hpp"
 #include "engine/CesiumEngine.hpp"
 #include "engine/MetricsAggregator.hpp"
+#include "engine/TerrainFloor.hpp"
 
 struct ANativeWindow;
 
@@ -47,6 +48,10 @@ struct CesiumBridgeAndroid {
 
   // ── Per-DoF camera demand setters ──────────────────────────────────────
   void setPosition(double lat, double lon);
+  // When true, altitudes passed to setAltitude/teleport are WGS84 ellipsoidal
+  // heights. They are converted to MSL before the integrator, and altitude
+  // readback is converted back. A horizontal move keeps that ellipsoidal height.
+  void setAltitudeDatumEllipsoid(bool ellipsoid);
   void setAltitude(double alt);
   void setHeading(double headingDeg);
   void setAttitude(double pitchDeg, double rollDeg);
@@ -137,6 +142,9 @@ private:
   int  viewportWidth_  = 0;
   int  viewportHeight_ = 0;
   bool initialized_    = false;
+  // Written from the render thread when the prop changes; read from the
+  // caller thread inside setAltitude / setPosition / teleport / readback.
+  std::atomic<bool> altitudeIsEllipsoid_{false};
 
   // Force-render flag — set on every demand change so the render loop knows
   // to dispatch at least one frame.
@@ -144,5 +152,6 @@ private:
 
   reactnativecesium::EngineConfig      config_;
   reactnativecesium::MetricsAggregator metrics_;
+  reactnativecesium::TerrainLeadState  terrainLead_{};
   double                               lastTickSeconds_ = 0.0;
 };

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

@@ -27,6 +27,8 @@ class CesiumBridgeJNI {
 
   // ── Per-DoF camera setters ───────────────────────────────────────────────
   fun setPosition(lat: Double, lon: Double) = nativeSetPosition(nativePtr, lat, lon)
+  fun setAltitudeDatumEllipsoid(ellipsoid: Boolean) =
+    nativeSetAltitudeDatumEllipsoid(nativePtr, ellipsoid)
   fun setAltitude(alt: Double) = nativeSetAltitude(nativePtr, alt)
   fun setHeading(headingDeg: Double) = nativeSetHeading(nativePtr, headingDeg)
   fun setAttitude(pitchDeg: Double, rollDeg: Double) = nativeSetAttitude(nativePtr, pitchDeg, rollDeg)
@@ -107,6 +109,7 @@ class CesiumBridgeJNI {
   private external fun nativeUpdateImageryAssetId(ptr: Long, assetId: Long)
 
   private external fun nativeSetPosition(ptr: Long, lat: Double, lon: Double)
+  private external fun nativeSetAltitudeDatumEllipsoid(ptr: Long, ellipsoid: Boolean)
   private external fun nativeSetAltitude(ptr: Long, alt: Double)
   private external fun nativeSetHeading(ptr: Long, headingDeg: Double)
   private external fun nativeSetAttitude(ptr: Long, pitchDeg: Double, rollDeg: Double)

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

@@ -105,6 +105,14 @@ class HybridCesiumView(private val appContext: Context) : HybridCesiumViewSpec()
   override var ionImageryAssetId: Double = 1.0
     set(value) { field = value; postToRender { bridge?.updateImageryAssetId(value.toLong()) } }
 
+  /** `"msl"` (default) or `"ellipsoid"`. Ellipsoid heights are converted to MSL. */
+  override var altitudeDatum: String? = "msl"
+    set(value) {
+      field = value
+      val ellipsoid = value == "ellipsoid"
+      postToRender { bridge?.setAltitudeDatumEllipsoid(ellipsoid) }
+    }
+
   // ── Optional perf / quality knobs ────────────────────────────────────────
   override var maximumCachedMiB: Double? = null
     set(value) { field = value; if (value != null) postToRender { bridge?.setMaximumCachedMiB(value.toInt()) } }
@@ -519,6 +527,7 @@ class HybridCesiumView(private val appContext: Context) : HybridCesiumViewSpec()
     // sqliteCacheMaxRows and taskProcessorThreads are applied before init() in
     // surfaceCreated; calling them here (after buildEngine) has no effect.
     minAltitudeAboveTerrain?.let { b.setMinAltitudeAboveTerrain(it.toFloat()) }
+    b.setAltitudeDatumEllipsoid(altitudeDatum == "ellipsoid")
   }
 
   /**

package/cpp/engine/CameraIntegrator.cpp

@@ -110,7 +110,7 @@ void CameraIntegrator::updateAlphaBeta(
 }
 
 void CameraIntegrator::extrapolate(
-    AlphaBeta& s, TimePoint now, double maxRateAbs, double demand) {
+    AlphaBeta& s, TimePoint now, double maxRateAbs, double demand, bool wrapAngle) {
   double dt = std::chrono::duration<double>(now - s.tState).count();
   if (dt <= 0.0) {
     s.tState = now;
@@ -166,8 +166,9 @@ void CameraIntegrator::extrapolate(
   // sensor streams always deliver a new update before the grace window
   // expires, so this term is never active for them.
   if (measurementsStopped && tunables::kDemandPullTauSec > 1.0e-6) {
-    s.value += (1.0 - std::exp(-dt / tunables::kDemandPullTauSec))
-               * (demand - s.value);
+    const double delta = wrapAngle ? shortAngleDeltaDeg(s.value, demand)
+                                   : (demand - s.value);
+    s.value += (1.0 - std::exp(-dt / tunables::kDemandPullTauSec)) * delta;
   }
 }
 
@@ -203,21 +204,11 @@ void CameraIntegrator::setAltitude(double altitudeMeters) {
   }
 
   altitudeMeters = std::min(altitudeMeters, kMaxAltMeters);
-  
-  // Adaptive alpha based on altitude error magnitude:
-  // - Large changes (pinch gesture, cliffs) → fast (α ≈ 0.7)
-  // - Small changes (gentle terrain) → smooth (α ≈ 0.3)
-  const double error = std::abs(altitudeMeters - alt_.value);
-  constexpr double kMinAlpha = 0.3;   // Smooth for small changes
-  constexpr double kMaxAlpha = 0.7;   // Fast for large changes
-  constexpr double kErrorScale = 20.0; // 20m error → max alpha
-  
-  const double adaptiveAlpha = kMinAlpha + (kMaxAlpha - kMinAlpha) * 
-                               std::min(error / kErrorScale, 1.0);
-  
+
   updateAlphaBeta(alt_, altitudeMeters, now,
-                  adaptiveAlpha, tunables::kBetaAlt, false);
+                  tunables::kAlphaAlt, tunables::kBetaAlt, false);
   demand_.altitude = altitudeMeters;
+  enforceTerrainFloor();
 }
 
 void CameraIntegrator::setHeading(double headingDeg) {
@@ -261,13 +252,8 @@ void CameraIntegrator::setViewCorrection(const glm::dquat& q) {
 }
 
 void CameraIntegrator::setVerticalFov(double degrees) {
-  const auto now = Clock::now();
   std::lock_guard<std::mutex> g(mutex_);
-
-  const double residual = degrees - vfov_.value;
-  vfov_.value   += tunables::kAlphaVfov * residual;
-  vfov_.velocity = 0.0;
-  vfov_.tState   = now;
+  demand_.verticalFov = degrees;
 }
 
 void CameraIntegrator::teleport(const CameraParams& target) {
@@ -305,6 +291,12 @@ void CameraIntegrator::teleport(const CameraParams& target) {
   if (demand_.verticalFov <= 0.0) {
     demand_.verticalFov = vfov_.value;
   }
+
+  // A slew lands on the requested altitude. The next rendered frame samples
+  // the terrain at the new position and establishes a new floor.
+  terrainFloorActive_ = false;
+  terrainFloorMsl_    = 0.0;
+  lastStep_           = now;
 }
 
 CameraParams CameraIntegrator::step() {
@@ -328,13 +320,27 @@ CameraParams CameraIntegrator::step() {
     latLonCapDegSec = glm::degrees(groundCap / kEarthMeanRadiusM);
   }
 
-  extrapolate(lat_,   now, latLonCapDegSec, demand_.latitude);
-  extrapolate(lon_,   now, latLonCapDegSec, demand_.longitude);
-  extrapolate(alt_,   now, climbCap,        demand_.altitude);
-  extrapolate(hdg_,   now, yawCap,          demand_.heading);
-  extrapolate(pitch_, now, pitchCap,        demand_.pitch);
-  extrapolate(roll_,  now, rollCap,         demand_.roll);
-  extrapolate(vfov_,  now, 0.0,             demand_.verticalFov);
+  extrapolate(lat_,   now, latLonCapDegSec, demand_.latitude,  false);
+  extrapolate(lon_,   now, latLonCapDegSec, demand_.longitude, true);
+  extrapolate(alt_,   now, climbCap,        demand_.altitude,  false);
+  extrapolate(hdg_,   now, yawCap,          demand_.heading,   true);
+  extrapolate(pitch_, now, pitchCap,        demand_.pitch,     true);
+  extrapolate(roll_,  now, rollCap,         demand_.roll,      true);
+
+  double frameDt = 0.0;
+  if (lastStep_.time_since_epoch().count() > 0) {
+    frameDt = std::chrono::duration<double>(now - lastStep_).count();
+    if (frameDt < 0.0) frameDt = 0.0;
+    if (frameDt > tunables::kMaxFrameDtSec) frameDt = tunables::kMaxFrameDtSec;
+  }
+  lastStep_ = now;
+
+  if (frameDt > 0.0 && tunables::kVfovTauSec > 1.0e-6) {
+    const double blend = 1.0 - std::exp(-frameDt / tunables::kVfovTauSec);
+    vfov_.value += blend * (demand_.verticalFov - vfov_.value);
+    vfov_.velocity = 0.0;
+    vfov_.tState = now;
+  }
 
   hdg_.value = wrap360(hdg_.value);
   lat_.value = std::clamp(lat_.value, -90.0, 90.0);
@@ -343,12 +349,19 @@ CameraParams CameraIntegrator::step() {
   // continuous value for short-arc maths and the camera transform doesn't
   // care.
 
-  // viewCorrection: SLERP toward the latest target.
+  // viewCorrection: time-based SLERP toward the latest target.
   glm::dquat cur = glm::normalize(viewCorrActual_);
   glm::dquat tgt = glm::normalize(viewCorrTarget_);
   if (glm::dot(cur, tgt) < 0.0) tgt = -tgt;
-  viewCorrActual_ = glm::normalize(
-      glm::slerp(cur, tgt, tunables::kAlphaViewCorr));
+  double slerpT = 1.0;
+  if (tunables::kViewCorrTauSec > 1.0e-6) {
+    slerpT = (frameDt > 0.0)
+                 ? (1.0 - std::exp(-frameDt / tunables::kViewCorrTauSec))
+                 : 0.0;
+  }
+  viewCorrActual_ = glm::normalize(glm::slerp(cur, tgt, slerpT));
+
+  enforceTerrainFloor();
 
   CameraParams out;
   out.latitude       = lat_.value;
@@ -362,23 +375,40 @@ CameraParams CameraIntegrator::step() {
   return out;
 }
 
-void CameraIntegrator::clampActualAltitude(double newAltMsl) {
-  const auto now = Clock::now();
+void CameraIntegrator::setTerrainFloor(double floorMsl) {
   std::lock_guard<std::mutex> g(mutex_);
-  
-  // Instead of snapping, feed the clamped altitude through the alpha-beta
-  // tracker for smooth interpolation. This matches how heading/pitch/roll work.
-  updateAlphaBeta(alt_, newAltMsl, now,
-                  tunables::kAlphaAlt, tunables::kBetaAlt, false);
-  
-  // Only clamp DOWNWARD velocity to prevent descending through terrain.
-  // Allow upward velocity for smooth ascents over rising terrain.
-  if (alt_.velocity < 0.0) {
+  if (!std::isfinite(floorMsl)) return;
+  terrainFloorActive_ = true;
+  terrainFloorMsl_ = std::min(floorMsl, kMaxAltMeters);
+  enforceTerrainFloor();
+}
+
+void CameraIntegrator::clearTerrainFloor() {
+  std::lock_guard<std::mutex> g(mutex_);
+  terrainFloorActive_ = false;
+  terrainFloorMsl_ = 0.0;
+}
+
+void CameraIntegrator::clampActualAltitude(double newAltMsl) {
+  setTerrainFloor(newAltMsl);
+}
+
+void CameraIntegrator::enforceTerrainFloor() {
+  if (!terrainFloorActive_) return;
+
+  const bool inContact =
+      demand_.altitude <= terrainFloorMsl_ + tunables::kEpsAltitudeMeters;
+  if (inContact) {
+    // Contour contact: the floor sample owns altitude, both directions.
+    // Residual vertical velocity would carry the camera into the next face.
+    alt_.value = terrainFloorMsl_;
     alt_.velocity = 0.0;
+    return;
+  }
+  if (alt_.value < terrainFloorMsl_) {
+    alt_.value = terrainFloorMsl_;
+    if (alt_.velocity < 0.0) alt_.velocity = 0.0;
   }
-  
-  // Do not touch demand_.altitude — getDemand() should still report what the
-  // user asked for.
 }
 
 void CameraIntegrator::setRateCaps(const CameraRateCaps& caps) {
@@ -410,7 +440,12 @@ bool CameraIntegrator::isActive() const {
   if (std::abs(demand_.latitude  - lat_.value)  > tunables::kEpsLatLon)         return true;
   if (std::abs(shortAngleDeltaDeg(lon_.value, demand_.longitude))
         > tunables::kEpsLatLon)                                                  return true;
-  if (std::abs(demand_.altitude  - alt_.value)  > tunables::kEpsAltitudeMeters) return true;
+  if (terrainFloorActive_ &&
+      demand_.altitude <= terrainFloorMsl_ + tunables::kEpsAltitudeMeters) {
+    if (std::abs(alt_.value - terrainFloorMsl_) > tunables::kEpsAltitudeMeters) return true;
+  } else if (std::abs(demand_.altitude - alt_.value) > tunables::kEpsAltitudeMeters) {
+    return true;
+  }
   if (angleAbsDeltaDeg(demand_.heading, hdg_.value) > tunables::kEpsAngleDeg)   return true;
   if (angleAbsDeltaDeg(demand_.pitch,   pitch_.value) > tunables::kEpsAngleDeg) return true;
   if (angleAbsDeltaDeg(demand_.roll,    roll_.value)  > tunables::kEpsAngleDeg) return true;

package/cpp/engine/CameraIntegrator.hpp

@@ -73,11 +73,18 @@ public:
   // values and an instant runaway.
   CameraParams step();
 
-  // Terrain-floor write-back hook. Replaces the *actual* altitude value with
-  // `newAltMsl` and zeroes vertical velocity so the integrator does not
-  // immediately try to descend back through the floor. The *demand* altitude
-  // is left untouched — getDemand().altitude continues to reflect what the
-  // consumer asked for.
+  // Terrain floor in metres MSL. While active, the rendered altitude is never
+  // below this value. When the demand altitude is at or below the floor the
+  // camera rides it exactly (uphill and downhill), so a later setAltitude
+  // under the surface cannot pull the rendered camera back inside. Demand
+  // itself is left untouched.
+  void setTerrainFloor(double floorMsl);
+
+  // Drops the floor so the next slew or the next frame can establish a new
+  // one. Used by teleport().
+  void clearTerrainFloor();
+
+  // Sets the terrain floor to `newAltMsl`. Same as setTerrainFloor.
   void clampActualAltitude(double newAltMsl);
 
   // Runtime override of the rate caps (driven by view props). 0 = uncapped
@@ -122,9 +129,14 @@ private:
                               double alpha, double beta, bool wrapAngle);
 
   // Advance the running estimate to `now`, clamp velocity to `maxRateAbs`
-  // (per second; 0 = uncapped). For angles, the resulting value is also
-  // normalised to its canonical range by the caller as needed.
-  static void extrapolate(AlphaBeta& s, TimePoint now, double maxRateAbs, double demand);
+  // (per second; 0 = uncapped). `wrapAngle` makes the silence demand-pull
+  // take the short arc (longitude, heading, pitch, roll).
+  static void extrapolate(AlphaBeta& s, TimePoint now, double maxRateAbs,
+                          double demand, bool wrapAngle);
+
+  // Snap the rendered altitude onto the floor when the camera is in contact
+  // or currently below it. Demand is not modified.
+  void enforceTerrainFloor();
 
   mutable std::mutex mutex_;
 
@@ -141,6 +153,13 @@ private:
 
   // Runtime overrides; 0 = use compile-time defaults from EngineTunables.
   CameraRateCaps caps_{};
+
+  // Last step() timestamp. Drives the dt-based fov blend and view-correction
+  // slerp. Epoch means "no step yet".
+  TimePoint lastStep_{};
+
+  bool   terrainFloorActive_ = false;
+  double terrainFloorMsl_    = 0.0;
 };
 
 } // namespace reactnativecesium