react-native-cesium 1.2.3 → 1.2.4

package/cpp/engine/CameraIntegrator.cpp

@@ -0,0 +1,374 @@
+#include "CameraIntegrator.hpp"
+
+#include "EngineTunables.hpp"
+
+#include <glm/gtc/quaternion.hpp>
+
+#include <algorithm>
+#include <cmath>
+
+namespace reactnativecesium {
+
+namespace {
+
+// WGS84 mean radius (m). Hard-coded so the integrator can be unit-tested in
+// isolation without linking CesiumGeospatial. Matches Ellipsoid::WGS84.
+inline constexpr double kEarthMeanRadiusM = 6371008.7714150595;
+
+inline double shortAngleDeltaDeg(double from, double to) {
+  return std::fmod(to - from + 540.0, 360.0) - 180.0;
+}
+
+inline double angleAbsDeltaDeg(double a, double b) {
+  return std::abs(shortAngleDeltaDeg(a, b));
+}
+
+inline double wrap360(double deg) {
+  double v = std::fmod(deg, 360.0);
+  if (v < 0.0) v += 360.0;
+  return v;
+}
+
+inline double clampAbs(double v, double maxAbs) {
+  if (maxAbs <= 0.0) return v;
+  if (v >  maxAbs) return  maxAbs;
+  if (v < -maxAbs) return -maxAbs;
+  return v;
+}
+
+inline double quatDotAbs(const glm::dquat& a, const glm::dquat& b) {
+  return std::abs(glm::dot(glm::normalize(a), glm::normalize(b)));
+}
+
+// Resolve a runtime rate cap (caps.X) against the compile-time default.
+// 0.0 means "no override" so we fall back to the EngineTunables value, which
+// may itself be 0.0 (i.e. uncapped). Negative values are treated as 0.
+inline double resolveCap(double rt, double dflt) {
+  return rt > 0.0 ? rt : (dflt > 0.0 ? dflt : 0.0);
+}
+
+} // namespace
+
+CameraIntegrator::CameraIntegrator(const CameraParams& initial) {
+  teleport(initial);
+}
+
+// ── α-β core ──────────────────────────────────────────────────────────────
+
+void CameraIntegrator::updateAlphaBeta(
+    AlphaBeta& s, double z, TimePoint tz,
+    double alpha, double beta, bool wrapAngle) {
+  // Predict the value at the time the measurement arrived. On the very first
+  // call (tState default-constructed = epoch) the predicted value is the
+  // current state (velocity == 0), so the result is identical to a snap.
+  const double dt   = std::chrono::duration<double>(tz - s.tState).count();
+  const double pred = s.value + s.velocity * std::max(dt, 0.0);
+
+  const double residual =
+      wrapAngle ? shortAngleDeltaDeg(pred, z) : (z - pred);
+
+  s.value = pred + alpha * residual;
+
+  // Velocity update is gated on a meaningful time gap. Two reasons:
+  //   - Bootstrap: a teleport(...) followed immediately by a setter in the
+  //     same microtask has dt ≈ 0. Dividing β by that produces an absurd
+  //     velocity estimate ("you climbed 100 m in zero seconds").
+  //   - Same-tick burst writes (e.g. setAltitude + setHeading inside a
+  //     single useAnimatedReaction tick): treat them as coincident updates
+  //     to two independent DoFs, not as a sample of the rate of change.
+  //
+  // 5 ms is well below any plausible sensor sample interval (max useful
+  // rate ~200 Hz) but comfortably above the coincident-call window. For
+  // longer gaps we also floor dt to 20 ms when computing β/dt so a single
+  // sub-frame measurement does not blow up the velocity estimate.
+  constexpr double kVelocityMinDtSec   = 0.005;
+  constexpr double kVelocityFloorDtSec = 0.020;
+  if (dt > kVelocityMinDtSec) {
+    const double dtForVel = std::max(dt, kVelocityFloorDtSec);
+    s.velocity += (beta / dtForVel) * residual;
+  }
+  s.tState = tz;
+
+  // Inter-arrival EWMA — used by the silence-aware velocity bleed in
+  // extrapolate(). The first setter after a teleport seeds tLastMeas
+  // without contributing to the EWMA (sentinel-epoch check). Sub-millisecond
+  // gaps are also skipped so a same-tick burst of writes does not pull the
+  // mean toward zero.
+  if (s.tLastMeas.time_since_epoch().count() > 0) {
+    const double interval = std::chrono::duration<double>(tz - s.tLastMeas).count();
+    if (interval > 1e-3) {
+      s.meanIntervalSec =
+          (1.0 - tunables::kIntervalEwmaAlpha) * s.meanIntervalSec
+          + tunables::kIntervalEwmaAlpha * interval;
+    }
+  }
+  s.tLastMeas = tz;
+}
+
+void CameraIntegrator::extrapolate(AlphaBeta& s, TimePoint now, double maxRateAbs) {
+  double dt = std::chrono::duration<double>(now - s.tState).count();
+  if (dt <= 0.0) {
+    s.tState = now;
+    return;
+  }
+  if (dt > tunables::kMaxFrameDtSec) {
+    dt = tunables::kMaxFrameDtSec;
+  }
+
+  // Silence-aware velocity bleed. Once measurements have stopped arriving
+  // for this DoF (e.g. the user released a pan gesture, or the joystick
+  // returned to centre), bleed the learned velocity exponentially. Both the
+  // grace window and the decay τ scale with the EWMA of inter-arrival times
+  // so a 60 Hz worklet bleeds in ~50 ms while a 1 Hz GPS glide is left
+  // alone between fixes.
+  if (s.tLastMeas.time_since_epoch().count() > 0) {
+    const double silence = std::chrono::duration<double>(now - s.tLastMeas).count();
+    const double grace   = tunables::kVelocitySilenceGraceFactor * s.meanIntervalSec;
+    if (silence > grace) {
+      const double tau = tunables::kVelocityBleedTauFactor * s.meanIntervalSec;
+      if (tau > 1.0e-6) {
+        s.velocity *= std::exp(-dt / tau);
+      } else {
+        s.velocity = 0.0;
+      }
+    }
+  }
+
+  if (maxRateAbs > 0.0) {
+    s.velocity = clampAbs(s.velocity, maxRateAbs);
+  }
+  s.value += s.velocity * dt;
+  s.tState = now;
+}
+
+// ── Demand setters ────────────────────────────────────────────────────────
+
+void CameraIntegrator::setPosition(double latitudeDeg, double longitudeDeg) {
+  const auto now = Clock::now();
+  std::lock_guard<std::mutex> g(mutex_);
+
+  if (tunables::kOutlierLatLonDeg > 0.0) {
+    if (std::abs(latitudeDeg  - lat_.value) > tunables::kOutlierLatLonDeg ||
+        std::abs(shortAngleDeltaDeg(lon_.value, longitudeDeg))
+            > tunables::kOutlierLatLonDeg) {
+      return;
+    }
+  }
+
+  updateAlphaBeta(lat_, latitudeDeg,  now,
+                  tunables::kAlphaPos, tunables::kBetaPos, false);
+  updateAlphaBeta(lon_, longitudeDeg, now,
+                  tunables::kAlphaPos, tunables::kBetaPos, true);
+  demand_.latitude  = latitudeDeg;
+  demand_.longitude = longitudeDeg;
+}
+
+void CameraIntegrator::setAltitude(double altitudeMeters) {
+  const auto now = Clock::now();
+  std::lock_guard<std::mutex> g(mutex_);
+
+  if (tunables::kOutlierAltMeters > 0.0 &&
+      std::abs(altitudeMeters - alt_.value) > tunables::kOutlierAltMeters) {
+    return;
+  }
+
+  updateAlphaBeta(alt_, altitudeMeters, now,
+                  tunables::kAlphaAlt, tunables::kBetaAlt, false);
+  demand_.altitude = altitudeMeters;
+}
+
+void CameraIntegrator::setHeading(double headingDeg) {
+  const auto now = Clock::now();
+  std::lock_guard<std::mutex> g(mutex_);
+
+  if (tunables::kOutlierHeadingDeg > 0.0 &&
+      angleAbsDeltaDeg(headingDeg, hdg_.value) > tunables::kOutlierHeadingDeg) {
+    return;
+  }
+
+  updateAlphaBeta(hdg_, headingDeg, now,
+                  tunables::kAlphaHdg, tunables::kBetaHdg, true);
+  hdg_.value = wrap360(hdg_.value);
+  demand_.heading = headingDeg;
+}
+
+void CameraIntegrator::setAttitude(double pitchDeg, double rollDeg) {
+  const auto now = Clock::now();
+  std::lock_guard<std::mutex> g(mutex_);
+
+  updateAlphaBeta(pitch_, pitchDeg, now,
+                  tunables::kAlphaPitch, tunables::kBetaPitch, true);
+  updateAlphaBeta(roll_,  rollDeg,  now,
+                  tunables::kAlphaRoll,  tunables::kBetaRoll,  true);
+  demand_.pitch = pitchDeg;
+  demand_.roll  = rollDeg;
+}
+
+void CameraIntegrator::setViewCorrection(const glm::dquat& q) {
+  std::lock_guard<std::mutex> g(mutex_);
+
+  const double ql2 = q.w * q.w + q.x * q.x + q.y * q.y + q.z * q.z;
+  if (ql2 < 1.0e-20) {
+    viewCorrTarget_ = glm::dquat(1.0, 0.0, 0.0, 0.0);
+  } else {
+    const double inv = 1.0 / std::sqrt(ql2);
+    viewCorrTarget_ = glm::dquat(q.w * inv, q.x * inv, q.y * inv, q.z * inv);
+  }
+  demand_.viewCorrection = viewCorrTarget_;
+}
+
+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;
+}
+
+void CameraIntegrator::teleport(const CameraParams& target) {
+  const auto now = Clock::now();
+  std::lock_guard<std::mutex> g(mutex_);
+
+  auto seed = [now](AlphaBeta& s, double v) {
+    s.value           = v;
+    s.velocity        = 0.0;
+    s.tState          = now;
+    s.tLastMeas       = TimePoint{}; // sentinel: bleed inactive until first setter
+    s.meanIntervalSec = 0.1;
+  };
+  seed(lat_,   target.latitude);
+  seed(lon_,   target.longitude);
+  seed(alt_,   target.altitude);
+  seed(hdg_,   wrap360(target.heading));
+  seed(pitch_, target.pitch);
+  seed(roll_,  target.roll);
+
+  const glm::dquat& qIn = target.viewCorrection;
+  const double ql2 = qIn.w*qIn.w + qIn.x*qIn.x + qIn.y*qIn.y + qIn.z*qIn.z;
+  if (ql2 < 1.0e-20) {
+    viewCorrTarget_ = viewCorrActual_ = glm::dquat(1.0, 0.0, 0.0, 0.0);
+  } else {
+    const double inv = 1.0 / std::sqrt(ql2);
+    viewCorrTarget_ = viewCorrActual_ =
+        glm::dquat(qIn.w * inv, qIn.x * inv, qIn.y * inv, qIn.z * inv);
+  }
+
+  seed(vfov_, target.verticalFov > 0.0 ? target.verticalFov : 0.0);
+
+  demand_ = target;
+  demand_.viewCorrection = viewCorrTarget_;
+  if (demand_.verticalFov <= 0.0) {
+    demand_.verticalFov = vfov_.value;
+  }
+}
+
+CameraParams CameraIntegrator::step() {
+  const auto now = Clock::now();
+  std::lock_guard<std::mutex> g(mutex_);
+
+  // Resolve effective rate caps once per frame; runtime override beats default.
+  const double yawCap   = resolveCap(caps_.maxYawRateDegSec,   tunables::kMaxYawRateDegSec);
+  const double pitchCap = resolveCap(caps_.maxPitchRateDegSec, tunables::kMaxPitchRateDegSec);
+  const double rollCap  = resolveCap(caps_.maxRollRateDegSec,  tunables::kMaxRollRateDegSec);
+  const double climbCap = resolveCap(caps_.maxClimbRateMps,    tunables::kMaxClimbRateMps);
+
+  // Convert ground-speed cap (m/s) to a per-DoF deg/s cap on latitude /
+  // longitude. We use the WGS84 mean radius and ignore the cos(lat)
+  // correction for the longitude term; this is a first-order approximation
+  // but fine for a flight-sim rate cap, and avoids tangling the rate cap
+  // with the current latitude (which would otherwise feed back into itself).
+  double latLonCapDegSec = 0.0;
+  const double groundCap = resolveCap(caps_.maxGroundSpeedMps, tunables::kMaxGroundSpeedMps);
+  if (groundCap > 0.0) {
+    latLonCapDegSec = glm::degrees(groundCap / kEarthMeanRadiusM);
+  }
+
+  extrapolate(lat_,   now, latLonCapDegSec);
+  extrapolate(lon_,   now, latLonCapDegSec);
+  extrapolate(alt_,   now, climbCap);
+  extrapolate(hdg_,   now, yawCap);
+  extrapolate(pitch_, now, pitchCap);
+  extrapolate(roll_,  now, rollCap);
+  extrapolate(vfov_,  now, 0.0); // no velocity term anyway
+
+  hdg_.value = wrap360(hdg_.value);
+  lat_.value = std::clamp(lat_.value, -90.0, 90.0);
+  // Longitude is allowed to drift over ±180; consumers usually want the raw
+  // continuous value for short-arc maths and the camera transform doesn't
+  // care.
+
+  // viewCorrection: 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));
+
+  CameraParams out;
+  out.latitude       = lat_.value;
+  out.longitude      = lon_.value;
+  out.altitude       = alt_.value;
+  out.heading        = hdg_.value;
+  out.pitch          = pitch_.value;
+  out.roll           = roll_.value;
+  out.verticalFov    = vfov_.value;
+  out.viewCorrection = viewCorrActual_;
+  return out;
+}
+
+void CameraIntegrator::clampActualAltitude(double newAltMsl) {
+  std::lock_guard<std::mutex> g(mutex_);
+  alt_.value    = newAltMsl;
+  alt_.velocity = 0.0;
+  // Do not touch demand_.altitude — getDemand() should still report what the
+  // user asked for.
+}
+
+void CameraIntegrator::setRateCaps(const CameraRateCaps& caps) {
+  std::lock_guard<std::mutex> g(mutex_);
+  caps_ = caps;
+}
+
+CameraParams CameraIntegrator::getDemand() const {
+  std::lock_guard<std::mutex> g(mutex_);
+  return demand_;
+}
+
+CameraParams CameraIntegrator::getActual() const {
+  std::lock_guard<std::mutex> g(mutex_);
+  CameraParams out;
+  out.latitude       = lat_.value;
+  out.longitude      = lon_.value;
+  out.altitude       = alt_.value;
+  out.heading        = hdg_.value;
+  out.pitch          = pitch_.value;
+  out.roll           = roll_.value;
+  out.verticalFov    = vfov_.value;
+  out.viewCorrection = viewCorrActual_;
+  return out;
+}
+
+bool CameraIntegrator::isActive() const {
+  std::lock_guard<std::mutex> g(mutex_);
+  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 (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;
+  if (std::abs(demand_.verticalFov - vfov_.value) > tunables::kEpsAngleDeg)     return true;
+  if (std::abs(lat_.velocity)   > tunables::kEpsLatLon         * 60.0)          return true;
+  if (std::abs(lon_.velocity)   > tunables::kEpsLatLon         * 60.0)          return true;
+  if (std::abs(alt_.velocity)   > tunables::kEpsAltitudeMeters * 60.0)          return true;
+  if (std::abs(hdg_.velocity)   > tunables::kEpsAngleDeg       * 60.0)          return true;
+  if (std::abs(pitch_.velocity) > tunables::kEpsAngleDeg       * 60.0)          return true;
+  if (std::abs(roll_.velocity)  > tunables::kEpsAngleDeg       * 60.0)          return true;
+  if ((1.0 - quatDotAbs(viewCorrActual_, viewCorrTarget_))
+        > tunables::kEpsQuatDot)                                                return true;
+  return false;
+}
+
+} // namespace reactnativecesium

