react-native-cesium 1.1.0 → 1.2.0

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

@@ -239,7 +239,8 @@ 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);
+  const auto smooth = reactnativecesium::CameraSmoother::step(
+      cur, tgt, dt, target_.recentIntervalSec());
   engine_->camera().setParams(smooth);
 
   // If we converged, clear the dirty flag so the next idle vsync can early-out.

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/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.mm

@@ -271,7 +271,8 @@
 
     const auto cur    = _engine->camera().getParams();
     const auto tgt    = _target.snapshot();
-    const auto smooth = reactnativecesium::CameraSmoother::step(cur, tgt, dt);
+    const auto smooth = reactnativecesium::CameraSmoother::step(
+        cur, tgt, dt, _target.recentIntervalSec());
     _engine->camera().setParams(smooth);
 
     if (!reactnativecesium::CameraTargetState::deltaExceedsEpsilon(smooth, tgt)) {

package/package.json

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