react-native-cesium 1.2.2 → 1.2.3

package/README.md

@@ -403,10 +403,11 @@ Every value you pass to `setCamera` / `setCameraQuaternion` is treated as a **de
 
 | DoF | Smoothing |
 | --- | --- |
-| `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. |
+| `latitude` / `longitude` | **Linear interpolation** — own independent EWMA. Constant-velocity glide at GPS cadence; near-instant at gesture rate. Cross-planet jumps (Δ > ~0.5°) bypass interpolation. Antimeridian crossings always rotate the short way. |
+| `altitude` | **Linear interpolation** — own independent EWMA. Self-tunes whether altitude comes from GPS (1 Hz → 1 s glide) or a barometer (50 Hz → ~20 ms, near-instant). Jumps > 500 m bypass interpolation. |
+| `heading` | **Linear interpolation** — own independent EWMA. Constant yaw-rate between GPS course-over-ground fixes; near-instant when heading comes from a magnetometer at high rate. Jumps > 90° bypass interpolation. |
+| `pitch` / `roll` | Exponential on the shortest-arc angular delta, fixed `τ ≈ 20 ms`. Almost always attitude-sensor driven; ease-out feel is appropriate. |
+| `viewCorrection` (quaternion) | SLERP-based exponential, fixed `τ ≈ 20 ms`, hemisphere-corrected. |
 | `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.

package/cpp/engine/CameraSmoother.cpp