package/cpp/engine/CameraIntegrator.hpp

@@ -0,0 +1,146 @@
+#pragma once
+
+#include "GlobeCamera.hpp"
+
+#include <chrono>
+#include <mutex>
+
+namespace reactnativecesium {
+
+// Runtime-tunable per-DoF rate caps and outlier thresholds. Mirrors the
+// compile-time defaults in EngineTunables but exposed as a struct so a view
+// prop can override them at runtime without recompiling.
+struct CameraRateCaps {
+  double maxYawRateDegSec   = 0.0;
+  double maxPitchRateDegSec = 0.0;
+  double maxRollRateDegSec  = 0.0;
+  double maxClimbRateMps    = 0.0;
+  double maxGroundSpeedMps  = 0.0;
+};
+
+// Single owner of the camera's per-DoF α-β tracker state. Measurements are
+// written from any thread (typically a Reanimated worklet on the UI thread or
+// a GPS / IMU callback on the JS thread); the render thread ticks step() once
+// per frame and reads the new actual camera back out.
+//
+// Internally every scalar DoF (latitude, longitude, altitude, heading, pitch,
+// roll, verticalFov) has independent (value, velocity, t_state) state. On a
+// measurement the residual is computed against the predicted value at the
+// arrival time and split between value (scaled by α) and velocity
+// (scaled by β / dt_arrival). On step() the value is extrapolated forward
+// using the running velocity, clamped against the rate cap for that DoF.
+//
+// viewCorrection is a unit quaternion with no useful velocity model; it uses
+// a single-coefficient SLERP toward the latest demand each frame.
+//
+// All public methods take `mutex_` briefly — contention is uncontested in
+// practice (writers are sub-microsecond and the render thread reads once per
+// frame). The integrator owns its own clock (Clock::now() inside both the
+// setters and step()), so no platform time-base needs to be threaded in.
+class CameraIntegrator {
+public:
+  using Clock     = std::chrono::steady_clock;
+  using TimePoint = Clock::time_point;
+
+  explicit CameraIntegrator(const CameraParams& initial = {});
+
+  // ── Per-DoF demand setters ──────────────────────────────────────────────
+  // Each call stamps the measurement with the current steady_clock now() and
+  // performs one α-β update against the predicted value at that time.
+  void setPosition(double latitudeDeg, double longitudeDeg);
+  void setAltitude(double altitudeMeters);
+  void setHeading(double headingDeg);
+  void setAttitude(double pitchDeg, double rollDeg);
+  void setViewCorrection(const glm::dquat& q);
+  void setVerticalFov(double degrees);
+
+  // Atomically reset every DoF to `target` — value, velocity (0), demand,
+  // all timestamps. Used for initial seeding and for explicit scripted
+  // scene jumps; bypasses the trackers entirely.
+  void teleport(const CameraParams& target);
+
+  // Render-thread tick. Extrapolates every DoF forward using its current
+  // velocity, applies rate caps, then returns the new actual camera. dt is
+  // clamped internally to kMaxFrameDtSec so a long sleep can't catapult the
+  // camera along a stale velocity vector.
+  //
+  // The wall-clock used to compute dt is Clock::now() (steady_clock) — the
+  // same clock the setters stamp with. This is deliberate: the integrator
+  // is the single owner of the time base. Earlier versions accepted an
+  // externally supplied `now` from the platform render loop, but on iOS
+  // Simulator `CACurrentMediaTime()` and `std::chrono::steady_clock` do
+  // not share an epoch, so mixing them produced multi-thousand-second dt
+  // 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.
+  void clampActualAltitude(double newAltMsl);
+
+  // Runtime override of the rate caps (driven by view props). 0 = uncapped
+  // for a given axis. The defaults match tunables::kMax*.
+  void setRateCaps(const CameraRateCaps& caps);
+
+  // ── Readback ────────────────────────────────────────────────────────────
+
+  // What the consumer last asked for (each DoF independently). This is the
+  // unfiltered demand: pre-α-β. Useful for HUDs that want to display the
+  // requested camera rather than the rendered one.
+  CameraParams getDemand() const;
+
+  // The most recent value of step() (or the initial seed if step() has not
+  // run yet). Equivalent to what is currently being rendered.
+  CameraParams getActual() const;
+
+  // True when there is meaningful work to do: any residual between actual
+  // and demand exceeds its epsilon, or any DoF has non-zero velocity. The
+  // render loop can use this to drop back to idle when the camera is at
+  // rest.
+  bool isActive() const;
+
+private:
+  // Per-DoF α-β state. `value` and `velocity` are the running estimates,
+  // `tState` the time of the last value update. `tLastMeas` is the time of
+  // the most recent setter call for this DoF (sentinel epoch == "no
+  // measurement seen yet"); `meanIntervalSec` is an EWMA of inter-arrival
+  // times used to drive the silence-aware velocity bleed.
+  struct AlphaBeta {
+    double    value           = 0.0;
+    double    velocity        = 0.0;
+    TimePoint tState{};
+    TimePoint tLastMeas{};
+    double    meanIntervalSec = 0.1; // seed: ~10 Hz, irrelevant after a few setters
+  };
+
+  // Apply one α-β measurement update. `wrapAngle` is true for the angular
+  // DoFs (heading, pitch, roll, longitude) so the residual is computed on
+  // the shortest signed arc.
+  static void updateAlphaBeta(AlphaBeta& s, double z, TimePoint tz,
+                              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);
+
+  mutable std::mutex mutex_;
+
+  AlphaBeta lat_, lon_, alt_;
+  AlphaBeta hdg_, pitch_, roll_;
+  AlphaBeta vfov_; // velocity always zero — α-only
+
+  // Quaternion SLERP target + most recent actual (rendered) value.
+  glm::dquat viewCorrTarget_{1.0, 0.0, 0.0, 0.0};
+  glm::dquat viewCorrActual_{1.0, 0.0, 0.0, 0.0};
+
+  // Demand mirrors (raw last-set values, no α-β filter applied).
+  CameraParams demand_{};
+
+  // Runtime overrides; 0 = use compile-time defaults from EngineTunables.
+  CameraRateCaps caps_{};
+};
+
+} // namespace reactnativecesium

