@navaramap/three-api 0.1.1 → 0.2.0

package/LICENSE

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

package/dist/featureGeometry.d.ts

@@ -0,0 +1,82 @@
+import { NormalizeWASMClass } from '@navaramap/core';
+import { PolygonMaterial, PolylineMaterial } from '@navaramap/engine-api';
+/**
+ * Geometry builders for standalone polygon and polyline meshes, using the
+ * vector layer's construction. Positions are RTE-encoded.
+ */
+/** A polygon layer material, as a plain object. */
+export type PolygonGeometryMaterial = NormalizeWASMClass<PolygonMaterial>;
+/** A polyline layer material, as a plain object. */
+export type PolylineGeometryMaterial = NormalizeWASMClass<PolylineMaterial>;
+/** A geographic bounding box, in degrees. */
+export type GeographicExtent = {
+    west: number;
+    south: number;
+    east: number;
+    north: number;
+};
+export type PolygonGeometryData = {
+    positionHigh: Float32Array;
+    positionLow: Float32Array;
+    /** Absent for a `clampToGround` polygon. */
+    normal?: Float32Array;
+    /** `xyz` = extrusion direction, `w` = 0 on the bottom cap, 1 on the top. */
+    scaleNormalAndCap: Float32Array;
+    indices: Uint32Array;
+    extent: GeographicExtent;
+};
+export type PolylineGeometryData = {
+    position: Float32Array;
+    positionHigh: Float32Array;
+    positionLow: Float32Array;
+    startHigh: Float32Array;
+    startLow: Float32Array;
+    endHigh: Float32Array;
+    endLow: Float32Array;
+    startNormal: Float32Array;
+    endNormalAndTextureCoordinateNormalizationX: Float32Array;
+    rightNormalAndTextureCoordinateNormalizationY: Float32Array;
+    indices: Uint32Array;
+    extent: GeographicExtent;
+};
+/** Flat `[lng, lat, height, ...]`, or ECEF `[x, y, z, ...]` when geocentric. */
+export type GeometryRing = Float64Array;
+/**
+ * Builds the geometry of one standalone polygon.
+ *
+ * @param rings - Outer ring first, then holes.
+ * @param geocentric - Read the positions as ECEF metres.
+ * @param material - A `polygon` layer material. Outline options are ignored.
+ * @throws When `material` does not deserialize.
+ * @returns `undefined` when the outer ring has fewer than three vertices or is
+ *   collinear.
+ */
+export declare function buildPolygonGeometry(rings: readonly GeometryRing[], geocentric: boolean, material: PolygonGeometryMaterial): PolygonGeometryData | undefined;
+/**
+ * Builds the geometry of one standalone polyline.
+ *
+ * @param positions - Flat `[lng, lat, height, ...]`, or ECEF when `geocentric`.
+ * @param geocentric - Read the positions as ECEF metres.
+ * @param ring - Join a repeated first vertex as a seam instead of two caps.
+ * @param material - A `polyline` layer material.
+ * @throws When `material` does not deserialize.
+ * @returns `undefined` when fewer than two distinct positions remain.
+ */
+export declare function buildPolylineGeometry(positions: Float64Array, geocentric: boolean, ring: boolean, material: PolylineGeometryMaterial): PolylineGeometryData | undefined;
+/** A height range in metres, relative to the ellipsoid. */
+export type HeightRange = {
+    min: number;
+    max: number;
+};
+/**
+ * `[min, max]` height a clamp-to-ground polygon volume over `extent` must
+ * span to enclose the ground heights `range`, given the flat cap triangles
+ * {@link buildPolygonGeometry} produces.
+ */
+export declare function polygonGroundVolume(range: HeightRange, extent: GeographicExtent): [number, number];
+/**
+ * `[min, max]` height a clamp-to-ground polyline volume over `extent` must
+ * span to enclose the ground heights `range`, given the straight segments
+ * {@link buildPolylineGeometry} produces.
+ */
+export declare function polylineGroundVolume(range: HeightRange, extent: GeographicExtent): [number, number];

