react-native-cesium 1.2.18 → 1.2.20

package/cpp/engine/CesiumEngine.hpp

@@ -12,8 +12,10 @@
 #include <CesiumUtility/IntrusivePointer.h>
 
 #include <chrono>
+#include <cstdint>
 #include <memory>
 #include <string>
+#include <vector>
 
 namespace Cesium3DTilesSelection {
 class Tileset;
@@ -103,8 +105,9 @@ struct EngineConfig {
   int32_t taskProcessorThreads = 0;
 
   // ── Camera constraints ───────────────────────────────────────────────
-  // Minimum altitude above the loaded terrain surface (metres MSL).
-  // 0 = no constraint (default). Typical use: 2.0 to prevent going underground.
+  // Clearance above the rendered terrain surface, in metres. The floor is
+  // always enforced. 0 means the camera may sit on the surface and may not
+  // go below it.
   float minAltitudeAboveTerrain = 0.0f;
 };
 
@@ -142,15 +145,20 @@ public:
 
   const EngineConfig& getConfig() const { return config_; }
 
-  // Ellipsoid height (metres) of the terrain surface under the camera nadir,
-  // sampled from loaded tile meshes. Meaningless until terrainFloorKnown().
-  float terrainFloorEllipsoidMeters() const { return terrainFloorEllipsoidM_; }
-  // True after at least one frame has sampled the floor from real terrain tiles.
-  bool terrainFloorKnown() const { return terrainFloorValid_; }
+  // Ellipsoid height (metres) of the rendered terrain surface at lat/lon,
+  // interpolated from the finest resident tile. False when no triangle
+  // contains the point (tiles not loaded yet, or the point is off the mesh).
+  // Uses the tiles captured by the previous updateFrame.
+  bool sampleTerrainEllipsoidMeters(double latitudeDeg,
+                                    double longitudeDeg,
+                                    float& outEllipsoidMeters);
 
 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).
@@ -185,11 +193,6 @@ private:
   GlobeCamera          camera_;
   TileLifecycleManager lifecycle_;
 
-  // Ellipsoid height of the terrain surface at the camera nadir (horizontal
-  // nearest-neighbour sample). Only written after a successful tile scan.
-  float terrainFloorEllipsoidM_ = 0.0f;
-  bool  terrainFloorValid_      = false;
-
   // Wall-clock timestamp of the previous updateFrame call. Used to compute
   // deltaTime for Tileset::updateViewGroup, which drives LOD transition fading.
   // Zero-initialised "not yet set" state — first frame passes 0 deltaTime.
@@ -224,22 +227,32 @@ private:
   // is guaranteed to contain the right bytes — fast path becomes legal.
   int                     stableSigFrames_      = 0;
 
-  // ── terrain-floor scan cache ──────────────────────────────────────
-  // The minAltitudeAboveTerrain clamp scans every vertex of every tile whose
-  // bounding region contains the camera lon/lat and picks the altitude of
-  // the vertex with the smallest horizontal (ENU) distance to the camera
-  // nadir (tie-break: lower ellipsoid height). That's an O(NV)
-  // scan over the visible primitives — dominant CPU cost when the camera
-  // sits over a dense LOD chain. Result depends only on the camera lon/lat
-  // and the set of visible primitives, so we cache it keyed on
-  // (camLon, camLat, geometrySignature). Threshold of ~1e-6 degrees (~10 cm)
-  // is far below the inter-vertex spacing of the densest tiles served by
-  // Cesium Ion world terrain, so the cached nearest vertex stays correct.
-  bool     floorCacheValid_      = false;
-  double   floorCacheCamLonDeg_  = 0.0;
-  double   floorCacheCamLatDeg_  = 0.0;
-  uint64_t floorCacheSignature_  = 0;
-  float    floorCacheValue_      = 0.0f;
+  // Tiles drawn by the last updateFrame. The next frame's terrain query
+  // reads this list before updateViewGroup can free the previous selection.
+  struct ResidentTerrainTile {
+    const TileGPUResources* res = nullptr;
+    double geometricError = 0.0;
+    double west = 0.0;
+    double south = 0.0;
+    double east = 0.0;
+    double north = 0.0;
+  };
+  std::vector<ResidentTerrainTile> residentTiles_;
+  uint64_t                         residentSignature_ = 0;
+
+  // One-entry hover cache. Keyed by resident signature, finest-tile identity,
+  // and a sub-metre lat/lon cell. A miss scans that one tile's triangles.
+  struct TerrainHeightCache {
+    bool valid = false;
+    const TileGPUResources* tile = nullptr;
+    int latCell = 0;
+    int lonCell = 0;
+    uint64_t signature = 0;
+    float height = 0.0f;
+  };
+  TerrainHeightCache heightCache_;
+
+  void clearResidentTerrain();
 };
 
 } // namespace reactnativecesium