package/cpp/engine/EngineTunables.hpp

@@ -41,44 +41,91 @@ inline constexpr double  kDefaultMaximumScreenSpaceError      = 32.0;
 inline constexpr int32_t kDefaultMaximumSimultaneousTileLoads = 12;
 inline constexpr int32_t kDefaultLoadingDescendantLimit       = 20;
 
-// Camera smoothing constants — shared between platform bridges so jank /
-// motion feel is identical on iOS and Android.
+// Camera smoothing constants — shared between platform bridges so motion
+// feel is identical on iOS and Android.
 //
-// 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).
+// Every scalar DoF (lat, lon, alt, heading, pitch, roll) is driven by an
+// α-β (constant-velocity predictor) tracker inside CameraIntegrator:
+//
+//   on measurement z at time t_z:
+//     pred       = value + velocity * (t_z - t_state)
+//     residual   = wrap(z - pred)                  // wrap only for angles
+//     value     += α * residual
+//     velocity  += (β / max(t_z - t_state, ε)) * residual
+//
+//   on render frame at time t_now:
+//     value     += velocity * dt                   // extrapolate
+//     // optional per-DoF rate cap applied here
+//
+// α controls how hard each measurement pulls the value (responsiveness).
+// β controls how aggressively velocity is corrected (anticipation). With
+// α ≈ 0.5–0.6 / β ≈ 0.05 every DoF stays smooth on a 1 Hz GPS feed (zero
+// steady-state lag at constant motion) while remaining instant under a
+// 60 Hz gesture-driven worklet.
+//
+// `viewCorrection` (a unit quaternion) uses a single-coefficient SLERP toward
+// the latest demand each frame — there is no useful velocity concept for it.
+// `verticalFovDeg` is a 1-D scalar with α only (no velocity term).
+inline constexpr double kAlphaPos    = 0.6;   inline constexpr double kBetaPos    = 0.05;
+inline constexpr double kAlphaAlt    = 0.6;   inline constexpr double kBetaAlt    = 0.05;
+inline constexpr double kAlphaHdg    = 0.55;  inline constexpr double kBetaHdg    = 0.05;
+inline constexpr double kAlphaPitch  = 0.5;   inline constexpr double kBetaPitch  = 0.05;
+inline constexpr double kAlphaRoll   = 0.5;   inline constexpr double kBetaRoll   = 0.05;
+inline constexpr double kAlphaVfov     = 0.4;   // no velocity term
+inline constexpr double kAlphaViewCorr = 0.5;   // SLERP toward target
+
+// Convergence epsilons (used to decide when the integrator has settled and
+// the render loop can drop back to idle).
 inline constexpr double kEpsLatLon          = 1e-7;
 inline constexpr double kEpsAltitudeMeters  = 0.1;
 inline constexpr double kEpsAngleDeg        = 0.05;
 inline constexpr double kEpsQuatDot         = 1e-8;
 
