@navaramap/three-api 0.0.6 → 0.0.8

package/dist/ellipsoidGeodesic.d.ts

@@ -27,6 +27,13 @@ export declare class EllipsoidGeodesic {
     constructor(start: LatLngHeight, end: LatLngHeight);
     /** Distance in meters between start and end points */
     get distance(): number;
+    /**
+     * Whether the geodesic solve converged. `false` for near-antipodal
+     * endpoints, where `distance` is only a rough estimate and the
+     * interpolation methods snap to the endpoints instead of following the
+     * unreliable solution.
+     */
+    get converged(): boolean;
     /** Heading at the start point in radians */
     get startHeading(): number;
     /** Heading at the end point in radians */

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';
@@ -71,6 +73,41 @@ 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.
+ *
+ * NOTE: unlike {@link geodeticToVector3} and the other helpers in this module,
+ * `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 ee, getWGS84SemiMinorAxis as te, northEastDownToFixedFrame as ne, northUpEastToFixedFrame as S, northWestUpToFixedFrame as C, screenToWorld as w, worldToScreen as T, xyzToGeodetic as E } from "@navaramap/engine-api";
+import { Euler as D, MathUtils as O, Matrix4 as k, Plane as A, Ray as j, Vector2 as M, Vector3 as N } from "three";
+//#region src/frames.ts
+function P() {
+	return new k().makeRotationY(Math.PI / 2);
+}
+function F(e, t) {
+	let n = new k().multiplyMatrices(e, new k().makeRotationFromEuler(new D(-O.degToRad(t.pitch ?? 0), -O.degToRad(t.heading ?? 0), O.degToRad(t.roll ?? 0), "YXZ")));
+	if (t.scale !== void 0) {
+		let e = t.scale;
+		n.scale(typeof e == "number" ? new N(e, e, e) : new N(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 I(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 N(i.normal.x, i.normal.y, i.normal.z), o = new A(a, -i.distance);
+	return i.free(), o;
 }
-function F(e, n, r) {
+function L(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 N(d.origin.x, d.origin.y, d.origin.z), p = new N(d.direction.x, d.direction.y, d.direction.z), m = new j(f, p);
+	return d.free(), m;
+}
+function R(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 N(a.x, a.y, a.z);
+		return a.free(), e;
 	}
 }
-function te(e) {
-	return m(new s(e.x, e.y, e.z));
+function z(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 B = Object.freeze({ value: 1 });
+function V(e, t = new N(), n = new N()) {
+	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 re = (e, t, n = new k()) => {
 	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 H(e, t, n = new N(), r = new k()) {
 	r.multiplyMatrices(e, t), n.setFromMatrixPosition(r);
 	let i = r.elements;
 	return i[12] = 0, i[13] = 0, i[14] = 0, {
@@ -44,14 +58,14 @@ 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 = {
+var U = new k(), W = new N(), G = (e, t) => {
+	U.copy(t).invert(), W.copy(e).applyMatrix4(U);
+	let n = f(W.x, W.y, W.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)
 	};
 	return n.free(), a;
-}, W = class {
+}, K = 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));
@@ -59,6 +73,9 @@ var V = new k(), H = new N(), U = (e, t) => {
 	get distance() {
 		return this._raw.distance;
 	}
+	get converged() {
+		return this._raw.converged;
+	}
 	get startHeading() {
 		return this._raw.start_heading;
 	}
@@ -104,77 +121,87 @@ var V = new k(), H = new N(), U = (e, t) => {
 };
 //#endregion
 //#region src/index.ts
-async function G() {
+async function q() {
 	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 J(e) {
+	let t = m(new r(e.lat, e.lng, e.height)), n = new N(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 Y(e) {
+	let t = new s(e.x, e.y, e.z), n = E(t), r = {
+		lat: n.lat,
+		lng: n.lng,
+		height: n.height
 	};
-	return t.free(), n;
+	return n.free(), r;
 }
-function J(e) {
+function X(e) {
 	return u(e);
 }
-function Y(e) {
+function ie(e) {
 	return l(e);
 }
-function X(e, n, r) {
+function ae(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 = w(i, s, l, new o(r.x, r.y));
+	if (!d) return;
+	let f = new N(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 oe(e) {
+	let t = p(new r(e.lat, e.lng, e.height)), n = new N(t.x, t.y, t.z);
 	return t.free(), n;
 }
+function Z(e) {
+	let t = new s(e.x, e.y, e.z), n = d(t);
+	return new k().fromArray(n);
+}
+function se(e) {
+	let t = new s(e.x, e.y, e.z), n = ne(t);
+	return new k().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 = S(t);
+	return new k().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 = C(t);
+	return new k().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(P());
 }
-function ie(e) {
-	let t = T(new s(e.x, e.y, e.z));
-	return new k().fromArray(t);
+function le(e) {
+	return F($(J({
+		lng: O.degToRad(e.lng),
+		lat: O.degToRad(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;
-}
-function oe() {
-	return x();
+	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 = T(i, o, l, new s(r.x, r.y, r.z));
+	if (!d) return;
+	let f = new M(d.x, d.y);
+	return d.free(), f;
 }
-function $() {
-	return S();
+function de() {
+	return ee();
 }
-function se() {
-	return y();
+function fe() {
+	return te();
 }
-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 { K as EllipsoidGeodesic, B as RTE_ONE_UNIFORM, G as calcCameraPosition, re as calcModelMatrixRTE, H as composeWorldMatrixForRTE, ae as convertScreenToWorld, ue as convertWorldToScreen, X as degreeToRadian, Z as eastNorthUpToFixedFrame, V as encodePositionRTE, oe as geodeticSurfaceNormal, J as geodeticToVector3, z as getHeightFromEllipsoid, L as getPickRay, I as getPlaneFromPointNormal, R as getRayPlaneIntersection, he as getWGS84Eccentricity, pe as getWGS84EccentricitySquared, me as getWGS84Flattening, de as getWGS84SemiMajorAxis, fe as getWGS84SemiMinorAxis, le as headingPitchRollToFixedFrame, q as initNavaraApi, se as northEastDownToFixedFrame, Q as northUpEastToFixedFrame, ce as northWestUpToFixedFrame, ie as radianToDegree, Y 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 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(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 w(){await(0,t.default)()}function T(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 E(e){let n=new t.Vec3(e.x,e.y,e.z),r=(0,t.xyzToGeodetic)(n),i={lat:r.lat,lng: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(e.lat,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:n.MathUtils.degToRad(e.lng),lat:n.MathUtils.degToRad(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.6",
+  "version": "0.0.8",
   "main": "dist/index.umd.cjs",
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -22,8 +22,8 @@
     "three": ">=0.183.0"
   },
   "dependencies": {
-    "@navaramap/core": "0.0.6",
-    "@navaramap/engine-api": "0.0.6"
+    "@navaramap/core": "0.0.8",
+    "@navaramap/engine-api": "0.0.8"
   },
   "devDependencies": {
     "@types/three": "0.185.1",

package/src/ellipsoidGeodesic.ts

@@ -42,6 +42,16 @@ export class EllipsoidGeodesic {
     return this._raw.distance;
   }
 
+  /**
+   * Whether the geodesic solve converged. `false` for near-antipodal
+   * endpoints, where `distance` is only a rough estimate and the
+   * interpolation methods snap to the endpoints instead of following the
+   * unreliable solution.
+   */
+  get converged(): boolean {
+    return this._raw.converged;
+  }
+
   /** Heading at the start point in radians */
   get startHeading(): number {
     return this._raw.start_heading;

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,135 @@
+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,
+    // 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

@@ -23,7 +23,13 @@ import initApi, {
   getWGS84Flattening as nvGetWGS84Flattening,
   getWGS84Eccentricity as nvGetWGS84Eccentricity,
 } from "@navaramap/engine-api";
-import { Vector3, Vector2, Matrix4, PerspectiveCamera } from "three";
+import { Vector3, Vector2, Matrix4, MathUtils, PerspectiveCamera } from "three";
+
+import {
+  composeHeadingPitchRoll,
+  nueToWunBasis,
+  type GeodeticPlacement,
+} from "./frames";
 
 export type { LatLngHeight, LatLng } from "@navaramap/core";
 export type {
@@ -35,6 +41,7 @@ export type {
   Vec2,
   Vec3,
 } from "@navaramap/core";
+export type { GeodeticPlacement } from "./frames";
 
 export * from "./intersection";
 export * from "./rte";
@@ -206,6 +213,54 @@ 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.
+ *
+ * NOTE: unlike {@link geodeticToVector3} and the other helpers in this module,
+ * `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: MathUtils.degToRad(placement.lng),
+    lat: MathUtils.degToRad(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