package/cpp/engine/EngineTunables.hpp

@@ -63,16 +63,17 @@ inline constexpr int32_t kDefaultLoadingDescendantLimit       = 20;
 // steady-state lag at constant motion) while remaining instant under a
 // 60 Hz gesture-driven worklet.
 //
-// `viewCorrection` (a unit quaternion) uses a single-coefficient SLERP toward
-// the latest demand each frame — there is no useful velocity concept for it.
-// `verticalFovDeg` is a 1-D scalar with α only (no velocity term).
+// `viewCorrection` (a unit quaternion) slerps toward the latest demand with a
+// time constant, so a single long frame does not close half the error.
+// `verticalFovDeg` eases toward its demand with the same kind of time constant
+// (no velocity term).
 inline constexpr double kAlphaPos    = 0.6;   inline constexpr double kBetaPos    = 0.05;
 inline constexpr double kAlphaAlt    = 0.6;   inline constexpr double kBetaAlt    = 0.05;
 inline constexpr double kAlphaHdg    = 0.55;  inline constexpr double kBetaHdg    = 0.05;
 inline constexpr double kAlphaPitch  = 0.75;  inline constexpr double kBetaPitch  = 0.05;
 inline constexpr double kAlphaRoll   = 0.75;  inline constexpr double kBetaRoll   = 0.05;
-inline constexpr double kAlphaVfov     = 0.4;   // no velocity term
-inline constexpr double kAlphaViewCorr = 0.5;   // SLERP toward target
+inline constexpr double kVfovTauSec      = 0.12; // seconds, dt-based blend
+inline constexpr double kViewCorrTauSec  = 0.08; // seconds, dt-based slerp
 
 // Convergence epsilons (used to decide when the integrator has settled and
 // the render loop can drop back to idle).

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/GltfToMesh.cpp

@@ -10,6 +10,7 @@
 
 #include <cmath>
 #include <cstring>