-// Linear interpolation parameters shared by lat/lon, altitude, and heading.
+// Per-DoF rate caps (per second). 0 = uncapped. Hard ceilings; the integrator
+// clamps the extrapolated velocity to these on every render tick. Useful to
+// reject a single noisy IMU sample without making the camera spin or pitch up
+// at hundreds of degrees per second. Default values are deliberately generous.
+inline constexpr double kMaxYawRateDegSec   = 360.0;
+inline constexpr double kMaxPitchRateDegSec = 360.0;
+inline constexpr double kMaxRollRateDegSec  = 720.0;
+inline constexpr double kMaxClimbRateMps    = 0.0;
+inline constexpr double kMaxGroundSpeedMps  = 0.0;
+
+// Render-step dt clamp (catch-up after a long pause / app foreground). Without
+// this, the first render after a multi-second sleep would extrapolate a long
+// way along the last known velocity vector and visibly jump.
+inline constexpr double kMaxFrameDtSec = 0.1;
+
+// Velocity bleed for bursty inputs. Without this, a gesture-driven feed (a
+// worklet that emits at 60 Hz during the pan and stops emitting on release,
+// or a joystick that pushes rates only while held) would leave the
+// integrator extrapolating along the last learned velocity forever — there
+// is no measurement-end signal in the per-DoF API.
+//
+// Each scalar DoF tracks an EWMA of inter-arrival times between its
+// measurements. While measurements keep arriving on schedule, silence is
+// small relative to the mean and velocity is extrapolated normally. Once
+// silence exceeds the grace window the velocity bleeds exponentially with a
+// time-constant proportional to the same mean interval — fast for gestures
+// (mean ≈ 16 ms → τ ≈ 32 ms), slow for 1 Hz GPS (mean ≈ 1 s → τ ≈ 2 s, but
+// silence rarely exceeds grace before the next fix arrives so the glide is
+// untouched).
 //
-// 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 kSmoothPositionTauMax  = 0.6;
-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
+// silence > kVelocitySilenceGraceFactor * meanIntervalSec → bleed active.
+// velocity *= exp(-frameDt / (kVelocityBleedTauFactor * meanIntervalSec))
+inline constexpr double kVelocitySilenceGraceFactor = 1.5;
+inline constexpr double kVelocityBleedTauFactor     = 2.0;
+// EWMA blend coefficient for the inter-arrival mean. Higher = faster adapt
+// to cadence changes (e.g. user switches from gesture to sparse GPS feed).
+inline constexpr double kIntervalEwmaAlpha          = 0.3;
+
+// Optional outlier rejection (off if 0). When > 0, a single measurement whose
+// residual against the predicted state exceeds the threshold is dropped (and
+// logged in debug builds). For deliberate jumps the consumer should call
+// teleport() instead. Disabled by default — easy to enable per-deployment.
+inline constexpr double kOutlierLatLonDeg   = 0.0;
+inline constexpr double kOutlierAltMeters   = 0.0;
+inline constexpr double kOutlierHeadingDeg  = 0.0;
 
 // Metrics throttle: emit telemetry every N rendered frames.
 inline constexpr int kMetricsEmitEveryFrames = 20;