@navaramap/three-api 0.0.7 → 0.1.0

package/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2026 MapLibre contributors
+Copyright (c) 2026 Navara contributors
 
 This project is dual-licensed under either of
 

package/README.md

@@ -1,3 +1,32 @@
 # @navaramap/three-api
 
-This is a api module for Navara for Web platform.
+Standalone geodetic and GIS math for Three.js, powered by Navara's WASM core. It covers geodetic ⇔ ECEF conversion, WGS84 ellipsoid constants and surface normals, local tangent frames (ENU/NED/NUE/NWU/WUN and heading/pitch/roll placement), screen ⇔ world projection and pick rays, ray/plane intersection, ellipsoid geodesics, and RTE (relative-to-eye) encoding for jitter-free rendering far from the origin. Everything is integrated with the Three.js type system (`Vector3`, `Matrix4`, cameras).
+
+Unlike the rest of the Navara stack, this package is usable without the map engine: it is the standalone form of Navara's API tier, for pure geometry computation in any Three.js app.
+
+## Usage
+
+Initialize the WASM module once before calling anything else (when using `@navaramap/three`, `view.init()` does this for you):
+
+```typescript
+import { initNavaraApi, geodeticToVector3 } from "@navaramap/three-api";
+
+await initNavaraApi();
+
+// Geodetic coordinates (degrees, meters) to ECEF Cartesian.
+const position = geodeticToVector3({
+  lng: 139.77,
+  lat: 35.68,
+  height: 0,
+});
+```
+
+All of these utilities are also re-exported by `@navaramap/three`, so applications using the map engine don't need a direct dependency on this package.
+
+## Documentation
+
+Every function is documented at https://navara-docs.reearth.workers.dev/.
+
+## License
+
+MIT OR Apache-2.0

package/dist/ellipsoidGeodesic.d.ts

@@ -3,11 +3,13 @@ import { LatLngHeight } from '@navaramap/core';
  * Wrapper class for geodesic calculations on an ellipsoid surface.
  * Precomputes common variables for optimization when instantiated.
  *