+#include <optional>
 
 namespace reactnativecesium {
 
@@ -64,12 +65,17 @@ GltfToMesh::convert(const CesiumGltf::Model& model,
 
         const CesiumGltf::PositionAccessorType posAccessor =
             CesiumGltf::getPositionAccessorView(gltf, primitive);
-        if (posAccessor.status() != CesiumGltf::AccessorViewStatus::Valid ||
-            posAccessor.size() <= 0)
+        const CesiumGltf::AccessorViewStatus posStatus =
+            std::visit(CesiumGltf::StatusFromAccessor{}, posAccessor);
+        if (posStatus != CesiumGltf::AccessorViewStatus::Valid)
+          return;
+
+        const int64_t vertexCount =
+            std::visit(CesiumGltf::CountFromAccessor{}, posAccessor);
+        if (vertexCount <= 0)
           return;
 
         const glm::dmat4 worldTransform = rootTransform * nodeTransform;
-        const int64_t    vertexCount    = posAccessor.size();
 
         // RTC centre = translation column of the world transform.
         // After applyRtcCenter this is the tile's ECEF centre embedded by
@@ -82,8 +88,11 @@ GltfToMesh::convert(const CesiumGltf::Model& model,
         prim.altitudes.reserve(static_cast<size_t>(vertexCount));
 
         for (int64_t i = 0; i < vertexCount; ++i) {
-          const auto&      p    = posAccessor[i];
-          const glm::dvec3 gltfLocal(p.value[0], p.value[1], p.value[2]);
+          const std::optional<glm::dvec3> pos = std::visit(
+              CesiumGltf::PositionFromAccessor{i}, posAccessor);
+          if (!pos)
+            continue;
+          const glm::dvec3 gltfLocal = *pos;
           // Absolute ECEF in double precision.
           const glm::dvec3 ecef(worldTransform * glm::dvec4(gltfLocal, 1.0));
           // Tile-local position (small float, retains full float32 precision

package/cpp/engine/ResourcePreparer.cpp

@@ -1,7 +1,7 @@
 #include "ResourcePreparer.hpp"
 
 #include <Cesium3DTilesSelection/Tile.h>
-#include <CesiumGltf/ImageAsset.h>
+#include <CesiumImage/ImageAsset.h>
 #include <CesiumGltf/Model.h>
 #include <CesiumUtility/JsonValue.h>
 
@@ -117,12 +117,12 @@ void ResourcePreparer::free(Cesium3DTilesSelection::Tile& /*tile*/,
 
 // ── Raster overlay pipeline ─────────────────────────────────────────────────
 
-void* ResourcePreparer::prepareRasterInLoadThread(CesiumGltf::ImageAsset& image,
+void* ResourcePreparer::prepareRasterInLoadThread(CesiumImage::ImageAsset& image,
                                                    const std::any&) {
   if (image.pixelData.empty() || image.width <= 0 || image.height <= 0) {
     return nullptr;
   }
-  if (image.compressedPixelFormat != CesiumGltf::GpuCompressedPixelFormat::NONE) {
+  if (image.compressedPixelFormat != CesiumImage::GpuCompressedPixelFormat::NONE) {
     return nullptr;
   }
   if (image.bytesPerChannel != 1) return nullptr;

package/cpp/engine/ResourcePreparer.hpp

@@ -64,7 +64,7 @@ public:
   void free(Cesium3DTilesSelection::Tile& tile, void* pLoadThreadResult,
             void* pMainThreadResult) noexcept override;
 
-  void* prepareRasterInLoadThread(CesiumGltf::ImageAsset& image,
+  void* prepareRasterInLoadThread(CesiumImage::ImageAsset& image,
                                   const std::any& rendererOptions) override;
   void* prepareRasterInMainThread(
       CesiumRasterOverlays::RasterOverlayTile& rasterTile,

package/cpp/engine/TerrainFloor.hpp

@@ -0,0 +1,70 @@
+#pragma once
+
+#include "CameraIntegrator.hpp"
+#include "CesiumEngine.hpp"
+#include "GeoidConverter.hpp"
+#include "TerrainHeight.hpp"
+
+#include <algorithm>
+
+namespace reactnativecesium {
+
+// Previous horizontal position and whether a real mesh sample has landed.
+// Shared by the iOS and Android render loops so both follow the same floor.
+struct TerrainLeadState {
+  bool hasPrev = false;
+  bool latched = false;
+  double prevLatDeg = 0.0;
+  double prevLonDeg = 0.0;
+};
+
+// A position slew drops the old floor and the one-frame lead. The next
+// rendered frame samples terrain at the new position.
+inline void noteTerrainSlew(CameraIntegrator& integrator, TerrainLeadState& lead) {
+  integrator.clearTerrainFloor();
+  lead = {};
+}
+
+// Samples the resident mesh at the stepped camera and one frame ahead, then
+// holds the rendered altitude to surface + clearance before the frame is drawn.
+// Demand is not modified. Returns the camera to render.
+inline CameraParams applyTerrainFloor(CesiumEngine& engine,
+                                      CameraIntegrator& integrator,
+                                      const CameraParams& stepped,
+                                      TerrainLeadState& lead,
+                                      double clearanceMeters) {
+  const double clearance = std::max(0.0, clearanceMeters);
+
+  double leadLat = stepped.latitude;
+  double leadLon = stepped.longitude;
+  const bool sampleLead = terrainLeadLatLon(
+      stepped.latitude, stepped.longitude,
+      lead.prevLatDeg, lead.prevLonDeg, lead.hasPrev,
+      leadLat, leadLon);
+
+  float nadir = 0.0f;
+  float ahead = 0.0f;
+  const bool hasNadir =
+      engine.sampleTerrainEllipsoidMeters(stepped.latitude, stepped.longitude, nadir);
+  const bool hasAhead = sampleLead &&
+      engine.sampleTerrainEllipsoidMeters(leadLat, leadLon, ahead);
+
+  float surface = 0.0f;
+  const bool haveMesh = resolveSurfaceEllipsoid(hasNadir, nadir, hasAhead, ahead, surface);
+  const double geoidN = mslToEllipsoidMeters(stepped.latitude, stepped.longitude, 0.0);
+  if (haveMesh) {
+    integrator.setTerrainFloor(static_cast<double>(surface) - geoidN + clearance);
+    lead.latched = true;
+  } else if (!lead.latched) {
+    // No mesh yet: stay at or above the ellipsoid. Once a mesh sample has
+    // landed, a later miss keeps the last floor instead of dropping to sea level.
+    integrator.setTerrainFloor(-geoidN + clearance);
+  }
+
+  lead.prevLatDeg = stepped.latitude;
+  lead.prevLonDeg = stepped.longitude;
+  lead.hasPrev = true;
+  return integrator.getActual();
+}
+
+} // namespace reactnativecesium

package/cpp/engine/TerrainHeight.hpp

@@ -0,0 +1,113 @@
+#pragma once
+
+#include <algorithm>
+#include <cmath>
+
+namespace reactnativecesium {
+
+// Pure terrain-floor helpers. No Cesium types, so the host harness can test
+// contour rules without a tileset.
+
+// Ignore a lead step shorter than this (hover) or longer than this (a slew,
+// not one frame of travel).
+inline constexpr double kTerrainLeadMinMeters = 0.05;
+inline constexpr double kTerrainLeadMaxMeters = 80.0;
+inline constexpr double kEarthRadiusMeters    = 6371008.7714150595;
+
+// Horizontal barycentric height. (pe, pn) and the triangle are in metres in
+// the same local east/north frame. Near-vertical triangles (terrain skirts)
+// have ~0 horizontal area and are rejected. On a hit, outHeight is the
+// interpolated ellipsoid height in metres.
+inline bool horizontalTriangleHeight(double pe, double pn,
+                                     double e0, double n0, float h0,
+                                     double e1, double n1, float h1,
+                                     double e2, double n2, float h2,
+                                     float& outHeight) {
+  const double v0e = e1 - e0;
+  const double v0n = n1 - n0;
+  const double v1e = e2 - e0;
+  const double v1n = n2 - n0;
+  const double v2e = pe - e0;
+  const double v2n = pn - n0;
+
+  const double dot00 = v0e * v0e + v0n * v0n;
+  const double dot01 = v0e * v1e + v0n * v1n;
+  const double dot11 = v1e * v1e + v1n * v1n;
+  const double dot02 = v0e * v2e + v0n * v2n;
+  const double dot12 = v1e * v2e + v1n * v2n;
+
+  // denom = (2 * signed horizontal area)^2.
+  const double denom = dot00 * dot11 - dot01 * dot01;
+  if (std::abs(denom) < 1.0e-12) return false;
+
+  const double e20 = e2 - e1;
+  const double n20 = n2 - n1;
+  const double edge2 = e20 * e20 + n20 * n20;
+  const double longest = std::sqrt(std::max(dot00, std::max(dot11, edge2)));
+  const double twiceArea = std::sqrt(std::abs(denom));
+  // Width of the triangle across its longest edge. Terrain skirts are
+  // vertical, so float error leaves them only millimetres wide.
+  if (longest < 1.0e-6 || twiceArea / longest < 0.05) return false;
+
+  const double inv = 1.0 / denom;
+  const double u = (dot11 * dot02 - dot01 * dot12) * inv;
+  const double v = (dot00 * dot12 - dot01 * dot02) * inv;
+  const double w = 1.0 - u - v;
+
+  constexpr double kEdge = -1.0e-4;
+  if (u < kEdge || v < kEdge || w < kEdge) return false;
+
+  outHeight = static_cast<float>(w * static_cast<double>(h0) +
+                                 u * static_cast<double>(h1) +
+                                 v * static_cast<double>(h2));
+  return true;
+}
+
+// Fresh each frame. The higher of the nadir sample and the one-frame lead.
+// A lower lead (past a crest) does not keep the previous peak. A higher lead
+// (valley turning uphill) raises the floor in this frame. No memory.
+inline bool resolveSurfaceEllipsoid(bool hasNadir, float nadir,
+                                    bool hasAhead, float ahead,
+                                    float& outHeight) {
+  if (hasNadir && hasAhead) {
+    outHeight = std::max(nadir, ahead);
+    return true;
+  }
+  if (hasNadir) {
+    outHeight = nadir;
+    return true;
+  }
+  if (hasAhead) {
+    outHeight = ahead;
+    return true;
+  }
+  return false;
+}
+
+// One frame ahead of (latDeg, lonDeg) along the last step. Returns false when
+// there is no distinct lead; out* are then equal to the current position.
+inline bool terrainLeadLatLon(double latDeg, double lonDeg,
+                              double prevLatDeg, double prevLonDeg,
+                              bool hasPrev,
+                              double& outLatDeg, double& outLonDeg) {
+  outLatDeg = latDeg;
+  outLonDeg = lonDeg;
+  if (!hasPrev) return false;
+
+  const double dLat = latDeg - prevLatDeg;
+  double dLon = lonDeg - prevLonDeg;
+  dLon = std::fmod(dLon + 540.0, 360.0) - 180.0;
+
+  const double latRad = latDeg * (3.14159265358979323846 / 180.0);
+  const double northM = dLat * (3.14159265358979323846 / 180.0) * kEarthRadiusMeters;
+  const double eastM =
+      dLon * (3.14159265358979323846 / 180.0) * kEarthRadiusMeters * std::cos(latRad);
+  const double dist = std::hypot(eastM, northM);
+  if (dist < kTerrainLeadMinMeters || dist > kTerrainLeadMaxMeters) return false;
+
+  outLatDeg = latDeg + dLat;
+  outLonDeg = lonDeg + dLon;
+  return true;
+}
+
+} // namespace reactnativecesium