react-native-cesium 1.2.3 → 1.2.4

package/cpp/engine/GlobeCamera.cpp

@@ -16,11 +16,22 @@ static constexpr double kFarPlane  = 50000000.0;
 static constexpr double kMinVfov   = 20.0;
 static constexpr double kMaxVfov   = 100.0;
 
-GlobeCamera::GlobeCamera() { recompute(); }
+GlobeCamera::GlobeCamera() {
+  params_.verticalFov = std::clamp(params_.verticalFov, kMinVfov, kMaxVfov);
+  recompute();
+}
 
 void GlobeCamera::setParams(const CameraParams& p) {
   std::lock_guard<std::mutex> lk(mutex_);
   params_ = p;
+  // A zero (default-init) verticalFov means "leave the previous value";
+  // anything else is clamped to the supported range.
+  if (p.verticalFov > 0.0) {
+    params_.verticalFov = std::clamp(p.verticalFov, kMinVfov, kMaxVfov);
+  } else {
+    // Restore the existing value rather than letting a zero overwrite it.
+    params_.verticalFov = std::clamp(params_.verticalFov, kMinVfov, kMaxVfov);
+  }
   dirty_  = true;
 }
 
@@ -31,12 +42,12 @@ CameraParams GlobeCamera::getParams() const {
 
 void GlobeCamera::setVerticalFovDegrees(double degrees) {
   std::lock_guard<std::mutex> lk(mutex_);
-  verticalFovDeg_ = std::clamp(degrees, kMinVfov, kMaxVfov);
+  params_.verticalFov = std::clamp(degrees, kMinVfov, kMaxVfov);
 }
 
 double GlobeCamera::getVerticalFovDegrees() const {
   std::lock_guard<std::mutex> lk(mutex_);
-  return verticalFovDeg_;
+  return params_.verticalFov;
 }
 
 void GlobeCamera::recompute() const {
@@ -151,7 +162,7 @@ GlobeCamera::computeViewState(double w, double h) const {
   recompute();
 
   double aspect = w / std::max(h, 1.0);
-  double vfov   = glm::radians(verticalFovDeg_);
+  double vfov   = glm::radians(params_.verticalFov);
   double hfov   = 2.0 * std::atan(std::tan(vfov * 0.5) * aspect);
 
   return Cesium3DTilesSelection::ViewState(
@@ -168,7 +179,7 @@ glm::mat4 GlobeCamera::computeVPMatrix(double w, double h) const {
       fullView[0], fullView[1], fullView[2], glm::dvec4(0.0, 0.0, 0.0, 1.0)));
 
   double aspect   = w / std::max(h, 1.0);
-  double vfov     = glm::radians(verticalFovDeg_);
+  double vfov     = glm::radians(params_.verticalFov);
   double tanHalfV = std::tan(vfov * 0.5);
   double tanHalfH = tanHalfV * aspect;
 
@@ -193,7 +204,7 @@ glm::dmat4 GlobeCamera::computeVPMatrixDouble(double w, double h) const {
       fullView[0], fullView[1], fullView[2], glm::dvec4(0.0, 0.0, 0.0, 1.0));
 
   double aspect   = w / std::max(h, 1.0);
-  double vfov     = glm::radians(verticalFovDeg_);
+  double vfov     = glm::radians(params_.verticalFov);
   double tanHalfV = std::tan(vfov * 0.5);
   double tanHalfH = tanHalfV * aspect;
 

package/cpp/engine/GlobeCamera.hpp

@@ -11,12 +11,16 @@
 namespace reactnativecesium {
 
 struct CameraParams {
-  double latitude  = 46.10;
-  double longitude = 7.80;
-  double altitude  = 5500.0;
-  double heading   = 220.0;
-  double pitch     = -10.0;
-  double roll      = 0.0;
+  double latitude    = 46.10;
+  double longitude   = 7.80;
+  double altitude    = 5500.0;
+  double heading     = 220.0;
+  double pitch       = -10.0;
+  double roll        = 0.0;
+  /// Vertical field of view in degrees. Clamped to [kMinVfov, kMaxVfov] by
+  /// GlobeCamera when written. Zero means "leave the previous value" — used
+  /// by partial constructors that don't want to opine on FOV.
+  double verticalFov = 60.0;
   /// Camera-space rotation applied after HPR (unit quaternion; w,x,y,z).
   glm::dquat viewCorrection{1.0, 0.0, 0.0, 0.0};
 };
@@ -28,6 +32,7 @@ public:
   void setParams(const CameraParams& params);
   CameraParams getParams() const;
 
+  /// Convenience helper — equivalent to mutating only verticalFov via setParams.
   void setVerticalFovDegrees(double degrees);
   double getVerticalFovDegrees() const;
 
@@ -56,8 +61,6 @@ private:
   mutable std::mutex mutex_;
   CameraParams params_;
 
-  double verticalFovDeg_ = 60.0;
-
   mutable bool       dirty_        = true;
   mutable glm::dvec3 ecefPosition_{0.0};
   mutable glm::dvec3 direction_{0.0, 1.0, 0.0};

package/cpp/engine/test/CameraIntegratorTest.cpp

@@ -0,0 +1,205 @@
+// Self-contained host harness for CameraIntegrator. NOT compiled into the
+// library — invoked manually by maintainers:
+//
+//   $ bash cpp/engine/test/build_and_run.sh
+//
+// The integrator uses steady_clock internally, so the harness mixes real
+// sleeps with calls — total wall-clock runtime is ~3 seconds.
+//
+// Each test prints PASS / FAIL with a short diagnostic. Exit code is the
+// number of failures.
+
+#include "../CameraIntegrator.hpp"
+#include "../EngineTunables.hpp"
+
+#include <chrono>
+#include <cmath>
+#include <cstdio>
+#include <cstdlib>
+#include <thread>
+
+using namespace reactnativecesium;
+
+static int g_failures = 0;
+
+#define CHECK(cond, label)                                                 \
+  do {                                                                     \
+    if (!(cond)) {                                                         \
+      std::fprintf(stderr, "FAIL [%s]: %s (line %d)\n",                    \
+                   label, #cond, __LINE__);                                \
+      ++g_failures;                                                        \
+    } else {                                                               \
+      std::fprintf(stderr, "PASS [%s]\n", label);                          \
+    }                                                                      \
+  } while (0)
+
+static bool approxEq(double a, double b, double tol) {
+  return std::fabs(a - b) <= tol;
+}
+
+// Sleep a few ms then call step() so the integrator advances along the
+// learned velocity. Returns the latest actual.
+static CameraParams stepFor(CameraIntegrator& integ, int totalMs, int tickMs = 16) {
+  CameraParams out;
+  for (int t = 0; t < totalMs; t += tickMs) {
+    std::this_thread::sleep_for(std::chrono::milliseconds(tickMs));
+    out = integ.step();
+  }
+  return out;
+}
+
+// 1. Step input: a single setter call should move the value toward the
+// target by α × residual (no further movement until another measurement).
+// Demand is preserved through getDemand() regardless.
+static void testStepInput() {
+  CameraParams seed;
+  seed.altitude = 100.0;
+  CameraIntegrator integ(seed);
+
+  integ.setAltitude(200.0);
+  auto out = stepFor(integ, 80);
+
+  // Single shot: should be between 100 and 200, much closer to value+α*residual
+  CHECK(out.altitude > 100.0 && out.altitude < 200.0, "step_input.between");
+  CHECK(approxEq(integ.getDemand().altitude, 200.0, 1e-9),
+        "step_input.demand_preserved");
+}
+
+// 2. Repeated setter at constant velocity. Simulates a 10 Hz altitude feed
+// climbing at 5 m/s. After enough samples, actual altitude should track
+// demand to within a fraction of one inter-arrival delta.
+static void testConstantVelocity() {
+  CameraIntegrator integ;
+  integ.teleport({}); // default seed: alt=5500
+
+  const double climbMps     = 5.0;
+  const double dtSampleSec  = 0.1;
+  const int    numSamples   = 25; // 2.5s of feed
+
+  double demandAlt = 5500.0;
+  for (int i = 0; i < numSamples; ++i) {
+    std::this_thread::sleep_for(std::chrono::milliseconds(
+        static_cast<int>(dtSampleSec * 1000)));
+    demandAlt += climbMps * dtSampleSec;
+    integ.setAltitude(demandAlt);
+    // A few render ticks between samples.
+    for (int k = 0; k < 6; ++k) {
+      std::this_thread::sleep_for(std::chrono::milliseconds(16));
+      integ.step();
+    }
+  }
+  auto actual = integ.getActual();
+  // Allow a tracking lag of one full sample delta.
+  CHECK(approxEq(actual.altitude, demandAlt, climbMps * dtSampleSec * 2.0),
+        "const_vel.tracks");
+}
+
+// 3. Rate cap bounds a single noisy heading spike.
+static void testRateCap() {
+  CameraIntegrator integ;
+  CameraRateCaps caps;
+  caps.maxYawRateDegSec = 90.0;
+  integ.setRateCaps(caps);
+
+  integ.teleport({}); // default heading=220
+
+  // 10 calm samples at 220° to settle.
+  for (int i = 0; i < 10; ++i) {
+    std::this_thread::sleep_for(std::chrono::milliseconds(20));
+    integ.setHeading(220.0);
+    integ.step();
+  }
+  // Single 110° spike.
+  std::this_thread::sleep_for(std::chrono::milliseconds(20));
+  integ.setHeading(330.0);
+  auto out = integ.step();
+  // Without a cap a 110° step would produce v ≈ 110 / 0.02 = 5500 deg/s
+  // and the next step() would extrapolate by v*dt = 5500*0.02 = 110°.
+  // With the 90 deg/s cap, the change in this single frame is at most
+  // 90 * 0.02 ≈ 1.8° beyond the α*residual jump (~66°).
+  CHECK(std::fabs(out.heading - 220.0) < 90.0, "rate_cap.bounded");
+}
+
+// 4. dt clamp prevents a stale velocity vector from jumping after a long
+// pause. We feed a 30 deg/s heading rate, then wait 5 real seconds with no
+// further measurements, and check that the next step() only advances by
+// kMaxFrameDtSec * velocity.
+static void testLongPause() {
+  CameraIntegrator integ;
+  integ.teleport({});
+  // Build a yaw rate.
+  for (int i = 1; i <= 10; ++i) {
+    std::this_thread::sleep_for(std::chrono::milliseconds(100));
+    integ.setHeading(220.0 + 3.0 * i);
+    integ.step();
+  }
+  auto beforePause = integ.getActual();
+  // Long real-time pause with no setters and no steps.
+  std::this_thread::sleep_for(std::chrono::milliseconds(1500));
+  auto out = integ.step();
+  // dt was clamped to 0.1 s, so heading advanced by at most
+  // velocity * 0.1 s. With v ≈ 30 deg/s, that's at most 3°.
+  CHECK(std::fabs(out.heading - beforePause.heading) < 10.0,
+        "long_pause.dt_clamped");
+}
+
+// 5. Gesture-end bleed. A 60 Hz worklet streams ramping heading values for
+// ~250 ms (simulating an active pan), then stops emitting entirely.
+// Without the silence-aware velocity bleed the integrator would extrapolate
+// the last learned velocity forever; with the bleed, motion should die in
+// well under a second.
+static void testGestureEndBleed() {
+  CameraIntegrator integ;
+  integ.teleport({});
+
+  // Active "gesture": 16 ms cadence, +0.5° heading per frame (= 31 deg/s).
+  double demand = 220.0;
+  for (int i = 0; i < 16; ++i) {
+    std::this_thread::sleep_for(std::chrono::milliseconds(16));
+    demand += 0.5;
+    integ.setHeading(demand);
+    integ.step();
+  }
+  const double duringHeading = integ.getActual().heading;
+
+  // "Release": no more setters, just render ticks at 60 Hz.
+  CameraParams out;
+  for (int i = 0; i < 60; ++i) {
+    std::this_thread::sleep_for(std::chrono::milliseconds(16));
+    out = integ.step();
+  }
+  const double endHeading = out.heading;
+  // Drift during the 1-second silence should be small — the integrator
+  // should have given up on the learned 31 deg/s rate well before the end.
+  CHECK(std::fabs(endHeading - duringHeading) < 5.0,
+        "gesture_end_bleed.stops");
+}
+
+// 6. Terrain clamp write-back — clampActualAltitude raises actual without
+// touching demand.
+static void testTerrainClamp() {
+  CameraIntegrator integ;
+  CameraParams seed;
+  seed.altitude = 100.0;
+  integ.teleport(seed);
+  integ.clampActualAltitude(150.0);
+  auto demand = integ.getDemand();
+  auto actual = integ.getActual();
+  CHECK(approxEq(actual.altitude, 150.0, 1e-6), "terrain_clamp.actual_raised");
+  CHECK(approxEq(demand.altitude, 100.0, 1e-6), "terrain_clamp.demand_preserved");
+}
+
+int main() {
+  testStepInput();
+  testConstantVelocity();
+  testRateCap();
+  testLongPause();
+  testGestureEndBleed();
+  testTerrainClamp();
+  if (g_failures == 0) {
+    std::fprintf(stderr, "\nALL TESTS PASSED.\n");
+  } else {
+    std::fprintf(stderr, "\n%d TEST(S) FAILED.\n", g_failures);
+  }
+  return g_failures;
+}

package/cpp/engine/test/build_and_run.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+# Compile and run CameraIntegratorTest against the iOS simulator-slice headers
+# from the vendored Cesium Native XCFramework. Lightweight smoke test —
+# not part of the production build.
+
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/../../.." && pwd)"
+HEADERS="$ROOT/vendor/ios/CesiumNative.xcframework/ios-arm64-simulator/Headers"
+
+if [[ ! -d "$HEADERS" ]]; then
+  echo "Cesium Native headers not found at $HEADERS"
+  echo "Run 'npm run update && CESIUM_BUILD_ONLY=ios npm run build' first."
+  exit 1
+fi
+
+OUT="$(mktemp -d)"
+echo "Building into $OUT..."
+
+xcrun -sdk macosx clang++ -std=c++20 -O0 -g \
+  -DGLM_FORCE_DEPTH_ZERO_TO_ONE=1 \
+  -I"$ROOT/cpp" -I"$HEADERS" \
+  -o "$OUT/cit" \
+  "$ROOT/cpp/engine/CameraIntegrator.cpp" \
+  "$ROOT/cpp/engine/test/CameraIntegratorTest.cpp"
+
+"$OUT/cit"

package/example/README.md

@@ -6,7 +6,7 @@ This app is the reference integration for `react-native-cesium`. For the current
 
 - rendering `CesiumView` inside a React Native screen
 - wiring a Nitro `hybridRef`
-- driving the camera with `setCamera(...)`
+- driving the camera through the per-DoF setters (`setPosition`, `setAltitude`, `setHeading`, `setAttitude`) from a Reanimated worklet — see [`hooks/useCameraController.ts`](./hooks/useCameraController.ts)
 - receiving runtime telemetry through `onMetrics`
 - showing Cesium attribution text from `creditsPlainText`
 

package/ios/CesiumBridge.h

@@ -3,9 +3,9 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
-// Thin Obj-C++ shell for the iOS side. All cross-platform logic (camera
-// demand state + smoothing, FPS / metrics aggregation, credit-HTML stripping)
-// lives in shared C++ next to CesiumEngine.
+// Thin Obj-C++ shell for the iOS side. All cross-platform logic (per-DoF
+// camera integrator, FPS / metrics aggregation, credit-HTML stripping) lives
+// in shared C++ next to CesiumEngine.
 @interface CesiumBridge : NSObject
 
 - (instancetype)initWithMetalLayer:(CAMetalLayer *)layer
@@ -15,32 +15,46 @@ NS_ASSUME_NONNULL_BEGIN
 
 - (void)updateIonAccessToken:(NSString *)token assetId:(int64_t)assetId;
 - (void)updateImageryAssetId:(int64_t)assetId;
-- (void)updateCameraLatitude:(double)lat
-                   longitude:(double)lon
-                    altitude:(double)alt
-                     heading:(double)heading
-                       pitch:(double)pitch
-                        roll:(double)roll;
-/// Same as `updateCameraLatitude:...` plus a camera-space view correction (w,x,y,z) applied after HPR.
-- (void)updateCameraQuaternionLatitude:(double)lat
-                             longitude:(double)lon
-                              altitude:(double)alt
-                               heading:(double)heading
-                                 pitch:(double)pitch
-                                  roll:(double)roll
-                       viewCorrectionW:(double)qw
-                                     x:(double)qx
-                                     y:(double)qy
-                                     z:(double)qz;
+
+// ── Per-DoF camera demand setters ────────────────────────────────────────
+// Each call records the measurement with the current native steady_clock
+// time and performs one α-β update against the predicted state at that
+// instant. Pitch / roll are bundled because they typically come from a
+// single IMU sample.
+- (void)setPositionLatitude:(double)lat longitude:(double)lon;
+- (void)setAltitude:(double)alt;
+- (void)setHeadingDeg:(double)deg;
+- (void)setAttitudePitch:(double)pitch roll:(double)roll;
+- (void)setViewCorrectionW:(double)qw x:(double)qx y:(double)qy z:(double)qz;
+
+/// Hard scene jump — resets every DoF (value + velocity + demand) atomically.
+- (void)teleportLatitude:(double)lat
+                longitude:(double)lon
+                 altitude:(double)alt
+                  heading:(double)heading
+                    pitch:(double)pitch
+                     roll:(double)roll
+           verticalFovDeg:(double)vfov;
+
 - (void)resize:(int)width height:(int)height;
 - (BOOL)shouldRenderNextFrame;
 - (void)markNeedsRender;
-- (void)renderFrameWithDt:(double)dt;
+/// Render one frame. `nowSeconds` is wall-clock seconds (steady_clock) used
+/// by the integrator to extrapolate every DoF forward.
+- (void)renderFrameAt:(double)nowSeconds;
 - (void)shutdown;
 
 // Camera / globe
 - (void)setVerticalFovDeg:(double)degrees;
 
+/// Runtime rate caps (0 = uncapped). See EngineTunables for compile-time
+/// defaults.
+- (void)setRateCapsYaw:(double)yawDegSec
+                  pitch:(double)pitchDegSec
+                   roll:(double)rollDegSec
+                  climb:(double)climbMps
+            groundSpeed:(double)groundMps;
+
 // Tileset tuning (runtime-mutable; no full rebuild)
 - (void)setMaximumScreenSpaceError:(double)v;
 - (void)setMaximumSimultaneousTileLoads:(int32_t)v;
@@ -73,13 +87,24 @@ NS_ASSUME_NONNULL_BEGIN
 @property (nonatomic, readonly) BOOL metricsTlsConfigured;
 @property (nonatomic, readonly, copy) NSString *metricsCreditsPlainText;
 
-- (double)readCameraLatitude;
-- (double)readCameraLongitude;
-- (double)readCameraAltitude;
-- (double)readCameraHeading;
-- (double)readCameraPitch;
-- (double)readCameraRoll;
-- (double)readVerticalFovDeg;
+// ── Actual camera readback (what was rendered most recently) ────────────
+- (double)readActualLatitude;
+- (double)readActualLongitude;
+- (double)readActualAltitude;
+- (double)readActualHeading;
+- (double)readActualPitch;
+- (double)readActualRoll;
+- (double)readActualVerticalFovDeg;
+
+// ── Demand camera readback (what the consumer last asked for) ───────────
+- (double)readDemandLatitude;
+- (double)readDemandLongitude;
+- (double)readDemandAltitude;
+- (double)readDemandHeading;
+- (double)readDemandPitch;
+- (double)readDemandRoll;
+- (double)readDemandVerticalFovDeg;
+
 - (double)readViewCorrectionW;
 - (double)readViewCorrectionX;
 - (double)readViewCorrectionY;