+ * All latitudes/longitudes and headings are in **degrees**.
+ *
  * @example
  * ```typescript
  * const geodesic = new EllipsoidGeodesic(
- *   { lat: 0.5, lng: 2.0, height: 0 },
- *   { lat: 0.6, lng: 2.1, height: 0 }
+ *   { lat: 35.6812, lng: 139.7671, height: 0 },
+ *   { lat: 34.7025, lng: 135.4959, height: 0 }
  * );
  *
  * console.log(geodesic.distance);
@@ -21,8 +23,8 @@ export declare class EllipsoidGeodesic {
     private _raw;
     /**
      * Create a new geodesic between two points on the ellipsoid.
-     * @param start - Start point in geodetic coordinates (lat/lng in radians)
-     * @param end - End point in geodetic coordinates (lat/lng in radians)
+     * @param start - Start point in geodetic coordinates (lat/lng in degrees)
+     * @param end - End point in geodetic coordinates (lat/lng in degrees)
      */
     constructor(start: LatLngHeight, end: LatLngHeight);
     /** Distance in meters between start and end points */
@@ -34,24 +36,24 @@ export declare class EllipsoidGeodesic {
      * unreliable solution.
      */
     get converged(): boolean;
-    /** Heading at the start point in radians */
+    /** Heading at the start point in degrees */
     get startHeading(): number;
-    /** Heading at the end point in radians */
+    /** Heading at the end point in degrees */
     get endHeading(): number;
-    /** Start point in geodetic coordinates */
+    /** Start point in geodetic coordinates (lat/lng in degrees) */
     get start(): LatLngHeight;
-    /** End point in geodetic coordinates */
+    /** End point in geodetic coordinates (lat/lng in degrees) */
     get end(): LatLngHeight;
     /**
      * Interpolate points along the geodesic path.
      * @param granularity - Distance between interpolated points in meters (optional)
-     * @returns Array of interpolated points in geodetic coordinates
+     * @returns Array of interpolated points in geodetic coordinates (lat/lng in degrees)
      */
     interpolatePoints(granularity?: number): LatLngHeight[];
     /**
      * Interpolate a point at a specific distance along the geodesic path.
      * @param distance - Distance from start point in meters
-     * @returns Interpolated point in geodetic coordinates
+     * @returns Interpolated point in geodetic coordinates (lat/lng in degrees)
      */
     interpolateDistance(distance: number): LatLngHeight;
     /**

package/dist/frames.d.ts

@@ -0,0 +1,69 @@
+import { XYZ } from '@navaramap/core';
+import { Matrix4 } from 'three';
+/**
+ * High-level geographic placement of a mesh object.
+ *
+ * All angles are in **degrees** and `height` is in metres, matching
+ * `ThreeView.setCamera`. The asset is oriented in a West-Up-North tangent
+ * frame, which matches glTF's own convention (front `+Z`, up `+Y`,
+ * right `-X`) on all three axes — so an unmodified glTF asset needs no
+ * up-axis correction.
+ */
+export type GeodeticPlacement = {
+    /** Longitude in degrees. */
+    lng: number;
+    /** Latitude in degrees. */
+    lat: number;
+    /**
+     * Metres above the ellipsoid, or above terrain when `heightReference` is
+     * `"terrain"`. Defaults to 0.
+     */
+    height?: number;
+    /**
+     * Degrees clockwise from north that the asset's front (glTF `+Z`) faces.
+     * Same convention as `setCamera`'s heading. Defaults to 0.
+     */
+    heading?: number;
+    /** Degrees, nose up positive. Defaults to 0. */
+    pitch?: number;
+    /** Degrees, right wing down positive. Defaults to 0. */
+    roll?: number;
+    /** Uniform or per-axis scale of the frame. Defaults to 1. */
+    scale?: number | XYZ;
+    /** How `height` is interpreted. Defaults to `"ellipsoid"`. */
+    heightReference?: "ellipsoid" | "terrain";
+};
+/**
+ * Basis change from the NUE frame `(north, up, east)` to the WUN frame
+ * `(west, up, north)`.
+ *
+ * With `Ry(+90°)` columns `(0,0,-1), (0,1,0), (1,0,0)`, the product
+ * `NUE · Ry(+90°)` has columns `(-east, up, north)`, which is WUN. WUN is the
+ * unique right-handed, Y-up tangent frame whose `+Z` is north, which is why it
+ * agrees with glTF on every axis.
+ *
+ * Returns a fresh matrix on every call, so callers cannot corrupt a shared
+ * instance.
+ *
+ * @returns A new `Matrix4` performing the NUE-to-WUN basis change.
+ */
+export declare function nueToWunBasis(): Matrix4;
+/**
+ * Composes a tangent frame with heading, pitch, roll and scale.
+ *
+ * Pure: takes the frame as a parameter and uses three.js `MathUtils.degToRad`,
+ * so it touches no WASM and is directly unit-testable.
+ *
+ * `Ry(-heading) · Rx(-pitch) · Rz(+roll)` is exactly three.js Euler order
+ * `"YXZ"`, the standard intrinsic yaw -> pitch -> roll order. Signs follow from
+ * the glTF axes in a WUN frame: positive heading swings `+Z` toward `-X`
+ * (east), positive pitch lifts `+Z` toward `+Y`, and positive roll about `+Z`
+ * drives the `-X` wing toward `-Y`.
+ *
+ * @param frame - Tangent frame to compose onto, normally from
+ *   `westUpNorthToFixedFrame`
+ * @param p - Heading, pitch, roll (degrees) and scale; each defaults to
+ *   no-op
+ * @returns `frame · R(heading, pitch, roll) · S(scale)`
+ */
+export declare function composeHeadingPitchRoll(frame: Matrix4, p: Pick<GeodeticPlacement, "heading" | "pitch" | "roll" | "scale">): Matrix4;

package/dist/frames.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -1,7 +1,9 @@
 import { LatLngHeight, Window as WindowObject } from '@navaramap/core';
 import { Vector3, Vector2, Matrix4, PerspectiveCamera } from 'three';
+import { GeodeticPlacement } from './frames';
 export type { LatLngHeight, LatLng } from '@navaramap/core';
 export type { Window, Transform, CameraFrustum, Plane, Ray, Vec2, Vec3, } from '@navaramap/core';
+export type { GeodeticPlacement } from './frames';
 export * from './intersection';
 export * from './rte';
 export * from './ellipsoidGeodesic';
@@ -11,14 +13,14 @@ export * from './ellipsoidGeodesic';
 export declare function initNavaraApi(): Promise<void>;
 /**
  * Converts geodetic coordinates (longitude, latitude, height) to a Cartesian Vector3 in ECEF coordinates.
- * @param lle - Geodetic coordinates (lng in radians, lat in radians, height in meters)
+ * @param lle - Geodetic coordinates (lng in degrees, lat in degrees, height in meters)
  * @returns Cartesian Vector3 in Earth-Centered Earth-Fixed (ECEF) coordinates
  */
 export declare function geodeticToVector3(lle: LatLngHeight): Vector3;
 /**
  * Converts a Cartesian Vector3 in ECEF coordinates to geodetic coordinates.
  * @param xyz - Cartesian Vector3 in Earth-Centered Earth-Fixed (ECEF) coordinates
- * @returns Geodetic coordinates (lng in radians, lat in radians, height in meters)
+ * @returns Geodetic coordinates (lng in degrees, lat in degrees, height in meters)
  */
 export declare function vector3ToGeodetic(xyz: Vector3): LatLngHeight;
 /**
@@ -43,7 +45,7 @@ export declare function radianToDegree(radian: number): number;
 export declare function convertScreenToWorld(windowObject: WindowObject, camera: PerspectiveCamera, vec2: Vector2): Vector3 | undefined;
 /**
  * Computes the surface normal vector at a geodetic position on the WGS84 ellipsoid.
- * @param lle - Geodetic coordinates (lng in radians, lat in radians, height in meters)
+ * @param lle - Geodetic coordinates (lng in degrees, lat in degrees, height in meters)
  * @returns Unit normal vector pointing outward from the ellipsoid surface
  */
 export declare function geodeticSurfaceNormal(lle: LatLngHeight): Vector3;
@@ -71,6 +73,40 @@ export declare function northUpEastToFixedFrame(origin: Vector3): Matrix4;
  * @returns 4x4 transformation matrix from NWU to ECEF
  */
 export declare function northWestUpToFixedFrame(origin: Vector3): Matrix4;
+/**
+ * Creates a local West-Up-North (WUN) reference frame transformation matrix at
+ * a position.
+ *
+ * WUN is the only right-handed, Y-up tangent frame whose `+Z` axis is north, so
+ * it agrees with glTF's own convention (front `+Z`, up `+Y`, right `-X`) on all
+ * three axes. An unmodified glTF asset placed in this frame needs **no**
+ * `Rx(+90°)` up-axis correction — the correction is absorbed here, once, as the
+ * `Ry(+90°)` basis change from NUE.
+ *
+ * @param origin - Origin position in ECEF coordinates
+ * @returns 4x4 transformation matrix from WUN to ECEF
+ */
+export declare function westUpNorthToFixedFrame(origin: Vector3): Matrix4;
+/**
+ * Builds a WUN tangent frame at a geodetic position and composes heading,
+ * pitch, roll and scale onto it — the single call that turns a geographic
+ * placement into a world matrix.
+ *
+ * `heading` is the compass bearing the asset's front faces, where the front is
+ * glTF's own `+Z` — the same convention as `ThreeView.setCamera`. Other globe
+ * engines differ in which axis they treat as an asset's front, so a model
+ * ported from one may need a multiple of 90° added to its heading.
+ *
+ * `lng`/`lat` and all angles here are in **degrees**, matching
+ * `setCamera` and the `geodetic` mesh Descriptor field.
+ *
+ * `heightReference` is intentionally not accepted: resolving terrain-relative
+ * height needs a view to sample from, so it is the Descriptor's job.
+ *
+ * @param placement - Geographic placement in degrees and metres
+ * @returns 4x4 transformation matrix from the placed local frame to ECEF
+ */
+export declare function headingPitchRollToFixedFrame(placement: Omit<GeodeticPlacement, "heightReference">): Matrix4;
 /**
  * Converts world coordinates to screen coordinates.
  * @param window - Window configuration with width, height, and pixelRatio

package/dist/index.js

@@ -1,42 +1,56 @@
-import e, { CameraFrustum as t, EllipsoidGeodesic as n, LLE as r, Ray as i, Transform as a, Vec2 as o, Vec3 as s, Window as c, angleToDegree as l, angleToRadian as u, eastNorthUpToFixedFrame as ee, encodePosition as d, geodeticSurfaceNormal as f, geodeticToXyz as p, getHeightFromEllipsoid as m, getPickRay as h, getPlaneFromPointNormal as g, getRayPlaneIntersection as _, getWGS84Eccentricity as v, getWGS84EccentricitySquared as y, getWGS84Flattening as b, getWGS84SemiMajorAxis as x, getWGS84SemiMinorAxis as S, northEastDownToFixedFrame as C, northUpEastToFixedFrame as w, northWestUpToFixedFrame as T, screenToWorld as E, worldToScreen as D, xyzToGeodetic as O } from "@navaramap/engine-api";
-import { Matrix4 as k, Plane as A, Ray as j, Vector2 as M, Vector3 as N } from "three";
+import e, { CameraFrustum as t, EllipsoidGeodesic as n, LLE as r, Ray as i, Transform as a, Vec2 as o, Vec3 as s, Window as c, angleToDegree as l, angleToRadian as u, eastNorthUpToFixedFrame as d, encodePosition as f, geodeticSurfaceNormal as p, geodeticToXyz as m, getHeightFromEllipsoid as h, getPickRay as g, getPlaneFromPointNormal as _, getRayPlaneIntersection as v, getWGS84Eccentricity as y, getWGS84EccentricitySquared as b, getWGS84Flattening as x, getWGS84SemiMajorAxis as S, getWGS84SemiMinorAxis as C, northEastDownToFixedFrame as ee, northUpEastToFixedFrame as te, northWestUpToFixedFrame as w, screenToWorld as T, worldToScreen as E, xyzToGeodetic as D } from "@navaramap/engine-api";
+import { Euler as O, MathUtils as k, Matrix4 as A, Plane as j, Ray as M, Vector2 as N, Vector3 as P } from "three";
+//#region src/frames.ts
+function F() {
+	return new A().makeRotationY(Math.PI / 2);
+}
+function I(e, t) {
+	let n = new A().multiplyMatrices(e, new A().makeRotationFromEuler(new O(-k.degToRad(t.pitch ?? 0), -k.degToRad(t.heading ?? 0), k.degToRad(t.roll ?? 0), "YXZ")));
+	if (t.scale !== void 0) {
+		let e = t.scale;
+		n.scale(typeof e == "number" ? new P(e, e, e) : new P(e.x, e.y, e.z));
+	}
+	return n;
+}
+//#endregion
 //#region src/intersection.ts
-function P(e, t) {
-	let n = g(new s(e.x, e.y, e.z), new s(t.x, t.y, t.z)), r = new A(new N(n.normal.x, n.normal.y, n.normal.z), -n.distance);
-	return n.free(), r;
+function L(e, t) {
+	let n = new s(e.x, e.y, e.z), r = new s(t.x, t.y, t.z), i = _(n, r), a = new P(i.normal.x, i.normal.y, i.normal.z), o = new j(a, -i.distance);
+	return i.free(), o;
 }
-function F(e, n, r) {
+function R(e, n, r) {
 	let i = new c(e.width, e.height, e.pixelRatio);
 	i.width *= i.pixelRatio, i.height *= i.pixelRatio;
-	let s = h(i, new a(n.position.x, n.position.y, n.position.z, n.quaternion.x, n.quaternion.y, n.quaternion.z, n.quaternion.w, n.scale.x, n.scale.y, n.scale.z), new t(n.near, n.far, u(n.fov), n.aspect), new o(r.x, r.y)), l = new j(new N(s.origin.x, s.origin.y, s.origin.z), new N(s.direction.x, s.direction.y, s.direction.z));
-	return s.free(), l;
-}
-function I(e, t) {
-	let n = _(new i(new s(e.origin.x, e.origin.y, e.origin.z), new s(e.direction.x, e.direction.y, e.direction.z)), g(new s(t.normal.x * -t.constant, t.normal.y * -t.constant, t.normal.z * -t.constant), new s(t.normal.x, t.normal.y, t.normal.z)));
-	if (n) {
-		let e = new N(n.x, n.y, n.z);
-		return n.free(), e;
+	let s = new a(n.position.x, n.position.y, n.position.z, n.quaternion.x, n.quaternion.y, n.quaternion.z, n.quaternion.w, n.scale.x, n.scale.y, n.scale.z), l = new t(n.near, n.far, u(n.fov), n.aspect), d = g(i, s, l, new o(r.x, r.y)), f = new P(d.origin.x, d.origin.y, d.origin.z), p = new P(d.direction.x, d.direction.y, d.direction.z), m = new M(f, p);
+	return d.free(), m;
+}
+function z(e, t) {
+	let n = new i(new s(e.origin.x, e.origin.y, e.origin.z), new s(e.direction.x, e.direction.y, e.direction.z)), r = _(new s(t.normal.x * -t.constant, t.normal.y * -t.constant, t.normal.z * -t.constant), new s(t.normal.x, t.normal.y, t.normal.z)), a = v(n, r);
+	if (a) {
+		let e = new P(a.x, a.y, a.z);
+		return a.free(), e;
 	}
 }
-function te(e) {
-	return m(new s(e.x, e.y, e.z));
+function B(e) {
+	let t = new s(e.x, e.y, e.z);
+	return h(t);
 }
 //#endregion
 //#region src/rte.ts
-var L = Object.freeze({ value: 1 });
-function R(e, t = new N(), n = new N()) {
-	let r = d(e.x, e.y, e.z);
+var V = Object.freeze({ value: 1 });
+function H(e, t = new P(), n = new P()) {
+	let r = f(e.x, e.y, e.z);
 	return t.set(r.high.x, r.high.y, r.high.z), n.set(r.low.x, r.low.y, r.low.z), r.free(), {
 		high: t,
 		low: n
 	};
 }
-var z = (e, t, n = new k()) => {
+var ne = (e, t, n = new A()) => {
 	n.multiplyMatrices(t, e);
 	let r = n.elements;
 	return r[12] = 0, r[13] = 0, r[14] = 0, n;
 };
-function B(e, t, n = new N(), r = new k()) {
+function U(e, t, n = new P(), r = new A()) {
 	r.multiplyMatrices(e, t), n.setFromMatrixPosition(r);
 	let i = r.elements;
 	return i[12] = 0, i[13] = 0, i[14] = 0, {
@@ -44,17 +58,17 @@ function B(e, t, n = new N(), r = new k()) {
 		rotationScale: r
 	};
 }
-var V = new k(), H = new N(), U = (e, t) => {
-	V.copy(t).invert(), H.copy(e).applyMatrix4(V);
-	let n = d(H.x, H.y, H.z), r = n.high, i = n.low, a = {
-		high: new N(r.x, r.y, r.z),
-		low: new N(i.x, i.y, i.z)
+var W = new A(), G = new P(), K = (e, t) => {
+	W.copy(t).invert(), G.copy(e).applyMatrix4(W);
+	let n = f(G.x, G.y, G.z), r = n.high, i = n.low, a = {
+		high: new P(r.x, r.y, r.z),
+		low: new P(i.x, i.y, i.z)
 	};
 	return n.free(), a;
-}, W = class {
+}, q = class {
 	_raw;
 	constructor(e, t) {
-		this._raw = new n(new r(e.lat, e.lng, e.height), new r(t.lat, t.lng, t.height));
+		this._raw = new n(new r(u(e.lat), u(e.lng), e.height), new r(u(t.lat), u(t.lng), t.height));
 	}
 	get distance() {
 		return this._raw.distance;
@@ -63,40 +77,40 @@ var V = new k(), H = new N(), U = (e, t) => {
 		return this._raw.converged;
 	}
 	get startHeading() {
-		return this._raw.start_heading;
+		return l(this._raw.start_heading);
 	}
 	get endHeading() {
-		return this._raw.end_heading;
+		return l(this._raw.end_heading);
 	}
 	get start() {
 		let e = this._raw.start;
 		return {
-			lat: e.lat,
-			lng: e.lng,
+			lat: l(e.lat),
+			lng: l(e.lng),
 			height: e.height
 		};
 	}
 	get end() {
 		let e = this._raw.end;
 		return {
-			lat: e.lat,
-			lng: e.lng,
+			lat: l(e.lat),
+			lng: l(e.lng),
 			height: e.height
 		};
 	}
 	interpolatePoints(e) {
 		let t = this._raw.interpolateGeodeticPoints(e ?? null), n = [];
 		for (let e of t) n.push({
-			lat: e.lat,
-			lng: e.lng,
+			lat: l(e.lat),
+			lng: l(e.lng),
 			height: e.height
 		}), e.free();
 		return n;
 	}
 	interpolateDistance(e) {
 		let t = this._raw.interpolateDistance(e), n = {
-			lat: t.lat,
-			lng: t.lng,
+			lat: l(t.lat),
+			lng: l(t.lng),
 			height: t.height
 		};
 		return t.free(), n;
@@ -107,77 +121,87 @@ var V = new k(), H = new N(), U = (e, t) => {
 };
 //#endregion
 //#region src/index.ts
-async function G() {
+async function J() {
 	await e();
 }
-function K(e) {
-	let t = p(new r(e.lat, e.lng, e.height)), n = new N(t.x, t.y, t.z);
+function Y(e) {
+	let t = m(new r(u(e.lat), u(e.lng), e.height)), n = new P(t.x, t.y, t.z);
 	return t.free(), n;
 }
-function q(e) {
-	let t = O(new s(e.x, e.y, e.z)), n = {
-		lat: t.lat,
-		lng: t.lng,
-		height: t.height
+function X(e) {
+	let t = new s(e.x, e.y, e.z), n = D(t), r = {
+		lat: l(n.lat),
+		lng: l(n.lng),
+		height: n.height
 	};
-	return t.free(), n;
+	return n.free(), r;
 }
-function J(e) {
+function Z(e) {
 	return u(e);
 }
-function Y(e) {
+function re(e) {
 	return l(e);
 }
-function X(e, n, r) {
+function ie(e, n, r) {
 	let i = new c(e.width, e.height, e.pixelRatio);
 	i.width *= i.pixelRatio, i.height *= i.pixelRatio;
-	let s = E(i, new a(n.position.x, n.position.y, n.position.z, n.quaternion.x, n.quaternion.y, n.quaternion.z, n.quaternion.w, n.scale.x, n.scale.y, n.scale.z), new t(n.near, n.far, u(n.fov), n.aspect), new o(r.x, r.y));
-	if (!s) return;
-	let l = new N(s.x, s.y, s.z);
-	return s.free(), l;
+	let s = new a(n.position.x, n.position.y, n.position.z, n.quaternion.x, n.quaternion.y, n.quaternion.z, n.quaternion.w, n.scale.x, n.scale.y, n.scale.z), l = new t(n.near, n.far, u(n.fov), n.aspect), d = T(i, s, l, new o(r.x, r.y));
+	if (!d) return;
+	let f = new P(d.x, d.y, d.z);
+	return d.free(), f;
 }
-function Z(e) {
-	let t = f(new r(e.lat, e.lng, e.height)), n = new N(t.x, t.y, t.z);
+function ae(e) {
+	let t = p(new r(u(e.lat), u(e.lng), e.height)), n = new P(t.x, t.y, t.z);
 	return t.free(), n;
 }
+function oe(e) {
+	let t = new s(e.x, e.y, e.z), n = d(t);
+	return new A().fromArray(n);
+}
+function se(e) {
+	let t = new s(e.x, e.y, e.z), n = ee(t);
+	return new A().fromArray(n);
+}
 function Q(e) {
-	let t = ee(new s(e.x, e.y, e.z));
-	return new k().fromArray(t);
+	let t = new s(e.x, e.y, e.z), n = te(t);
+	return new A().fromArray(n);
 }
-function ne(e) {
-	let t = C(new s(e.x, e.y, e.z));
-	return new k().fromArray(t);
+function ce(e) {
+	let t = new s(e.x, e.y, e.z), n = w(t);
+	return new A().fromArray(n);
 }
-function re(e) {
-	let t = w(new s(e.x, e.y, e.z));
-	return new k().fromArray(t);
+function $(e) {
+	return Q(e).multiply(F());
 }
-function ie(e) {
-	let t = T(new s(e.x, e.y, e.z));
-	return new k().fromArray(t);
+function le(e) {
+	return I($(Y({
+		lng: e.lng,
+		lat: e.lat,
+		height: e.height ?? 0
+	})), e);
 }
-function ae(e, n, r) {
+function ue(e, n, r) {
 	let i = new c(e.width, e.height, e.pixelRatio);
 	i.width *= i.pixelRatio, i.height *= i.pixelRatio;
-	let o = D(i, new a(n.position.x, n.position.y, n.position.z, n.quaternion.x, n.quaternion.y, n.quaternion.z, n.quaternion.w, n.scale.x, n.scale.y, n.scale.z), new t(n.near, n.far, u(n.fov), n.aspect), new s(r.x, r.y, r.z));
-	if (!o) return;
-	let l = new M(o.x, o.y);
-	return o.free(), l;
+	let o = new a(n.position.x, n.position.y, n.position.z, n.quaternion.x, n.quaternion.y, n.quaternion.z, n.quaternion.w, n.scale.x, n.scale.y, n.scale.z), l = new t(n.near, n.far, u(n.fov), n.aspect), d = E(i, o, l, new s(r.x, r.y, r.z));
+	if (!d) return;
+	let f = new N(d.x, d.y);
+	return d.free(), f;
 }
-function oe() {
-	return x();
-}
-function $() {
+function de() {
 	return S();
 }
-function se() {
-	return y();
+function fe() {
+	return C();
 }
-function ce() {
+function pe() {
 	return b();
 }
-function le() {
-	return v();
+function me() {
+	return x();
+}
+function he() {
+	return y();
 }
 //#endregion
-export { W as EllipsoidGeodesic, L as RTE_ONE_UNIFORM, U as calcCameraPosition, z as calcModelMatrixRTE, B as composeWorldMatrixForRTE, X as convertScreenToWorld, ae as convertWorldToScreen, J as degreeToRadian, Q as eastNorthUpToFixedFrame, R as encodePositionRTE, Z as geodeticSurfaceNormal, K as geodeticToVector3, te as getHeightFromEllipsoid, F as getPickRay, P as getPlaneFromPointNormal, I as getRayPlaneIntersection, le as getWGS84Eccentricity, se as getWGS84EccentricitySquared, ce as getWGS84Flattening, oe as getWGS84SemiMajorAxis, $ as getWGS84SemiMinorAxis, G as initNavaraApi, ne as northEastDownToFixedFrame, re as northUpEastToFixedFrame, ie as northWestUpToFixedFrame, Y as radianToDegree, q as vector3ToGeodetic };
+export { q as EllipsoidGeodesic, V as RTE_ONE_UNIFORM, K as calcCameraPosition, ne as calcModelMatrixRTE, U as composeWorldMatrixForRTE, ie as convertScreenToWorld, ue as convertWorldToScreen, Z as degreeToRadian, oe as eastNorthUpToFixedFrame, H as encodePositionRTE, ae as geodeticSurfaceNormal, Y as geodeticToVector3, B as getHeightFromEllipsoid, R as getPickRay, L as getPlaneFromPointNormal, z as getRayPlaneIntersection, he as getWGS84Eccentricity, pe as getWGS84EccentricitySquared, me as getWGS84Flattening, de as getWGS84SemiMajorAxis, fe as getWGS84SemiMinorAxis, le as headingPitchRollToFixedFrame, J as initNavaraApi, se as northEastDownToFixedFrame, Q as northUpEastToFixedFrame, ce as northWestUpToFixedFrame, re as radianToDegree, X as vector3ToGeodetic, $ as westUpNorthToFixedFrame };

package/dist/index.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.umd.cjs

@@ -1 +1 @@
-(function(e,t){typeof exports==`object`&&typeof module<`u`?t(exports,require("@navaramap/engine-api"),require("three")):typeof define==`function`&&define.amd?define([`exports`,`@navaramap/engine-api`,`three`],t):(e=typeof globalThis<`u`?globalThis:e||self,t(e.NavaraThreeApi={},e._navaramap_engine_api,e.three))})(this,function(e,t,n){Object.defineProperty(e,Symbol.toStringTag,{value:`Module`});var r=Object.create,i=Object.defineProperty,a=Object.getOwnPropertyDescriptor,o=Object.getOwnPropertyNames,s=Object.getPrototypeOf,c=Object.prototype.hasOwnProperty,l=(e,t,n,r)=>{if(t&&typeof t==`object`||typeof t==`function`)for(var s=o(t),l=0,u=s.length,d;l<u;l++)d=s[l],!c.call(e,d)&&d!==n&&i(e,d,{get:(e=>t[e]).bind(null,d),enumerable:!(r=a(t,d))||r.enumerable});return e};t=((e,t,n)=>(n=e==null?{}:r(s(e)),l(t||!e||!e.__esModule?i(n,`default`,{value:e,enumerable:!0}):n,e)))(t,1);function u(e,r){let i=(0,t.getPlaneFromPointNormal)(new t.Vec3(e.x,e.y,e.z),new t.Vec3(r.x,r.y,r.z)),a=new n.Plane(new n.Vector3(i.normal.x,i.normal.y,i.normal.z),-i.distance);return i.free(),a}function d(e,r,i){let a=new t.Window(e.width,e.height,e.pixelRatio);a.width*=a.pixelRatio,a.height*=a.pixelRatio;let o=(0,t.getPickRay)(a,new t.Transform(r.position.x,r.position.y,r.position.z,r.quaternion.x,r.quaternion.y,r.quaternion.z,r.quaternion.w,r.scale.x,r.scale.y,r.scale.z),new t.CameraFrustum(r.near,r.far,(0,t.angleToRadian)(r.fov),r.aspect),new t.Vec2(i.x,i.y)),s=new n.Ray(new n.Vector3(o.origin.x,o.origin.y,o.origin.z),new n.Vector3(o.direction.x,o.direction.y,o.direction.z));return o.free(),s}function f(e,r){let i=(0,t.getRayPlaneIntersection)(new t.Ray(new t.Vec3(e.origin.x,e.origin.y,e.origin.z),new t.Vec3(e.direction.x,e.direction.y,e.direction.z)),(0,t.getPlaneFromPointNormal)(new t.Vec3(r.normal.x*-r.constant,r.normal.y*-r.constant,r.normal.z*-r.constant),new t.Vec3(r.normal.x,r.normal.y,r.normal.z)));if(i){let e=new n.Vector3(i.x,i.y,i.z);return i.free(),e}}function p(e){return(0,t.getHeightFromEllipsoid)(new t.Vec3(e.x,e.y,e.z))}var m=Object.freeze({value:1});function h(e,r=new n.Vector3,i=new n.Vector3){let a=(0,t.encodePosition)(e.x,e.y,e.z);return r.set(a.high.x,a.high.y,a.high.z),i.set(a.low.x,a.low.y,a.low.z),a.free(),{high:r,low:i}}var g=(e,t,r=new n.Matrix4)=>{r.multiplyMatrices(t,e);let i=r.elements;return i[12]=0,i[13]=0,i[14]=0,r};function _(e,t,r=new n.Vector3,i=new n.Matrix4){i.multiplyMatrices(e,t),r.setFromMatrixPosition(i);let a=i.elements;return a[12]=0,a[13]=0,a[14]=0,{position:r,rotationScale:i}}var v=new n.Matrix4,y=new n.Vector3,b=(e,r)=>{v.copy(r).invert(),y.copy(e).applyMatrix4(v);let i=(0,t.encodePosition)(y.x,y.y,y.z),a=i.high,o=i.low,s={high:new n.Vector3(a.x,a.y,a.z),low:new n.Vector3(o.x,o.y,o.z)};return i.free(),s},x=class{_raw;constructor(e,n){this._raw=new t.EllipsoidGeodesic(new t.LLE(e.lat,e.lng,e.height),new t.LLE(n.lat,n.lng,n.height))}get distance(){return this._raw.distance}get converged(){return this._raw.converged}get startHeading(){return this._raw.start_heading}get endHeading(){return this._raw.end_heading}get start(){let e=this._raw.start;return{lat:e.lat,lng:e.lng,height:e.height}}get end(){let e=this._raw.end;return{lat:e.lat,lng:e.lng,height:e.height}}interpolatePoints(e){let t=this._raw.interpolateGeodeticPoints(e??null),n=[];for(let e of t)n.push({lat:e.lat,lng:e.lng,height:e.height}),e.free();return n}interpolateDistance(e){let t=this._raw.interpolateDistance(e),n={lat:t.lat,lng:t.lng,height:t.height};return t.free(),n}dispose(){this._raw.free()}};async function S(){await(0,t.default)()}function C(e){let r=(0,t.geodeticToXyz)(new t.LLE(e.lat,e.lng,e.height)),i=new n.Vector3(r.x,r.y,r.z);return r.free(),i}function w(e){let n=(0,t.xyzToGeodetic)(new t.Vec3(e.x,e.y,e.z)),r={lat:n.lat,lng:n.lng,height:n.height};return n.free(),r}function T(e){return(0,t.angleToRadian)(e)}function E(e){return(0,t.angleToDegree)(e)}function D(e,r,i){let a=new t.Window(e.width,e.height,e.pixelRatio);a.width*=a.pixelRatio,a.height*=a.pixelRatio;let o=(0,t.screenToWorld)(a,new t.Transform(r.position.x,r.position.y,r.position.z,r.quaternion.x,r.quaternion.y,r.quaternion.z,r.quaternion.w,r.scale.x,r.scale.y,r.scale.z),new t.CameraFrustum(r.near,r.far,(0,t.angleToRadian)(r.fov),r.aspect),new t.Vec2(i.x,i.y));if(!o)return;let s=new n.Vector3(o.x,o.y,o.z);return o.free(),s}function O(e){let r=(0,t.geodeticSurfaceNormal)(new t.LLE(e.lat,e.lng,e.height)),i=new n.Vector3(r.x,r.y,r.z);return r.free(),i}function k(e){let r=(0,t.eastNorthUpToFixedFrame)(new t.Vec3(e.x,e.y,e.z));return new n.Matrix4().fromArray(r)}function A(e){let r=(0,t.northEastDownToFixedFrame)(new t.Vec3(e.x,e.y,e.z));return new n.Matrix4().fromArray(r)}function j(e){let r=(0,t.northUpEastToFixedFrame)(new t.Vec3(e.x,e.y,e.z));return new n.Matrix4().fromArray(r)}function M(e){let r=(0,t.northWestUpToFixedFrame)(new t.Vec3(e.x,e.y,e.z));return new n.Matrix4().fromArray(r)}function N(e,r,i){let a=new t.Window(e.width,e.height,e.pixelRatio);a.width*=a.pixelRatio,a.height*=a.pixelRatio;let o=(0,t.worldToScreen)(a,new t.Transform(r.position.x,r.position.y,r.position.z,r.quaternion.x,r.quaternion.y,r.quaternion.z,r.quaternion.w,r.scale.x,r.scale.y,r.scale.z),new t.CameraFrustum(r.near,r.far,(0,t.angleToRadian)(r.fov),r.aspect),new t.Vec3(i.x,i.y,i.z));if(!o)return;let s=new n.Vector2(o.x,o.y);return o.free(),s}function P(){return(0,t.getWGS84SemiMajorAxis)()}function F(){return(0,t.getWGS84SemiMinorAxis)()}function I(){return(0,t.getWGS84EccentricitySquared)()}function L(){return(0,t.getWGS84Flattening)()}function R(){return(0,t.getWGS84Eccentricity)()}e.EllipsoidGeodesic=x,e.RTE_ONE_UNIFORM=m,e.calcCameraPosition=b,e.calcModelMatrixRTE=g,e.composeWorldMatrixForRTE=_,e.convertScreenToWorld=D,e.convertWorldToScreen=N,e.degreeToRadian=T,e.eastNorthUpToFixedFrame=k,e.encodePositionRTE=h,e.geodeticSurfaceNormal=O,e.geodeticToVector3=C,e.getHeightFromEllipsoid=p,e.getPickRay=d,e.getPlaneFromPointNormal=u,e.getRayPlaneIntersection=f,e.getWGS84Eccentricity=R,e.getWGS84EccentricitySquared=I,e.getWGS84Flattening=L,e.getWGS84SemiMajorAxis=P,e.getWGS84SemiMinorAxis=F,e.initNavaraApi=S,e.northEastDownToFixedFrame=A,e.northUpEastToFixedFrame=j,e.northWestUpToFixedFrame=M,e.radianToDegree=E,e.vector3ToGeodetic=w});
+(function(e,t){typeof exports==`object`&&typeof module<`u`?t(exports,require("@navaramap/engine-api"),require("three")):typeof define==`function`&&define.amd?define([`exports`,`@navaramap/engine-api`,`three`],t):(e=typeof globalThis<`u`?globalThis:e||self,t(e.NavaraThreeApi={},e._navaramap_engine_api,e.three))})(this,function(e,t,n){Object.defineProperty(e,Symbol.toStringTag,{value:`Module`});var r=Object.create,i=Object.defineProperty,a=Object.getOwnPropertyDescriptor,o=Object.getOwnPropertyNames,s=Object.getPrototypeOf,c=Object.prototype.hasOwnProperty,l=(e,t,n,r)=>{if(t&&typeof t==`object`||typeof t==`function`)for(var s=o(t),l=0,u=s.length,d;l<u;l++)d=s[l],!c.call(e,d)&&d!==n&&i(e,d,{get:(e=>t[e]).bind(null,d),enumerable:!(r=a(t,d))||r.enumerable});return e};t=((e,t,n)=>(n=e==null?{}:r(s(e)),l(t||!e||!e.__esModule||!c.call(e,`default`)?i(n,`default`,{value:e,enumerable:!0}):n,e)))(t,1);function u(){return new n.Matrix4().makeRotationY(Math.PI/2)}function d(e,t){let r=new n.Matrix4().multiplyMatrices(e,new n.Matrix4().makeRotationFromEuler(new n.Euler(-n.MathUtils.degToRad(t.pitch??0),-n.MathUtils.degToRad(t.heading??0),n.MathUtils.degToRad(t.roll??0),`YXZ`)));if(t.scale!==void 0){let e=t.scale;r.scale(typeof e==`number`?new n.Vector3(e,e,e):new n.Vector3(e.x,e.y,e.z))}return r}function f(e,r){let i=new t.Vec3(e.x,e.y,e.z),a=new t.Vec3(r.x,r.y,r.z),o=(0,t.getPlaneFromPointNormal)(i,a),s=new n.Vector3(o.normal.x,o.normal.y,o.normal.z),c=new n.Plane(s,-o.distance);return o.free(),c}function p(e,r,i){let a=new t.Window(e.width,e.height,e.pixelRatio);a.width*=a.pixelRatio,a.height*=a.pixelRatio;let o=new t.Transform(r.position.x,r.position.y,r.position.z,r.quaternion.x,r.quaternion.y,r.quaternion.z,r.quaternion.w,r.scale.x,r.scale.y,r.scale.z),s=new t.CameraFrustum(r.near,r.far,(0,t.angleToRadian)(r.fov),r.aspect),c=(0,t.getPickRay)(a,o,s,new t.Vec2(i.x,i.y)),l=new n.Vector3(c.origin.x,c.origin.y,c.origin.z),u=new n.Vector3(c.direction.x,c.direction.y,c.direction.z),d=new n.Ray(l,u);return c.free(),d}function m(e,r){let i=new t.Ray(new t.Vec3(e.origin.x,e.origin.y,e.origin.z),new t.Vec3(e.direction.x,e.direction.y,e.direction.z)),a=(0,t.getPlaneFromPointNormal)(new t.Vec3(r.normal.x*-r.constant,r.normal.y*-r.constant,r.normal.z*-r.constant),new t.Vec3(r.normal.x,r.normal.y,r.normal.z)),o=(0,t.getRayPlaneIntersection)(i,a);if(o){let e=new n.Vector3(o.x,o.y,o.z);return o.free(),e}}function h(e){let n=new t.Vec3(e.x,e.y,e.z);return(0,t.getHeightFromEllipsoid)(n)}var g=Object.freeze({value:1});function _(e,r=new n.Vector3,i=new n.Vector3){let a=(0,t.encodePosition)(e.x,e.y,e.z);return r.set(a.high.x,a.high.y,a.high.z),i.set(a.low.x,a.low.y,a.low.z),a.free(),{high:r,low:i}}var v=(e,t,r=new n.Matrix4)=>{r.multiplyMatrices(t,e);let i=r.elements;return i[12]=0,i[13]=0,i[14]=0,r};function y(e,t,r=new n.Vector3,i=new n.Matrix4){i.multiplyMatrices(e,t),r.setFromMatrixPosition(i);let a=i.elements;return a[12]=0,a[13]=0,a[14]=0,{position:r,rotationScale:i}}var b=new n.Matrix4,x=new n.Vector3,S=(e,r)=>{b.copy(r).invert(),x.copy(e).applyMatrix4(b);let i=(0,t.encodePosition)(x.x,x.y,x.z),a=i.high,o=i.low,s={high:new n.Vector3(a.x,a.y,a.z),low:new n.Vector3(o.x,o.y,o.z)};return i.free(),s},C=class{_raw;constructor(e,n){this._raw=new t.EllipsoidGeodesic(new t.LLE((0,t.angleToRadian)(e.lat),(0,t.angleToRadian)(e.lng),e.height),new t.LLE((0,t.angleToRadian)(n.lat),(0,t.angleToRadian)(n.lng),n.height))}get distance(){return this._raw.distance}get converged(){return this._raw.converged}get startHeading(){return(0,t.angleToDegree)(this._raw.start_heading)}get endHeading(){return(0,t.angleToDegree)(this._raw.end_heading)}get start(){let e=this._raw.start;return{lat:(0,t.angleToDegree)(e.lat),lng:(0,t.angleToDegree)(e.lng),height:e.height}}get end(){let e=this._raw.end;return{lat:(0,t.angleToDegree)(e.lat),lng:(0,t.angleToDegree)(e.lng),height:e.height}}interpolatePoints(e){let n=this._raw.interpolateGeodeticPoints(e??null),r=[];for(let e of n)r.push({lat:(0,t.angleToDegree)(e.lat),lng:(0,t.angleToDegree)(e.lng),height:e.height}),e.free();return r}interpolateDistance(e){let n=this._raw.interpolateDistance(e),r={lat:(0,t.angleToDegree)(n.lat),lng:(0,t.angleToDegree)(n.lng),height:n.height};return n.free(),r}dispose(){this._raw.free()}};async function w(){await(0,t.default)()}function T(e){let r=(0,t.geodeticToXyz)(new t.LLE((0,t.angleToRadian)(e.lat),(0,t.angleToRadian)(e.lng),e.height)),i=new n.Vector3(r.x,r.y,r.z);return r.free(),i}function E(e){let n=new t.Vec3(e.x,e.y,e.z),r=(0,t.xyzToGeodetic)(n),i={lat:(0,t.angleToDegree)(r.lat),lng:(0,t.angleToDegree)(r.lng),height:r.height};return r.free(),i}function D(e){return(0,t.angleToRadian)(e)}function O(e){return(0,t.angleToDegree)(e)}function k(e,r,i){let a=new t.Window(e.width,e.height,e.pixelRatio);a.width*=a.pixelRatio,a.height*=a.pixelRatio;let o=new t.Transform(r.position.x,r.position.y,r.position.z,r.quaternion.x,r.quaternion.y,r.quaternion.z,r.quaternion.w,r.scale.x,r.scale.y,r.scale.z),s=new t.CameraFrustum(r.near,r.far,(0,t.angleToRadian)(r.fov),r.aspect),c=(0,t.screenToWorld)(a,o,s,new t.Vec2(i.x,i.y));if(!c)return;let l=new n.Vector3(c.x,c.y,c.z);return c.free(),l}function A(e){let r=(0,t.geodeticSurfaceNormal)(new t.LLE((0,t.angleToRadian)(e.lat),(0,t.angleToRadian)(e.lng),e.height)),i=new n.Vector3(r.x,r.y,r.z);return r.free(),i}function j(e){let r=new t.Vec3(e.x,e.y,e.z),i=(0,t.eastNorthUpToFixedFrame)(r);return new n.Matrix4().fromArray(i)}function M(e){let r=new t.Vec3(e.x,e.y,e.z),i=(0,t.northEastDownToFixedFrame)(r);return new n.Matrix4().fromArray(i)}function N(e){let r=new t.Vec3(e.x,e.y,e.z),i=(0,t.northUpEastToFixedFrame)(r);return new n.Matrix4().fromArray(i)}function P(e){let r=new t.Vec3(e.x,e.y,e.z),i=(0,t.northWestUpToFixedFrame)(r);return new n.Matrix4().fromArray(i)}function F(e){return N(e).multiply(u())}function I(e){return d(F(T({lng:e.lng,lat:e.lat,height:e.height??0})),e)}function L(e,r,i){let a=new t.Window(e.width,e.height,e.pixelRatio);a.width*=a.pixelRatio,a.height*=a.pixelRatio;let o=new t.Transform(r.position.x,r.position.y,r.position.z,r.quaternion.x,r.quaternion.y,r.quaternion.z,r.quaternion.w,r.scale.x,r.scale.y,r.scale.z),s=new t.CameraFrustum(r.near,r.far,(0,t.angleToRadian)(r.fov),r.aspect),c=(0,t.worldToScreen)(a,o,s,new t.Vec3(i.x,i.y,i.z));if(!c)return;let l=new n.Vector2(c.x,c.y);return c.free(),l}function R(){return(0,t.getWGS84SemiMajorAxis)()}function z(){return(0,t.getWGS84SemiMinorAxis)()}function B(){return(0,t.getWGS84EccentricitySquared)()}function V(){return(0,t.getWGS84Flattening)()}function H(){return(0,t.getWGS84Eccentricity)()}e.EllipsoidGeodesic=C,e.RTE_ONE_UNIFORM=g,e.calcCameraPosition=S,e.calcModelMatrixRTE=v,e.composeWorldMatrixForRTE=y,e.convertScreenToWorld=k,e.convertWorldToScreen=L,e.degreeToRadian=D,e.eastNorthUpToFixedFrame=j,e.encodePositionRTE=_,e.geodeticSurfaceNormal=A,e.geodeticToVector3=T,e.getHeightFromEllipsoid=h,e.getPickRay=p,e.getPlaneFromPointNormal=f,e.getRayPlaneIntersection=m,e.getWGS84Eccentricity=H,e.getWGS84EccentricitySquared=B,e.getWGS84Flattening=V,e.getWGS84SemiMajorAxis=R,e.getWGS84SemiMinorAxis=z,e.headingPitchRollToFixedFrame=I,e.initNavaraApi=w,e.northEastDownToFixedFrame=M,e.northUpEastToFixedFrame=N,e.northWestUpToFixedFrame=P,e.radianToDegree=O,e.vector3ToGeodetic=E,e.westUpNorthToFixedFrame=F});

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@navaramap/three-api",
   "type": "module",
-  "version": "0.0.7",
+  "version": "0.1.0",
   "main": "dist/index.umd.cjs",
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -22,8 +22,8 @@
     "three": ">=0.183.0"
   },
   "dependencies": {
-    "@navaramap/engine-api": "0.0.7",
-    "@navaramap/core": "0.0.7"
+    "@navaramap/core": "0.1.0",
+    "@navaramap/engine-api": "0.1.0"
   },
   "devDependencies": {
     "@types/three": "0.185.1",

package/src/ellipsoidGeodesic.ts

@@ -2,17 +2,21 @@ import type { LatLngHeight } from "@navaramap/core";
 import {
   EllipsoidGeodesic as EllipsoidGeodesicImpl,
   LLE,
+  angleToRadian,
+  angleToDegree,
 } from "@navaramap/engine-api";
 
 /**
  * Wrapper class for geodesic calculations on an ellipsoid surface.
  * Precomputes common variables for optimization when instantiated.
  *
+ * All latitudes/longitudes and headings are in **degrees**.
+ *
  * @example
  * ```typescript
  * const geodesic = new EllipsoidGeodesic(
- *   { lat: 0.5, lng: 2.0, height: 0 },
- *   { lat: 0.6, lng: 2.1, height: 0 }
+ *   { lat: 35.6812, lng: 139.7671, height: 0 },
+ *   { lat: 34.7025, lng: 135.4959, height: 0 }
  * );
  *
  * console.log(geodesic.distance);