@@ -29,34 +29,31 @@ CameraParams CameraSmoother::step(
     const CameraParams& current, const CameraParams& target, double dt) {
   CameraParams next = current;
 
-  // 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.
+  // lat / lon / altitude / heading: snap directly to the (already linearly-
+  // interpolated) target from CameraTargetState::snapshot(). The constant-
+  // velocity motion is fully handled there; no additional smoothing is applied
+  // here so the movement stays linear rather than decelerating.
   next.latitude  = target.latitude;
   next.longitude = target.longitude;
+  next.altitude  = target.altitude;
+  next.heading   = target.heading;
 
-  const double aAlt   = 1.0 - std::exp(-tunables::kSmoothAltitude * dt);
-  const double aHdg   = 1.0 - std::exp(-tunables::kSmoothHeading  * dt);
+  // pitch / roll / viewCorrection: exponential ease-out. These are almost
+  // always driven by high-rate attitude sensors (accelerometer, gyroscope)
+  // where the ease-out feel is appropriate and desired.
   const double aPitch = 1.0 - std::exp(-tunables::kSmoothPitch    * dt);
   const double aRoll  = 1.0 - std::exp(-tunables::kSmoothRoll     * dt);
   const double aViewQ = 1.0 - std::exp(-tunables::kSmoothViewCorr * dt);
 
-  next.altitude = current.altitude + aAlt * (target.altitude - current.altitude);
-  next.heading  = lerpAngleDeg(current.heading, target.heading, aHdg);
-  next.pitch    = lerpAngleDeg(current.pitch,   target.pitch,   aPitch);
-  next.roll     = lerpAngleDeg(current.roll,    target.roll,    aRoll);
+  next.pitch    = lerpAngleDeg(current.pitch, target.pitch, aPitch);
+  next.roll     = lerpAngleDeg(current.roll,  target.roll,  aRoll);
 
   glm::dquat cq = glm::normalize(current.viewCorrection);
   glm::dquat tq = glm::normalize(target.viewCorrection);
   if (glm::dot(cq, tq) < 0.0) tq = -tq;
   next.viewCorrection = glm::normalize(glm::slerp(cq, tq, aViewQ));
 
-  // Eventually-exact convergence: snap once the residual is sub-epsilon.
-  if (std::abs(target.altitude - next.altitude) <= tunables::kEpsAltitudeMeters)
-    next.altitude = target.altitude;
-  if (angleDeltaAbsDeg(next.heading, target.heading) <= tunables::kEpsAngleDeg)
-    next.heading = target.heading;
+  // Eventually-exact convergence for exponential DoFs: snap once sub-epsilon.
   if (angleDeltaAbsDeg(next.pitch, target.pitch) <= tunables::kEpsAngleDeg)
     next.pitch = target.pitch;
   if (angleDeltaAbsDeg(next.roll, target.roll) <= tunables::kEpsAngleDeg)

package/cpp/engine/CameraSmoother.hpp

@@ -7,14 +7,17 @@ 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:
-//   - 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
-//     to the target so we eventually reach exact equality.
+// lat / lon / altitude / heading are snapped directly to the target.
+// CameraTargetState::snapshot() has already linearly interpolated those DoFs
+// to their "current" position based on each DoF's own EWMA inter-arrival
+// interval, so snapping here gives constant-velocity motion between fixes
+// with no ease-in/ease-out. At gesture rates (~60 Hz) the EWMA collapses to
+// ~16 ms so the snap is indistinguishable from the previous behaviour.
+//
+// pitch / roll / viewCorrection use fixed-rate exponential decay
+// `1 - exp(-k * dt)` with k from EngineTunables — appropriate for high-rate
+// attitude sensors where the ease-out feel is desirable.
+// Once a DoF drops below its matching epsilon it is snapped to exact equality.
 class CameraSmoother {
 public:
   static CameraParams step(const CameraParams& current,

package/cpp/engine/CameraTargetState.cpp

@@ -15,11 +15,29 @@ 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) {
+// Shortest signed angular delta wrapped to [-180, 180].
+inline double shortAngleDeltaDeg(double from, double to) {
   return std::fmod(to - from + 540.0, 360.0) - 180.0;
 }
 
+// Advance an EWMA with a new sample, or seed it on first use.
+inline void updateEwma(double& ewma, bool& active,
+                       std::chrono::steady_clock::time_point& lastTime,
+                       const std::chrono::steady_clock::time_point& now,
+                       double seedSec) {
+  if (!active) {
+    ewma     = seedSec;
+    lastTime = now;
+    active   = true;
+  } else {
+    const double dt = std::chrono::duration<double>(now - lastTime).count();
+    if (dt > 0.0) {
+      ewma = ewma + tunables::kEwmaIntervalAlpha * (dt - ewma);
+    }
+    lastTime = now;
+  }
+}
+
 } // namespace
 
 // ── Public writers ────────────────────────────────────────────────────────────
@@ -28,8 +46,8 @@ 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.
+    // Deliberately do NOT touch any interpolation state: setAll is init-only
+    // and the first rendered frame must snap to the requested position.
   }
   dirty_.store(true, std::memory_order_release);
   forceRender_.store(true, std::memory_order_release);
@@ -40,33 +58,58 @@ void CameraTargetState::setHpr(double lat, double lon, double alt,
   {
     std::lock_guard<std::mutex> g(mutex_);
 
+    const auto now = std::chrono::steady_clock::now();
+
+    // ── lat / lon ─────────────────────────────────────────────────────────
     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;
+      if (!hasPosInterp_) {
+        // First runtime change: seed "from" = destination for a clean snap,
+        // then enable interpolation for subsequent updates.
+        posFromLat_ = lat;
+        posFromLon_ = lon;
+        updateEwma(posEwmaIntervalSec_, hasPosInterp_, posUpdateTime_, now,
+                   tunables::kSmoothPositionTauMax / tunables::kSmoothPositionAlpha);
       } 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;
+        updateEwma(posEwmaIntervalSec_, hasPosInterp_, posUpdateTime_, now,
+                   tunables::kSmoothPositionTauMax / tunables::kSmoothPositionAlpha);
+      }
+    }
 
-        const double dt = std::chrono::duration<double>(now - posUpdateTime_).count();
-        if (dt > 0.0) {
-          ewmaIntervalSec_ = ewmaIntervalSec_ +
-              tunables::kEwmaIntervalAlpha * (dt - ewmaIntervalSec_);
-        }
-        posUpdateTime_ = now;
+    // ── altitude ──────────────────────────────────────────────────────────
+    const bool altChanged =
+        std::abs(alt - target_.altitude) > tunables::kEpsAltitudeMeters;
+
+    if (altChanged) {
+      if (!hasAltInterp_) {
+        altFrom_ = alt;
+        updateEwma(altEwmaIntervalSec_, hasAltInterp_, altUpdateTime_, now,
+                   tunables::kSmoothPositionTauMax / tunables::kSmoothPositionAlpha);
+      } else {
+        altFrom_ = target_.altitude;
+        updateEwma(altEwmaIntervalSec_, hasAltInterp_, altUpdateTime_, now,
+                   tunables::kSmoothPositionTauMax / tunables::kSmoothPositionAlpha);
+      }
+    }
+
+    // ── heading ───────────────────────────────────────────────────────────
+    const bool hdgChanged =
+        angleDeltaAbsDeg(heading, target_.heading) > tunables::kEpsAngleDeg;
+
+    if (hdgChanged) {
+      if (!hasHdgInterp_) {
+        hdgFrom_ = heading;
+        updateEwma(hdgEwmaIntervalSec_, hasHdgInterp_, hdgUpdateTime_, now,
+                   tunables::kSmoothPositionTauMax / tunables::kSmoothPositionAlpha);
+      } else {
+        hdgFrom_ = target_.heading;
+        updateEwma(hdgEwmaIntervalSec_, hasHdgInterp_, hdgUpdateTime_, now,
+                   tunables::kSmoothPositionTauMax / tunables::kSmoothPositionAlpha);
       }
     }
 
@@ -85,8 +128,8 @@ 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.
+    // Interpolation state is not touched — viewCorrection carries no
+    // positional information and must not affect any of the three EWMAs.
   }
   dirty_.store(true, std::memory_order_release);
   forceRender_.store(true, std::memory_order_release);
