react-native-cesium 1.2.19 → 1.2.20

package/README.md

@@ -294,6 +294,7 @@ When you pass a callback ref to `CesiumView`, wrap it with `callback(...)` from
 
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
+| `altitudeDatum` | `"msl"` \| `"ellipsoid"` | `"msl"` | Vertical datum of every public altitude: `initialCamera`, `setAltitude`, `teleport`, and the altitude returned by `getActualCamera`, `getDemandCamera`, and `onActualCamera`. `"msl"` is metres above mean sea level. `"ellipsoid"` is WGS84 ellipsoidal height (Android `Location.getAltitude()`). Ellipsoidal heights are converted to mean sea level with EGM96 before the camera integrator, and converted back on read. Switching the prop does not move the camera: later reads use the new unit, and the next altitude or position write is interpreted in that unit. Leave this at `"msl"` for gesture and scripted altitudes. Use `"ellipsoid"` for a GPS ellipsoidal height, and call `setPosition` and `setAltitude` one after the other on the same thread. |
 | `onMetrics` | `(metrics: CesiumMetrics) => void` | `undefined` | Receives throttled runtime stats and credits text. |
 
 **Optional performance / quality knobs**
@@ -348,7 +349,7 @@ type CameraState = {
 | --- | --- |------------------------------|-------------------------------------------------------------------------------------------------------|
 | `latitude` | `number` | `-90..90`                    | Camera latitude in degrees.                                                                           |
 | `longitude` | `number` | `-180..180`                  | Camera longitude in degrees.                                                                          |
-| `altitude` | `number` | Meters above sea level (MSL) | Camera height in meters.                                                                              |
+| `altitude` | `number` | Metres | Camera height. Mean sea level unless `altitudeDatum` is `"ellipsoid"`, in which case this is WGS84 ellipsoidal height. Writes and reads use the same unit. |
 | `heading` | `number` | Degrees                      | Compass direction the camera faces. Example: `0` faces north, `90` faces east.                        |
 | `pitch` | `number` | Degrees                      | Tilt angle. Negative values look downward toward terrain; positive values tilt up toward horizon/sky. |
 | `roll` | `number` | Degrees                      | Bank/rotation around forward axis. Positive right bank, negative left bank.                           |
@@ -385,15 +386,15 @@ Each axis (position, altitude, heading, attitude, viewCorrection, verticalFov) h
 
 | Method | Signature | Description |
 | --- | --- | --- |
-| `setPosition` | `(latitude: number, longitude: number) => void` | New geographic position **demand** (degrees). Each call stamps the measurement with the native steady-clock time of arrival and runs one α-β update against the predicted state at that instant. Latitude is clamped to ±90 on extrapolation; longitude is continuous (no wrap normalisation) so shortest-arc residual maths stays correct across the antimeridian. |
-| `setAltitude` | `(altitudeMeters: number) => void` | New altitude demand (metres MSL). |
+| `setPosition` | `(latitude: number, longitude: number) => void` | New geographic position **demand** (degrees). Each call stamps the measurement with the native steady-clock time of arrival and runs one α-β update against the predicted state at that instant. Latitude is clamped to ±90 on extrapolation; longitude is continuous (no wrap normalisation) so shortest-arc residual maths stays correct across the antimeridian. When `altitudeDatum` is `"ellipsoid"`, a horizontal move keeps the demanded ellipsoidal height and recomputes mean sea level at the new point. `"msl"` leaves altitude unchanged. |
+| `setAltitude` | `(altitudeMeters: number) => void` | New altitude demand, in metres. Mean sea level unless `altitudeDatum` is `"ellipsoid"`, in which case it is WGS84 height and is converted to mean sea level before the integrator. A later read reports the same sample back in this unit. |
 | `setHeading` | `(headingDeg: number) => void` | New heading demand (degrees; `0` = north, increasing clockwise). The integrator computes the shortest-arc residual, so feeding it `359 → 1` rotates 2° clockwise, not 358° counter-clockwise. |
 | `setAttitude` | `(pitchDeg: number, rollDeg: number) => void` | New pitch and roll demand (degrees). Bundled because almost every IMU emits them together — but you can pass the previous value for either axis if only one of them has changed. |
 | `setViewCorrection` | `(q: Quaternion) => void` | New camera-space rotation applied **after** HPR. SLERPed toward the latest demand each frame. Use for boresight calibration, screen-fixed HUD alignment, etc. Non-unit values are normalised on the native side. |
 | `setVerticalFov` | `(deg: number) => void` | New vertical FOV demand (degrees). Clamped to `20..100` on the native side. |
-| `teleport` | `(camera: CameraState) => void` | Hard scene jump — atomically resets every DoF (value, velocity, demand) to `camera`. Bypasses the integrator entirely. Use for `Fly to coordinate` actions or seeding from saved state. |
-| `getActualCamera` | `() => Promise<CameraState>` | Most recently rendered camera (post-integration). This is what the user is currently looking at and what a HUD overlay should mirror. Differs from `getDemandCamera()` while a glide is in progress or when the terrain-floor clamp has raised the altitude. |
-| `getDemandCamera` | `() => Promise<CameraState>` | What the consumer last asked for (per-DoF demand). Useful for diagnostics, or for showing the requested camera alongside the rendered one. |
+| `teleport` | `(camera: CameraState) => void` | Hard scene jump — atomically resets every DoF (value, velocity, demand) to `camera`. Bypasses the integrator entirely. Use for `Fly to coordinate` actions or seeding from saved state. `camera.altitude` uses the unit selected by `altitudeDatum`. |
+| `getActualCamera` | `() => Promise<CameraState>` | Most recently rendered camera (post-integration). This is what the user is currently looking at and what a HUD overlay should mirror. Differs from `getDemandCamera()` while a glide is in progress or when the terrain-floor clamp has raised the altitude. Altitude is in the unit selected by `altitudeDatum`. |
+| `getDemandCamera` | `() => Promise<CameraState>` | What the consumer last asked for (per-DoF demand). Useful for diagnostics, or for showing the requested camera alongside the rendered one. Altitude is in the unit selected by `altitudeDatum`. |
 | `getViewCorrection` | `() => Promise<Quaternion>` | Current view-correction quaternion (smoothed toward the latest demand). Identity (`w=1, x=y=z=0`) if you have never called `setViewCorrection`. |
 
 #### Threading: setters vs getters
@@ -415,7 +416,7 @@ Avoid assuming **main-thread-only** vs **JS-thread-only** labels beyond the abov
 
 The integrator tracks two camera states simultaneously:
 
-- **Demand** — what the consumer asked for, exactly as it was passed to the setters. `getDemandCamera()` returns this.
+- **Demand** — what the consumer asked for. `getDemandCamera()` returns this, with altitude in the unit selected by `altitudeDatum`.
 - **Actual** — what the integrator extrapolated to and what was passed to the GPU on the last frame. `getActualCamera()` returns this.
 
 For a steady GPS feed with no terrain clamp the two values converge within a few frames. They diverge when:
@@ -461,6 +462,8 @@ imuSubscription.on('attitude', (att) => {
 })
 ```
 
+`fix.altitudeMsl` matches the default `altitudeDatum="msl"`. Android `Location.getAltitude()` is a WGS84 ellipsoidal height: set `altitudeDatum="ellipsoid"` and pass that value to `setAltitude` instead. Call `setPosition` and `setAltitude` one after the other on the same thread so the geoid is applied at that fix.
+
 Each setter is synchronous, takes the integrator's mutex briefly, and is safe to call at any rate from any thread.
 
 ### `CesiumMetrics`

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

@@ -1,6 +1,7 @@
 #include "CesiumBridgeAndroid.h"
 
 #include "engine/EngineTunables.hpp"
+#include "engine/GeoidConverter.hpp"
 #include "engine/TerrainFloor.hpp"
 #include "vulkan/VulkanBackend.h"
 
@@ -149,13 +150,34 @@ void CesiumBridgeAndroid::updateImageryAssetId(int64_t assetId) {
 
 void CesiumBridgeAndroid::setPosition(double lat, double lon) {
   if (!initialized_ || !integrator_) 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 CesiumBridgeAndroid::setAltitudeDatumEllipsoid(bool ellipsoid) {
+  altitudeIsEllipsoid_.store(ellipsoid, std::memory_order_release);
+}
+
 void CesiumBridgeAndroid::setAltitude(double alt) {
   if (!initialized_ || !integrator_) return;
-  integrator_->setAltitude(alt);
+  const auto demand = integrator_->getDemand();
+  integrator_->setAltitude(reactnativecesium::demandAltitudeToMslMeters(
+      demand.latitude, demand.longitude, alt,
+      altitudeIsEllipsoid_.load(std::memory_order_acquire)));
   forceRender_.store(true, std::memory_order_release);
 }
 
@@ -184,7 +206,8 @@ void CesiumBridgeAndroid::teleport(double lat, double lon, double alt,
   reactnativecesium::CameraParams p;
   p.latitude       = lat;
   p.longitude      = lon;
-  p.altitude       = alt;
+  p.altitude       = reactnativecesium::demandAltitudeToMslMeters(
+      lat, lon, alt, altitudeIsEllipsoid_.load(std::memory_order_acquire));
   p.heading        = heading;
   p.pitch          = pitch;
   p.roll           = roll;
@@ -338,7 +361,11 @@ double CesiumBridgeAndroid::readActualLongitude() {
   return integrator_ ? integrator_->getActual().longitude : 0.0;
 }
 double CesiumBridgeAndroid::readActualAltitude() {
-  return integrator_ ? integrator_->getActual().altitude : 0.0;
+  if (!integrator_) return 0.0;
+  const auto actual = integrator_->getActual();
+  return reactnativecesium::mslToDemandAltitudeMeters(
+      actual.latitude, actual.longitude, actual.altitude,
+      altitudeIsEllipsoid_.load(std::memory_order_acquire));
 }
 double CesiumBridgeAndroid::readActualHeading() {
   return integrator_ ? integrator_->getActual().heading : 0.0;
@@ -362,7 +389,11 @@ double CesiumBridgeAndroid::readDemandLongitude() {
   return integrator_ ? integrator_->getDemand().longitude : 0.0;
 }
 double CesiumBridgeAndroid::readDemandAltitude() {
-  return integrator_ ? integrator_->getDemand().altitude : 0.0;
+  if (!integrator_) return 0.0;
+  const auto demand = integrator_->getDemand();
+  return reactnativecesium::mslToDemandAltitudeMeters(
+      demand.latitude, demand.longitude, demand.altitude,
+      altitudeIsEllipsoid_.load(std::memory_order_acquire));
 }
 double CesiumBridgeAndroid::readDemandHeading() {
   return integrator_ ? integrator_->getDemand().heading : 0.0;
@@ -453,6 +484,11 @@ Java_com_margelo_nitro_reactnativecesium_CesiumBridgeJNI_nativeSetPosition(
   getBridge(ptr)->setPosition(lat, lon);
 }
 JNIEXPORT void JNICALL
+Java_com_margelo_nitro_reactnativecesium_CesiumBridgeJNI_nativeSetAltitudeDatumEllipsoid(
+    JNIEnv*, jobject, jlong ptr, jboolean ellipsoid) {
+  getBridge(ptr)->setAltitudeDatumEllipsoid(ellipsoid == JNI_TRUE);
+}
+JNIEXPORT void JNICALL
 Java_com_margelo_nitro_reactnativecesium_CesiumBridgeJNI_nativeSetAltitude(
     JNIEnv*, jobject, jlong ptr, jdouble alt) {
   getBridge(ptr)->setAltitude(alt);

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

@@ -48,6 +48,10 @@ struct CesiumBridgeAndroid {
 
   // ── Per-DoF camera demand setters ──────────────────────────────────────
   void setPosition(double lat, double lon);
+  // When true, altitudes passed to setAltitude/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 setHeading(double headingDeg);
   void setAttitude(double pitchDeg, double rollDeg);
@@ -138,6 +142,9 @@ private:
   int  viewportWidth_  = 0;
   int  viewportHeight_ = 0;
   bool initialized_    = false;
+  // Written from the render thread when the prop changes; read from the
+  // caller thread inside setAltitude / setPosition / teleport / readback.
+  std::atomic<bool> altitudeIsEllipsoid_{false};
 
   // Force-render flag — set on every demand change so the render loop knows
   // to dispatch at least one frame.

package/android/src/main/java/com/margelo/nitro/reactnativecesium/CesiumBridgeJNI.kt

@@ -27,6 +27,8 @@ class CesiumBridgeJNI {
 
   // ── Per-DoF camera setters ───────────────────────────────────────────────
   fun setPosition(lat: Double, lon: Double) = nativeSetPosition(nativePtr, lat, lon)
+  fun setAltitudeDatumEllipsoid(ellipsoid: Boolean) =
+    nativeSetAltitudeDatumEllipsoid(nativePtr, ellipsoid)
   fun setAltitude(alt: Double) = nativeSetAltitude(nativePtr, alt)
   fun setHeading(headingDeg: Double) = nativeSetHeading(nativePtr, headingDeg)
   fun setAttitude(pitchDeg: Double, rollDeg: Double) = nativeSetAttitude(nativePtr, pitchDeg, rollDeg)
@@ -107,6 +109,7 @@ class CesiumBridgeJNI {
   private external fun nativeUpdateImageryAssetId(ptr: Long, assetId: Long)
 
   private external fun nativeSetPosition(ptr: Long, lat: Double, lon: Double)
+  private external fun nativeSetAltitudeDatumEllipsoid(ptr: Long, ellipsoid: Boolean)
   private external fun nativeSetAltitude(ptr: Long, alt: Double)
   private external fun nativeSetHeading(ptr: Long, headingDeg: Double)
   private external fun nativeSetAttitude(ptr: Long, pitchDeg: Double, rollDeg: Double)

package/android/src/main/java/com/margelo/nitro/reactnativecesium/HybridCesiumView.kt

@@ -105,6 +105,14 @@ class HybridCesiumView(private val appContext: Context) : HybridCesiumViewSpec()
   override var ionImageryAssetId: Double = 1.0
     set(value) { field = value; postToRender { bridge?.updateImageryAssetId(value.toLong()) } }
 
+  /** `"msl"` (default) or `"ellipsoid"`. Ellipsoid heights are converted to MSL. */
+  override var altitudeDatum: String? = "msl"
+    set(value) {
+      field = value
+      val ellipsoid = value == "ellipsoid"
+      postToRender { bridge?.setAltitudeDatumEllipsoid(ellipsoid) }
+    }
+
   // ── Optional perf / quality knobs ────────────────────────────────────────
   override var maximumCachedMiB: Double? = null
     set(value) { field = value; if (value != null) postToRender { bridge?.setMaximumCachedMiB(value.toInt()) } }
@@ -519,6 +527,7 @@ class HybridCesiumView(private val appContext: Context) : HybridCesiumViewSpec()
     // sqliteCacheMaxRows and taskProcessorThreads are applied before init() in
     // surfaceCreated; calling them here (after buildEngine) has no effect.
     minAltitudeAboveTerrain?.let { b.setMinAltitudeAboveTerrain(it.toFloat()) }
+    b.setAltitudeDatumEllipsoid(altitudeDatum == "ellipsoid")
   }
 
   /**

package/cpp/engine/CesiumEngine.cpp

@@ -212,6 +212,21 @@ void CesiumEngine::shutdown() {
   creditSystem_.reset();
 }
 
+void CesiumEngine::drainAsyncWork() {
+  // Worker tasks post main-thread continuations and return. Those
+  // continuations (Ion raster-overlay loads in particular) can queue more
+  // worker tasks, so pump both sides until the pool stays idle.
+  for (int pass = 0; pass < 16; ++pass) {
+    if (taskProcessor_) {
+      taskProcessor_->waitUntilIdle();
+    }
+    asyncSystem_.dispatchMainThreadTasks();
+  }
+  if (taskProcessor_) {
+    taskProcessor_->waitUntilIdle();
+  }
+}
+
 void CesiumEngine::updateConfig(const EngineConfig& config) {
   // Only token / asset id changes force a full tileset rebuild. Everything
   // else is mutated in place via tileset_->getOptions() to avoid the very
@@ -407,19 +422,27 @@ void CesiumEngine::applyImageryOverlay(int64_t targetAssetId) {
 }
 
 void CesiumEngine::destroyTileset() {
-  currentOverlay_ = nullptr;
-  currentImageryAssetId_ = 1;
-  tileset_.reset();
-  if (taskProcessor_) {
-    taskProcessor_->waitUntilIdle();
+  // Detach the imagery overlay while this engine still owns it. Dropping
+  // currentOverlay_ before in-flight IonRasterOverlay tasks finish frees the
+  // overlay out from under their destructors (heap corruption).
+  if (tileset_ && currentOverlay_) {
+    tileset_->getOverlays().remove(currentOverlay_);
   }
-  // every TileGPUResources* baked into cachedDraws_ has just been freed.
-  // Clearing the cache guarantees no dangling pointer survives into the next
-  // updateFrame and forces a clean slow-path rebuild.
+  drainAsyncWork();
+
+  // Drop draw-cache pointers before the tileset frees TileGPUResources.
   lastDrawSignature_   = 0;
   stableSigFrames_     = 0;
   cachedDraws_.clear();
   clearResidentTerrain();
+
+  tileset_.reset();
+  currentImageryAssetId_ = 1;
+  // Tileset destruction schedules further async cleanup. Drain that while
+  // this engine still owns the overlay, then release it. Dropping the
+  // overlay first frees it under those continuations.
+  drainAsyncWork();
+  currentOverlay_ = nullptr;
 }
 
 void CesiumEngine::setImageryAssetId(int64_t assetId) {

package/cpp/engine/CesiumEngine.hpp

@@ -156,6 +156,9 @@ public:
 private:
   void createTileset();
   void destroyTileset();
+  // Wait until worker tasks and the main-thread continuations they post have
+  // finished. Safe to call with or without a live tileset.
+  void drainAsyncWork();
 
   // Apply runtime-mutable bits of `cfg` to the live tileset. Returns true if a
   // value actually changed (callers can use this to trigger force-render).

package/cpp/engine/GeoidConverter.cpp

@@ -3,34 +3,55 @@
 #include "../third_party/egm96/EGM96.h"
 
 #include <cmath>
+#include <limits>
 
 namespace reactnativecesium {
 
 namespace {
 
 double normalizeLongitudeDegrees(double longitudeDeg) {
-  if (!std::isfinite(longitudeDeg)) return 0.0;
   double wrapped = std::fmod(longitudeDeg + 180.0, 360.0);
   if (wrapped < 0.0) wrapped += 360.0;
   return wrapped - 180.0;
 }
 
+// Geoid undulation N, where HAE = MSL + N. NaN when the position or the
+// model result is non-finite; callers then return the input height unchanged.
+double geoidUndulationMeters(double latitudeDeg, double longitudeDeg) {
+  if (!std::isfinite(latitudeDeg) || !std::isfinite(longitudeDeg)) {
+    return std::numeric_limits<double>::quiet_NaN();
+  }
+
+  const double undulation = egm96_compute_altitude_offset(
+      latitudeDeg, normalizeLongitudeDegrees(longitudeDeg));
+  if (!std::isfinite(undulation)) {
+    return std::numeric_limits<double>::quiet_NaN();
+  }
+  return undulation;
+}
+
+double applyUndulation(double heightMeters,
+                       double latitudeDeg,
+                       double longitudeDeg,
+                       double sign) {
+  if (!std::isfinite(heightMeters)) return heightMeters;
+  const double undulation = geoidUndulationMeters(latitudeDeg, longitudeDeg);
+  if (!std::isfinite(undulation)) return heightMeters;
+  return heightMeters + sign * undulation;
+}
+
 } // namespace
 
 double mslToEllipsoidMeters(double latitudeDeg,
                             double longitudeDeg,
                             double mslMeters) {
-  if (!std::isfinite(latitudeDeg) || !std::isfinite(longitudeDeg) ||
-      !std::isfinite(mslMeters)) {
-    return mslMeters;
-  }
-
-  const double normalizedLon = normalizeLongitudeDegrees(longitudeDeg);
-  const double geoidOffset =
-      egm96_compute_altitude_offset(latitudeDeg, normalizedLon);
+  return applyUndulation(mslMeters, latitudeDeg, longitudeDeg, 1.0);
+}
 
-  if (!std::isfinite(geoidOffset)) return mslMeters;
-  return mslMeters + geoidOffset;
+double ellipsoidToMslMeters(double latitudeDeg,
+                            double longitudeDeg,
+                            double ellipsoidMeters) {
+  return applyUndulation(ellipsoidMeters, latitudeDeg, longitudeDeg, -1.0);
 }
 
 } // namespace reactnativecesium

package/cpp/engine/GeoidConverter.hpp

@@ -7,4 +7,45 @@ double mslToEllipsoidMeters(double latitudeDeg,
                             double longitudeDeg,
                             double mslMeters);
 
+/// Converts WGS84 ellipsoidal height (HAE) to orthometric height (MSL).
+double ellipsoidToMslMeters(double latitudeDeg,
+                            double longitudeDeg,
+                            double ellipsoidMeters);
+
+/// `ellipsoidHeight` selects HAE→MSL. Otherwise `altitudeMeters` is already MSL.
+inline double demandAltitudeToMslMeters(double latitudeDeg,
+                                        double longitudeDeg,
+                                        double altitudeMeters,
+                                        bool ellipsoidHeight) {
+  if (!ellipsoidHeight) return altitudeMeters;
+  return ellipsoidToMslMeters(latitudeDeg, longitudeDeg, altitudeMeters);
+}
+
+/// `ellipsoidHeight` selects MSL→HAE. Otherwise `mslMeters` is already the
+/// demand datum. Inverse of `demandAltitudeToMslMeters`.
+inline double mslToDemandAltitudeMeters(double latitudeDeg,
+                                        double longitudeDeg,
+                                        double mslMeters,
+                                        bool ellipsoidHeight) {
+  if (!ellipsoidHeight) return mslMeters;
+  return mslToEllipsoidMeters(latitudeDeg, longitudeDeg, mslMeters);
+}
+
+/// Mean-sea-level change below this is left alone when a horizontal move
+/// re-expresses an ellipsoidal height. One centimetre.
+inline constexpr double kHorizontalMoveMslEpsilonMeters = 0.01;
+
+/// Keeps the same ellipsoidal height when the horizontal position changes.
+/// `oldMslMeters` is mean sea level at the old point; the result is mean sea
+/// level at the new point.
+inline double mslAfterHorizontalMove(double oldLatitudeDeg,
+                                     double oldLongitudeDeg,
+                                     double oldMslMeters,
+                                     double newLatitudeDeg,
+                                     double newLongitudeDeg) {
+  const double hae =
+      mslToEllipsoidMeters(oldLatitudeDeg, oldLongitudeDeg, oldMslMeters);
+  return ellipsoidToMslMeters(newLatitudeDeg, newLongitudeDeg, hae);
+}
+
 } // namespace reactnativecesium

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

@@ -4,6 +4,7 @@
 #include "engine/CameraIntegrator.hpp"
 #include "engine/CesiumEngine.hpp"
 #include "engine/EngineTunables.hpp"
+#include "engine/GeoidConverter.hpp"
 #include "engine/MetricsAggregator.hpp"
 #include "engine/TerrainFloor.hpp"
 #include "metal/MetalBackend.h"
@@ -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
@@ -65,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];
@@ -184,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);
 }
 
@@ -223,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;
@@ -427,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; }
@@ -436,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

package/lib/typescript/src/specs/cesium-view.nitro.d.ts

@@ -6,6 +6,11 @@ import type { HybridView, HybridViewProps, HybridViewMethods } from 'react-nativ
 export interface CameraState {
     latitude: number;
     longitude: number;
+    /**
+     * Metres. Mean sea level unless `altitudeDatum` is `"ellipsoid"`, in which
+     * case this is WGS84 ellipsoidal height. `getActualCamera`,
+     * `getDemandCamera`, and `onActualCamera` report altitude in that same unit.
+     */
     altitude: number;
     heading: number;
     pitch: number;
@@ -51,6 +56,16 @@ export interface CesiumViewProps extends HybridViewProps {
     /** 1 = off; 2 or 4 = MSAA when supported. */
     msaaSampleCount: number;
     ionImageryAssetId: number;
+    /**
+     * Vertical datum of public altitude numbers, in both directions.
+     * `"msl"` (default) is metres above mean sea level.
+     * `"ellipsoid"` is WGS84 ellipsoidal height (Android `Location.getAltitude`).
+     * Ellipsoidal heights are converted to mean sea level with EGM96 before the
+     * camera integrator, and converted back on read. Switching this prop does
+     * not move the camera: later reads use the new unit, and the next
+     * `setAltitude`, `setPosition`, or `teleport` is interpreted in that unit.
+     */
+    altitudeDatum?: string;
     /** RAM budget for live tileset, in mebibytes. Default 256. */
     maximumCachedMiB?: number;
     /** Pre-load ancestor tiles around the visible set (smoother panning, more loads). Default true. */
@@ -132,9 +147,17 @@ export interface CesiumViewMethods extends HybridViewMethods {
      * for GPS or scripted position updates. Latitude is clamped to ±90 by the
      * integrator; longitude is continuous (no wrap normalisation) so the
      * shortest-arc residual maths stays correct across the antimeridian.
+     * When `altitudeDatum` is `"ellipsoid"`, a horizontal move keeps the
+     * demanded ellipsoidal height and recomputes mean sea level at the new
+     * point. Mean-sea-level mode leaves altitude unchanged.
      */
     setPosition(latitude: number, longitude: number): void;
-    /** New altitude demand (metres above mean sea level). */
+    /**
+     * New altitude demand, in metres. Interpreted as mean sea level unless
+     * `altitudeDatum` is `"ellipsoid"`, in which case it is WGS84 height and
+     * converted to MSL before the integrator. A later read reports the same
+     * sample back in this unit.
+     */
     setAltitude(altitudeMeters: number): void;
     /** New heading demand (degrees, 0 = north, increasing clockwise). */
     setHeading(headingDeg: number): void;
@@ -163,13 +186,14 @@ export interface CesiumViewMethods extends HybridViewMethods {
      * Most recent camera that was rendered (post-integration). This is what
      * the user is currently looking at and is what a HUD overlay should
      * mirror. Differs from `getDemandCamera()` while a glide is in progress
-     * or when the terrain-floor clamp has raised the altitude.
+     * or when the terrain-floor clamp has raised the altitude. Altitude is in
+     * the unit selected by `altitudeDatum`.
      */
     getActualCamera(): Promise<CameraState>;
     /**
      * What the consumer last asked for (per-DoF demand). Useful for
      * diagnostics or for showing the requested camera alongside the rendered
-     * one.
+     * one. Altitude is in the unit selected by `altitudeDatum`.
      */
     getDemandCamera(): Promise<CameraState>;
     /** Current view-correction quaternion (smoothed toward the latest demand). */

package/lib/typescript/src/specs/cesium-view.nitro.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cesium-view.nitro.d.ts","sourceRoot":"","sources":["../../../../src/specs/cesium-view.nitro.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cesium-view.nitro.d.ts","sourceRoot":"","sources":["../../../../src/specs/cesium-view.nitro.ts"],"names":[],"mappings":"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"}

package/nitrogen/generated/android/ReactNativeCesiumOnLoad.cpp

@@ -30,7 +30,7 @@ int initialize(JavaVM* vm) {
 }
 
 struct JHybridCesiumViewSpecImpl: public jni::JavaClass<JHybridCesiumViewSpecImpl, JHybridCesiumViewSpec::JavaPart> {
-  static constexpr auto kJavaDescriptor = "Lcom/margelo/nitro/reactnativecesium/HybridCesiumView;";
+  static constexpr auto kJavaDescriptor = "Lcom/reactnativecesium/HybridCesiumView;";
   static std::shared_ptr<JHybridCesiumViewSpec> create() {
     static const auto constructorFn = javaClassStatic()->getConstructor<JHybridCesiumViewSpecImpl::javaobject()>();
     jni::local_ref<JHybridCesiumViewSpec::JavaPart> javaPart = javaClassStatic()->newObject(constructorFn);

package/nitrogen/generated/android/c++/JHybridCesiumViewSpec.cpp

@@ -140,6 +140,15 @@ namespace margelo::nitro::reactnativecesium {
     static const auto method = _javaPart->javaClassStatic()->getMethod<void(double /* ionImageryAssetId */)>("setIonImageryAssetId");
     method(_javaPart, ionImageryAssetId);
   }
+  std::optional<std::string> JHybridCesiumViewSpec::getAltitudeDatum() {
+    static const auto method = _javaPart->javaClassStatic()->getMethod<jni::local_ref<jni::JString>()>("getAltitudeDatum");
+    auto __result = method(_javaPart);
+    return __result != nullptr ? std::make_optional(__result->toStdString()) : std::nullopt;
+  }
+  void JHybridCesiumViewSpec::setAltitudeDatum(const std::optional<std::string>& altitudeDatum) {
+    static const auto method = _javaPart->javaClassStatic()->getMethod<void(jni::alias_ref<jni::JString> /* altitudeDatum */)>("setAltitudeDatum");
+    method(_javaPart, altitudeDatum.has_value() ? jni::make_jstring(altitudeDatum.value()) : nullptr);
+  }
   std::optional<double> JHybridCesiumViewSpec::getMaximumCachedMiB() {
     static const auto method = _javaPart->javaClassStatic()->getMethod<jni::local_ref<jni::JDouble>()>("getMaximumCachedMiB");
     auto __result = method(_javaPart);

package/nitrogen/generated/android/c++/JHybridCesiumViewSpec.hpp

@@ -68,6 +68,8 @@ namespace margelo::nitro::reactnativecesium {
     void setMsaaSampleCount(double msaaSampleCount) override;
     double getIonImageryAssetId() override;
     void setIonImageryAssetId(double ionImageryAssetId) override;
+    std::optional<std::string> getAltitudeDatum() override;
+    void setAltitudeDatum(const std::optional<std::string>& altitudeDatum) override;
     std::optional<double> getMaximumCachedMiB() override;
     void setMaximumCachedMiB(std::optional<double> maximumCachedMiB) override;
     std::optional<bool> getPreloadAncestors() override;

package/nitrogen/generated/android/c++/views/JHybridCesiumViewStateUpdater.cpp

@@ -98,6 +98,11 @@ void JHybridCesiumViewStateUpdater::updateViewProps(jni::alias_ref<jni::JClass>
         : !newProps->ionImageryAssetId.hasSameValue(oldProps->ionImageryAssetId)) {
     hybridView->setIonImageryAssetId(newProps->ionImageryAssetId.get());
   }
+  if (oldProps == nullptr
+        ? newProps->altitudeDatum.isProvided()
+        : !newProps->altitudeDatum.hasSameValue(oldProps->altitudeDatum)) {
+    hybridView->setAltitudeDatum(newProps->altitudeDatum.get());
+  }
   if (oldProps == nullptr
         ? newProps->maximumCachedMiB.isProvided()
         : !newProps->maximumCachedMiB.hasSameValue(oldProps->maximumCachedMiB)) {

package/nitrogen/generated/android/kotlin/com/margelo/nitro/reactnativecesium/HybridCesiumViewSpec.kt

@@ -82,6 +82,12 @@ abstract class HybridCesiumViewSpec: HybridView() {
   @set:Keep
   abstract var ionImageryAssetId: Double
   
+  @get:DoNotStrip
+  @get:Keep
+  @set:DoNotStrip
+  @set:Keep
+  abstract var altitudeDatum: String?
+  
   @get:DoNotStrip
   @get:Keep
   @set:DoNotStrip

package/nitrogen/generated/ios/ReactNativeCesium-Swift-Cxx-Bridge.hpp

@@ -41,6 +41,21 @@ namespace ReactNativeCesium { class HybridCesiumViewSpec_cxx; }
  */
 namespace margelo::nitro::reactnativecesium::bridge::swift {
 
+  // pragma MARK: std::optional<std::string>
+  /**
+   * Specialized version of `std::optional<std::string>`.
+   */
+  using std__optional_std__string_ = std::optional<std::string>;
+  inline std::optional<std::string> create_std__optional_std__string_(const std::string& value) noexcept {
+    return std::optional<std::string>(value);
+  }
+  inline bool has_value_std__optional_std__string_(const std::optional<std::string>& optional) noexcept {
+    return optional.has_value();
+  }
+  inline std::string get_std__optional_std__string_(const std::optional<std::string>& optional) noexcept {
+    return optional.value();
+  }
+  
   // pragma MARK: std::optional<double>
   /**
    * Specialized version of `std::optional<double>`.

package/nitrogen/generated/ios/c++/HybridCesiumViewSpecSwift.hpp

@@ -128,6 +128,13 @@ namespace margelo::nitro::reactnativecesium {
     inline void setIonImageryAssetId(double ionImageryAssetId) noexcept override {
       _swiftPart.setIonImageryAssetId(std::forward<decltype(ionImageryAssetId)>(ionImageryAssetId));
     }
+    inline std::optional<std::string> getAltitudeDatum() noexcept override {
+      auto __result = _swiftPart.getAltitudeDatum();
+      return __result;
+    }
+    inline void setAltitudeDatum(const std::optional<std::string>& altitudeDatum) noexcept override {
+      _swiftPart.setAltitudeDatum(altitudeDatum);
+    }
     inline std::optional<double> getMaximumCachedMiB() noexcept override {
       auto __result = _swiftPart.getMaximumCachedMiB();
       return __result;

package/nitrogen/generated/ios/c++/views/HybridCesiumViewComponent.mm

@@ -152,6 +152,12 @@ using namespace margelo::nitro::reactnativecesium::views;
           : !newViewProps.ionImageryAssetId.hasSameValue(oldViewProps->ionImageryAssetId)) {
       swiftPart.setIonImageryAssetId(newViewProps.ionImageryAssetId.get());
     }
+    // altitudeDatum: optional
+    if (oldViewProps == nullptr
+          ? newViewProps.altitudeDatum.isProvided()
+          : !newViewProps.altitudeDatum.hasSameValue(oldViewProps->altitudeDatum)) {
+      swiftPart.setAltitudeDatum(newViewProps.altitudeDatum.get());
+    }
     // maximumCachedMiB: optional
     if (oldViewProps == nullptr
           ? newViewProps.maximumCachedMiB.isProvided()

package/nitrogen/generated/ios/swift/HybridCesiumViewSpec.swift

@@ -19,6 +19,7 @@ public protocol HybridCesiumViewSpec_protocol: HybridObject, HybridView {
   var loadingDescendantLimit: Double { get set }
   var msaaSampleCount: Double { get set }
   var ionImageryAssetId: Double { get set }
+  var altitudeDatum: String? { get set }
   var maximumCachedMiB: Double? { get set }
   var preloadAncestors: Bool? { get set }
   var preloadSiblings: Bool? { get set }

package/nitrogen/generated/ios/swift/HybridCesiumViewSpec_cxx.swift

@@ -220,6 +220,30 @@ open class HybridCesiumViewSpec_cxx {
     }
   }
   
+  public final var altitudeDatum: bridge.std__optional_std__string_ {
+    @inline(__always)
+    get {
+      return { () -> bridge.std__optional_std__string_ in
+        if let __unwrappedValue = self.__implementation.altitudeDatum {
+          return bridge.create_std__optional_std__string_(std.string(__unwrappedValue))
+        } else {
+          return .init()
+        }
+      }()
+    }
+    @inline(__always)
+    set {
+      self.__implementation.altitudeDatum = { () -> String? in
+        if bridge.has_value_std__optional_std__string_(newValue) {
+          let __unwrapped = bridge.get_std__optional_std__string_(newValue)
+          return String(__unwrapped)
+        } else {
+          return nil
+        }
+      }()
+    }
+  }
+  
   public final var maximumCachedMiB: bridge.std__optional_double_ {
     @inline(__always)
     get {

package/nitrogen/generated/shared/c++/HybridCesiumViewSpec.cpp

@@ -32,6 +32,8 @@ namespace margelo::nitro::reactnativecesium {
       prototype.registerHybridSetter("msaaSampleCount", &HybridCesiumViewSpec::setMsaaSampleCount);
       prototype.registerHybridGetter("ionImageryAssetId", &HybridCesiumViewSpec::getIonImageryAssetId);
       prototype.registerHybridSetter("ionImageryAssetId", &HybridCesiumViewSpec::setIonImageryAssetId);
+      prototype.registerHybridGetter("altitudeDatum", &HybridCesiumViewSpec::getAltitudeDatum);
+      prototype.registerHybridSetter("altitudeDatum", &HybridCesiumViewSpec::setAltitudeDatum);
       prototype.registerHybridGetter("maximumCachedMiB", &HybridCesiumViewSpec::getMaximumCachedMiB);
       prototype.registerHybridSetter("maximumCachedMiB", &HybridCesiumViewSpec::setMaximumCachedMiB);
       prototype.registerHybridGetter("preloadAncestors", &HybridCesiumViewSpec::getPreloadAncestors);

package/nitrogen/generated/shared/c++/HybridCesiumViewSpec.hpp

@@ -73,6 +73,8 @@ namespace margelo::nitro::reactnativecesium {
       virtual void setMsaaSampleCount(double msaaSampleCount) = 0;
       virtual double getIonImageryAssetId() = 0;
       virtual void setIonImageryAssetId(double ionImageryAssetId) = 0;
+      virtual std::optional<std::string> getAltitudeDatum() = 0;
+      virtual void setAltitudeDatum(const std::optional<std::string>& altitudeDatum) = 0;
       virtual std::optional<double> getMaximumCachedMiB() = 0;
       virtual void setMaximumCachedMiB(std::optional<double> maximumCachedMiB) = 0;
       virtual std::optional<bool> getPreloadAncestors() = 0;

package/nitrogen/generated/shared/c++/views/HybridCesiumViewComponent.cpp

@@ -29,6 +29,7 @@ namespace margelo::nitro::reactnativecesium::views {
     loadingDescendantLimit(nitro::ReactProp<double>::fromRawValue("CesiumView", "loadingDescendantLimit", rawProps, sourceProps.loadingDescendantLimit)),
     msaaSampleCount(nitro::ReactProp<double>::fromRawValue("CesiumView", "msaaSampleCount", rawProps, sourceProps.msaaSampleCount)),
     ionImageryAssetId(nitro::ReactProp<double>::fromRawValue("CesiumView", "ionImageryAssetId", rawProps, sourceProps.ionImageryAssetId)),
+    altitudeDatum(nitro::ReactProp<std::optional<std::string>>::fromRawValue("CesiumView", "altitudeDatum", rawProps, sourceProps.altitudeDatum)),
     maximumCachedMiB(nitro::ReactProp<std::optional<double>>::fromRawValue("CesiumView", "maximumCachedMiB", rawProps, sourceProps.maximumCachedMiB)),
     preloadAncestors(nitro::ReactProp<std::optional<bool>>::fromRawValue("CesiumView", "preloadAncestors", rawProps, sourceProps.preloadAncestors)),
     preloadSiblings(nitro::ReactProp<std::optional<bool>>::fromRawValue("CesiumView", "preloadSiblings", rawProps, sourceProps.preloadSiblings)),
@@ -62,6 +63,7 @@ namespace margelo::nitro::reactnativecesium::views {
       case hashString("loadingDescendantLimit"): return true;
       case hashString("msaaSampleCount"): return true;
       case hashString("ionImageryAssetId"): return true;
+      case hashString("altitudeDatum"): return true;
       case hashString("maximumCachedMiB"): return true;
       case hashString("preloadAncestors"): return true;
       case hashString("preloadSiblings"): return true;

package/nitrogen/generated/shared/c++/views/HybridCesiumViewComponent.hpp

@@ -54,6 +54,7 @@ namespace margelo::nitro::reactnativecesium::views {
     nitro::ReactProp<double> loadingDescendantLimit;
     nitro::ReactProp<double> msaaSampleCount;
     nitro::ReactProp<double> ionImageryAssetId;
+    nitro::ReactProp<std::optional<std::string>> altitudeDatum;
     nitro::ReactProp<std::optional<double>> maximumCachedMiB;
     nitro::ReactProp<std::optional<bool>> preloadAncestors;
     nitro::ReactProp<std::optional<bool>> preloadSiblings;
@@ -87,6 +88,7 @@ namespace margelo::nitro::reactnativecesium::views {
              loadingDescendantLimit.hasSameValue(other.loadingDescendantLimit) &&
              msaaSampleCount.hasSameValue(other.msaaSampleCount) &&
              ionImageryAssetId.hasSameValue(other.ionImageryAssetId) &&
+             altitudeDatum.hasSameValue(other.altitudeDatum) &&
              maximumCachedMiB.hasSameValue(other.maximumCachedMiB) &&
              preloadAncestors.hasSameValue(other.preloadAncestors) &&
              preloadSiblings.hasSameValue(other.preloadSiblings) &&
@@ -121,6 +123,7 @@ namespace margelo::nitro::reactnativecesium::views {
              loadingDescendantLimit.isProvided() ||
              msaaSampleCount.isProvided() ||
              ionImageryAssetId.isProvided() ||
+             altitudeDatum.isProvided() ||
              maximumCachedMiB.isProvided() ||
              preloadAncestors.isProvided() ||
              preloadSiblings.isProvided() ||

package/nitrogen/generated/shared/json/CesiumViewConfig.json

@@ -13,6 +13,7 @@
     "loadingDescendantLimit": true,
     "msaaSampleCount": true,
     "ionImageryAssetId": true,
+    "altitudeDatum": true,
     "maximumCachedMiB": true,
     "preloadAncestors": true,
     "preloadSiblings": true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-cesium",
-  "version": "1.2.19",
+  "version": "1.2.20",
   "description": "Experimental Cesium rendering for React Native via Nitro",
   "main": "./lib/commonjs/index.js",
   "module": "./lib/module/index.js",

package/src/specs/cesium-view.nitro.ts

@@ -11,6 +11,11 @@ import type {
 export interface CameraState {
   latitude: number
   longitude: number
+  /**
+   * Metres. Mean sea level unless `altitudeDatum` is `"ellipsoid"`, in which
+   * case this is WGS84 ellipsoidal height. `getActualCamera`,
+   * `getDemandCamera`, and `onActualCamera` report altitude in that same unit.
+   */
   altitude: number
   heading: number
   pitch: number
@@ -59,6 +64,16 @@ export interface CesiumViewProps extends HybridViewProps {
   /** 1 = off; 2 or 4 = MSAA when supported. */
   msaaSampleCount: number
   ionImageryAssetId: number
+  /**
+   * Vertical datum of public altitude numbers, in both directions.
+   * `"msl"` (default) is metres above mean sea level.
+   * `"ellipsoid"` is WGS84 ellipsoidal height (Android `Location.getAltitude`).
+   * Ellipsoidal heights are converted to mean sea level with EGM96 before the
+   * camera integrator, and converted back on read. Switching this prop does
+   * not move the camera: later reads use the new unit, and the next
+   * `setAltitude`, `setPosition`, or `teleport` is interpreted in that unit.
+   */
+  altitudeDatum?: string
 
   // ── Optional perf / quality knobs ────────────────────────────────────────
   // Note: all optional props below use "set once" semantics. Once a value has
@@ -157,10 +172,18 @@ export interface CesiumViewMethods extends HybridViewMethods {
    * for GPS or scripted position updates. Latitude is clamped to ±90 by the
    * integrator; longitude is continuous (no wrap normalisation) so the
    * shortest-arc residual maths stays correct across the antimeridian.
+   * When `altitudeDatum` is `"ellipsoid"`, a horizontal move keeps the
+   * demanded ellipsoidal height and recomputes mean sea level at the new
+   * point. Mean-sea-level mode leaves altitude unchanged.
    */
   setPosition(latitude: number, longitude: number): void
 
-  /** New altitude demand (metres above mean sea level). */
+  /**
+   * New altitude demand, in metres. Interpreted as mean sea level unless
+   * `altitudeDatum` is `"ellipsoid"`, in which case it is WGS84 height and
+   * converted to MSL before the integrator. A later read reports the same
+   * sample back in this unit.
+   */
   setAltitude(altitudeMeters: number): void
 
   /** New heading demand (degrees, 0 = north, increasing clockwise). */
@@ -195,14 +218,15 @@ export interface CesiumViewMethods extends HybridViewMethods {
    * Most recent camera that was rendered (post-integration). This is what
    * the user is currently looking at and is what a HUD overlay should
    * mirror. Differs from `getDemandCamera()` while a glide is in progress
-   * or when the terrain-floor clamp has raised the altitude.
+   * or when the terrain-floor clamp has raised the altitude. Altitude is in
+   * the unit selected by `altitudeDatum`.
    */
   getActualCamera(): Promise<CameraState>
 
   /**
    * What the consumer last asked for (per-DoF demand). Useful for
    * diagnostics or for showing the requested camera alongside the rendered
-   * one.
+   * one. Altitude is in the unit selected by `altitudeDatum`.
    */
   getDemandCamera(): Promise<CameraState>