@@ -27,13 +31,13 @@ export class EllipsoidGeodesic {
 
   /**
    * Create a new geodesic between two points on the ellipsoid.
-   * @param start - Start point in geodetic coordinates (lat/lng in radians)
-   * @param end - End point in geodetic coordinates (lat/lng in radians)
+   * @param start - Start point in geodetic coordinates (lat/lng in degrees)
+   * @param end - End point in geodetic coordinates (lat/lng in degrees)
    */
   constructor(start: LatLngHeight, end: LatLngHeight) {
     this._raw = new EllipsoidGeodesicImpl(
-      new LLE(start.lat, start.lng, start.height),
-      new LLE(end.lat, end.lng, end.height),
+      new LLE(angleToRadian(start.lat), angleToRadian(start.lng), start.height),
+      new LLE(angleToRadian(end.lat), angleToRadian(end.lng), end.height),
     );
   }
 
@@ -52,32 +56,40 @@ export class EllipsoidGeodesic {
     return this._raw.converged;
   }
 
-  /** Heading at the start point in radians */
+  /** Heading at the start point in degrees */
   get startHeading(): number {
-    return this._raw.start_heading;
+    return angleToDegree(this._raw.start_heading);
   }
 
-  /** Heading at the end point in radians */
+  /** Heading at the end point in degrees */
   get endHeading(): number {
-    return this._raw.end_heading;
+    return angleToDegree(this._raw.end_heading);
   }
 
-  /** Start point in geodetic coordinates */
+  /** Start point in geodetic coordinates (lat/lng in degrees) */
   get start(): LatLngHeight {
     const lle = this._raw.start;
-    return { lat: lle.lat, lng: lle.lng, height: lle.height };
+    return {
+      lat: angleToDegree(lle.lat),
+      lng: angleToDegree(lle.lng),
+      height: lle.height,
+    };
   }
 
-  /** End point in geodetic coordinates */
+  /** End point in geodetic coordinates (lat/lng in degrees) */
   get end(): LatLngHeight {
     const lle = this._raw.end;
-    return { lat: lle.lat, lng: lle.lng, height: lle.height };
+    return {
+      lat: angleToDegree(lle.lat),
+      lng: angleToDegree(lle.lng),
+      height: lle.height,
+    };
   }
 
   /**
    * Interpolate points along the geodesic path.
    * @param granularity - Distance between interpolated points in meters (optional)
-   * @returns Array of interpolated points in geodetic coordinates
+   * @returns Array of interpolated points in geodetic coordinates (lat/lng in degrees)
    */
   interpolatePoints(granularity?: number): LatLngHeight[] {
     const wasmPoints = this._raw.interpolateGeodeticPoints(granularity ?? null);
@@ -85,8 +97,8 @@ export class EllipsoidGeodesic {
     const results: LatLngHeight[] = [];
     for (const point of wasmPoints) {
       results.push({
-        lat: point.lat,
-        lng: point.lng,
+        lat: angleToDegree(point.lat),
+        lng: angleToDegree(point.lng),
         height: point.height,
       });
       point.free();
@@ -98,14 +110,14 @@ export class EllipsoidGeodesic {
   /**
    * Interpolate a point at a specific distance along the geodesic path.
    * @param distance - Distance from start point in meters
-   * @returns Interpolated point in geodetic coordinates
+   * @returns Interpolated point in geodetic coordinates (lat/lng in degrees)
    */
   interpolateDistance(distance: number): LatLngHeight {
     const wasmPoint = this._raw.interpolateDistance(distance);
 
     const result: LatLngHeight = {
-      lat: wasmPoint.lat,
-      lng: wasmPoint.lng,
+      lat: angleToDegree(wasmPoint.lat),
+      lng: angleToDegree(wasmPoint.lng),
       height: wasmPoint.height,
     };
 

package/src/frames.test.ts

@@ -0,0 +1,154 @@
+import { Matrix4, Vector3 } from "three";
+import { describe, expect, it } from "vitest";
+
+import { composeHeadingPitchRoll, nueToWunBasis } from "./frames";
+
+// glTF 2.0: an asset's front faces +Z, its up is +Y, and -X is its right.
+const FRONT = new Vector3(0, 0, 1);
+const RIGHT = new Vector3(-1, 0, 0);
+
+// Directions in the WUN local frame, where +x = west, +y = up, +z = north.
+const NORTH = [0, 0, 1] as const;
+const SOUTH = [0, 0, -1] as const;
+const EAST = [-1, 0, 0] as const;
+const WEST = [1, 0, 0] as const;
+const UP = [0, 1, 0] as const;
+const DOWN = [0, -1, 0] as const;
+
+const expectDir = (
+  m: Matrix4,
+  axis: Vector3,
+  expected: readonly [number, number, number],
+) => {
+  const actual = axis.clone().transformDirection(m);
+  expect(actual.x).toBeCloseTo(expected[0], 6);
+  expect(actual.y).toBeCloseTo(expected[1], 6);
+  expect(actual.z).toBeCloseTo(expected[2], 6);
+};
+
+describe("composeHeadingPitchRoll", () => {
+  it("faces north with no rotation, right hand to the east", () => {
+    const m = composeHeadingPitchRoll(new Matrix4(), {});
+    expectDir(m, FRONT, NORTH);
+    expectDir(m, RIGHT, EAST);
+  });
+
+  it("reads heading as a clockwise compass bearing", () => {
+    expectDir(
+      composeHeadingPitchRoll(new Matrix4(), { heading: 0 }),
+      FRONT,
+      NORTH,
+    );
+    expectDir(
+      composeHeadingPitchRoll(new Matrix4(), { heading: 90 }),
+      FRONT,
+      EAST,
+    );
+    expectDir(
+      composeHeadingPitchRoll(new Matrix4(), { heading: 180 }),
+      FRONT,
+      SOUTH,
+    );
+    expectDir(
+      composeHeadingPitchRoll(new Matrix4(), { heading: 270 }),
+      FRONT,
+      WEST,
+    );
+  });
+
+  it("lifts the nose for positive pitch", () => {
+    expectDir(composeHeadingPitchRoll(new Matrix4(), { pitch: 90 }), FRONT, UP);
+    expectDir(
+      composeHeadingPitchRoll(new Matrix4(), { pitch: -90 }),
+      FRONT,
+      DOWN,
+    );
+  });
+
+  it("drops the right wing for positive roll, leaving the nose alone", () => {
+    const m = composeHeadingPitchRoll(new Matrix4(), { roll: 90 });
+    expectDir(m, RIGHT, DOWN);
+    expectDir(m, FRONT, NORTH);
+  });
+
+  it("applies yaw, then pitch, then roll", () => {
+    // Roll is innermost: it turns the asset about its own nose before pitch
+    // tips that nose up, so the rolled right wing ends up pointing north.
+    // Reversing the order would put the right wing east instead.
+    const m = composeHeadingPitchRoll(new Matrix4(), { pitch: 90, roll: 90 });
+    expectDir(m, FRONT, UP);
+    expectDir(m, RIGHT, NORTH);
+  });
+
+  it("accepts uniform and per-axis scale", () => {
+    const uniform = new Vector3().setFromMatrixScale(
+      composeHeadingPitchRoll(new Matrix4(), { scale: 2.5 }),
+    );
+    expect(uniform.x).toBeCloseTo(2.5, 6);
+    expect(uniform.y).toBeCloseTo(2.5, 6);
+    expect(uniform.z).toBeCloseTo(2.5, 6);
+
+    const perAxis = new Vector3().setFromMatrixScale(
+      composeHeadingPitchRoll(new Matrix4(), { scale: { x: 2, y: 3, z: 4 } }),
+    );
+    expect(perAxis.x).toBeCloseTo(2, 6);
+    expect(perAxis.y).toBeCloseTo(3, 6);
+    expect(perAxis.z).toBeCloseTo(4, 6);
+  });
+
+  it("round-trips heading through a bearing, matching setCamera", () => {
+    // navara_camera::helpers::get_heading yields 0 for north and 90 for east.
+    // This test is the guard against the mesh and camera conventions drifting.
+    for (const heading of [0, 17, 45, 90, 137, 180, 233, 270, 359]) {
+      const front = FRONT.clone().transformDirection(
+        composeHeadingPitchRoll(new Matrix4(), { heading }),
+      );
+      const bearing = (Math.atan2(-front.x, front.z) * 180) / Math.PI;
+      expect((bearing + 360) % 360).toBeCloseTo(heading, 4);
+    }
+  });
+
+  it("maps the asset front into ECEF through a real WUN frame", () => {
+    // WUN at lng 0, lat 0: west = -Y_ecef, up = +X_ecef, north = +Z_ecef.
+    const wun = new Matrix4().makeBasis(
+      new Vector3(0, -1, 0),
+      new Vector3(1, 0, 0),
+      new Vector3(0, 0, 1),
+    );
+    expectDir(composeHeadingPitchRoll(wun, { heading: 0 }), FRONT, [0, 0, 1]);
+    expectDir(composeHeadingPitchRoll(wun, { heading: 90 }), FRONT, [0, 1, 0]);
+    expectDir(composeHeadingPitchRoll(wun, { pitch: 90 }), FRONT, [1, 0, 0]);
+  });
+});
+
+describe("nueToWunBasis", () => {
+  // navara_core's local_frame_to_fixed_frame builds
+  //   east = normalize(-origin.y, origin.x, 0) and north = up x east,
+  // so the ECEF axes at these two points are exact and hand-checkable.
+  const cases = [
+    {
+      name: "lng 0, lat 0",
+      up: new Vector3(1, 0, 0),
+      east: new Vector3(0, 1, 0),
+      north: new Vector3(0, 0, 1),
+    },
+    {
+      name: "lng 90, lat 0",
+      up: new Vector3(0, 1, 0),
+      east: new Vector3(-1, 0, 0),
+      north: new Vector3(0, 0, 1),
+    },
+  ];
+
+  it.each(cases)(
+    "turns an NUE basis into a WUN basis at $name",
+    ({ up, east, north }) => {
+      const nue = new Matrix4().makeBasis(north, up, east);
+      const wun = new Matrix4().makeBasis(east.clone().negate(), up, north);
+      const converted = nue.clone().multiply(nueToWunBasis());
+      converted.elements.forEach((value, i) => {
+        expect(value).toBeCloseTo(wun.elements[i], 6);
+      });
+    },
+  );
+});

package/src/frames.ts

@@ -0,0 +1,98 @@
+import type { XYZ } from "@navaramap/core";
+import { Euler, MathUtils, Matrix4, Vector3 } from "three";
+
+/**
+ * High-level geographic placement of a mesh object.
+ *
+ * All angles are in **degrees** and `height` is in metres, matching
+ * `ThreeView.setCamera`. The asset is oriented in a West-Up-North tangent
+ * frame, which matches glTF's own convention (front `+Z`, up `+Y`,
+ * right `-X`) on all three axes — so an unmodified glTF asset needs no
+ * up-axis correction.
+ */
+export type GeodeticPlacement = {
+  /** Longitude in degrees. */
+  lng: number;
+  /** Latitude in degrees. */
+  lat: number;
+  /**
+   * Metres above the ellipsoid, or above terrain when `heightReference` is
+   * `"terrain"`. Defaults to 0.
+   */
+  height?: number;
+  /**
+   * Degrees clockwise from north that the asset's front (glTF `+Z`) faces.
+   * Same convention as `setCamera`'s heading. Defaults to 0.
+   */
+  heading?: number;
+  /** Degrees, nose up positive. Defaults to 0. */
+  pitch?: number;
+  /** Degrees, right wing down positive. Defaults to 0. */
+  roll?: number;
+  /** Uniform or per-axis scale of the frame. Defaults to 1. */
+  scale?: number | XYZ;
+  /** How `height` is interpreted. Defaults to `"ellipsoid"`. */
+  heightReference?: "ellipsoid" | "terrain";
+};
+
+/**
+ * Basis change from the NUE frame `(north, up, east)` to the WUN frame
+ * `(west, up, north)`.
+ *
+ * With `Ry(+90°)` columns `(0,0,-1), (0,1,0), (1,0,0)`, the product
+ * `NUE · Ry(+90°)` has columns `(-east, up, north)`, which is WUN. WUN is the
+ * unique right-handed, Y-up tangent frame whose `+Z` is north, which is why it
+ * agrees with glTF on every axis.
+ *
+ * Returns a fresh matrix on every call, so callers cannot corrupt a shared
+ * instance.
+ *
+ * @returns A new `Matrix4` performing the NUE-to-WUN basis change.
+ */
+export function nueToWunBasis(): Matrix4 {
+  return new Matrix4().makeRotationY(Math.PI / 2);
+}
+
+/**
+ * Composes a tangent frame with heading, pitch, roll and scale.
+ *
+ * Pure: takes the frame as a parameter and uses three.js `MathUtils.degToRad`,
+ * so it touches no WASM and is directly unit-testable.
+ *
+ * `Ry(-heading) · Rx(-pitch) · Rz(+roll)` is exactly three.js Euler order
+ * `"YXZ"`, the standard intrinsic yaw -> pitch -> roll order. Signs follow from
+ * the glTF axes in a WUN frame: positive heading swings `+Z` toward `-X`
+ * (east), positive pitch lifts `+Z` toward `+Y`, and positive roll about `+Z`
+ * drives the `-X` wing toward `-Y`.
+ *
+ * @param frame - Tangent frame to compose onto, normally from
+ *   `westUpNorthToFixedFrame`
+ * @param p - Heading, pitch, roll (degrees) and scale; each defaults to
+ *   no-op
+ * @returns `frame · R(heading, pitch, roll) · S(scale)`
+ */
+export function composeHeadingPitchRoll(
+  frame: Matrix4,
+  p: Pick<GeodeticPlacement, "heading" | "pitch" | "roll" | "scale">,
+): Matrix4 {
+  const result = new Matrix4().multiplyMatrices(
+    frame,
+    new Matrix4().makeRotationFromEuler(
+      new Euler(
+        -MathUtils.degToRad(p.pitch ?? 0),
+        -MathUtils.degToRad(p.heading ?? 0),
+        MathUtils.degToRad(p.roll ?? 0),
+        "YXZ",
+      ),
+    ),
+  );
+
+  if (p.scale !== undefined) {
+    const s = p.scale;
+    result.scale(
+      typeof s === "number" ? new Vector3(s, s, s) : new Vector3(s.x, s.y, s.z),
+    );
+  }
+
+  return result;
+}

package/src/index.test.ts

@@ -0,0 +1,137 @@
+import { Vector3 } from "three";
+import { describe, expect, it, vi } from "vitest";
+
+// The WASM math is covered by Rust unit tests; mock it with a transparent JS
+// model so these tests exercise only the TypeScript wiring — specifically that
+// the basis change is applied on the RIGHT (`multiply`, not `premultiply`) and that
+// degrees are converted before reaching geodeticToXyz.
+const SEMI_MAJOR = 6378137;
+
+vi.mock("@navaramap/engine-api", () => {
+  class LLE {
+    constructor(
+      public lat: number,
+      public lng: number,
+      public height: number,
+    ) {}
+    free() {}
+  }
+  class Vec3 {
+    constructor(
+      public x: number,
+      public y: number,
+      public z: number,
+    ) {}
+    free() {}
+  }
+  return {
+    default: vi.fn(),
+    LLE,
+    Vec3,
+    angleToRadian: (deg: number) => (deg * Math.PI) / 180,
+    angleToDegree: (rad: number) => (rad * 180) / Math.PI,
+    // Transparent model: the rotation is pinned to the NUE basis at
+    // lng 0 / lat 0 (column-major: x = north (0,0,1), y = up (1,0,0),
+    // z = east (0,1,0)), but the ORIGIN is threaded through from the
+    // argument. Hardcoding the translation would make the
+    // degree-conversion assertion below unobservable — it could never
+    // fail, whatever the implementation did.
+    northUpEastToFixedFrame: (origin: Vec3) => [
+      0,
+      0,
+      1,
+      0,
+      1,
+      0,
+      0,
+      0,
+      0,
+      1,
+      0,
+      0,
+      origin.x,
+      origin.y,
+      origin.z,
+      1,
+    ],
+    geodeticToXyz: (lle: LLE) => ({
+      x: SEMI_MAJOR + lle.height,
+      y: lle.lng,
+      z: lle.lat,
+      free() {},
+    }),
+  };
+});
+
+const { headingPitchRollToFixedFrame, westUpNorthToFixedFrame } =
+  await import("./index");
+
+describe("westUpNorthToFixedFrame", () => {
+  it("turns the NUE columns into (-east, up, north)", () => {
+    const wun = westUpNorthToFixedFrame(new Vector3(SEMI_MAJOR, 0, 0));
+
+    // `makeRotationY(Math.PI / 2)` leaves cos(PI/2) = 6.1e-17 in the
+    // matrix, so these are near-equalities, not exact ones.
+    const expectColumn = (
+      index: number,
+      expected: readonly [number, number, number],
+    ) => {
+      const column = new Vector3().setFromMatrixColumn(wun, index);
+      expect(column.x).toBeCloseTo(expected[0], 12);
+      expect(column.y).toBeCloseTo(expected[1], 12);
+      expect(column.z).toBeCloseTo(expected[2], 12);
+    };
+
+    expectColumn(0, [0, -1, 0]); // west
+    expectColumn(1, [1, 0, 0]); // up
+    expectColumn(2, [0, 0, 1]); // north
+  });
+
+  it("keeps the ECEF origin in the translation column", () => {
+    const wun = westUpNorthToFixedFrame(new Vector3(SEMI_MAJOR, 0, 0));
+    const origin = new Vector3().setFromMatrixPosition(wun);
+    expect(origin.x).toBeCloseTo(SEMI_MAJOR, 6);
+    expect(origin.y).toBeCloseTo(0, 12);
+    expect(origin.z).toBeCloseTo(0, 12);
+  });
+});
+
+describe("headingPitchRollToFixedFrame", () => {
+  it("converts lng/lat from degrees before building the origin", () => {
+    // The mock echoes the radian lng/lat back as y/z, so the conversion is
+    // observable in the translation column.
+    const m = headingPitchRollToFixedFrame({ lng: 180, lat: 90, height: 12 });
+    const origin = new Vector3().setFromMatrixPosition(m);
+    expect(origin.x).toBeCloseTo(SEMI_MAJOR + 12, 6);
+    expect(origin.y).toBeCloseTo(Math.PI, 6);
+    expect(origin.z).toBeCloseTo(Math.PI / 2, 6);
+  });
+
+  it("orients the asset front by heading in the WUN frame", () => {
+    // At lng 0 / lat 0 the mocked frame gives ECEF north = +Z, east = +Y.
+    const front = new Vector3(0, 0, 1);
+
+    const north = front
+      .clone()
+      .transformDirection(
+        headingPitchRollToFixedFrame({ lng: 0, lat: 0, heading: 0 }),
+      );
+    expect(north.x).toBeCloseTo(0, 6);
+    expect(north.y).toBeCloseTo(0, 6);
+    expect(north.z).toBeCloseTo(1, 6);
+
+    const east = front
+      .clone()
+      .transformDirection(
+        headingPitchRollToFixedFrame({ lng: 0, lat: 0, heading: 90 }),
+      );
+    expect(east.x).toBeCloseTo(0, 6);
+    expect(east.y).toBeCloseTo(1, 6);
+    expect(east.z).toBeCloseTo(0, 6);
+  });
+
+  it("defaults height to zero", () => {
+    const m = headingPitchRollToFixedFrame({ lng: 0, lat: 0 });
+    expect(new Vector3().setFromMatrixPosition(m).x).toBeCloseTo(SEMI_MAJOR, 6);
+  });
+});

package/src/index.ts

@@ -25,6 +25,12 @@ import initApi, {
 } from "@navaramap/engine-api";
 import { Vector3, Vector2, Matrix4, PerspectiveCamera } from "three";
 
+import {
+  composeHeadingPitchRoll,
+  nueToWunBasis,
+  type GeodeticPlacement,
+} from "./frames";
+
 export type { LatLngHeight, LatLng } from "@navaramap/core";
 export type {
   Window,
@@ -35,6 +41,7 @@ export type {
   Vec2,
   Vec3,
 } from "@navaramap/core";
+export type { GeodeticPlacement } from "./frames";
 
 export * from "./intersection";
 export * from "./rte";
@@ -49,11 +56,13 @@ export async function initNavaraApi() {
 
 /**
  * Converts geodetic coordinates (longitude, latitude, height) to a Cartesian Vector3 in ECEF coordinates.
- * @param lle - Geodetic coordinates (lng in radians, lat in radians, height in meters)
+ * @param lle - Geodetic coordinates (lng in degrees, lat in degrees, height in meters)
  * @returns Cartesian Vector3 in Earth-Centered Earth-Fixed (ECEF) coordinates
  */
 export function geodeticToVector3(lle: LatLngHeight): Vector3 {
-  const pos = geodeticToXyz(new LLE(lle.lat, lle.lng, lle.height));
+  const pos = geodeticToXyz(
+    new LLE(angleToRadian(lle.lat), angleToRadian(lle.lng), lle.height),
+  );
   const result = new Vector3(pos.x, pos.y, pos.z);
   pos.free();
   return result;
@@ -62,12 +71,16 @@ export function geodeticToVector3(lle: LatLngHeight): Vector3 {
 /**
  * Converts a Cartesian Vector3 in ECEF coordinates to geodetic coordinates.
  * @param xyz - Cartesian Vector3 in Earth-Centered Earth-Fixed (ECEF) coordinates
- * @returns Geodetic coordinates (lng in radians, lat in radians, height in meters)
+ * @returns Geodetic coordinates (lng in degrees, lat in degrees, height in meters)
  */
 export function vector3ToGeodetic(xyz: Vector3): LatLngHeight {
   const vec3 = new Vec3(xyz.x, xyz.y, xyz.z);
   const lle = xyzToGeodetic(vec3);
-  const result = { lat: lle.lat, lng: lle.lng, height: lle.height };
+  const result = {
+    lat: angleToDegree(lle.lat),
+    lng: angleToDegree(lle.lng),
+    height: lle.height,
+  };
   lle.free();
   return result;
 }
@@ -148,11 +161,13 @@ export function convertScreenToWorld(
 
 /**
  * Computes the surface normal vector at a geodetic position on the WGS84 ellipsoid.
- * @param lle - Geodetic coordinates (lng in radians, lat in radians, height in meters)
+ * @param lle - Geodetic coordinates (lng in degrees, lat in degrees, height in meters)
  * @returns Unit normal vector pointing outward from the ellipsoid surface
  */
 export function geodeticSurfaceNormal(lle: LatLngHeight): Vector3 {
-  const pos = nvGeodeticSurfaceNormal(new LLE(lle.lat, lle.lng, lle.height));
+  const pos = nvGeodeticSurfaceNormal(
+    new LLE(angleToRadian(lle.lat), angleToRadian(lle.lng), lle.height),
+  );
   const result = new Vector3(pos.x, pos.y, pos.z);
   pos.free();
   return result;
@@ -206,6 +221,53 @@ export function northWestUpToFixedFrame(origin: Vector3): Matrix4 {
   return matrix;
 }
 
+/**
+ * Creates a local West-Up-North (WUN) reference frame transformation matrix at
+ * a position.
+ *
+ * WUN is the only right-handed, Y-up tangent frame whose `+Z` axis is north, so
+ * it agrees with glTF's own convention (front `+Z`, up `+Y`, right `-X`) on all
+ * three axes. An unmodified glTF asset placed in this frame needs **no**
+ * `Rx(+90°)` up-axis correction — the correction is absorbed here, once, as the
+ * `Ry(+90°)` basis change from NUE.
+ *
+ * @param origin - Origin position in ECEF coordinates
+ * @returns 4x4 transformation matrix from WUN to ECEF
+ */
+export function westUpNorthToFixedFrame(origin: Vector3): Matrix4 {
+  return northUpEastToFixedFrame(origin).multiply(nueToWunBasis());
+}
+
+/**
+ * Builds a WUN tangent frame at a geodetic position and composes heading,
+ * pitch, roll and scale onto it — the single call that turns a geographic
+ * placement into a world matrix.
+ *
+ * `heading` is the compass bearing the asset's front faces, where the front is
+ * glTF's own `+Z` — the same convention as `ThreeView.setCamera`. Other globe
+ * engines differ in which axis they treat as an asset's front, so a model
+ * ported from one may need a multiple of 90° added to its heading.
+ *
+ * `lng`/`lat` and all angles here are in **degrees**, matching
+ * `setCamera` and the `geodetic` mesh Descriptor field.
+ *
+ * `heightReference` is intentionally not accepted: resolving terrain-relative
+ * height needs a view to sample from, so it is the Descriptor's job.
+ *
+ * @param placement - Geographic placement in degrees and metres
+ * @returns 4x4 transformation matrix from the placed local frame to ECEF
+ */
+export function headingPitchRollToFixedFrame(
+  placement: Omit<GeodeticPlacement, "heightReference">,
+): Matrix4 {
+  const origin = geodeticToVector3({
+    lng: placement.lng,
+    lat: placement.lat,
+    height: placement.height ?? 0,
+  });
+  return composeHeadingPitchRoll(westUpNorthToFixedFrame(origin), placement);
+}
+
 /**
  * Converts world coordinates to screen coordinates.
  * @param window - Window configuration with width, height, and pixelRatio