package/dist/index.d.ts

@@ -4,6 +4,7 @@ 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 './featureGeometry';
 export * from './intersection';
 export * from './rte';
 export * from './ellipsoidGeodesic';
@@ -49,6 +50,14 @@ export declare function convertScreenToWorld(windowObject: WindowObject, camera:
  * @returns Unit normal vector pointing outward from the ellipsoid surface
  */
 export declare function geodeticSurfaceNormal(lle: LatLngHeight): Vector3;
+/**
+ * Projects a Cartesian position onto the WGS84 ellipsoid surface along the
+ * geodetic normal.
+ * @param xyz - Cartesian Vector3 in Earth-Centered Earth-Fixed (ECEF) coordinates
+ * @returns The surface position in ECEF coordinates, or undefined when the
+ * position is too close to the ellipsoid's center to project
+ */
+export declare function scaleToGeodeticSurface(xyz: Vector3): Vector3 | undefined;
 /**
  * Creates a local East-North-Up (ENU) reference frame transformation matrix at a position.
  * @param origin - Origin position in ECEF coordinates

package/dist/index.js

@@ -1,4 +1,4 @@
-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 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, buildPolygonGeometry as d, buildPolylineGeometry as f, eastNorthUpToFixedFrame as p, encodePosition as m, geodeticSurfaceNormal as h, geodeticToXyz as g, getHeightFromEllipsoid as _, getPickRay as v, getPlaneFromPointNormal as y, getRayPlaneIntersection as b, getWGS84Eccentricity as ee, getWGS84EccentricitySquared as te, getWGS84Flattening as ne, getWGS84SemiMajorAxis as re, getWGS84SemiMinorAxis as ie, northEastDownToFixedFrame as ae, northUpEastToFixedFrame as oe, northWestUpToFixedFrame as x, polygonGroundVolume as S, polylineGroundVolume as C, scaleToGeodeticSurface 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() {
@@ -13,44 +13,118 @@ function I(e, t) {
 	return n;
 }
 //#endregion
+//#region src/featureGeometry.ts
+function L(e) {
+	return {
+		west: l(e.west),
+		south: l(e.south),
+		east: l(e.east),
+		north: l(e.north)
+	};
+}
+function R(e) {
+	let t = 0;
+	for (let n of e) t += n.length;
+	let n = new Float64Array(t), r = 0;
+	for (let t of e) n.set(t, r), r += t.length;
+	return n;
+}
+function z(e) {
+	let t = new Uint32Array(e.length);
+	for (let n = 0; n < e.length; n++) t[n] = e[n].length / 3;
+	return t;
+}
+function B(e, t, n) {
+	let r = d(R(e), z(e), t, n);
+	if (r) try {
+		let e = r.position_3d_high(), t = r.position_3d_low(), n = r.extent;
+		if (!e || !t || !n) throw Error("buildPolygonGeometry: incomplete RTE geometry");
+		let i = r.scale_normal_and_cap();
+		if (!i) throw Error("buildPolygonGeometry: missing extrusion attribute");
+		return {
+			positionHigh: e,
+			positionLow: t,
+			normal: r.normal(),
+			scaleNormalAndCap: i,
+			indices: r.indices(),
+			extent: L(n)
+		};
+	} finally {
+		r.free();
+	}
+}
+function V(e, t, n, r) {
+	let i = f(e, t, n, r);
+	if (i) try {
+		let e = i.position_high(), t = i.position_low(), n = i.start_high(), r = i.start_low(), a = i.end_high(), o = i.end_low(), s = i.start_normals(), c = i.end_normal_and_texture_coordinate_normalization_x(), l = i.extent;
+		if (!e || !t || !n || !r || !a || !o || !s || !c || !l) throw Error("buildPolylineGeometry: incomplete RTE geometry");
+		return {
+			position: i.position(),
+			positionHigh: e,
+			positionLow: t,
+			startHigh: n,
+			startLow: r,
+			endHigh: a,
+			endLow: o,
+			startNormal: s,
+			endNormalAndTextureCoordinateNormalizationX: c,
+			rightNormalAndTextureCoordinateNormalizationY: i.right_normal_and_texture_coordinate_normalization_y(),
+			indices: i.indices(),
+			extent: L(l)
+		};
+	} finally {
+		i.free();
+	}
+}
+function H(e, t, n) {
+	let r = e(t.min, t.max, u(n.west), u(n.south), u(n.east), u(n.north));
+	return [r[0], r[1]];
+}
+function U(e, t) {
+	return H(S, e, t);
+}
+function W(e, t) {
+	return H(C, e, t);
+}
+//#endregion
 //#region src/intersection.ts
-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);
+function G(e, t) {
+	let n = new s(e.x, e.y, e.z), r = new s(t.x, t.y, t.z), i = y(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 R(e, n, r) {
+function K(e, n, r) {
 	let i = new c(e.width, e.height, e.pixelRatio);
 	i.width *= i.pixelRatio, i.height *= i.pixelRatio;
-	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);
+	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 = v(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);
+function q(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 = y(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 = b(n, r);
 	if (a) {
 		let e = new P(a.x, a.y, a.z);
 		return a.free(), e;
 	}
 }
-function B(e) {
+function se(e) {
 	let t = new s(e.x, e.y, e.z);
-	return h(t);
+	return _(t);
 }
 //#endregion
 //#region src/rte.ts
-var V = Object.freeze({ value: 1 });
-function H(e, t = new P(), n = new P()) {
-	let r = f(e.x, e.y, e.z);
+var ce = Object.freeze({ value: 1 });
+function le(e, t = new P(), n = new P()) {
+	let r = m(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 ne = (e, t, n = new A()) => {
+var ue = (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 U(e, t, n = new P(), r = new A()) {
+function de(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, {
@@ -58,14 +132,14 @@ function U(e, t, n = new P(), r = new A()) {
 		rotationScale: r
 	};
 }
-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 = {
+var J = new A(), Y = new P(), fe = (e, t) => {
+	J.copy(t).invert(), Y.copy(e).applyMatrix4(J);
+	let n = m(Y.x, Y.y, Y.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;
-}, q = class {
+}, pe = class {
 	_raw;
 	constructor(e, t) {
 		this._raw = new n(new r(u(e.lat), u(e.lng), e.height), new r(u(t.lat), u(t.lng), t.height));
@@ -121,14 +195,14 @@ var W = new A(), G = new P(), K = (e, t) => {
 };
 //#endregion
 //#region src/index.ts
-async function J() {
+async function me() {
 	await e();
 }
-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);
+function X(e) {
+	let t = g(new r(u(e.lat), u(e.lng), e.height)), n = new P(t.x, t.y, t.z);
 	return t.free(), n;
 }
-function X(e) {
+function he(e) {
 	let t = new s(e.x, e.y, e.z), n = D(t), r = {
 		lat: l(n.lat),
 		lng: l(n.lng),
@@ -136,13 +210,13 @@ function X(e) {
 	};
 	return n.free(), r;
 }
-function Z(e) {
+function ge(e) {
 	return u(e);
 }
-function re(e) {
+function _e(e) {
 	return l(e);
 }
-function ie(e, n, r) {
+function ve(e, n, r) {
 	let i = new c(e.width, e.height, e.pixelRatio);
 	i.width *= i.pixelRatio, i.height *= i.pixelRatio;
 	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));
@@ -150,37 +224,43 @@ function ie(e, n, r) {
 	let f = new P(d.x, d.y, d.z);
 	return d.free(), f;
 }
-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);
+function ye(e) {
+	let t = h(new r(u(e.lat), u(e.lng), e.height)), n = new P(t.x, t.y, t.z);
+	return t.free(), n;
+}
+function be(e) {
+	let t = w(new s(e.x, e.y, e.z));
+	if (!t) return;
+	let 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);
+function xe(e) {
+	let t = new s(e.x, e.y, e.z), n = p(t);
 	return new A().fromArray(n);
 }
-function se(e) {
-	let t = new s(e.x, e.y, e.z), n = ee(t);
+function Se(e) {
+	let t = new s(e.x, e.y, e.z), n = ae(t);
 	return new A().fromArray(n);
 }
-function Q(e) {
-	let t = new s(e.x, e.y, e.z), n = te(t);
+function Z(e) {
+	let t = new s(e.x, e.y, e.z), n = oe(t);
 	return new A().fromArray(n);
 }
-function ce(e) {
-	let t = new s(e.x, e.y, e.z), n = w(t);
+function Ce(e) {
+	let t = new s(e.x, e.y, e.z), n = x(t);
 	return new A().fromArray(n);
 }
-function $(e) {
-	return Q(e).multiply(F());
+function Q(e) {
+	return Z(e).multiply(F());
 }
-function le(e) {
-	return I($(Y({
+function $(e) {
+	return I(Q(X({
 		lng: e.lng,
 		lat: e.lat,
 		height: e.height ?? 0
 	})), e);
 }
-function ue(e, n, r) {
+function we(e, n, r) {
 	let i = new c(e.width, e.height, e.pixelRatio);
 	i.width *= i.pixelRatio, i.height *= i.pixelRatio;
 	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));
@@ -188,20 +268,20 @@ function ue(e, n, r) {
 	let f = new N(d.x, d.y);
 	return d.free(), f;
 }
-function de() {
-	return S();
+function Te() {
+	return re();
 }
-function fe() {
-	return C();
+function Ee() {
+	return ie();
 }
-function pe() {
-	return b();
+function De() {
+	return te();
 }
-function me() {
-	return x();
+function Oe() {
+	return ne();
 }
-function he() {
-	return y();
+function ke() {
+	return ee();
 }
 //#endregion
-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 };
+export { pe as EllipsoidGeodesic, ce as RTE_ONE_UNIFORM, B as buildPolygonGeometry, V as buildPolylineGeometry, fe as calcCameraPosition, ue as calcModelMatrixRTE, de as composeWorldMatrixForRTE, ve as convertScreenToWorld, we as convertWorldToScreen, ge as degreeToRadian, xe as eastNorthUpToFixedFrame, le as encodePositionRTE, ye as geodeticSurfaceNormal, X as geodeticToVector3, se as getHeightFromEllipsoid, K as getPickRay, G as getPlaneFromPointNormal, q as getRayPlaneIntersection, ke as getWGS84Eccentricity, De as getWGS84EccentricitySquared, Oe as getWGS84Flattening, Te as getWGS84SemiMajorAxis, Ee as getWGS84SemiMinorAxis, $ as headingPitchRollToFixedFrame, me as initNavaraApi, Se as northEastDownToFixedFrame, Z as northUpEastToFixedFrame, Ce as northWestUpToFixedFrame, U as polygonGroundVolume, W as polylineGroundVolume, _e as radianToDegree, be as scaleToGeodeticSurface, he as vector3ToGeodetic, Q as westUpNorthToFixedFrame };

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||!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});
+(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){return{west:(0,t.angleToDegree)(e.west),south:(0,t.angleToDegree)(e.south),east:(0,t.angleToDegree)(e.east),north:(0,t.angleToDegree)(e.north)}}function p(e){let t=0;for(let n of e)t+=n.length;let n=new Float64Array(t),r=0;for(let t of e)n.set(t,r),r+=t.length;return n}function m(e){let t=new Uint32Array(e.length);for(let n=0;n<e.length;n++)t[n]=e[n].length/3;return t}function h(e,n,r){let i=(0,t.buildPolygonGeometry)(p(e),m(e),n,r);if(i)try{let e=i.position_3d_high(),t=i.position_3d_low(),n=i.extent;if(!e||!t||!n)throw Error(`buildPolygonGeometry: incomplete RTE geometry`);let r=i.scale_normal_and_cap();if(!r)throw Error(`buildPolygonGeometry: missing extrusion attribute`);return{positionHigh:e,positionLow:t,normal:i.normal(),scaleNormalAndCap:r,indices:i.indices(),extent:f(n)}}finally{i.free()}}function g(e,n,r,i){let a=(0,t.buildPolylineGeometry)(e,n,r,i);if(a)try{let e=a.position_high(),t=a.position_low(),n=a.start_high(),r=a.start_low(),i=a.end_high(),o=a.end_low(),s=a.start_normals(),c=a.end_normal_and_texture_coordinate_normalization_x(),l=a.extent;if(!e||!t||!n||!r||!i||!o||!s||!c||!l)throw Error(`buildPolylineGeometry: incomplete RTE geometry`);return{position:a.position(),positionHigh:e,positionLow:t,startHigh:n,startLow:r,endHigh:i,endLow:o,startNormal:s,endNormalAndTextureCoordinateNormalizationX:c,rightNormalAndTextureCoordinateNormalizationY:a.right_normal_and_texture_coordinate_normalization_y(),indices:a.indices(),extent:f(l)}}finally{a.free()}}function _(e,n,r){let i=e(n.min,n.max,(0,t.angleToRadian)(r.west),(0,t.angleToRadian)(r.south),(0,t.angleToRadian)(r.east),(0,t.angleToRadian)(r.north));return[i[0],i[1]]}function v(e,n){return _(t.polygonGroundVolume,e,n)}function y(e,n){return _(t.polylineGroundVolume,e,n)}function b(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 x(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 S(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 C(e){let n=new t.Vec3(e.x,e.y,e.z);return(0,t.getHeightFromEllipsoid)(n)}var w=Object.freeze({value:1});function T(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 E=(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 D(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 O=new n.Matrix4,k=new n.Vector3,A=(e,r)=>{O.copy(r).invert(),k.copy(e).applyMatrix4(O);let i=(0,t.encodePosition)(k.x,k.y,k.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},j=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 M(){await(0,t.default)()}function N(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 P(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 F(e){return(0,t.angleToRadian)(e)}function I(e){return(0,t.angleToDegree)(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.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 R(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 z(e){let r=(0,t.scaleToGeodeticSurface)(new t.Vec3(e.x,e.y,e.z));if(!r)return;let i=new n.Vector3(r.x,r.y,r.z);return r.free(),i}function B(e){let r=new t.Vec3(e.x,e.y,e.z),i=(0,t.eastNorthUpToFixedFrame)(r);return new n.Matrix4().fromArray(i)}function V(e){let r=new t.Vec3(e.x,e.y,e.z),i=(0,t.northEastDownToFixedFrame)(r);return new n.Matrix4().fromArray(i)}function H(e){let r=new t.Vec3(e.x,e.y,e.z),i=(0,t.northUpEastToFixedFrame)(r);return new n.Matrix4().fromArray(i)}function U(e){let r=new t.Vec3(e.x,e.y,e.z),i=(0,t.northWestUpToFixedFrame)(r);return new n.Matrix4().fromArray(i)}function W(e){return H(e).multiply(u())}function G(e){return d(W(N({lng:e.lng,lat:e.lat,height:e.height??0})),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.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 q(){return(0,t.getWGS84SemiMajorAxis)()}function J(){return(0,t.getWGS84SemiMinorAxis)()}function Y(){return(0,t.getWGS84EccentricitySquared)()}function X(){return(0,t.getWGS84Flattening)()}function Z(){return(0,t.getWGS84Eccentricity)()}e.EllipsoidGeodesic=j,e.RTE_ONE_UNIFORM=w,e.buildPolygonGeometry=h,e.buildPolylineGeometry=g,e.calcCameraPosition=A,e.calcModelMatrixRTE=E,e.composeWorldMatrixForRTE=D,e.convertScreenToWorld=L,e.convertWorldToScreen=K,e.degreeToRadian=F,e.eastNorthUpToFixedFrame=B,e.encodePositionRTE=T,e.geodeticSurfaceNormal=R,e.geodeticToVector3=N,e.getHeightFromEllipsoid=C,e.getPickRay=x,e.getPlaneFromPointNormal=b,e.getRayPlaneIntersection=S,e.getWGS84Eccentricity=Z,e.getWGS84EccentricitySquared=Y,e.getWGS84Flattening=X,e.getWGS84SemiMajorAxis=q,e.getWGS84SemiMinorAxis=J,e.headingPitchRollToFixedFrame=G,e.initNavaraApi=M,e.northEastDownToFixedFrame=V,e.northUpEastToFixedFrame=H,e.northWestUpToFixedFrame=U,e.polygonGroundVolume=v,e.polylineGroundVolume=y,e.radianToDegree=I,e.scaleToGeodeticSurface=z,e.vector3ToGeodetic=P,e.westUpNorthToFixedFrame=W});

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@navaramap/three-api",
   "type": "module",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "main": "dist/index.umd.cjs",
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -12,7 +12,7 @@
   "license": "MIT OR Apache-2.0",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/reearth/navara.git",
+    "url": "git+https://github.com/maplibre/navara.git",
     "directory": "web/navara_three_api"
   },
   "publishConfig": {
@@ -22,11 +22,11 @@
     "three": ">=0.183.0"
   },
   "dependencies": {
-    "@navaramap/core": "0.1.1",
-    "@navaramap/engine-api": "0.1.1"
+    "@navaramap/core": "0.2.0",
+    "@navaramap/engine-api": "0.2.0"
   },
   "devDependencies": {
-    "@types/three": "0.185.1",
+    "@types/three": "0.185.4",
     "three": "0.185.1"
   },
   "scripts": {

package/src/featureGeometry.ts

@@ -0,0 +1,255 @@
+import type { NormalizeWASMClass } from "@navaramap/core";
+import {
+  buildPolygonGeometry as buildPolygonGeometryWasm,
+  buildPolylineGeometry as buildPolylineGeometryWasm,
+  polygonGroundVolume as polygonGroundVolumeWasm,
+  polylineGroundVolume as polylineGroundVolumeWasm,
+  angleToDegree,
+  angleToRadian,
+  type PolygonMaterial,
+  type PolylineMaterial,
+} from "@navaramap/engine-api";
+
+/**
+ * Geometry builders for standalone polygon and polyline meshes, using the
+ * vector layer's construction. Positions are RTE-encoded.
+ */
+
+/** A polygon layer material, as a plain object. */
+export type PolygonGeometryMaterial = NormalizeWASMClass<PolygonMaterial>;
+
+/** A polyline layer material, as a plain object. */
+export type PolylineGeometryMaterial = NormalizeWASMClass<PolylineMaterial>;
+
+/** A geographic bounding box, in degrees. */
+export type GeographicExtent = {
+  west: number;
+  south: number;
+  east: number;
+  north: number;
+};
+
+export type PolygonGeometryData = {
+  positionHigh: Float32Array;
+  positionLow: Float32Array;
+  /** Absent for a `clampToGround` polygon. */
+  normal?: Float32Array;
+  /** `xyz` = extrusion direction, `w` = 0 on the bottom cap, 1 on the top. */
+  scaleNormalAndCap: Float32Array;
+  indices: Uint32Array;
+  extent: GeographicExtent;
+};
+
+export type PolylineGeometryData = {
+  position: Float32Array;
+  positionHigh: Float32Array;
+  positionLow: Float32Array;
+  startHigh: Float32Array;
+  startLow: Float32Array;
+  endHigh: Float32Array;
+  endLow: Float32Array;
+  startNormal: Float32Array;
+  endNormalAndTextureCoordinateNormalizationX: Float32Array;
+  rightNormalAndTextureCoordinateNormalizationY: Float32Array;
+  indices: Uint32Array;
+  extent: GeographicExtent;
+};
+
+/** Flat `[lng, lat, height, ...]`, or ECEF `[x, y, z, ...]` when geocentric. */
+export type GeometryRing = Float64Array;
+
+function toDegrees(extent: {
+  west: number;
+  south: number;
+  east: number;
+  north: number;
+}): GeographicExtent {
+  return {
+    west: angleToDegree(extent.west),
+    south: angleToDegree(extent.south),
+    east: angleToDegree(extent.east),
+    north: angleToDegree(extent.north),
+  };
+}
+
+/** Concatenates rings; the builder splits them by `ringLengths`. */
+function concatRings(rings: readonly GeometryRing[]): Float64Array {
+  let total = 0;
+  for (const ring of rings) total += ring.length;
+
+  const coordinates = new Float64Array(total);
+  let offset = 0;
+  for (const ring of rings) {
+    coordinates.set(ring, offset);
+    offset += ring.length;
+  }
+  return coordinates;
+}
+
+function ringLengths(rings: readonly GeometryRing[]): Uint32Array {
+  const lengths = new Uint32Array(rings.length);
+  for (let i = 0; i < rings.length; i++) {
+    lengths[i] = rings[i].length / 3;
+  }
+  return lengths;
+}
+
+/**
+ * Builds the geometry of one standalone polygon.
+ *
+ * @param rings - Outer ring first, then holes.
+ * @param geocentric - Read the positions as ECEF metres.
+ * @param material - A `polygon` layer material. Outline options are ignored.
+ * @throws When `material` does not deserialize.
+ * @returns `undefined` when the outer ring has fewer than three vertices or is
+ *   collinear.
+ */
+export function buildPolygonGeometry(
+  rings: readonly GeometryRing[],
+  geocentric: boolean,
+  material: PolygonGeometryMaterial,
+): PolygonGeometryData | undefined {
+  const built = buildPolygonGeometryWasm(
+    concatRings(rings),
+    ringLengths(rings),
+    geocentric,
+    material,
+  );
+  if (!built) return undefined;
+
+  try {
+    const positionHigh = built.position_3d_high();
+    const positionLow = built.position_3d_low();
+    const extent = built.extent;
+    if (!positionHigh || !positionLow || !extent) {
+      throw new Error("buildPolygonGeometry: incomplete RTE geometry");
+    }
+
+    const scaleNormalAndCap = built.scale_normal_and_cap();
+    if (!scaleNormalAndCap) {
+      throw new Error("buildPolygonGeometry: missing extrusion attribute");
+    }
+
+    return {
+      positionHigh,
+      positionLow,
+      normal: built.normal(),
+      scaleNormalAndCap,
+      indices: built.indices(),
+      extent: toDegrees(extent),
+    };
+  } finally {
+    built.free();
+  }
+}
+
+/**
+ * Builds the geometry of one standalone polyline.
+ *
+ * @param positions - Flat `[lng, lat, height, ...]`, or ECEF when `geocentric`.
+ * @param geocentric - Read the positions as ECEF metres.
+ * @param ring - Join a repeated first vertex as a seam instead of two caps.
+ * @param material - A `polyline` layer material.
+ * @throws When `material` does not deserialize.
+ * @returns `undefined` when fewer than two distinct positions remain.
+ */
+export function buildPolylineGeometry(
+  positions: Float64Array,
+  geocentric: boolean,
+  ring: boolean,
+  material: PolylineGeometryMaterial,
+): PolylineGeometryData | undefined {
+  const built = buildPolylineGeometryWasm(
+    positions,
+    geocentric,
+    ring,
+    material,
+  );
+  if (!built) return undefined;
+
+  try {
+    const positionHigh = built.position_high();
+    const positionLow = built.position_low();
+    const startHigh = built.start_high();
+    const startLow = built.start_low();
+    const endHigh = built.end_high();
+    const endLow = built.end_low();
+    const startNormal = built.start_normals();
+    const endNormal = built.end_normal_and_texture_coordinate_normalization_x();
+    const extent = built.extent;
+    if (
+      !positionHigh ||
+      !positionLow ||
+      !startHigh ||
+      !startLow ||
+      !endHigh ||
+      !endLow ||
+      !startNormal ||
+      !endNormal ||
+      !extent
+    ) {
+      throw new Error("buildPolylineGeometry: incomplete RTE geometry");
+    }
+
+    return {
+      position: built.position(),
+      positionHigh,
+      positionLow,
+      startHigh,
+      startLow,
+      endHigh,
+      endLow,
+      startNormal,
+      endNormalAndTextureCoordinateNormalizationX: endNormal,
+      rightNormalAndTextureCoordinateNormalizationY:
+        built.right_normal_and_texture_coordinate_normalization_y(),
+      indices: built.indices(),
+      extent: toDegrees(extent),
+    };
+  } finally {
+    built.free();
+  }
+}
+
+/** A height range in metres, relative to the ellipsoid. */
+export type HeightRange = { min: number; max: number };
+
+function groundVolume(
+  build: typeof polygonGroundVolumeWasm,
+  range: HeightRange,
+  extent: GeographicExtent,
+): [number, number] {
+  const heights = build(
+    range.min,
+    range.max,
+    angleToRadian(extent.west),
+    angleToRadian(extent.south),
+    angleToRadian(extent.east),
+    angleToRadian(extent.north),
+  );
+  return [heights[0], heights[1]];
+}
+
+/**
+ * `[min, max]` height a clamp-to-ground polygon volume over `extent` must
+ * span to enclose the ground heights `range`, given the flat cap triangles
+ * {@link buildPolygonGeometry} produces.
+ */
+export function polygonGroundVolume(
+  range: HeightRange,
+  extent: GeographicExtent,
+): [number, number] {
+  return groundVolume(polygonGroundVolumeWasm, range, extent);
+}
+
+/**
+ * `[min, max]` height a clamp-to-ground polyline volume over `extent` must
+ * span to enclose the ground heights `range`, given the straight segments
+ * {@link buildPolylineGeometry} produces.
+ */
+export function polylineGroundVolume(
+  range: HeightRange,
+  extent: GeographicExtent,
+): [number, number] {
+  return groundVolume(polylineGroundVolumeWasm, range, extent);
+}

package/src/index.ts

@@ -13,6 +13,7 @@ import initApi, {
   screenToWorld,
   worldToScreen,
   geodeticSurfaceNormal as nvGeodeticSurfaceNormal,
+  scaleToGeodeticSurface as nvScaleToGeodeticSurface,
   eastNorthUpToFixedFrame as nvEastNorthUpToFixedFrame,
   northEastDownToFixedFrame as nvNorthEastDownToFixedFrame,
   northUpEastToFixedFrame as nvNorthUpEastToFixedFrame,
@@ -43,6 +44,7 @@ export type {
 } from "@navaramap/core";
 export type { GeodeticPlacement } from "./frames";
 
+export * from "./featureGeometry";
 export * from "./intersection";
 export * from "./rte";
 export * from "./ellipsoidGeodesic";
@@ -173,6 +175,23 @@ export function geodeticSurfaceNormal(lle: LatLngHeight): Vector3 {
   return result;
 }
 
+/**
+ * Projects a Cartesian position onto the WGS84 ellipsoid surface along the
+ * geodetic normal.
+ * @param xyz - Cartesian Vector3 in Earth-Centered Earth-Fixed (ECEF) coordinates
+ * @returns The surface position in ECEF coordinates, or undefined when the
+ * position is too close to the ellipsoid's center to project
+ */
+export function scaleToGeodeticSurface(xyz: Vector3): Vector3 | undefined {
+  const pos = nvScaleToGeodeticSurface(new Vec3(xyz.x, xyz.y, xyz.z));
+  if (!pos) {
+    return undefined;
+  }
+  const result = new Vector3(pos.x, pos.y, pos.z);
+  pos.free();
+  return result;
+}
+
 /**
  * Creates a local East-North-Up (ENU) reference frame transformation matrix at a position.
  * @param origin - Origin position in ECEF coordinates