react-native-cumquat

A stateful C++ spatial projection engine for React Native AR applications.

Cumquat is a New Architecture TurboModule. Android and iOS compile the same C++20 implementation; JavaScript receives a typed engine wrapper rather than raw JSI handles.

Status

This package is pre-release software. The engine was extracted from the AR Atlas Otoka application, where the same C++ core is compiled on Android and iOS.

• React Native New Architecture only
• Shared C++20 engine
• Android and iOS
• Stateful POI dataset and view state
• Quaternion or heading/pitch/roll orientation
• Screen projection, clipping, edge-direction coordinates and picking

Install

npm install react-native-cumquat

Rebuild the native application after installation. Expo Go cannot load custom native modules; Expo projects need a development build.

API

import {
  CumquatEngine,
  getCumquatNativeVersion,
} from 'react-native-cumquat';
import type {
  POIInput,
  SensorState,
  ViewState,
} from 'react-native-cumquat';

Create and initialize

const engine = CumquatEngine.create({
  datasetRadiusMeters: 135_000,
  maxVisiblePOIs: 256,
});

const pois: POIInput[] = [
  {
    id: 'sljeme',
    name: 'Sljeme',
    latitude: 45.899462653,
    longitude: 15.944820919,
    altitude: 1033,
  },
];

engine.initialize(pois);

Set mutable view state

const viewState: ViewState = {
  horizontalFovDegrees: 90,
  minDistanceMeters: 0,
  maxDistanceMeters: 13_500,
};

engine.setViewState(viewState);

Update from sensors

const sensorState: SensorState = {
  timestampNs: Date.now() * 1_000_000,
  location: {
    latitude: 45.80041,
    longitude: 15.95619,
    altitude: 120,
  },
  orientationQuaternion: { x: 0, y: 0, z: 0, w: 1 },
  initialHeadingDegrees: 0,
  headingDegrees: 0,
  pitchDegrees: 0,
  rollDegrees: 0,
  viewportWidth: 1000,
  viewportHeight: 600,
};

engine.update(sensorState);
const frame = engine.getFrame();

frame.orientation exposes the exact normalized quaternion used for the frame, together with its coordinate convention. It is null while Cumquat is waiting for the synchronized heading/quaternion reference.

if (frame.orientation?.convention === 'earth-from-device') {
  // frame.orientation.quaternion rotates device axes into geographic ENU.
}

initialHeadingDegrees must be supplied with the first usable orientation quaternion. Cumquat consumes that synchronized pair once to establish geographic north. It then derives every projection update from a continuous non-magnetic orientation source; later headingDegrees changes cannot rotate or realign the scene. Reinitializing the engine clears this reference and requires a new pair.

On Android the motion source is TYPE_GAME_ROTATION_VECTOR. Cumquat does not subscribe to Android's magnetically corrected TYPE_ROTATION_VECTOR, so a disturbed field cannot silently establish a different startup reference. The application decides when its one-time heading is acceptable and supplies it as initialHeadingDegrees; every later update is driven only by the game vector.

frame.projectedPOIs contains active-radius POIs in stable dataset order, including offscreen and distance-clipped entries. frame.visiblePOIs contains the visible depth-sorted subset used for picking.

Pick and dispose

const result = engine.pick(screenX, screenY, 32);
engine.dispose();

The engine must be disposed when its owning screen or service is destroyed.

Native architecture

src/NativeCumquat.ts
        |
        | React Native Codegen
        v
cpp/bridge/NativeCumquatModule.cpp
        |
        v
cpp/core/Engine.cpp
        +-- cpp/geo/Geodesy.cpp
        +-- cpp/projection/Projection.cpp

The package uses the standard pure-C++ library registration generated by create-react-native-library:

• CumquatSpec is the Codegen library name.
• Cumquat is the JavaScript TurboModule name.
• CumquatImpl is the C++ autolinking entry point.
• NativeCumquatModule owns native engine handles and delegates to the shared core.

Development

yarn
yarn typecheck
yarn lint
yarn test
yarn prepare
npm pack --dry-run

yarn prepare regenerates the Codegen artifacts in android/generated and ios/generated. Run it after changing src/NativeCumquat.ts and before publishing.

Native rebuild boundary

Changes to C++, the Codegen spec, generated code, the podspec, Android CMake, or native dependencies require rebuilding and reinstalling the consuming application. JavaScript-only changes may be delivered separately only when they remain compatible with the installed native binary.

License

MIT