react-native-cesium 1.2.1 → 1.2.2

package/README.md

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

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

@@ -244,8 +244,7 @@ void CesiumBridgeAndroid::renderFrame(double dt) {
 
   const auto cur    = engine_->camera().getParams();
   const auto tgt    = target_.snapshot();
-  auto smooth = reactnativecesium::CameraSmoother::step(
-      cur, tgt, dt, target_.recentIntervalSec());
+  auto smooth = reactnativecesium::CameraSmoother::step(cur, tgt, dt);
 
   // ── Terrain floor clamp ───────────────────────────────────────────────
   const float minAbove = engine_->getConfig().minAltitudeAboveTerrain;

package/cpp/engine/CameraSmoother.cpp

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

package/cpp/engine/CameraSmoother.hpp

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

package/cpp/engine/CameraTargetState.cpp

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

package/cpp/engine/CameraTargetState.hpp

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

package/ios/CesiumBridge.mm

@@ -277,8 +277,7 @@
 
     const auto cur    = _engine->camera().getParams();
     const auto tgt    = _target.snapshot();
-    auto smooth = reactnativecesium::CameraSmoother::step(
-        cur, tgt, dt, _target.recentIntervalSec());
+    auto smooth = reactnativecesium::CameraSmoother::step(cur, tgt, dt);
 
     // ── Terrain floor clamp ───────────────────────────────────────────────
     // Uses terrain floor from the previous frame (one-frame lag is

package/package.json

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