react-native-cesium 1.0.1 → 1.0.4

package/README.md

@@ -18,13 +18,26 @@ Experimental Cesium rendering for React Native using [Nitro Modules](https://git
 ## Requirements
 
 - React Native **new architecture**
+- React Native Nitro Modules is a dependency
 - Follow the native build instructions below: additional setup is required by you.
 - A valid Cesium Ion access token and asset IDs for your content (get these from https://ion.cesium.com)
 - **Disk and time:** building Cesium Native pulls **vcpkg** dependencies, can use **several GB** of disk, and often takes a long time on first build.
 
 ## Installation
 
-Add the package to your app:
+First install the Nitro Modules runtime dependency:
+
+```bash
+yarn add react-native-nitro-modules
+```
+
+or:
+
+```bash
+npm install react-native-nitro-modules
+```
+
+Then add `react-native-cesium`:
 
 ```bash
 yarn add react-native-cesium
@@ -123,22 +136,54 @@ The **post-install** helper is currently needed to:
 - prepend this package's `cpp/` headers before the locally built XCFramework headers
 - exclude `x86_64` iOS simulator builds, because the simulator slice is Apple Silicon `arm64` only
 
+### Android (Gradle automatic ensure-native)
+
+Unlike iOS, you **do not** need to copy anything into your **application’s** `android/build.gradle` (or `settings.gradle`) so Cesium Native can be cloned and built automatically. React Native already includes this package as an Android library dependency; this repo’s **`android/build.gradle`** registers **`ensureCesiumNativeAndroid`** and makes **`preBuild`** depend on it.
+
+What happens on **`./gradlew`** / Android Studio build:
+
+1. **`preBuild`** runs **`ensureCesiumNativeAndroid`** before CMake compiles the JNI/native code.
+2. That task checks for a marker file under the installed package:  
+   `vendor/android/share/cesium-native/cmake/cesium-nativeConfig.cmake`.
+3. If the marker **exists**, the task does nothing.
+4. If the marker is **missing**, it runs (from the package root, e.g. `node_modules/react-native-cesium`):  
+   `node scripts/cesium/ensure-native.mjs --android`  
+   which may run **`update`** then a **`CESIUM_BUILD_ONLY=android`** **`build`**, same as a manual run (can take a long time).
+5. If **`REACT_NATIVE_CESIUM_SKIP_NATIVE_BUILD=1`** is set and artifacts are still missing, the build **fails fast** with an error instead of running the script.
+
+You still need a discoverable **Android NDK** (expand **Additional Android specific requirements** under [System dependencies](#system-dependencies) above) so that build can succeed.
+
 ### Building
 
 **Automatic (default):** assuming you have done the above and have all the required dependencies in place, when the native output is missing, the package tries to build it for you:
 
 - **iOS:** add **`pre_install`** in your app **`Podfile`** (one-time; see [Required Podfile hooks](#required-podfile-hooks-ios)) so **`pod install`** runs **`scripts/cesium/ensure-native.mjs --ios`**, which runs **`npm run update`** / **`yarn run update`** (if needed) and then **`CESIUM_BUILD_ONLY=ios`** build. The first run can take **a long time** and needs the same **system dependencies** as a manual build (CMake, Ninja, Xcode, disk space, etc.).
-- **Android:** the library’s Gradle **`preBuild`** runs **`ensure-native.mjs --android`** if **`vendor/android`** is incomplete, which runs **`CESIUM_BUILD_ONLY=android`** build. Requires **ANDROID_NDK_HOME** (or an NDK the build script can find).
+- **Android:** no extra hooks in your app; see [Android (Gradle automatic ensure-native)](#android-gradle-automatic-ensure-native). Needs a discoverable **NDK**.
+
+**Manual (optional):** run the **`update`** and **`build`** scripts defined in **`react-native-cesium`’s `package.json`**. They are **not** available as top-level commands in your app; you must run them **in the context of the installed package**.
+
+From your **application project root** (where your app’s `package.json` lives), after `yarn add` / `npm install`:
+
+**Yarn:**
+
+```bash
+yarn --cwd node_modules/react-native-cesium run update
+yarn --cwd node_modules/react-native-cesium run build
+```
 
-**Manual (optional):** from the package directory (e.g. `node_modules/react-native-cesium`):
+**npm:**
 
 ```bash
-yarn run update # fetches Cesium Native source locally from GitHub
-yarn run build # builds iOS and Android artifacts; can take a long time
+npm run update --prefix node_modules/react-native-cesium
+npm run build --prefix node_modules/react-native-cesium
 ```
 
-- `npm run update` / `yarn run update` checks out **Cesium Native `v0.59.0`** into `vendor/cesium-native` (created next to the package files; typically ignored in app repos).
-- `npm run build` / `yarn run build` runs `scripts/cesium/build.mjs` (**CMake**, **vcpkg** under `vendor/vcpkg` unless **`VCPKG_ROOT`** is set, **Ninja** on macOS) and writes **`vendor/ios/CesiumNative.xcframework`** and/or **`vendor/android`** depending on **`CESIUM_BUILD_ONLY`**.
+**Alternative:** `cd node_modules/react-native-cesium` and run `yarn run update` / `yarn run build` (or the equivalent `npm run …`).
+
+**Yarn/npm workspaces:** if `react-native-cesium` is a workspace package in your monorepo, use your tool’s workspace runner, e.g. `yarn workspace react-native-cesium run update` (exact syntax depends on your workspace layout).
+
+- `update` checks out **Cesium Native `v0.59.0`** into `vendor/cesium-native` under the package (next to its other files; typically ignored in app repos).
+- `build` runs `scripts/cesium/build.mjs` (**CMake**, **vcpkg** under `vendor/vcpkg` unless **`VCPKG_ROOT`** is set, **Ninja** on macOS) and writes **`vendor/ios/CesiumNative.xcframework`** and/or **`vendor/android`** depending on **`CESIUM_BUILD_ONLY`**.
 
 Then install pods (iOS):
 
@@ -152,6 +197,7 @@ The public JS surface is exported from `react-native-cesium`:
 
 - `CesiumView`
 - `CameraState`
+- `Quaternion`
 - `CesiumMetrics`
 - `CesiumViewProps`
 - `CesiumViewMethods`
@@ -256,22 +302,65 @@ 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. Example: `30` zooms in/narrows view; `90` gives wider peripheral view with more perspective distortion. |
+| 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 of view: vertical vs horizontal, full vs half, and Cesium alignment
+
+Use this when matching **Skia**, **custom HUDs**, or **CesiumJS** math to the same frustum as this view.
+
+| Concept | What this library uses |
+| --- | --- |
+| **API field** | `verticalFovDeg` is the **full** vertical aperture in **degrees** (top to bottom through the view axis), not a half-angle and not the horizontal FOV. |
+| **Horizontal FOV** | Not stored. With viewport width `w` and height `h` in pixels and `aspect = w / h`, the native tile `ViewState` uses **full** vertical FOV `vfov_rad = radians(verticalFovDeg)` and **full** horizontal FOV `hfov_rad = 2 * atan(tan(vfov_rad / 2) * aspect)`. |
+| **Half-angles** | The projection uses the usual symmetric perspective form: `tan(vfov_rad / 2)` (and the same pattern horizontally via aspect). Those are **half** of the full vertical/horizontal FOV, in radians—standard for `tan` of frustum slopes, not an alternate “FOV definition.” |
+| **Cesium Native `ViewState`** | `GlobeCamera` passes that `vfov_rad` and `hfov_rad` into `Cesium3DTilesSelection::ViewState` together with the viewport size—consistent with **full-angle** vertical/horizontal FOV in radians for culling. |
+| **CesiumJS `PerspectiveFrustum` / `Camera.frustum`** | **Comparable vertical angle:** In CesiumJS, `PerspectiveFrustum#fovy` is the **full vertical** FOV in **radians** (derived from `fov` and `aspectRatio`). This package’s `verticalFovDeg` is always **vertical** in **degrees**; use `vfov_rad = Cesium.Math.toRadians(verticalFovDeg)` (or equivalent) to compare to `fovy` when the **same aspect ratio** and symmetric frustum assumptions apply. This repo uses **Cesium Native**, not CesiumJS—tile culling uses `ViewState` with `vfov_rad` / `hfov_rad` as above, not the JS frustum object. |
+
+### `Quaternion`
+
+Used for **camera-space view correction** with `setCameraQuaternion` (see below). Components are `w, x, y, z` (Hamilton convention). Non-unit values are normalized on the native side.
+
+```ts
+type Quaternion = {
+  w: number
+  x: number
+  y: number
+  z: number
+}
+```
 
 ### `CesiumViewMethods`
 
 | Method | Signature | Description                                                                                                                                   |
 | --- | --- |-----------------------------------------------------------------------------------------------------------------------------------------------|
-| `setCamera` | `(camera: CameraState) => void` | Applies a new camera state at runtime. Example: animate route steps by calling `setCamera(...)` on each step. |
-| `getCameraState` | `() => Promise<CameraState>` | Returns the current native camera snapshot. |
+| `setCamera` | `(camera: CameraState) => void` | Applies a new camera state at runtime (position, heading, pitch, roll, vertical FOV). Does **not** change the stored view-correction quaternion; use `setCameraQuaternion` when you need to update that. |
+| `setCameraQuaternion` | `(camera: CameraState, viewCorrection: Quaternion) => void` | Same camera fields as `setCamera`, plus a rotation applied **in camera space after** heading/pitch/roll. Use this for screen-fixed adjustments (e.g. boresight calibration, aligning a synthetic horizon overlay) without expressing the offset as extra Euler angles. |
+| `getCameraState` | `() => Promise<CameraState>` | Returns the current native camera snapshot (lat/lon/alt, HPR, VFOV). This is the underlying globe attitude; it does **not** encode the view correction into HPR. |
+| `getViewCorrection` | `() => Promise<Quaternion>` | Returns the **smoothed** view-correction quaternion currently applied (identity `w=1,x=y=z=0` if you have never called `setCameraQuaternion`). |
+
+#### Threading: `setCamera` / `setCameraQuaternion` vs `getCameraState` / `getViewCorrection`
+
+| Call style | Supported / best practice |
+| --- | --- |
+| **`setCamera` / `setCameraQuaternion`** | **Synchronous** native updates. **Supported** from the **UI thread**, including **Reanimated worklets** and **`useAnimatedReaction`** when you call through a Nitro `hybridRef` (same pattern as driving camera demand from shared values). This is the intended path for high-frequency camera updates. |
+| **`getCameraState` / `getViewCorrection`** | **Async** (`Promise`). **Call from the JavaScript thread** (e.g. `useEffect`, handlers, throttled HUD state)—not from worklets—unless you have a clear, tested pattern for async in your runtime. |
+
+Avoid assuming **main-thread-only** vs **JS-thread-only** labels beyond the above: Nitro invokes the hybrid object on the thread that called the method; use sync setters on the UI/worklet path you already use for gestures, and reserve Promise-based getters for JS.
+
+#### `setCamera` vs `setCameraQuaternion`
+
+- Use **`setCamera`** alone when you only need the classic globe camera.
+- Use **`setCameraQuaternion`** when you need both the usual `CameraState` **and** a small rotation relative to the uncorrected camera (HUD alignment, horizon line offset in screen space, lens/display calibration, etc.).
+- 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.
 
 ### `CesiumMetrics`
 
@@ -290,7 +379,8 @@ type CameraState = {
 The example app in [`example/App.tsx`](./example/App.tsx) is the best current integration reference. It shows:
 
 - creating and storing a Nitro `hybridRef`
-- driving camera updates with `setCamera(...)`
+- driving camera updates with `setCamera(...)` from a Reanimated **`useAnimatedReaction`** (UI-thread / worklet path; see **Threading** under `CesiumViewMethods` above)
+- the `setCameraQuaternion` / `getViewCorrection` APIs for camera-space HUD alignment (the example does not demonstrate them yet; see **`CesiumViewMethods`** above)
 - listening to `onMetrics`
 - switching imagery layers
 - presenting Cesium attribution from `creditsPlainText`

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

@@ -6,6 +6,8 @@
 #include <android/native_window_jni.h>
 #include <android/log.h>
 
+#include <glm/gtc/quaternion.hpp>
+
 #include <cmath>
 #include <regex>
 #include <sstream>
@@ -19,9 +21,15 @@ static const double kSmoothAlt   = 25.0;
 static const double kSmoothHdg   = 30.0;
 static const double kSmoothRoll  = 50.0;
 static const double kSmoothPitch = 50.0;
+static const double kSmoothViewCorr = 50.0;
 static const double kEpsLatLon   = 1e-7;
 static const double kEpsAlt      = 0.1;
 static const double kEpsAngleDeg = 0.05;
+static const double kEpsQuatDot  = 1e-8;
+
+static double quatDotAbs(const glm::dquat& a, const glm::dquat& b) {
+  return std::abs(glm::dot(glm::normalize(a), glm::normalize(b)));
+}
 
 static double lerpAngleDeg(double a, double b, double t) {
   double diff = std::fmod(b - a + 540.0, 360.0) - 180.0;
@@ -89,6 +97,10 @@ void CesiumBridgeAndroid::buildEngine() {
   camTargetHeading_ = params.heading;
   camTargetPitch_   = params.pitch;
   camTargetRoll_    = params.roll;
+  camTargetViewQw_  = params.viewCorrection.w;
+  camTargetViewQx_  = params.viewCorrection.x;
+  camTargetViewQy_  = params.viewCorrection.y;
+  camTargetViewQz_  = params.viewCorrection.z;
 
   auto* backendPtr = vulkanBackend_.get();
   engine_->getResourcePreparer()->setGPUTextureCreator(
@@ -155,6 +167,32 @@ void CesiumBridgeAndroid::updateCamera(double lat, double lon, double alt,
   camTargetHeading_ = heading;
   camTargetPitch_   = pitch;
   camTargetRoll_    = roll;
+  // Does not change camTargetViewQ* (view correction target).
+  forceRenderNextFrame_ = true;
+}
+
+void CesiumBridgeAndroid::updateCameraQuaternion(double lat, double lon, double alt,
+                                                 double heading, double pitch, double roll,
+                                                 double qw, double qx, double qy, double qz) {
+  if (!initialized_) return;
+  camTargetLat_     = lat;
+  camTargetLon_     = lon;
+  camTargetAlt_     = alt;
+  camTargetHeading_ = heading;
+  camTargetPitch_   = pitch;
+  camTargetRoll_    = roll;
+  const double ql2 = qw * qw + qx * qx + qy * qy + qz * qz;
+  glm::dquat   q;
+  if (ql2 < 1e-20) {
+    q = glm::dquat(1.0, 0.0, 0.0, 0.0);
+  } else {
+    const double inv = 1.0 / std::sqrt(ql2);
+    q = glm::dquat(qw * inv, qx * inv, qy * inv, qz * inv);
+  }
+  camTargetViewQw_ = q.w;
+  camTargetViewQx_ = q.x;
+  camTargetViewQy_ = q.y;
+  camTargetViewQz_ = q.z;
   forceRenderNextFrame_ = true;
 }
 
@@ -204,13 +242,15 @@ bool CesiumBridgeAndroid::shouldRenderNextFrame() {
   if (!initialized_ || !engine_) return false;
 
   const auto cur = engine_->camera().getParams();
+  glm::dquat tgt(camTargetViewQw_, camTargetViewQx_, camTargetViewQy_, camTargetViewQz_);
   const bool cameraDirty =
       std::abs(camTargetLat_ - cur.latitude) > kEpsLatLon ||
       std::abs(camTargetLon_ - cur.longitude) > kEpsLatLon ||
       std::abs(camTargetAlt_ - cur.altitude) > kEpsAlt ||
       angleDeltaAbsDeg(cur.heading, camTargetHeading_) > kEpsAngleDeg ||
       angleDeltaAbsDeg(cur.pitch, camTargetPitch_) > kEpsAngleDeg ||
-      angleDeltaAbsDeg(cur.roll, camTargetRoll_) > kEpsAngleDeg;
+      angleDeltaAbsDeg(cur.roll, camTargetRoll_) > kEpsAngleDeg ||
+      (1.0 - quatDotAbs(cur.viewCorrection, tgt)) > kEpsQuatDot;
 
   return forceRenderNextFrame_ ||
          frameResult_->tilesLoading > 0 ||
@@ -231,12 +271,19 @@ void CesiumBridgeAndroid::renderFrame(double dt) {
   const double aHdg   = 1.0 - std::exp(-kSmoothHdg * dt);
   const double aPitch = 1.0 - std::exp(-kSmoothPitch * dt);
   const double aRoll  = 1.0 - std::exp(-kSmoothRoll * dt);
+  const double aViewQ = 1.0 - std::exp(-kSmoothViewCorr * dt);
 
   cur.altitude = cur.altitude + aAlt * (camTargetAlt_ - cur.altitude);
   cur.heading  = lerpAngleDeg(cur.heading, camTargetHeading_, aHdg);
   cur.pitch    = lerpAngleDeg(cur.pitch, camTargetPitch_, aPitch);
   cur.roll     = lerpAngleDeg(cur.roll, camTargetRoll_, aRoll);
 
+  glm::dquat cq = glm::normalize(cur.viewCorrection);
+  glm::dquat tq = glm::normalize(glm::dquat(camTargetViewQw_, camTargetViewQx_, camTargetViewQy_, camTargetViewQz_));
+  if (glm::dot(cq, tq) < 0.0)
+    tq = -tq;
+  cur.viewCorrection = glm::normalize(glm::slerp(cq, tq, aViewQ));
+
   if (std::abs(camTargetAlt_ - cur.altitude) <= kEpsAlt)
     cur.altitude = camTargetAlt_;
   if (angleDeltaAbsDeg(cur.heading, camTargetHeading_) <= kEpsAngleDeg)
@@ -245,6 +292,8 @@ void CesiumBridgeAndroid::renderFrame(double dt) {
     cur.pitch = camTargetPitch_;
   if (angleDeltaAbsDeg(cur.roll, camTargetRoll_) <= kEpsAngleDeg)
     cur.roll = camTargetRoll_;
+  if ((1.0 - quatDotAbs(cur.viewCorrection, tq)) <= kEpsQuatDot)
+    cur.viewCorrection = tq;
 
   engine_->camera().setParams(cur);
   engine_->updateFrame(viewportWidth_, viewportHeight_, *frameResult_);
@@ -313,6 +362,19 @@ double CesiumBridgeAndroid::readVerticalFovDeg() {
   return engine_ ? engine_->camera().getVerticalFovDegrees() : 60.0;
 }
 
+double CesiumBridgeAndroid::readViewCorrectionW() {
+  return engine_ ? engine_->camera().getParams().viewCorrection.w : 1.0;
+}
+double CesiumBridgeAndroid::readViewCorrectionX() {
+  return engine_ ? engine_->camera().getParams().viewCorrection.x : 0.0;
+}
+double CesiumBridgeAndroid::readViewCorrectionY() {
+  return engine_ ? engine_->camera().getParams().viewCorrection.y : 0.0;
+}
+double CesiumBridgeAndroid::readViewCorrectionZ() {
+  return engine_ ? engine_->camera().getParams().viewCorrection.z : 0.0;
+}
+
 // ── JNI native method implementations ──────────────────────────────────────────
 
 static CesiumBridgeAndroid* getBridge(jlong ptr) {
@@ -373,6 +435,14 @@ Java_com_margelo_nitro_reactnativecesium_CesiumBridgeJNI_nativeUpdateCamera(
   getBridge(ptr)->updateCamera(lat, lon, alt, heading, pitch, roll);
 }
 
+JNIEXPORT void JNICALL
+Java_com_margelo_nitro_reactnativecesium_CesiumBridgeJNI_nativeUpdateCameraQuaternion(
+    JNIEnv*, jobject, jlong ptr, jdouble lat, jdouble lon, jdouble alt,
+    jdouble heading, jdouble pitch, jdouble roll,
+    jdouble qw, jdouble qx, jdouble qy, jdouble qz) {
+  getBridge(ptr)->updateCameraQuaternion(lat, lon, alt, heading, pitch, roll, qw, qx, qy, qz);
+}
+
 JNIEXPORT void JNICALL
 Java_com_margelo_nitro_reactnativecesium_CesiumBridgeJNI_nativeSetVerticalFovDeg(
     JNIEnv*, jobject, jlong ptr, jdouble deg) {
@@ -449,6 +519,23 @@ Java_com_margelo_nitro_reactnativecesium_CesiumBridgeJNI_nativeGetVerticalFovDeg
   return getBridge(ptr)->readVerticalFovDeg();
 }
 
+JNIEXPORT jdouble JNICALL
+Java_com_margelo_nitro_reactnativecesium_CesiumBridgeJNI_nativeGetViewCorrectionW(JNIEnv*, jobject, jlong ptr) {
+  return getBridge(ptr)->readViewCorrectionW();
+}
+JNIEXPORT jdouble JNICALL
+Java_com_margelo_nitro_reactnativecesium_CesiumBridgeJNI_nativeGetViewCorrectionX(JNIEnv*, jobject, jlong ptr) {
+  return getBridge(ptr)->readViewCorrectionX();
+}
+JNIEXPORT jdouble JNICALL
+Java_com_margelo_nitro_reactnativecesium_CesiumBridgeJNI_nativeGetViewCorrectionY(JNIEnv*, jobject, jlong ptr) {
+  return getBridge(ptr)->readViewCorrectionY();
+}
+JNIEXPORT jdouble JNICALL
+Java_com_margelo_nitro_reactnativecesium_CesiumBridgeJNI_nativeGetViewCorrectionZ(JNIEnv*, jobject, jlong ptr) {
+  return getBridge(ptr)->readViewCorrectionZ();
+}
+
 JNIEXPORT jdouble JNICALL
 Java_com_margelo_nitro_reactnativecesium_CesiumBridgeJNI_nativeGetMetricsFps(JNIEnv*, jobject, jlong ptr) {
   return getBridge(ptr)->metricsFps();

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

@@ -22,6 +22,9 @@ struct CesiumBridgeAndroid {
   void updateImageryAssetId(int64_t assetId);
   void updateCamera(double lat, double lon, double alt,
                     double heading, double pitch, double roll);
+  void updateCameraQuaternion(double lat, double lon, double alt,
+                              double heading, double pitch, double roll,
+                              double qw, double qx, double qy, double qz);
   void setVerticalFovDeg(double degrees);
   void setMaximumScreenSpaceError(double v);
   void setMaximumSimultaneousTileLoads(int v);
@@ -40,6 +43,10 @@ struct CesiumBridgeAndroid {
   double readCameraPitch();
   double readCameraRoll();
   double readVerticalFovDeg();
+  double readViewCorrectionW();
+  double readViewCorrectionX();
+  double readViewCorrectionY();
+  double readViewCorrectionZ();
 
   // Metrics
   double metricsFps() const { return metricsFps_; }
@@ -52,7 +59,6 @@ struct CesiumBridgeAndroid {
 
 private:
   void buildEngine();
-  reactnativecesium::CameraParams makeCamTarget();
 
   std::unique_ptr<reactnativecesium::VulkanBackend> vulkanBackend_;
   std::unique_ptr<reactnativecesium::CesiumEngine>  engine_;
@@ -78,6 +84,10 @@ private:
   double camTargetHeading_ = 129.0;
   double camTargetPitch_   = -45.0;
   double camTargetRoll_    = 0.0;
+  double camTargetViewQw_  = 1.0;
+  double camTargetViewQx_  = 0.0;
+  double camTargetViewQy_  = 0.0;
+  double camTargetViewQz_  = 0.0;
   bool   forceRenderNextFrame_ = true;
 
   // Metrics

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

@@ -25,6 +25,19 @@ class CesiumBridgeJNI {
   fun updateImageryAssetId(assetId: Long) = nativeUpdateImageryAssetId(nativePtr, assetId)
   fun updateCamera(lat: Double, lon: Double, alt: Double, heading: Double, pitch: Double, roll: Double) =
     nativeUpdateCamera(nativePtr, lat, lon, alt, heading, pitch, roll)
+
+  fun updateCameraQuaternion(
+    lat: Double,
+    lon: Double,
+    alt: Double,
+    heading: Double,
+    pitch: Double,
+    roll: Double,
+    qw: Double,
+    qx: Double,
+    qy: Double,
+    qz: Double,
+  ) = nativeUpdateCameraQuaternion(nativePtr, lat, lon, alt, heading, pitch, roll, qw, qx, qy, qz)
   fun setVerticalFovDeg(deg: Double) = nativeSetVerticalFovDeg(nativePtr, deg)
   fun setMaxSSE(v: Double) = nativeSetMaxSSE(nativePtr, v)
   fun setMaxSimLoads(v: Int) = nativeSetMaxSimLoads(nativePtr, v)
@@ -43,6 +56,11 @@ class CesiumBridgeJNI {
   fun getCameraRoll(): Double = nativeGetCameraRoll(nativePtr)
   fun getVerticalFovDeg(): Double = nativeGetVerticalFovDeg(nativePtr)
 
+  fun getViewCorrectionW(): Double = nativeGetViewCorrectionW(nativePtr)
+  fun getViewCorrectionX(): Double = nativeGetViewCorrectionX(nativePtr)
+  fun getViewCorrectionY(): Double = nativeGetViewCorrectionY(nativePtr)
+  fun getViewCorrectionZ(): Double = nativeGetViewCorrectionZ(nativePtr)
+
   fun getMetricsFps(): Double = nativeGetMetricsFps(nativePtr)
   fun getMetricsTilesRendered(): Int = nativeGetMetricsTilesRendered(nativePtr)
   fun getMetricsTilesLoading(): Int = nativeGetMetricsTilesLoading(nativePtr)
@@ -59,6 +77,19 @@ class CesiumBridgeJNI {
   private external fun nativeUpdateIonAccessToken(ptr: Long, token: String, assetId: Long)
   private external fun nativeUpdateImageryAssetId(ptr: Long, assetId: Long)
   private external fun nativeUpdateCamera(ptr: Long, lat: Double, lon: Double, alt: Double, heading: Double, pitch: Double, roll: Double)
+  private external fun nativeUpdateCameraQuaternion(
+    ptr: Long,
+    lat: Double,
+    lon: Double,
+    alt: Double,
+    heading: Double,
+    pitch: Double,
+    roll: Double,
+    qw: Double,
+    qx: Double,
+    qy: Double,
+    qz: Double,
+  )
   private external fun nativeSetVerticalFovDeg(ptr: Long, deg: Double)
   private external fun nativeSetMaxSSE(ptr: Long, v: Double)
   private external fun nativeSetMaxSimLoads(ptr: Long, v: Int)
@@ -74,6 +105,10 @@ class CesiumBridgeJNI {
   private external fun nativeGetCameraPitch(ptr: Long): Double
   private external fun nativeGetCameraRoll(ptr: Long): Double
   private external fun nativeGetVerticalFovDeg(ptr: Long): Double
+  private external fun nativeGetViewCorrectionW(ptr: Long): Double
+  private external fun nativeGetViewCorrectionX(ptr: Long): Double
+  private external fun nativeGetViewCorrectionY(ptr: Long): Double
+  private external fun nativeGetViewCorrectionZ(ptr: Long): Double
   private external fun nativeGetMetricsFps(ptr: Long): Double
   private external fun nativeGetMetricsTilesRendered(ptr: Long): Int
   private external fun nativeGetMetricsTilesLoading(ptr: Long): Int

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

@@ -17,6 +17,7 @@ class HybridCesiumView(private val appContext: Context) : HybridCesiumViewSpec()
   private var usingLowRefreshRate = false
   private var lastFrameTimeNanos = 0L
   private var lastPushedCamera: CameraState? = null
+  private var lastPushedViewCorrection: Quaternion? = null
   private var renderLoopActive = false
 
   override var ionAccessToken: String = ""
@@ -174,6 +175,24 @@ class HybridCesiumView(private val appContext: Context) : HybridCesiumViewSpec()
     pushCameraIfChanged(camera)
   }
 
+  override fun setCameraQuaternion(camera: CameraState, viewCorrection: Quaternion) {
+    initialCamera = camera
+    pushCameraQuaternionIfChanged(camera, viewCorrection)
+  }
+
+  override fun getViewCorrection(): Promise<Quaternion> {
+    val b = bridge
+      ?: return Promise.resolved(Quaternion(w = 1.0, x = 0.0, y = 0.0, z = 0.0))
+    return Promise.resolved(
+      Quaternion(
+        w = b.getViewCorrectionW(),
+        x = b.getViewCorrectionX(),
+        y = b.getViewCorrectionY(),
+        z = b.getViewCorrectionZ(),
+      ),
+    )
+  }
+
   private fun pushCameraIfChanged(camera: CameraState) {
     val b = bridge ?: return
     val last = lastPushedCamera
@@ -193,6 +212,42 @@ class HybridCesiumView(private val appContext: Context) : HybridCesiumViewSpec()
     b.setVerticalFovDeg(camera.verticalFovDeg)
   }
 
+  private fun pushCameraQuaternionIfChanged(camera: CameraState, viewCorrection: Quaternion) {
+    val b = bridge ?: return
+    val last = lastPushedCamera
+    val lastQ = lastPushedViewCorrection
+    if (last != null && lastQ != null &&
+      last.latitude == camera.latitude &&
+      last.longitude == camera.longitude &&
+      last.altitude == camera.altitude &&
+      last.heading == camera.heading &&
+      last.pitch == camera.pitch &&
+      last.roll == camera.roll &&
+      last.verticalFovDeg == camera.verticalFovDeg &&
+      lastQ.w == viewCorrection.w &&
+      lastQ.x == viewCorrection.x &&
+      lastQ.y == viewCorrection.y &&
+      lastQ.z == viewCorrection.z
+    ) {
+      return
+    }
+    lastPushedCamera = camera
+    lastPushedViewCorrection = viewCorrection
+    b.updateCameraQuaternion(
+      camera.latitude,
+      camera.longitude,
+      camera.altitude,
+      camera.heading,
+      camera.pitch,
+      camera.roll,
+      viewCorrection.w,
+      viewCorrection.x,
+      viewCorrection.y,
+      viewCorrection.z,
+    )
+    b.setVerticalFovDeg(camera.verticalFovDeg)
+  }
+
   private fun syncPropsTobridge() {
     bridge?.setMaxSSE(maximumScreenSpaceError)
     bridge?.setMaxSimLoads(maximumSimultaneousTileLoads.toInt())

package/cpp/engine/GlobeCamera.cpp

@@ -3,6 +3,7 @@
 #include <CesiumGeospatial/GlobeTransforms.h>
 
 #include <glm/gtc/matrix_transform.hpp>
+#include <glm/gtc/quaternion.hpp>
 
 #include <algorithm>
 #include <cmath>
@@ -75,6 +76,27 @@ void GlobeCamera::recompute() const {
     right = glm::normalize(rolledRight);
   }
 
+  // 4. Optional camera-space correction (columns: right, camUp, forward).
+  const glm::dquat& qIn = params_.viewCorrection;
+  const double         ql2 =
+      qIn.w * qIn.w + qIn.x * qIn.x + qIn.y * qIn.y + qIn.z * qIn.z;
+  glm::dquat qCorr;
+  if (ql2 < 1e-20) {
+    qCorr = glm::dquat(1.0, 0.0, 0.0, 0.0);
+  } else {
+    const double inv = 1.0 / std::sqrt(ql2);
+    qCorr = glm::dquat(qIn.w * inv, qIn.x * inv, qIn.y * inv, qIn.z * inv);
+  }
+  glm::dmat3 R_basis(right, camUp, fwd);
+  glm::dmat3 R_corr  = glm::mat3_cast(qCorr);
+  glm::dmat3 R_final = R_basis * R_corr;
+  glm::dvec3 r0      = glm::normalize(glm::dvec3(R_final[0]));
+  glm::dvec3 r2      = glm::normalize(glm::dvec3(R_final[2]));
+  // Gram–Schmidt: preserve forward (column 2), rebuild right/up (matches right × fwd = camUp).
+  fwd   = r2;
+  right = glm::normalize(r0 - glm::dot(r0, fwd) * fwd);
+  camUp = glm::normalize(glm::cross(right, fwd));
+
   direction_ = fwd;
   up_        = camUp;
 }

package/cpp/engine/GlobeCamera.hpp

@@ -5,6 +5,7 @@
 #include <Cesium3DTilesSelection/ViewState.h>
 
 #include <glm/glm.hpp>
+#include <glm/gtc/quaternion.hpp>
 #include <mutex>
 
 namespace reactnativecesium {
@@ -16,6 +17,8 @@ struct CameraParams {
   double heading   = 220.0;
   double pitch     = -10.0;
   double roll      = 0.0;
+  /// Camera-space rotation applied after HPR (unit quaternion; w,x,y,z).
+  glm::dquat viewCorrection{1.0, 0.0, 0.0, 0.0};
 };
 
 class GlobeCamera {

package/ios/CesiumBridge.h

@@ -18,6 +18,17 @@ NS_ASSUME_NONNULL_BEGIN
                      heading:(double)heading
                        pitch:(double)pitch
                         roll:(double)roll;
+/// Same as `updateCameraLatitude:...` plus camera-space view correction (w,x,y,z). Does not replace HPR; applied after HPR in the engine.
+- (void)updateCameraQuaternionLatitude:(double)lat
+                             longitude:(double)lon
+                              altitude:(double)alt
+                               heading:(double)heading
+                                 pitch:(double)pitch
+                                  roll:(double)roll
+                       viewCorrectionW:(double)qw
+                                     x:(double)qx
+                                     y:(double)qy
+                                     z:(double)qz;
 - (void)resize:(int)width height:(int)height;
 - (BOOL)shouldRenderNextFrame;
 - (void)markNeedsRender;
@@ -49,6 +60,10 @@ NS_ASSUME_NONNULL_BEGIN
 - (double)readCameraPitch;
 - (double)readCameraRoll;
 - (double)readVerticalFovDeg;
+- (double)readViewCorrectionW;
+- (double)readViewCorrectionX;
+- (double)readViewCorrectionY;
+- (double)readViewCorrectionZ;
 
 @end