@@ -100,12 +143,11 @@ CameraParams CameraTargetState::snapshot() const {
 
   CameraParams result = target_;
 
-  if (hasInterpolation_ && ewmaIntervalSec_ > 0.0) {
+  // ── lat / lon ─────────────────────────────────────────────────────────────
+  if (hasPosInterp_ && posEwmaIntervalSec_ > 0.0) {
     const double dLat = target_.latitude - posFromLat_;
-    const double dLon = lonDeltaDeg(posFromLon_, target_.longitude);
+    const double dLon = shortAngleDeltaDeg(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;
@@ -113,13 +155,36 @@ CameraParams CameraTargetState::snapshot() const {
     if (!snapThrough) {
       const double elapsed =
           std::chrono::duration<double>(now - posUpdateTime_).count();
-      const double t = std::min(elapsed / ewmaIntervalSec_, 1.0);
-
+      const double t = std::min(elapsed / posEwmaIntervalSec_, 1.0);
       result.latitude  = posFromLat_ + t * dLat;
       result.longitude = posFromLon_ + t * dLon;
     }
   }
 
+  // ── altitude ──────────────────────────────────────────────────────────────
+  if (hasAltInterp_ && altEwmaIntervalSec_ > 0.0) {
+    const double dAlt = target_.altitude - altFrom_;
+
+    if (std::abs(dAlt) <= tunables::kAltSnapThroughMeters) {
+      const double elapsed =
+          std::chrono::duration<double>(now - altUpdateTime_).count();
+      const double t = std::min(elapsed / altEwmaIntervalSec_, 1.0);
+      result.altitude = altFrom_ + t * dAlt;
+    }
+  }
+
+  // ── heading ───────────────────────────────────────────────────────────────
+  if (hasHdgInterp_ && hdgEwmaIntervalSec_ > 0.0) {
+    const double dHdg = shortAngleDeltaDeg(hdgFrom_, target_.heading);
+
+    if (std::abs(dHdg) <= tunables::kHdgSnapThroughDeg) {
+      const double elapsed =
+          std::chrono::duration<double>(now - hdgUpdateTime_).count();
+      const double t = std::min(elapsed / hdgEwmaIntervalSec_, 1.0);
+      result.heading = hdgFrom_ + t * dHdg;
+    }
+  }
+
   return result;
 }
 

package/cpp/engine/CameraTargetState.hpp

@@ -22,41 +22,49 @@ 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.
+// Per-DoF linear interpolation (lat/lon, altitude, heading)
+// ──────────────────────────────────────────────────────────
+// Each of lat/lon, altitude, and heading maintains its own independent EWMA
+// of inter-arrival times and only updates that EWMA when *its own value*
+// actually changes. snapshot() then linearly interpolates each DoF from its
+// previous value to its current target over its own EWMA interval.
 //
-// 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.
+// This means lat/lon, altitude, and heading each self-tune independently:
+//   - 60 Hz gesture input → EWMA ~16 ms → interpolation near-instant (snap)
+//   - 1 Hz GPS → EWMA ~1 s → constant-velocity glide between fixes
+//   - 50 Hz barometer for altitude + 1 Hz GPS for lat/lon → altitude behaves
+//     near-instant, lat/lon glides — with no special-casing needed.
+//
+// Special cases in snapshot():
+//   - t >= 1: camera has reached the target, returns target_ directly.
+//   - Snap-through guard: large jumps bypass interpolation so deliberate
+//     teleports remain instant.
+//   - First change per DoF: "from" = destination, so lerp(dest, dest, t) = dest
+//     for all t — clean snap, no startup glide.
+//   - setAll (init-only): never touches any interpolation state.
+//
+// pitch / roll / viewCorrection are NOT interpolated here; CameraSmoother
+// applies fixed-rate exponential curves to them (appropriate for high-rate
+// attitude sensors).
 class CameraTargetState {
 public:
   CameraTargetState() = default;
 
   // Replace the entire target. Used only for engine initialisation; does NOT
-  // update position-interpolation state so the first rendered frame snaps.
+  // update any 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.
+  // Independently tracks cadence for lat/lon, altitude, and heading.
   void setHpr(double lat, double lon, double alt,
               double heading, double pitch, double roll);
 
   void setViewCorrection(const glm::dquat& q);
 
-  // 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).
+  // Snapshot the demand target for this render frame. lat/lon, altitude, and
+  // heading are linearly interpolated to their "current" position based on
+  // each DoF's own EWMA interval. pitch/roll/viewCorrection are returned as-is
+  // (CameraSmoother handles their exponential curves).
   CameraParams snapshot() const;
 
   // Lightweight, lock-free check used by the render thread to decide whether
@@ -86,18 +94,33 @@ private:
   std::atomic<bool> dirty_{false};
   std::atomic<bool> forceRender_{true};
 
-  // ── 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};
+  // ── Per-DoF linear interpolation state (all protected by mutex_) ─────────
+  // Each DoF has: a "from" value, a wall-clock timestamp of the last change,
+  // an EWMA of inter-arrival times, and an "active" flag.
+  //
+  // Pattern per DoF:
+  //   First change:      from = destination (snap), seed EWMA, set active.
+  //   Subsequent change: from = old target, update EWMA, reset clock.
+  //   snapshot():        t = clamp(elapsed/ewma, 0, 1); result = from + t*delta.
+
+  // lat / lon
+  double                                posFromLat_{0.0};
+  double                                posFromLon_{0.0};
+  std::chrono::steady_clock::time_point posUpdateTime_{};
+  double                                posEwmaIntervalSec_{0.0};
+  bool                                  hasPosInterp_{false};
+
+  // altitude
+  double                                altFrom_{0.0};
+  std::chrono::steady_clock::time_point altUpdateTime_{};
+  double                                altEwmaIntervalSec_{0.0};
+  bool                                  hasAltInterp_{false};
+
+  // heading
+  double                                hdgFrom_{0.0};
+  std::chrono::steady_clock::time_point hdgUpdateTime_{};
+  double                                hdgEwmaIntervalSec_{0.0};
+  bool                                  hasHdgInterp_{false};
 };
 
 } // namespace reactnativecesium

package/cpp/engine/CesiumEngine.cpp

@@ -434,7 +434,9 @@ void CesiumEngine::updateFrame(double w, double h, FrameResult& result) {
   asyncSystem_.dispatchMainThreadTasks();
 
   const auto viewState     = camera_.computeViewState(w, h);
-  const auto& updateResult = tileset_->updateView({viewState});
+  const auto& updateResult =
+      tileset_->updateViewGroup(tileset_->getDefaultViewGroup(), {viewState});
+  tileset_->loadTiles();
 
   // Only emit the fallback ellipsoid when no real terrain is being rendered
   // this frame. Otherwise it would be over-drawn anyway (~8k vertices and

package/cpp/engine/EngineTunables.hpp

@@ -43,31 +43,43 @@ inline constexpr int32_t kDefaultLoadingDescendantLimit       = 20;
 
 // Camera smoothing constants — shared between platform bridges so jank /
 // motion feel is identical on iOS and Android.
-inline constexpr double kSmoothAltitude     = 25.0;
-inline constexpr double kSmoothHeading      = 30.0;
+//
+// lat / lon / altitude / heading use per-DoF linear interpolation inside
+// CameraTargetState::snapshot(): each DoF tracks its own EWMA of inter-arrival
+// times and linearly lerps from its previous value to its current target over
+// that interval. At ~60 Hz (gestures) the EWMA collapses to ~16 ms so the
+// motion is indistinguishable from a snap; at 1 Hz (GPS) the DoF glides at
+// constant velocity between fixes — no teleports or ease-out deceleration.
+// pitch / roll / viewCorrection remain on their fixed exponential curves
+// because they are almost always driven by high-rate attitude sensors.
+
+// Exponential smoothing for pitch / roll / viewCorrection (k = 1/τ).
 inline constexpr double kSmoothPitch        = 50.0;
 inline constexpr double kSmoothRoll         = 50.0;
 inline constexpr double kSmoothViewCorr     = 50.0;
+
+// Convergence epsilons (used by deltaExceedsEpsilon and snap-to-exact).
 inline constexpr double kEpsLatLon          = 1e-7;
 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.
+// Linear interpolation parameters shared by lat/lon, altitude, and heading.
+//
+// kSmoothPositionTauMax / kSmoothPositionAlpha is the seed value for the EWMA
+// on the first update (gives a generous interpolation window before the cadence
+// is known). kEwmaIntervalAlpha controls how quickly the EWMA adapts to a rate
+// change (0.3 = ~3-5 samples to converge to a new cadence).
 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;
 
+// Snap-through guards: deltas larger than these skip interpolation so a
+// deliberate teleport (e.g. setCamera(NewYork → Tokyo)) remains instant.
+inline constexpr double kPosSnapThroughDeg     = 0.5;    // lat or lon, ~55 km
+inline constexpr double kAltSnapThroughMeters  = 500.0;  // altitude
+inline constexpr double kHdgSnapThroughDeg     = 90.0;   // heading
+
 // Metrics throttle: emit telemetry every N rendered frames.
 inline constexpr int kMetricsEmitEveryFrames = 20;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-cesium",
-  "version": "1.2.2",
+  "version": "1.2.3",
   "description": "Experimental Cesium rendering for React Native via Nitro (iOS/Metal today; Android planned)",
   "main": "./lib/commonjs/index.js",
   "module": "./lib/module/index.js",
@@ -79,7 +79,7 @@
     "conventional-changelog-conventionalcommits": "^9.3.1",
     "nitrogen": "0.35.6",
     "react": "19.2.3",
-    "react-native": "0.85.2",
+    "react-native": "0.85.3",
     "react-native-builder-bob": "^0.41.0",
     "semantic-release": "^25.0.3",
     "typescript": "^5.9.3"