react-native-cesium 1.0.6 → 1.2.0

package/README.md

@@ -242,8 +242,14 @@ export function GlobeScreen() {
         maximumScreenSpaceError={16}
         maximumSimultaneousTileLoads={8}
         loadingDescendantLimit={20}
-        msaaSampleCount={1}
+        msaaSampleCount={4}
         ionImageryAssetId={2}
+        // Optional perf / quality knobs (see "Optional performance / quality knobs" below).
+        // Omit to use the built-in defaults; values shown here are typical for a high-end phone.
+        maximumCachedMiB={384}
+        preloadAncestors
+        forbidHoles
+        enableLodTransitionPeriod
         onMetrics={callback((metrics: CesiumMetrics) => {
           console.log('Cesium FPS:', metrics.fps)
         })}
@@ -279,7 +285,7 @@ When you pass a callback ref to `CesiumView`, wrap it with `callback(...)` from
 | `maximumScreenSpaceError` | `number` | `32` | Quality/performance trade-off for tile refinement. Lower values are sharper (more work); higher values are faster/blurrier.                                                                                  |
 | `maximumSimultaneousTileLoads` | `number` | `12` | Max concurrent tile fetch/decode operations. Raising `8 -> 16` can improve fast camera moves on good networks but may increase memory/bandwidth spikes.                                                      |
 | `loadingDescendantLimit` | `number` | `20` | Caps descendant tile fan-out during traversal. Lower values like `10` smooth bursts on low-end devices; higher values like `40` can fill detail faster.                                                      |
-| `msaaSampleCount` | `number` | `1` | Anti-aliasing sample count. iOS uses `1`, `2`, or `4` (`>=4 -> 4`, `>=2 -> 2`, otherwise `1`); Android currently renders at `1` (MSAA setting is currently ignored in Vulkan backend). |
+| `msaaSampleCount` | `number` | `1` | Anti-aliasing sample count. Both backends support `1`, `2`, `4`, or `8`; the value is clamped to the largest sample count the physical device can frame-buffer (Metal: `device.supportsTextureSampleCount`, Vulkan: `framebufferColorSampleCounts & framebufferDepthSampleCounts`). On tiled mobile GPUs the multisample colour buffer is allocated `LAZILY_ALLOCATED` where supported, so MSAA's memory cost is largely on-chip. |
 | `ionImageryAssetId` | `number` | `1` | Imagery layer to drape over terrain/tiles. Use a satellite imagery asset for a photoreal look, or switch to a streets/map layer for legibility. See your Cesium Ion Asset IDs. |
 
 **Consumer-optional props (TypeScript)**
@@ -288,6 +294,35 @@ When you pass a callback ref to `CesiumView`, wrap it with `callback(...)` from
 | --- | --- | --- | --- |
 | `onMetrics` | `(metrics: CesiumMetrics) => void` | `undefined` | Receives throttled runtime stats and credits text. |
 
+**Optional performance / quality knobs**
+
+These props are all optional. Leave them unset to use the built-in defaults; set them to override per-screen for fine-grained control. They are runtime-mutable: changing them at any time after the view has mounted re-applies to the live tileset (no engine rebuild) except where noted.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `maximumCachedMiB` | `number` | `256` | RAM budget (mebibytes) for decoded geometry / textures held by the live tileset. Lower values (e.g. `128`) reduce peak memory on entry-level devices; higher values (`512+`) keep more tiles resident across long pans. |
+| `preloadAncestors` | `boolean` | `true` | Pre-load ancestor tiles around the visible set. Smoother panning at higher load pressure. |
+| `preloadSiblings` | `boolean` | `true` | Pre-load sibling tiles around the visible set. Same trade-off as `preloadAncestors`. |
+| `forbidHoles` | `boolean` | `true` | When `true`, Cesium keeps coarser ancestor tiles visible until all children load. Setting to `false` during fast pans reduces upload pressure at the cost of brief visible "holes". |
+| `enableWaterMask` | `boolean` | `true` | Decode the per-tile water-mask texture used for coastline shading and the ocean-vs-land hypsometric branch. Disable to save bandwidth on memory-constrained devices. |
+| `enableFogCulling` | `boolean` | `false` | When `true`, tiles fully inside the atmospheric fog volume are culled before refinement. |
+| `enforceCulledScreenSpaceError` | `boolean` | `true` | When `enableFogCulling` is `true`, allow fogged tiles to refine to a coarser SSE — saves work on tiles that will never be visually scrutinised. |
+| `culledScreenSpaceError` | `number` | `64` | The relaxed SSE applied to fogged tiles when `enforceCulledScreenSpaceError` is `true`. |
+| `enableLodTransitionPeriod` | `boolean` | `false` | Cross-fade between LODs as tiles refine instead of hard-popping. Smoother visually; very small per-frame cost. |
+| `lodTransitionLength` | `number` | `1.0` | Length in seconds of the LOD cross-fade when `enableLodTransitionPeriod` is `true`. |
+| `sqliteCacheMaxRows` | `number` | `4096` | Maximum number of cached HTTP responses Cesium keeps in `cesium_cache.db` between sessions. Tablets can comfortably go to `16384`. **Re-applied only on the next view init** — runtime changes take effect after the next mount. |
+| `taskProcessorThreads` | `number` | `0` (auto) | Worker pool size for tile parsing / texture decode. `0` (default) auto-sizes to `clamp(2, std::thread::hardware_concurrency() - 1, 8)`. Override for benchmarking or to throttle background CPU on shared-render apps. **Re-applied only on the next view init.** |
+
+#### Suggested presets
+
+The defaults are tuned for current-generation phones (e.g. iPhone 13/Pixel 6 and newer). Useful starting points for other classes of device:
+
+| Profile | `maximumScreenSpaceError` | `maximumSimultaneousTileLoads` | `maximumCachedMiB` | `forbidHoles` | `enableLodTransitionPeriod` |
+| --- | --- | --- | --- | --- | --- |
+| **High-end / tablet** | `16` | `16` | `512` | `true` | `true` |
+| **Default / phone** | `32` | `12` | `256` | `true` | `false` |
+| **Battery-saver / low-end** | `48` | `6` | `128` | `false` | `false` |
+
 ### `CameraState`
 
 ```ts
@@ -302,15 +337,15 @@ type CameraState = {
 }
 ```
 
-| Field | Type | Valid range / format | Description                                                                                           |
-| --- | --- | --- |-------------------------------------------------------------------------------------------------------|
-| `latitude` | `number` | `-90..90` | Camera latitude in degrees.                                                                           |
-| `longitude` | `number` | `-180..180` | Camera longitude in degrees.                                                                          |
-| `altitude` | `number` | Meters above ellipsoid | Camera height in meters.                                                                              |
-| `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.                           |
-| `verticalFovDeg` | `number` | `20..100` (clamped) | Vertical field of view in degrees; see **Field of view** (next section).                              |
+| Field | Type | Valid range / format         | Description                                                                                           |
+| --- | --- |------------------------------|-------------------------------------------------------------------------------------------------------|
+| `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.                                                                              |
+| `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.                           |
+| `verticalFovDeg` | `number` | `20..100` (clamped)          | Vertical field of view in degrees; see **Field of view** (next section).                              |
 
 ### Field of view: vertical vs horizontal, full vs half, and Cesium alignment
 
@@ -362,6 +397,22 @@ Avoid assuming **main-thread-only** vs **JS-thread-only** labels beyond the abov
 - You may **mix** the two: calling `setCamera` updates position and HPR but leaves the last view-correction target unchanged, so a calibration quaternion set earlier continues to apply until you change it with `setCameraQuaternion`.
 - Prefer **`setCameraQuaternion`** on frames where you need to drive both the globe camera and the correction together so the native target stays consistent.
 
+#### Smoothing of incoming camera updates
+
+Every value you pass to `setCamera` / `setCameraQuaternion` is treated as a **demand** target — what you would *like* the camera to be — rather than a per-frame command. The native render thread runs an exponential filter every frame that converges the displayed camera onto your demand target, which means a coarse 1 Hz position feed (e.g. external GPS) does **not** teleport the view once a second. Instead it eases between samples.
+
+| DoF | Smoothing |
+| --- | --- |
+| `latitude` / `longitude` | **Adaptive** exponential filter. Time constant `τ = clamp(α · ewmaInterval, τmin, τmax)` where `ewmaInterval` tracks the cadence of your `setCamera` calls. ~60 Hz gestures collapse `τ` to the floor (≤1 frame of trail, indistinguishable from the previous "snap" behaviour); ~1 Hz GPS feeds expand `τ` so each sample is ~95 % converged before the next arrives. Cross-planet jumps (Δ > ~0.5°) bypass the smoother and snap, so a deliberate teleport stays instant. Antimeridian crossings always rotate the short way. |
+| `altitude` | Exponential, fixed `τ ≈ 40 ms`. |
+| `heading` / `pitch` / `roll` | Exponential on the shortest-arc angular delta, fixed `τ ≈ 20–33 ms`. |
+| `viewCorrection` (quaternion) | SLERP-based exponential, fixed `τ ≈ 20 ms`, hemisphere-corrected so it always takes the short rotation. |
+| `verticalFovDeg` | Applied directly (not smoothed). |
+
+You don't have to do anything special to take advantage of this — the smoother already runs, it's the same code path whether your driver is a Reanimated worklet at 60 Hz, a `setInterval` push at 10 Hz, or a 1 Hz GPS subscription. Just call `setCamera` whenever you have a new value.
+
+If the smoothing ever feels off for your data source, the relevant constants live in [`cpp/engine/EngineTunables.hpp`](cpp/engine/EngineTunables.hpp) (`kSmoothPositionAlpha`, `kSmoothPositionTauMin`, `kSmoothPositionTauMax`, `kPosSnapThroughDeg`, `kEwmaIntervalAlpha`, plus the per-DoF `kSmooth*` rates).
+
 ### `CesiumMetrics`
 
 | Field | Type | Description                                                                                                                                 |
@@ -371,6 +422,7 @@ Avoid assuming **main-thread-only** vs **JS-thread-only** labels beyond the abov
 | `tilesLoading` | `number` | Number of tiles still loading. If this stays high for long periods, reduce load pressure (`maximumSimultaneousTileLoads`) or check network. |
 | `tilesVisited` | `number` | Number of tiles visited during traversal/culling.                                                                                           |
 | `ionTokenConfigured` | `boolean` | Whether a non-empty Ion token is configured natively. `false` is a quick signal to check `ionAccessToken`.                                  |
+| `tlsConfigured` | `boolean` | Whether libcurl resolved a CA bundle for HTTPS. `false` means TLS to `api.cesium.com` may fail; on iOS verify `cacert.pem` is in the main bundle, on Android that the asset is bundled (the package ships one for you). |
 | `tilesetReady` | `boolean` | Whether the primary tileset is initialized and ready.                                                                                       |
 | `creditsPlainText` | `string` | Plain-text attribution/credits from Cesium data sources. Display this in your app footer to satisfy attribution requirements.               |
 
@@ -393,6 +445,7 @@ The example project currently links this library locally via `link:..`.
 
 - Native rendering is built on [Cesium Native](https://github.com/CesiumGS/cesium-native)
 - Cesium Native is licensed under Apache 2.0; see [`NOTICE`](./NOTICE)
+- EGM96 altitude offset calculations using [EGM96](https://github.com/emericg/EGM96)
 - React Native integration is built with [Nitro Modules](https://github.com/mrousavy/nitro)
 
 

package/ReactNativeCesium.podspec

@@ -32,7 +32,7 @@ Pod::Spec.new do |s|
   s.source_files = [
     "ios/**/*.{swift}",
     "ios/**/*.{h,m,mm}",
-    "cpp/**/*.{hpp,cpp,h,mm}",
+    "cpp/**/*.{hpp,cpp,h,mm,c}",
   ]
 
   s.public_header_files = [

package/android/CMakeLists.txt

@@ -69,11 +69,13 @@ add_library(${PACKAGE_NAME} SHARED
         ../cpp/engine/ResourcePreparer.cpp
         ../cpp/engine/GltfToMesh.cpp
         ../cpp/engine/GlobeCamera.cpp
-        ../cpp/engine/DeletionQueue.cpp
+        ../cpp/engine/GeoidConverter.cpp
         ../cpp/engine/TileLifecycleManager.cpp
-        # Vulkan backend
+        ../cpp/engine/CameraSmoother.cpp
+        ../cpp/engine/CameraTargetState.cpp
+        ../cpp/engine/MetricsAggregator.cpp
+        ../cpp/third_party/egm96/EGM96.c
         src/main/cpp/vulkan/VulkanBackend.cpp
-        # JNI bridge
         src/main/cpp/CesiumBridgeAndroid.cpp
 )