react-native-cesium 1.2.18 → 1.2.20

package/cpp/engine/test/CameraIntegratorTest.cpp

@@ -11,7 +11,9 @@
 
 #include "../CameraIntegrator.hpp"
 #include "../EngineTunables.hpp"
+#include "../TerrainHeight.hpp"
 
+#include <algorithm>
 #include <chrono>
 #include <cmath>
 #include <cstdio>
@@ -189,6 +191,257 @@ static void testTerrainClamp() {
   CHECK(approxEq(demand.altitude, 100.0, 1e-6), "terrain_clamp.demand_preserved");
 }
 
+static void followFloors(const double* floors, int count, const char* label,
+                         bool expectRiseThenFall) {
+  CameraIntegrator integ;
+  CameraParams seed;
+  seed.altitude = floors[0];
+  integ.teleport(seed);
+  // A demand under every floor, plus a downward velocity sample, must not
+  // pull the rendered camera through the surface.
+  integ.setAltitude(0.0);
+  std::this_thread::sleep_for(std::chrono::milliseconds(20));
+  integ.setAltitude(0.0);
+
+  double prev = 0.0;
+  bool havePrev = false;
+  bool sawPeak = false;
+  for (int i = 0; i < count; ++i) {
+    const double floor = floors[i];
+    integ.setAltitude(0.0);
+    integ.setTerrainFloor(floor);
+    const CameraParams actual = integ.step();
+    char buf[96];
+    std::snprintf(buf, sizeof(buf), "%s.exact_%d", label, i);
+    CHECK(approxEq(actual.altitude, floor, 1e-6), buf);
+    CHECK(approxEq(integ.getDemand().altitude, 0.0, 1e-9), label);
+    if (havePrev) {
+      if (!expectRiseThenFall) {
+        std::snprintf(buf, sizeof(buf), "%s.monotonic_%d", label, i);
+        if (floors[i] > floors[i - 1]) {
+          CHECK(actual.altitude > prev - 1e-6, buf);
+        } else {
+          CHECK(actual.altitude < prev + 1e-6, buf);
+        }
+      }
+      if (expectRiseThenFall && floors[i] < floors[i - 1]) {
+        sawPeak = true;
+        std::snprintf(buf, sizeof(buf), "%s.descends_%d", label, i);
+        CHECK(actual.altitude < prev - 1e-6, buf);
+      }
+      if (expectRiseThenFall && sawPeak && floors[i] > floors[i - 1]) {
+        std::snprintf(buf, sizeof(buf), "%s.climbs_%d", label, i);
+        CHECK(actual.altitude > prev + 1e-6, buf);
+      }
+    }
+    prev = actual.altitude;
+    havePrev = true;
+  }
+}
+
+static void testUphillContact() {
+  const double floors[] = {100.0, 110.0, 120.0, 130.0};
+  followFloors(floors, 4, "uphill", false);
+}
+
+static void testDownhillContact() {
+  const double floors[] = {130.0, 120.0, 110.0, 100.0};
+  followFloors(floors, 4, "downhill", false);
+}
+
+static void testCrest() {
+  const double floors[] = {100.0, 110.0, 120.0, 110.0, 100.0};
+  followFloors(floors, 5, "crest", true);
+}
+
+static void testValley() {
+  const double floors[] = {120.0, 110.0, 100.0, 110.0, 120.0};
+  followFloors(floors, 5, "valley", true);
+
+  // Descent velocity must not carry the camera into the rising face.
+  CameraIntegrator integ;
+  CameraParams seed;
+  seed.altitude = 100.0;
+  integ.teleport(seed);
+  integ.clearTerrainFloor();
+  integ.setAltitude(0.0);
+  std::this_thread::sleep_for(std::chrono::milliseconds(20));
+  integ.setAltitude(0.0);
+  CHECK(integ.getActual().altitude < 100.0, "valley.velocity_descended");
+  integ.setTerrainFloor(110.0);
+  CHECK(approxEq(integ.getActual().altitude, 110.0, 1e-6), "valley.climb_exact");
+  CHECK(approxEq(integ.step().altitude, 110.0, 1e-6), "valley.climb_holds");
+}
+
+static void testSetAltitudeUnderFloor() {
+  CameraIntegrator integ;
+  CameraParams seed;
+  seed.altitude = 100.0;
+  integ.teleport(seed);
+  integ.setTerrainFloor(150.0);
+  integ.setAltitude(10.0);
+  CHECK(approxEq(integ.getActual().altitude, 150.0, 1e-6), "under_floor.actual");
+  CHECK(approxEq(integ.getDemand().altitude, 10.0, 1e-9), "under_floor.demand");
+  const CameraParams stepped = integ.step();
+  CHECK(approxEq(stepped.altitude, 150.0, 1e-6), "under_floor.after_step");
+}
+
+static void testIdleOnFloor() {
+  CameraIntegrator integ;
+  CameraParams seed;
+  seed.altitude = 100.0;
+  integ.teleport(seed);
+  integ.setTerrainFloor(150.0);
+  integ.setAltitude(40.0);
+  const CameraParams stepped = integ.step();
+  CHECK(approxEq(stepped.altitude, 150.0, 1e-6), "idle_floor.actual");
+  CHECK(!integ.isActive(), "idle_floor.inactive");
+}
+
+static void testFlyingAboveFloor() {
+  CameraIntegrator integ;
+  CameraParams seed;
+  seed.altitude = 500.0;
+  integ.teleport(seed);
+  integ.setTerrainFloor(100.0);
+  const CameraParams stepped = integ.step();
+  CHECK(approxEq(stepped.altitude, 500.0, 1e-3), "above_floor.untouched");
+  CHECK(approxEq(integ.getDemand().altitude, 500.0, 1e-9), "above_floor.demand");
+}
+
+static double wrap180(double deg) {
+  double v = std::fmod(deg + 180.0, 360.0);
+  if (v < 0.0) v += 360.0;
+  return v - 180.0;
+}
+
+static void testHeadingShortPull() {
+  CameraIntegrator integ;
+  CameraParams seed;
+  seed.heading = 350.0;
+  integ.teleport(seed);
+  integ.setHeading(10.0);
+  std::this_thread::sleep_for(std::chrono::milliseconds(250));
+  bool onShortArc = true;
+  for (int i = 0; i < 90; ++i) {
+    std::this_thread::sleep_for(std::chrono::milliseconds(20));
+    const double h = integ.step().heading;
+    if (!(h >= 330.0 || h <= 40.0)) onShortArc = false;
+  }
+  CHECK(onShortArc, "heading_pull.short_arc");
+  const double end = integ.getActual().heading;
+  const double err = std::abs(wrap180(end - 10.0));
+  CHECK(err < 2.0, "heading_pull.converged");
+}
+
+static void testLongitudeShortPull() {
+  CameraIntegrator integ;
+  CameraParams seed;
+  seed.longitude = 179.0;
+  integ.teleport(seed);
+  integ.setPosition(seed.latitude, -179.0);
+  std::this_thread::sleep_for(std::chrono::milliseconds(250));
+  bool onShortArc = true;
+  for (int i = 0; i < 90; ++i) {
+    std::this_thread::sleep_for(std::chrono::milliseconds(20));
+    const double wrapped = wrap180(integ.step().longitude);
+    if (!(std::abs(wrapped) > 90.0)) onShortArc = false;
+  }
+  CHECK(onShortArc, "lon_pull.short_arc");
+  const double err = std::abs(wrap180(integ.getActual().longitude - (-179.0)));
+  CHECK(err < 2.0, "lon_pull.converged");
+}
+
+static void testVerticalFovConverges() {
+  CameraIntegrator integ;
+  CameraParams seed;
+  seed.verticalFov = 60.0;
+  integ.teleport(seed);
+  integ.setVerticalFov(30.0);
+  std::this_thread::sleep_for(std::chrono::milliseconds(16));
+  const double first = integ.step().verticalFov;
+  CHECK(first < 59.0 && first > 40.0, "vfov.first_step_eases");
+  CameraParams mid;
+  for (int i = 0; i < 80; ++i) {
+    std::this_thread::sleep_for(std::chrono::milliseconds(16));
+    mid = integ.step();
+  }
+  CHECK(approxEq(mid.verticalFov, 30.0, 0.5), "vfov.converged");
+  std::this_thread::sleep_for(std::chrono::milliseconds(200));
+  const double held = integ.step().verticalFov;
+  CHECK(approxEq(held, 30.0, 0.5), "vfov.stays");
+}
+
+static void testLeadAndTriangle() {
+  float out = 0.0f;
+  CHECK(resolveSurfaceEllipsoid(true, 100.0f, true, 90.0f, out) && out == 100.0f,
+        "lead.crest_no_sticky_peak");
+  CHECK(resolveSurfaceEllipsoid(true, 100.0f, true, 110.0f, out) && out == 110.0f,
+        "lead.valley_raises");
+  CHECK(resolveSurfaceEllipsoid(true, 120.0f, false, 0.0f, out) && out == 120.0f,
+        "lead.nadir_only");
+  CHECK(!resolveSurfaceEllipsoid(false, 0.0f, false, 0.0f, out), "lead.neither");
+
+  double lat = 0.0, lon = 0.0;
+  const bool slew = terrainLeadLatLon(0.0, 1.0, 0.0, 0.0, true, lat, lon);
+  CHECK(!slew, "lead.slew_ignored");
+
+  const bool step = terrainLeadLatLon(0.0, 0.0001, 0.0, 0.0, true, lat, lon);
+  CHECK(step, "lead.one_frame");
+  CHECK(approxEq(lat, 0.0, 1e-12), "lead.lat");
+  CHECK(approxEq(lon, 0.0002, 1e-9), "lead.lon_ahead");
+
+  float h = -1.0f;
+  const bool hit = horizontalTriangleHeight(
+      2.0, 2.0,
+      0.0, 0.0, 0.0f,
+      10.0, 0.0, 0.0f,
+      0.0, 10.0, 30.0f,
+      h);
+  CHECK(hit && approxEq(h, 6.0, 1e-3), "tri.interpolated");
+
+  float outside = 0.0f;
+  CHECK(!horizontalTriangleHeight(
+            20.0, 20.0,
+            0.0, 0.0, 0.0f,
+            10.0, 0.0, 0.0f,
+            0.0, 10.0, 30.0f,
+            outside),
+        "tri.outside");
+
+  float skirt = 0.0f;
+  CHECK(!horizontalTriangleHeight(
+            1.0, 0.0,
+            0.0, 0.0, 100.0f,
+            0.0, 0.0, 0.0f,
+            5.0, 0.0, 100.0f,
+            skirt),
+        "tri.skirt_rejected");
+  // 100 m edge, 1 mm of horizontal width: a float-error skirt, not terrain.
+  CHECK(!horizontalTriangleHeight(
+            0.0, 0.0005,
+            0.0, 0.0, 100.0f,
+            100.0, 0.0, 100.0f,
+            0.0, 0.001, 0.0f,
+            skirt),
+        "tri.thin_skirt_rejected");
+
+  float low = 0.0f, high = 0.0f;
+  const bool lowHit = horizontalTriangleHeight(
+      2.0, 2.0,
+      0.0, 0.0, 5.0f,
+      10.0, 0.0, 5.0f,
+      0.0, 10.0, 5.0f,
+      low);
+  const bool highHit = horizontalTriangleHeight(
+      2.0, 2.0,
+      0.0, 0.0, 20.0f,
+      10.0, 0.0, 20.0f,
+      0.0, 10.0, 20.0f,
+      high);
+  CHECK(lowHit && highHit && std::max(low, high) == 20.0f, "tri.overlap_keeps_higher");
+}
+
 int main() {
   testStepInput();
   testConstantVelocity();
@@ -196,6 +449,17 @@ int main() {
   testLongPause();
   testGestureEndBleed();
   testTerrainClamp();
+  testUphillContact();
+  testDownhillContact();
+  testCrest();
+  testValley();
+  testSetAltitudeUnderFloor();
+  testIdleOnFloor();
+  testFlyingAboveFloor();
+  testHeadingShortPull();
+  testLongitudeShortPull();
+  testVerticalFovConverges();
+  testLeadAndTriangle();
   if (g_failures == 0) {
     std::fprintf(stderr, "\nALL TESTS PASSED.\n");
   } else {

package/cpp/engine/test/GeoidConverterTest.cpp

@@ -0,0 +1,77 @@
+// Host check for the EGM96 MSL <-> ellipsoid conversion.
+//
+//   clang++ -std=c++20 -I cpp -o /tmp/geoid cpp/engine/test/GeoidConverterTest.cpp \
+//     cpp/engine/GeoidConverter.cpp cpp/third_party/egm96/EGM96.c
+//
+// Or: bash cpp/engine/test/build_and_run.sh
+
+#include "../GeoidConverter.hpp"
+
+#include <cmath>
+#include <cstdio>
+
+using namespace reactnativecesium;
+
+static int g_failures = 0;
+
+static void check(bool ok, const char* label) {
+  if (!ok) {
+    std::fprintf(stderr, "FAIL [%s]\n", label);
+    ++g_failures;
+    return;
+  }
+  std::fprintf(stderr, "PASS [%s]\n", label);
+}
+
+static void checkInverse(const char* label, double lat, double lon, double msl) {
+  const double hae = mslToEllipsoidMeters(lat, lon, msl);
+  const double back = ellipsoidToMslMeters(lat, lon, hae);
+  const double undulation = hae - msl;
+  if (!std::isfinite(hae) || !std::isfinite(back) || std::fabs(back - msl) > 1e-6) {
+    std::fprintf(stderr, "FAIL [%s]: msl=%.3f hae=%.3f back=%.3f\n", label, msl, hae, back);
+    ++g_failures;
+    return;
+  }
+  if (std::fabs(undulation) < 1.0) {
+    std::fprintf(stderr, "FAIL [%s]: undulation %.3f m is unexpectedly ~0\n", label, undulation);
+    ++g_failures;
+    return;
+  }
+  std::fprintf(stderr, "PASS [%s] undulation %.2f m\n", label, undulation);
+}
+
+static void checkDemandRoundTrip(const char* label, double lat, double lon, double msl) {
+  const double hae = mslToDemandAltitudeMeters(lat, lon, msl, true);
+  const double back = demandAltitudeToMslMeters(lat, lon, hae, true);
+  check(std::isfinite(hae) && std::isfinite(back) && std::fabs(back - msl) < 1e-6, label);
+
+  const double mslIdentity = demandAltitudeToMslMeters(lat, lon, msl, false);
+  const double haeIdentity = mslToDemandAltitudeMeters(lat, lon, msl, false);
+  check(mslIdentity == msl && haeIdentity == msl, "datum_msl_identity");
+}
+
+int main() {
+  // UK geoid is about +45 m. Alps about +50 m. Indian Ocean is negative.
+  checkInverse("uk", 51.5, -0.1, 1000.0);
+  checkInverse("alps", 46.0, 8.0, 2000.0);
+  checkInverse("indian_ocean", -10.0, 80.0, 50.0);
+
+  const double nan = std::nan("");
+  check(ellipsoidToMslMeters(nan, 0.0, 10.0) == 10.0, "ellipsoid_non_finite");
+  check(mslToEllipsoidMeters(nan, 0.0, 10.0) == 10.0, "msl_non_finite");
+
+  checkDemandRoundTrip("demand_round_trip", 51.5, -0.1, 1000.0);
+
+  constexpr double kUkLat = 51.5;
+  constexpr double kUkLon = -0.1;
+  constexpr double kOceanLat = -10.0;
+  constexpr double kOceanLon = 80.0;
+  constexpr double kMsl = 1000.0;
+  const double hae = mslToEllipsoidMeters(kUkLat, kUkLon, kMsl);
+  const double moved = mslAfterHorizontalMove(kUkLat, kUkLon, kMsl, kOceanLat, kOceanLon);
+  const double movedHae = mslToEllipsoidMeters(kOceanLat, kOceanLon, moved);
+  check(std::isfinite(moved) && std::fabs(movedHae - hae) < 1e-6, "move_preserves_hae");
+  check(std::fabs(moved - kMsl) > 1.0, "move_changes_msl");
+
+  return g_failures == 0 ? 0 : 1;
+}

package/cpp/engine/test/build_and_run.sh

@@ -1,12 +1,29 @@
 #!/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.
+# Compile and run the host engine tests. GeoidConverterTest needs only EGM96.
+# CameraIntegratorTest needs the iOS simulator-slice headers from the vendored
+# Cesium Native XCFramework. Lightweight smoke tests — not part of the
+# production build.
 
 set -euo pipefail
 
 ROOT="$(cd "$(dirname "$0")/../../.." && pwd)"
 HEADERS="$ROOT/vendor/ios/CesiumNative.xcframework/ios-arm64-simulator/Headers"
+OUT="$(mktemp -d)"
+echo "Building into $OUT..."
+
+xcrun -sdk macosx clang -std=c11 -O0 -g \
+  -I"$ROOT/cpp" \
+  -c "$ROOT/cpp/third_party/egm96/EGM96.c" \
+  -o "$OUT/EGM96.o"
+
+xcrun -sdk macosx clang++ -std=c++20 -O0 -g \
+  -I"$ROOT/cpp" \
+  -o "$OUT/geoid" \
+  "$ROOT/cpp/engine/test/GeoidConverterTest.cpp" \
+  "$ROOT/cpp/engine/GeoidConverter.cpp" \
+  "$OUT/EGM96.o"
+
+"$OUT/geoid"
 
 if [[ ! -d "$HEADERS" ]]; then
   echo "Cesium Native headers not found at $HEADERS"
@@ -14,9 +31,6 @@ if [[ ! -d "$HEADERS" ]]; then
   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" \

package/ios/CesiumBridge.h

@@ -33,6 +33,11 @@ NS_ASSUME_NONNULL_BEGIN
 // instant. Pitch / roll are bundled because they typically come from a
 // single IMU sample.
 - (void)setPositionLatitude:(double)lat longitude:(double)lon;
+/// When YES, altitudes passed to setAltitude: and teleport are WGS84
+/// ellipsoidal heights. They are converted to MSL before the integrator, and
+/// altitude readback is converted back. A horizontal move keeps that
+/// ellipsoidal height.
+- (void)setAltitudeDatumEllipsoid:(BOOL)ellipsoid;
 - (void)setAltitude:(double)alt;
 - (void)setHeadingDeg:(double)deg;
 - (void)setAttitudePitch:(double)pitch roll:(double)roll;

package/ios/CesiumBridge.mm

@@ -6,6 +6,7 @@
 #include "engine/EngineTunables.hpp"
 #include "engine/GeoidConverter.hpp"
 #include "engine/MetricsAggregator.hpp"
+#include "engine/TerrainFloor.hpp"
 #include "metal/MetalBackend.h"
 
 #include <glm/gtc/quaternion.hpp>
@@ -35,6 +36,9 @@
   int   _viewportHeight;
   BOOL  _initialized;
   BOOL  _suspended;
+  // Written when the prop changes; read from the caller thread inside
+  // setAltitude / setPosition / teleport / readback.
+  std::atomic<bool> _altitudeIsEllipsoid;
 
   // Last wall-clock tick used to compute the metrics-only frame dt EMA. Kept
   // per-instance (not a function-local static) so a hot reload that destroys
@@ -48,6 +52,8 @@
   // Sentinel (epoch) means "no loading seen yet".
   std::chrono::steady_clock::time_point _lastLoadingTime;
 
+  reactnativecesium::TerrainLeadState _terrainLead;
+
   NSString* _cacheDir;
 }
 
@@ -63,8 +69,9 @@
   if (self) {
     _viewportWidth     = width;
     _viewportHeight    = height;
-    _initialized       = NO;
-    _suspended         = NO;
+    _initialized          = NO;
+    _suspended            = NO;
+    _altitudeIsEllipsoid.store(false, std::memory_order_relaxed);
     _lastTickSec       = 0.0;
     _forceRender.store(true, std::memory_order_release);
     _cacheDir          = [cacheDir copy];
@@ -182,13 +189,45 @@
 
 - (void)setPositionLatitude:(double)lat longitude:(double)lon {
   if (!_initialized) return;
+  const bool ellipsoid = _altitudeIsEllipsoid.load(std::memory_order_acquire);
+  double adjustedMsl = 0.0;
+  bool adjustAltitude = false;
+  if (ellipsoid) {
+    const auto demand = _integrator->getDemand();
+    adjustedMsl = reactnativecesium::mslAfterHorizontalMove(
+        demand.latitude, demand.longitude, demand.altitude, lat, lon);
+    adjustAltitude = std::abs(adjustedMsl - demand.altitude) >
+                     reactnativecesium::kHorizontalMoveMslEpsilonMeters;
+  }
   _integrator->setPosition(lat, lon);
+  if (adjustAltitude) {
+    _integrator->setAltitude(adjustedMsl);
+  }
   _forceRender.store(true, std::memory_order_release);
 }
 
+- (void)setAltitudeDatumEllipsoid:(BOOL)ellipsoid {
+  _altitudeIsEllipsoid.store(ellipsoid == YES, std::memory_order_release);
+}
+
+- (double)mslAltitude:(double)alt latitude:(double)lat longitude:(double)lon {
+  return reactnativecesium::demandAltitudeToMslMeters(
+      lat, lon, alt, _altitudeIsEllipsoid.load(std::memory_order_acquire));
+}
+
+- (double)demandAltitudeFromMsl:(double)msl
+                       latitude:(double)lat
+                      longitude:(double)lon {
+  return reactnativecesium::mslToDemandAltitudeMeters(
+      lat, lon, msl, _altitudeIsEllipsoid.load(std::memory_order_acquire));
+}
+
 - (void)setAltitude:(double)alt {
   if (!_initialized) return;
-  _integrator->setAltitude(alt);
+  const auto demand = _integrator->getDemand();
+  _integrator->setAltitude([self mslAltitude:alt
+                                    latitude:demand.latitude
+                                   longitude:demand.longitude]);
   _forceRender.store(true, std::memory_order_release);
 }
 
@@ -221,7 +260,7 @@
   reactnativecesium::CameraParams p;
   p.latitude    = lat;
   p.longitude   = lon;
-  p.altitude    = alt;
+  p.altitude    = [self mslAltitude:alt latitude:lat longitude:lon];
   p.heading     = heading;
   p.pitch       = pitch;
   p.roll        = roll;
@@ -230,6 +269,7 @@
   // jump, not a boresight reset. Use setViewCorrection(identity) to clear it.
   p.viewCorrection = _integrator->getActual().viewCorrection;
   _integrator->teleport(p);
+  reactnativecesium::noteTerrainSlew(*_integrator, _terrainLead);
   // Apply directly to the engine so the next render uses the teleported value
   // without one frame of "almost there" interpolation.
   _engine->camera().setParams(p);
@@ -382,32 +422,9 @@
     // The integrator owns its own clock now — see CameraIntegrator::step().
     // `nowSeconds` is still used below for the FPS-EMA dt only.
     auto actual = _integrator->step();
-
-    // ── Terrain floor following using integrator's alpha-beta smoothing ───
-    // Set demand altitude to terrain floor, let the integrator's alpha-beta
-    // tracker smoothly interpolate. The tracker already provides adaptive
-    // exponential easing (alpha=0.6, beta=0.05 in EngineTunables.hpp).
-    const float minAbove = _engine->getConfig().minAltitudeAboveTerrain;
-    if (minAbove > 0.0f && _engine->terrainFloorKnown()) {
-      const double geoidN =
-          reactnativecesium::mslToEllipsoidMeters(actual.latitude, actual.longitude, 0.0);
-      const double floorEllipsoid = static_cast<double>(_engine->terrainFloorEllipsoidMeters());
-      const double floorMsl = floorEllipsoid - geoidN;
-      const double minMsl = floorMsl + static_cast<double>(minAbove);
-
-      // Continuously update demand to follow terrain
-      const double demandAlt = _integrator->getDemand().altitude;
-      if (demandAlt <= 0.0) {
-        _integrator->setAltitude(minMsl);
-        actual = _integrator->getActual();
-      }
-      
-      // Safety floor: hard clamp if already below terrain (shouldn't happen with look-ahead)
-      if (actual.altitude < minMsl) {
-        _integrator->clampActualAltitude(minMsl);
-        actual = _integrator->getActual();
-      }
-    }
+    actual = reactnativecesium::applyTerrainFloor(
+        *_engine, *_integrator, actual, _terrainLead,
+        static_cast<double>(_engine->getConfig().minAltitudeAboveTerrain));
 
     _engine->camera().setParams(actual);
 
@@ -447,7 +464,13 @@
 // ── Actual camera readback (post-integration; what was rendered) ─────────
 - (double)readActualLatitude       { return _integrator ? _integrator->getActual().latitude       : 0.0; }
 - (double)readActualLongitude      { return _integrator ? _integrator->getActual().longitude      : 0.0; }
-- (double)readActualAltitude       { return _integrator ? _integrator->getActual().altitude       : 0.0; }
+- (double)readActualAltitude {
+  if (!_integrator) return 0.0;
+  const auto actual = _integrator->getActual();
+  return [self demandAltitudeFromMsl:actual.altitude
+                            latitude:actual.latitude
+                           longitude:actual.longitude];
+}
 - (double)readActualHeading        { return _integrator ? _integrator->getActual().heading        : 0.0; }
 - (double)readActualPitch          { return _integrator ? _integrator->getActual().pitch          : 0.0; }
 - (double)readActualRoll           { return _integrator ? _integrator->getActual().roll           : 0.0; }
@@ -456,7 +479,13 @@
 // ── Demand camera readback (what the consumer last asked for) ────────────
 - (double)readDemandLatitude       { return _integrator ? _integrator->getDemand().latitude       : 0.0; }
 - (double)readDemandLongitude      { return _integrator ? _integrator->getDemand().longitude      : 0.0; }
-- (double)readDemandAltitude       { return _integrator ? _integrator->getDemand().altitude       : 0.0; }
+- (double)readDemandAltitude {
+  if (!_integrator) return 0.0;
+  const auto demand = _integrator->getDemand();
+  return [self demandAltitudeFromMsl:demand.altitude
+                            latitude:demand.latitude
+                           longitude:demand.longitude];
+}
 - (double)readDemandHeading        { return _integrator ? _integrator->getDemand().heading        : 0.0; }
 - (double)readDemandPitch          { return _integrator ? _integrator->getDemand().pitch          : 0.0; }
 - (double)readDemandRoll           { return _integrator ? _integrator->getDemand().roll           : 0.0; }

package/ios/HybridCesiumView.swift

@@ -72,6 +72,11 @@ class HybridCesiumView: HybridCesiumViewSpec {
   var ionImageryAssetId: Double = 1 {
     didSet { let v = Int64(ionImageryAssetId); postToRender { [weak self] in self?.bridge?.updateImageryAssetId(v) } }
   }
+  /// `"msl"` (default) or `"ellipsoid"`. Ellipsoid heights are converted to MSL
+  /// before the camera integrator.
+  var altitudeDatum: String? = "msl" {
+    didSet { pushAltitudeDatum() }
+  }
 
   // ── Optional perf / quality knobs ────────────────────────────────────────
   var maximumCachedMiB: Double? {
@@ -460,6 +465,12 @@ class HybridCesiumView: HybridCesiumViewSpec {
     // sqliteCacheMaxRows and taskProcessorThreads are applied at construction
     // time via the CesiumBridge initializer; calling them here has no effect.
     if let v = minAltitudeAboveTerrain { bridge?.setMinAltitudeAboveTerrain(Float(v)) }
+    bridge?.setAltitudeDatumEllipsoid(altitudeDatum == "ellipsoid")
+  }
+
+  private func pushAltitudeDatum() {
+    let ellipsoid = altitudeDatum == "ellipsoid"
+    postToRender { [weak self] in self?.bridge?.setAltitudeDatumEllipsoid(ellipsoid) }
   }
 
   // MARK: - Render Loop