cesium-to-three 0.1.0

package/dist/types/lib/ground/math/ellipsoid-geodesic.d.ts

@@ -0,0 +1,93 @@
+import type { Cartographic } from './cartographic';
+/** Vincenty 椭球（贴地线只用 WGS84，公开 ellipsoid 也只暴露这两项）。 */
+export interface GeodesicEllipsoid {
+    maximumRadius: number;
+    minimumRadius: number;
+}
+/** 插值预算常量（一次 `vincentyInverseFormula` + `setConstants` 后定型）。 */
+interface GeodesicConstants {
+    a: number;
+    b: number;
+    f: number;
+    cosineHeading: number;
+    sineHeading: number;
+    tanU: number;
+    cosineU: number;
+    sineU: number;
+    sigma: number;
+    sineAlpha: number;
+    sineSquaredAlpha: number;
+    cosineSquaredAlpha: number;
+    cosineAlpha: number;
+    u2Over4: number;
+    u4Over16: number;
+    u6Over64: number;
+    u8Over256: number;
+    a0: number;
+    a1: number;
+    a2: number;
+    a3: number;
+    distanceRatio: number;
+}
+/**
+ * 大地线（geodesic）：椭球面两点间的最短曲面路径。Vincenty 逆解 + 反求插值。
+ *
+ * 行为与 Cesium `EllipsoidGeodesic` 字节级一致。所有计算在 JS Float64
+ * 上完成，不依赖 GPU。贴地线 `line-densify.ts` 每段构造一个实例，按
+ * 等弧长插值取中间点。
+ */
+export declare class EllipsoidGeodesic {
+    /** 椭球（默认 WGS84）。 */
+    readonly _ellipsoid: GeodesicEllipsoid;
+    /** 起点 cartographic（height 永远 0）。 */
+    readonly _start: Cartographic;
+    /** 终点 cartographic（height 永远 0）。 */
+    readonly _end: Cartographic;
+    /** 起点航向（弧度，由 Vincenty 写入）。 */
+    _startHeading: number;
+    /** 终点航向（弧度，由 Vincenty 写入）。 */
+    _endHeading: number;
+    /** 椭球面距离（米，由 Vincenty 写入）。 */
+    _distance: number;
+    /** Vincenty u² = cos²α·(a²-b²)/b²。 */
+    _uSquared: number;
+    /** 插值常量缓存（setConstants 写入）。 */
+    _constants: GeodesicConstants;
+    /**
+     * @param start     可选起点。
+     * @param end       可选终点。
+     * @param ellipsoid 可选椭球，默认 WGS84。
+     */
+    constructor(start?: Cartographic, end?: Cartographic, ellipsoid?: GeodesicEllipsoid);
+    /** 起点航向（构造后只读）。 */
+    get startHeading(): number;
+    /** 终点航向（构造后只读）。 */
+    get endHeading(): number;
+    /** 椭球面距离（米）。 */
+    get surfaceDistance(): number;
+    /**
+     * 重设起止点。
+     *
+     * @param start 起点。
+     * @param end   终点。
+     */
+    setEndPoints(start: Cartographic, end: Cartographic): void;
+    /**
+     * 按 fraction（0..1）取大地线上点。等价 `interpolateUsingSurfaceDistance(_distance * fraction)`。
+     *
+     * @param fraction 0..1 之间的弧长比例。
+     * @param result   接收结果的 Cartographic。
+     * @returns        填好的 result。
+     */
+    interpolateUsingFraction(fraction: number, result: Cartographic): Cartographic;
+    /**
+     * 按弧长取大地线上点（Vincenty 正解）。
+     *
+     * @param distance 距起点的弧长（米）。
+     * @param result   接收结果的 Cartographic（lon/lat 弧度，height=0）。
+     * @returns        填好的 result。
+     */
+    interpolateUsingSurfaceDistance(distance: number, result: Cartographic): Cartographic;
+}
+export {};
+//# sourceMappingURL=ellipsoid-geodesic.d.ts.map

package/dist/types/lib/ground/math/ellipsoid-geodesic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ellipsoid-geodesic.d.ts","sourceRoot":"","sources":["../../../../../src/lib/ground/math/ellipsoid-geodesic.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAInD,qDAAqD;AACrD,MAAM,WAAW,iBAAiB;IACjC,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;CACtB;AAED,gEAAgE;AAChE,UAAU,iBAAiB;IAC1B,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,EAAE,MAAM,CAAC;IACzB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,aAAa,EAAE,MAAM,CAAC;CACtB;AAsRD;;;;;;GAMG;AACH,qBAAa,iBAAiB;IAC7B,oBAAoB;IACpB,SAAgB,UAAU,EAAE,iBAAiB,CAAC;IAE9C,oCAAoC;IACpC,SAAgB,MAAM,EAAE,YAAY,CAAC;IAErC,oCAAoC;IACpC,SAAgB,IAAI,EAAE,YAAY,CAAC;IAEnC,8BAA8B;IACvB,aAAa,SAAO;IAE3B,8BAA8B;IACvB,WAAW,SAAO;IAEzB,8BAA8B;IACvB,SAAS,SAAO;IAEvB,sCAAsC;IAC/B,SAAS,SAAO;IAEvB,+BAA+B;IACxB,UAAU,EAAE,iBAAiB,CAAC;IAErC;;;;OAIG;gBAEF,KAAK,CAAC,EAAE,YAAY,EACpB,GAAG,CAAC,EAAE,YAAY,EAClB,SAAS,GAAE,iBAAiC;IAY7C,mBAAmB;IACnB,IAAW,YAAY,IAAI,MAAM,CAEhC;IAED,mBAAmB;IACnB,IAAW,UAAU,IAAI,MAAM,CAE9B;IAED,gBAAgB;IAChB,IAAW,eAAe,IAAI,MAAM,CAEnC;IAED;;;;;OAKG;IACI,YAAY,CAAE,KAAK,EAAE,YAAY,EAAE,GAAG,EAAE,YAAY,GAAI,IAAI;IAInE;;;;;;OAMG;IACI,wBAAwB,CAC9B,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,YAAY,GAClB,YAAY;IAIf;;;;;;OAMG;IACI,+BAA+B,CACrC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,YAAY,GAClB,YAAY;CAiFf"}

package/dist/types/lib/ground/math/ellipsoid-rhumb-line.d.ts

@@ -0,0 +1,45 @@
+import type { Cartographic } from './cartographic';
+import type { GeodesicEllipsoid } from './ellipsoid-geodesic';
+/**
+ * 椭球恒向线（rhumb line）：保持恒定方位角的曲面路径。
+ *
+ * 与 `EllipsoidGeodesic` 接口对称。贴地线 `line-densify.ts` 在 `arcType==='rhumb'`
+ * 时构造一个实例并按弧长插值；`line-preprocess.ts` 跨本初子午线 / IDL 拆段
+ * 时用 `findIntersectionWithLongitude` 在恒向线上求交点。
+ */
+export declare class EllipsoidRhumbLine {
+    readonly _ellipsoid: GeodesicEllipsoid;
+    readonly _start: Cartographic;
+    readonly _end: Cartographic;
+    _heading: number;
+    _distance: number;
+    _ellipticity: number;
+    _ellipticitySquared: number;
+    constructor(start?: Cartographic, end?: Cartographic, ellipsoid?: GeodesicEllipsoid);
+    /** 起止两点的恒向线弧长（米）。 */
+    get surfaceDistance(): number;
+    /** 恒方位角（弧度）。 */
+    get heading(): number;
+    setEndPoints(start: Cartographic, end: Cartographic): void;
+    /**
+     * 按 fraction（0..1）取恒向线上点。
+     */
+    interpolateUsingFraction(fraction: number, result: Cartographic): Cartographic;
+    /**
+     * 按弧长取恒向线上点。
+     *
+     * @param distance 弧长（米）。
+     * @param result   接收结果的 Cartographic。
+     * @returns        填好的 result。
+     */
+    interpolateUsingSurfaceDistance(distance: number, result: Cartographic): Cartographic;
+    /**
+     * 找恒向线与给定经线的交点。逐字 Cesium，含 90°/0° 退化、对跖与 EPSILON14 边界处理。
+     *
+     * @param intersectionLongitude 经度（弧度）。
+     * @param result                接收结果的 Cartographic。
+     * @returns                     填好的 result；E-W 与给定经线重合等无穷交点情形返回 undefined。
+     */
+    findIntersectionWithLongitude(intersectionLongitude: number, result: Cartographic): Cartographic | undefined;
+}
+//# sourceMappingURL=ellipsoid-rhumb-line.d.ts.map

package/dist/types/lib/ground/math/ellipsoid-rhumb-line.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ellipsoid-rhumb-line.d.ts","sourceRoot":"","sources":["../../../../../src/lib/ground/math/ellipsoid-rhumb-line.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAGnD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AA+W9D;;;;;;GAMG;AACH,qBAAa,kBAAkB;IAC9B,SAAgB,UAAU,EAAE,iBAAiB,CAAC;IAC9C,SAAgB,MAAM,EAAE,YAAY,CAAC;IACrC,SAAgB,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,SAAO;IACf,SAAS,SAAO;IAChB,YAAY,SAAO;IACnB,mBAAmB,SAAO;gBAGhC,KAAK,CAAC,EAAE,YAAY,EACpB,GAAG,CAAC,EAAE,YAAY,EAClB,SAAS,GAAE,iBAAiC;IAW7C,qBAAqB;IACrB,IAAW,eAAe,IAAI,MAAM,CAEnC;IAED,gBAAgB;IAChB,IAAW,OAAO,IAAI,MAAM,CAE3B;IAEM,YAAY,CAAE,KAAK,EAAE,YAAY,EAAE,GAAG,EAAE,YAAY,GAAI,IAAI;IAInE;;OAEG;IACI,wBAAwB,CAC9B,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,YAAY,GAClB,YAAY;IAOf;;;;;;OAMG;IACI,+BAA+B,CACrC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,YAAY,GAClB,YAAY;IAWf;;;;;;OAMG;IACI,6BAA6B,CACnC,qBAAqB,EAAE,MAAM,EAC7B,MAAM,EAAE,YAAY,GAClB,YAAY,GAAG,SAAS;CA6D3B"}

package/dist/types/lib/ground/math/ellipsoid.d.ts

@@ -0,0 +1,94 @@
+import { Vector3 } from 'three';
+import type { Cartographic } from './cartographic';
+/**
+ * 由 Cartographic(λ, φ)算椭球表面 (λ, φ) 处的单位法向(指向外)。
+ *
+ * 算法:用参数化球向量 (cosφ·cosλ, cosφ·sinλ, sinφ) 作为初始方向,
+ * 然后 normalize。在椭球(a ≠ c)上,这个球向量长度并非 1,但
+ * **方向**恰好沿椭球面法向(因为椭球隐式方程的梯度与该球向量共线)。
+ *
+ * Cesium 对应:Ellipsoid.js:321-341
+ *
+ * @param carto 经度 / 纬度(弧度),height 字段被忽略。
+ * @param out   输出单位向量(模 1)。
+ * @returns     out。
+ */
+export declare function geodeticSurfaceNormalCartographic(carto: Cartographic, out: Vector3): Vector3;
+/**
+ * 由 ECEF 点计算椭球表面在该点的单位法向。
+ *
+ * 椭球隐式方程 F(x,y,z) = (x/a)² + (y/b)² + (z/c)² − 1 = 0 的梯度
+ * ∇F = (2x/a², 2y/b², 2z/c²) 方向即法向;归一化后即单位向量。
+ * 系数 2 不影响方向,省略。
+ *
+ * Cesium 对应:Ellipsoid.js:350-371
+ *
+ * @param cart ECEF 点(米);若位于椭球中心附近(模² < EPSILON14²)返回 undefined。
+ * @param out  输出单位向量。
+ * @returns    out 或 undefined(中心退化)。
+ */
+export declare function geodeticSurfaceNormal(cart: Vector3, out: Vector3): Vector3 | undefined;
+/**
+ * Newton 投影:把任意 ECEF 点投影到椭球表面(垂足投影)。
+ *
+ * 物理意义:求 cart 到椭球面的最近点(沿椭球法向回退)。
+ * 数值方法:设 P' = (px/(1 + λ/a²), py/(1 + λ/b²), pz/(1 + λ/c²)),
+ * 代入椭球方程得 func(λ) = 0,用 Newton-Raphson 迭代求 λ。每次迭代
+ * 精度平方提升,通常 2-3 次即收敛到 |func| ≤ EPSILON12(1e-12)。
+ *
+ * Cesium 对应:scaleToGeodeticSurface.js:25-146
+ *
+ * @param cart ECEF 输入点。
+ * @param out  输出椭球表面点(可与 cart 同实例)。
+ * @returns    out 或 undefined(中心点 + 非有限 ratio 兜底)。
+ */
+export declare function scaleToGeodeticSurface(cart: Vector3, out: Vector3): Vector3 | undefined;
+/**
+ * Cartographic (λ, φ, h) → ECEF (x, y, z),即 Cesium 著名的 gamma 投影法。
+ *
+ * 算法:n = 单位法向(球向量),k = (a²·n.x, b²·n.y, c²·n.z),
+ * gamma = √(n · k),椭球表面点 P = k / gamma,加高度偏移 h · n 即得。
+ *
+ * Cesium 对应:Ellipsoid.js:385-399
+ *
+ * @param carto 输入 cartographic。
+ * @param out   输出 ECEF 点。
+ * @returns     out。
+ */
+export declare function cartographicToCartesian(carto: Cartographic, out: Vector3): Vector3;
+/**
+ * ECEF → Cartographic(经纬度 + 高度)。
+ *
+ * 步骤:
+ *   1. Newton 投影到椭球面 → 表面点 P
+ *   2. 在 P 处计算单位法向 n(此时 n 指向 cart 方向)
+ *   3. 高度偏移 h_vec = cart − P;|h_vec| · sign(h_vec · cart) 即高度
+ *   4. 经度 = atan2(n.y, n.x);纬度 = asin(n.z)
+ *
+ * Cesium 对应:Ellipsoid.js:443-499
+ *
+ * @param cart 输入 ECEF 点。
+ * @param out  输出 cartographic。
+ * @returns    out 或 undefined(scaleToGeodeticSurface 返回 undefined 时)。
+ */
+export declare function cartesianToCartographic(cart: Vector3, out: Cartographic): Cartographic | undefined;
+/**
+ * 把一个 Float64 ECEF 点数组(原地)按 height 提升或降低。
+ *
+ * 调用规则:
+ *   - scaleToSurface = false:假设输入点已在椭球面,直接加 height · normal
+ *   - scaleToSurface = true:先 Newton 投影到椭球面再加 height · normal
+ *
+ * 矩形 extruded 路径中:
+ *   - top 层用 false(顶点来自 grid 采样,确实在表面)
+ *   - bottom 层用 true(同 buffer 已被前一步污染过,Newton 兜底;实际是 no-op)
+ *
+ * Cesium 对应:PolygonPipeline.js:593-631
+ *
+ * @param positions     ECEF 点数组(长度必须是 3 的倍数,原地修改)。
+ * @param height        高度偏移,米。
+ * @param scaleToSurface 见上述调用规则。
+ * @returns             原 positions(链式调用)。
+ */
+export declare function scaleToGeodeticHeight(positions: Float64Array, height: number, scaleToSurface: boolean): Float64Array;
+//# sourceMappingURL=ellipsoid.d.ts.map

package/dist/types/lib/ground/math/ellipsoid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ellipsoid.d.ts","sourceRoot":"","sources":["../../../../../src/lib/ground/math/ellipsoid.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAEhC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAuCnD;;;;;;;;;;;;GAYG;AACH,wBAAgB,iCAAiC,CAChD,KAAK,EAAE,YAAY,EACnB,GAAG,EAAE,OAAO,GACV,OAAO,CAYT;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CACpC,IAAI,EAAE,OAAO,EACb,GAAG,EAAE,OAAO,GACV,OAAO,GAAG,SAAS,CAcrB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,CACrC,IAAI,EAAE,OAAO,EACb,GAAG,EAAE,OAAO,GACV,OAAO,GAAG,SAAS,CA4FrB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CACtC,KAAK,EAAE,YAAY,EACnB,GAAG,EAAE,OAAO,GACV,OAAO,CA+BT;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,uBAAuB,CACtC,IAAI,EAAE,OAAO,EACb,GAAG,EAAE,YAAY,GACf,YAAY,GAAG,SAAS,CA8B1B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,qBAAqB,CACpC,SAAS,EAAE,YAAY,EACvB,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,OAAO,GACrB,YAAY,CAkCd"}

package/dist/types/lib/ground/math/enu-frame.d.ts

@@ -0,0 +1,27 @@
+import { Matrix4, Vector3 } from 'three';
+/**
+ * 在给定 ECEF 原点构造 ENU(东-北-上)→ ECEF 变换矩阵。
+ *
+ * 输出矩阵 M 的列布局:
+ *   列 0:east  基底(单位向量)
+ *   列 1:north 基底(单位向量)
+ *   列 2:up    基底(单位向量,沿椭球面法向)
+ *   列 3:平移 = origin
+ *
+ * 对任意局部 ENU 坐标 (e, n, u),`M · [e, n, u, 1]^T` 给出该点的 ECEF 坐标。
+ *
+ * 完整实现三个分支(必须全部保留,与 Cesium 字节级对齐):
+ *   分支 1:|origin|² < EPSILON14² → 退化为约定基底(east=Y,north=Z,up=X)
+ *   分支 2:|origin.x|, |origin.y| < EPSILON14 → 极点约定(east=X,north=±Y,up=±Z)
+ *   分支 3:一般情况 → up = geodeticSurfaceNormal(origin),
+ *                     east = normalize(-origin.y, origin.x, 0),
+ *                     north = up × east
+ *
+ * Cesium 对应:Transforms.js:99-279(生成器)+ L276-279(具体绑定 east+north)
+ *
+ * @param origin ECEF 原点(米);可以是椭球表面或上方任意点。
+ * @param out    输出 4×4 矩阵(原地写入)。
+ * @returns      out(链式调用)。
+ */
+export declare function eastNorthUpToFixedFrame(origin: Vector3, out: Matrix4): Matrix4;
+//# sourceMappingURL=enu-frame.d.ts.map

package/dist/types/lib/ground/math/enu-frame.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enu-frame.d.ts","sourceRoot":"","sources":["../../../../../src/lib/ground/math/enu-frame.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAWzC;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,uBAAuB,CACtC,MAAM,EAAE,OAAO,EACf,GAAG,EAAE,OAAO,GACV,OAAO,CAoDT"}

package/dist/types/lib/ground/math/matrix4-helpers.d.ts

@@ -0,0 +1,20 @@
+import type { Matrix4, Vector3 } from 'three';
+/**
+ * 4×4 矩阵乘以 3D 点(齐次坐标 w = 1)。
+ *
+ * 公式(列主序矩阵):
+ *   out.x = e[0]·p.x + e[4]·p.y + e[8]·p.z  + e[12]
+ *   out.y = e[1]·p.x + e[5]·p.y + e[9]·p.z  + e[13]
+ *   out.z = e[2]·p.x + e[6]·p.y + e[10]·p.z + e[14]
+ *
+ * 等价 Cesium `Matrix4.multiplyByPoint(matrix, cartesian, result)`,
+ * 同样支持 result === cartesian(原地变换),因为先把 p.x/y/z 读到
+ * 局部变量再写回 out。
+ *
+ * @param matrix 4×4 列主序变换矩阵(Three Matrix4)。
+ * @param point  输入点(可与 out 同实例)。
+ * @param out    输出向量(原地写入)。
+ * @returns      out(链式调用)。
+ */
+export declare function matrix4MultiplyByPoint(matrix: Matrix4, point: Vector3, out: Vector3): Vector3;
+//# sourceMappingURL=matrix4-helpers.d.ts.map

package/dist/types/lib/ground/math/matrix4-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"matrix4-helpers.d.ts","sourceRoot":"","sources":["../../../../../src/lib/ground/math/matrix4-helpers.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAE9C;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,sBAAsB,CACrC,MAAM,EAAE,OAAO,EACf,KAAK,EAAE,OAAO,EACd,GAAG,EAAE,OAAO,GACV,OAAO,CAWT"}

package/dist/types/lib/ground/math/rte-encoding.d.ts

@@ -0,0 +1,51 @@
+import type { Vector3 } from 'three';
+/**
+ * 把一个 Float64 标量拆为 (high, low) 两个 Float32 等价分量。
+ *
+ * 算法逐字复刻 Cesium `EncodedCartesian3.encode`:
+ *   - 正数:doubleHigh = floor(value / 65536) · 65536;return (doubleHigh, value − doubleHigh)
+ *   - 负数:对称处理(对 −value 取 doubleHigh,然后 high = −doubleHigh,low = value + doubleHigh)
+ *
+ * 验证:high + low === value(Float64 精度无损)。
+ *
+ * @param value 任意 Float64 标量(米尺度典型 ±1e7)。
+ * @returns     高低分量对象。返回新对象,V8 逃逸分析后栈分配。
+ */
+export declare function encodeScalarRTE(value: number): {
+    high: number;
+    low: number;
+};
+/**
+ * 把一个 Vector3 的三个分量分别 RTE 编码,写入 outHigh / outLow。
+ *
+ * 等价 Cesium `EncodedCartesian3.fromCartesian(source, result)`。
+ *
+ * 使用场景:
+ *   - 每帧:classification.ts 中编码相机位置(czm_encodedCameraPositionMC*)
+ *   - 一次性:computeRectanglePlanarExtents 中编码 SW 角点(u_southWest_*)
+ *
+ * @param source  输入 ECEF 向量(米)。
+ * @param outHigh 输出高分量向量。
+ * @param outLow  输出低分量向量。
+ */
+export declare function encodeVec3RTE(source: Vector3, outHigh: Vector3, outLow: Vector3): void;
+/**
+ * 把一整个 Float64Array(ECEF 顶点数组)拆为两个等长 Float32Array。
+ *
+ * 等价 Cesium `GeometryPipeline.encodeAttribute(geom, 'position', 'position3DHigh', 'position3DLow')`,
+ * 但解耦自 Cesium 的 Geometry 容器 — 直接返回两个 Float32Array,
+ * 由 caller 装入 Three BufferGeometry。
+ *
+ * 类型转换说明:
+ *   `high[i] = hi`(hi 是 Float64)在 TypedArray 隐式转换时截断到 Float32。
+ *   由于 hi 永远是 65536 的整数倍且 |hi| < 1e7 < 2²⁴,Float32 精确表示无损。
+ *   `low[i] = lo` 同理(|lo| < 65536)。
+ *
+ * @param positions ECEF 顶点数组(长度 = 3 × vertexCount)。
+ * @returns         两个 Float32Array,长度同输入。
+ */
+export declare function encodePositionsToHighLowArrays(positions: Float64Array): {
+    high: Float32Array;
+    low: Float32Array;
+};
+//# sourceMappingURL=rte-encoding.d.ts.map

package/dist/types/lib/ground/math/rte-encoding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rte-encoding.d.ts","sourceRoot":"","sources":["../../../../../src/lib/ground/math/rte-encoding.ts"],"names":[],"mappings":"AAyBA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAErC;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAE,KAAK,EAAE,MAAM,GAAI;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAU9E;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAC5B,MAAM,EAAE,OAAO,EACf,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,OAAO,GACb,IAAI,CAON;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,8BAA8B,CAC7C,SAAS,EAAE,YAAY,GACrB;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,GAAG,EAAE,YAAY,CAAA;CAAE,CAY3C"}

package/dist/types/lib/ground/math/vec3-helpers.d.ts

@@ -0,0 +1,50 @@
+import { Vector3 } from 'three';
+/**
+ * 从 Float64Array / Float32Array / number[] 的 (offset, offset+1, offset+2)
+ * 三个分量读入一个 Vector3,等价 Cesium `Cartesian3.fromArray(arr, offset, out)`。
+ *
+ * 调用方负责保证 array 与 offset 范围有效,本函数不做边界检查
+ * (热路径上由调用上下文 invariant 保证)。
+ *
+ * @param array  数据源(支持 TypedArray / 普通数组)。
+ * @param offset 起始下标(读取 array[offset..offset+2])。
+ * @param out    输出 Vector3(原地修改),便于 scratch 复用。
+ * @returns      out(链式调用)。
+ */
+export declare function vec3FromArrayInto(array: ArrayLike<number>, offset: number, out: Vector3): Vector3;
+/**
+ * 两个 Vector3 在 EPSILON 容差内是否相等。
+ *
+ * 用绝对差(component-wise abs ≤ epsilon),等价 Cesium 的 absolute 模式。
+ * Cesium 同名 API 还支持 relative epsilon,但矩形路径只需 absolute。
+ *
+ * @param a       第一个向量。
+ * @param b       第二个向量。
+ * @param epsilon 各分量绝对差上限(含等号)。
+ * @returns       三个分量都在容差内为 true。
+ */
+export declare function vec3EqualsEpsilon(a: Vector3, b: Vector3, epsilon: number): boolean;
+/**
+ * 分量乘法,等价 Cesium `Cartesian3.multiplyComponents(a, b, out)`:
+ * out = (a.x · b.x, a.y · b.y, a.z · b.z)。
+ *
+ * Three 的 `Vector3.multiply(other)` 也是分量乘,但语义 = self.multiply(other),
+ * 不支持 out 参数 / 不允许 a 与 b 同向 out。封装一遍以匹配 Cesium 调用方式。
+ *
+ * @param a   左乘向量。
+ * @param b   右乘向量。
+ * @param out 输出向量(可与 a 或 b 同实例)。
+ * @returns   out(链式调用)。
+ */
+export declare function vec3MultiplyComponents(a: Vector3, b: Vector3, out: Vector3): Vector3;
+/**
+ * 向量模长平方(x² + y² + z²)。
+ *
+ * 与 Three `Vector3.lengthSq()` 等价,提供同名函数仅为对照
+ * Cesium `Cartesian3.magnitudeSquared` 调用风格,避免上下文切换。
+ *
+ * @param v 输入向量(不修改)。
+ * @returns 模长的平方(米²)。
+ */
+export declare function vec3MagnitudeSquared(v: Vector3): number;
+//# sourceMappingURL=vec3-helpers.d.ts.map

package/dist/types/lib/ground/math/vec3-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vec3-helpers.d.ts","sourceRoot":"","sources":["../../../../../src/lib/ground/math/vec3-helpers.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAEhC;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAChC,KAAK,EAAE,SAAS,CAAC,MAAM,CAAC,EACxB,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,OAAO,GACV,OAAO,CAKT;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAI,OAAO,CAMpF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,GAAI,OAAO,CAKtF;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAE,CAAC,EAAE,OAAO,GAAI,MAAM,CAEzD"}

package/dist/types/lib/ground/math/wgs84-helpers.d.ts

@@ -0,0 +1,22 @@
+import { Vector3 } from 'three';
+/**
+ * 把 (lon°, lat°, h) 转为 ECEF Vector3,Three.js 世界坐标系。
+ *
+ * @param longitudeDegrees 经度,度(范围 [-180, 180])。
+ * @param latitudeDegrees  纬度,度(范围 [-90, 90])。
+ * @param height           高度,米;默认 0(椭球表面)。
+ * @returns                ECEF Vector3(每次新建,可以安全持有)。
+ */
+export declare function wgs84PositionFromDegrees(longitudeDegrees: number, latitudeDegrees: number, height?: number): Vector3;
+/**
+ * 把 (lon°, lat°) 转为该地理位置的椭球面单位法向(指向外)。
+ *
+ * 高度不影响法向,故不接受 height 参数。Up 向量、相机方向、ENU 基底
+ * 的 U 轴等场景使用。
+ *
+ * @param longitudeDegrees 经度,度。
+ * @param latitudeDegrees  纬度,度。
+ * @returns                单位法向 Vector3(每次新建)。
+ */
+export declare function wgs84NormalFromDegrees(longitudeDegrees: number, latitudeDegrees: number): Vector3;
+//# sourceMappingURL=wgs84-helpers.d.ts.map

package/dist/types/lib/ground/math/wgs84-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wgs84-helpers.d.ts","sourceRoot":"","sources":["../../../../../src/lib/ground/math/wgs84-helpers.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAYhC;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACvC,gBAAgB,EAAE,MAAM,EACxB,eAAe,EAAE,MAAM,EACvB,MAAM,SAAM,GACV,OAAO,CAQT;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACrC,gBAAgB,EAAE,MAAM,EACxB,eAAe,EAAE,MAAM,GACrB,OAAO,CAQT"}

package/dist/types/lib/ground/polygon/ellipsoid-tangent-plane.d.ts

@@ -0,0 +1,71 @@
+import { Vector2, Vector3 } from 'three';
+/**
+ * 椭球切平面数据结构。
+ *
+ * 数学不变量:
+ *   - `origin` 在椭球面上(由 scaleToGeodeticSurface 保证)
+ *   - `normal` 是 origin 处的椭球面外法向(单位向量)
+ *   - `xAxis` / `yAxis` 在切平面内,正交,单位向量,且 `xAxis × yAxis = normal`(右手系)
+ *   - `xAxis` 对齐 ENU 的 east 基底,`yAxis` 对齐 ENU 的 north 基底
+ *   - `distance` 是 Cesium Plane 公式中的常数项:`distance = -dot(origin, normal)`
+ *     ⇒ 平面方程为 `dot(P, normal) + distance = 0`
+ */
+export interface EllipsoidTangentPlane {
+    /** 切点(椭球面上的 ECEF 位置,米) */
+    origin: Vector3;
+    /** 切平面外法向(单位向量,沿椭球面在 origin 处的法线) */
+    normal: Vector3;
+    /** 切平面 "east" 基底(单位向量,正交于 normal) */
+    xAxis: Vector3;
+    /** 切平面 "north" 基底(单位向量,正交于 normal 与 xAxis,组成右手系) */
+    yAxis: Vector3;
+    /** Cesium Plane 公式常数项:plane(P) = dot(P, normal) + distance = 0 */
+    distance: number;
+}
+/**
+ * 由一组 ECEF 点构造切平面,中心取 AABB(轴对齐包围盒)中心。
+ *
+ * 复刻 Cesium `EllipsoidTangentPlane.fromPoints` 调用 `AxisAlignedBoundingBox.fromPoints`
+ * 取 `box.center = (box.minimum + box.maximum) / 2` 这一精确路径。**不要**用算术平均
+ * (`Σ p_i / N`),否则会与 Cesium 字节级输出有微差(R2)。
+ *
+ * 算法 6 步:
+ *   1. AABB 扫描:遍历 points 求 (minX, minY, minZ) 与 (maxX, maxY, maxZ)
+ *   2. center = ((min + max) / 2)
+ *   3. origin = scaleToGeodeticSurface(center)  ◄── math/ellipsoid.ts
+ *   4. 在 origin 上构造 ENU → ECEF 矩阵   ◄── math/enu-frame.ts
+ *   5. 从矩阵列 0/1/2 取 xAxis (east) / yAxis (north) / normal (up)
+ *   6. distance = -dot(origin, normal)
+ *
+ * 数值示例(珠峰 5 顶点 polygon):
+ *   AABB.min ≈ (+299870, +5627990, +2971890)
+ *   AABB.max ≈ (+304850, +5628570, +2977340)
+ *   center  ≈ (+302360, +5628280, +2974615)
+ *   origin  = scaleToGeodeticSurface(center) ≈ 几乎不变(已在椭球面附近)
+ *   normal  ≈ (+0.0473, +0.8830, +0.4670)    ≈ (cos27.99°cos86.92°, cos27.99°sin86.92°, sin27.99°)
+ *   xAxis   ≈ (+0.9988, -0.0537, +0.0000)    ≈ ENU east
+ *   yAxis   ≈ (-0.0251, -0.4664, +0.8842)    ≈ ENU north
+ *
+ * @param points 输入 ECEF 点数组(非空,典型为 polygon outer ring)。
+ * @returns      构造好的切平面(原 Vector3 实例,可安全持有)。
+ * @throws       points 为空 / origin 在椭球中心退化时。
+ */
+export declare function tangentPlaneFromPoints(points: readonly Vector3[]): EllipsoidTangentPlane;
+/**
+ * 把一组 ECEF 点投影到切平面 2D 坐标系。
+ *
+ * 复刻 Cesium EllipsoidTangentPlane.projectPointsOntoPlane(L215-238) +
+ * projectPointOntoPlane(L160-203):**逐点构造一条从 P 出发、方向 = normalize(P)
+ * 的 ray,与切平面求交**,然后把交点减去 origin 后投影到 (xAxis, yAxis) 得 2D 坐标。
+ *
+ * **关键不变量**:对 polygon-rings.ts 已 scaleToGeodeticSurface 过的输入,所有 P
+ * 都在椭球面上、且离 tangentPlane.origin ≤ 数 km 量级,ray 永远会成功命中切平面。
+ * Cesium 把"投影失败的点"从输出数组中剔除(`projectPointsOntoPlane` 内部 `count++`
+ * 跳过 undefined);本实现也保留同样语义(返回的数组长度可能小于输入)。
+ *
+ * @param tangentPlane 切平面(由 tangentPlaneFromPoints 产出)。
+ * @param points       输入 ECEF 点序列。
+ * @returns            2D 切平面坐标数组(长度 ≤ points.length,失败点被剔除)。
+ */
+export declare function projectPointsOntoPlane(tangentPlane: EllipsoidTangentPlane, points: readonly Vector3[]): Vector2[];
+//# sourceMappingURL=ellipsoid-tangent-plane.d.ts.map

package/dist/types/lib/ground/polygon/ellipsoid-tangent-plane.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ellipsoid-tangent-plane.d.ts","sourceRoot":"","sources":["../../../../../src/lib/ground/polygon/ellipsoid-tangent-plane.ts"],"names":[],"mappings":"AAmBA,OAAO,EAAW,OAAO,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAUlD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,qBAAqB;IACrC,0BAA0B;IAC1B,MAAM,EAAE,OAAO,CAAC;IAEhB,qCAAqC;IACrC,MAAM,EAAE,OAAO,CAAC;IAEhB,qCAAqC;IACrC,KAAK,EAAE,OAAO,CAAC;IAEf,oDAAoD;IACpD,KAAK,EAAE,OAAO,CAAC;IAEf,kEAAkE;IAClE,QAAQ,EAAE,MAAM,CAAC;CACjB;AAYD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,sBAAsB,CAAE,MAAM,EAAE,SAAS,OAAO,EAAE,GAAI,qBAAqB,CAkE1F;AAkDD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,sBAAsB,CACrC,YAAY,EAAE,qBAAqB,EACnC,MAAM,EAAE,SAAS,OAAO,EAAE,GACxB,OAAO,EAAE,CAuDX"}

package/dist/types/lib/ground/polygon/polygon-cap-construction.d.ts

@@ -0,0 +1,59 @@
+import type { EllipsoidTangentPlane } from './ellipsoid-tangent-plane';
+import type { PolygonHierarchy } from './polygon-hierarchy';
+/**
+ * Polygon cap(顶面)构造结果。
+ *
+ * - `positions`:Float64 ECEF 顶点(在椭球面上),长度 = 3 × vertexCount。
+ *   vertexCount = 原 ring 顶点总数(外环 + holes 合并)+ subdivision 新增中点数。
+ *   subdivision 中点在 ring 顶点之后追加(由 computeSubdivision 实现保证)。
+ *   ⚠️ 注意:cap.positions 是 Float64Array,**下游 scaleToGeodeticHeight 会原地修改它**
+ *   — 调用方若需要保留原始 cap.positions,自行 slice() 一份。
+ *
+ * - `indices`:顶面三角形索引,vertexCount ≤ 65535 时为 Uint16Array,否则 Uint32Array。
+ *
+ * - `tangentPlane`:切平面(从 processPolygonRings 透传);
+ *   polygon-extents.ts / polygon-style-points.ts 在更上层可能用得到。
+ *
+ * - `rings`:原始 ring 边界数组(**不含 subdivision 新中点**)。
+ *   排列:[ 外环信息, hole_0 信息, hole_1 信息, ... ]。
+ *   `startIndex` 与 `length` 在 `positions[0..originalRingTotal × 3)` 子区间内有效。
+ *   polygon-wall-construction.ts 用它遍历每个 ring 的边界顶点产 wall。
+ */
+export interface PolygonCapResult {
+    positions: Float64Array;
+    indices: Uint16Array | Uint32Array;
+    tangentPlane: EllipsoidTangentPlane;
+    rings: {
+        startIndex: number;
+        length: number;
+    }[];
+}
+/**
+ * 从 PolygonHierarchy 构造顶面三角网格(在椭球面上的 cap)。
+ *
+ * 算法(5 步):
+ *   1. processPolygonRings(hierarchy):
+ *      → { positions: Vector3[], positions2D: Vector2[],
+ *          holeStartIndices: number[], tangentPlane, rings }
+ *
+ *   2. triangulate(positions2D, holeStartIndices):
+ *      → number[],每 3 个一组 = 一个三角形;顶点 ID 在 positions 数组的索引空间。
+ *
+ *   3. computeSubdivision(positions, rawIndices, granularity):
+ *      → { positions: Float64Array, indices: Uint32Array }
+ *      ECEF 顶点扩充为(原 + 中点)的 Float64 数组;索引指向扩充后顶点。
+ *
+ *   4. 索引类型选择:
+ *      vertexCount = positions.length / 3
+ *      若 ≤ 65535 → 拷一份到 Uint16Array(GPU 上传更省 buffer,WebGL 1 默认即支持)
+ *      否则保持 Uint32Array
+ *
+ *   5. 返回 PolygonCapResult。`rings` 字段从 processPolygonRings 透传,
+ *      **仍指向 ring 边界顶点 ID**(不包含 subdivision 中点 — 中点 ID ≥ ring 总长度)。
+ *
+ * @param hierarchy   Polygon hierarchy(已被 polygon-hierarchy.ts 转为 Vector3 ECEF)。
+ * @param granularity 角分辨率(弧度),控制 subdivision 阈值。
+ * @returns           PolygonCapResult。
+ */
+export declare function constructPolygonCap(hierarchy: PolygonHierarchy, granularity: number): PolygonCapResult;
+//# sourceMappingURL=polygon-cap-construction.d.ts.map

package/dist/types/lib/ground/polygon/polygon-cap-construction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"polygon-cap-construction.d.ts","sourceRoot":"","sources":["../../../../../src/lib/ground/polygon/polygon-cap-construction.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AACvE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAK5D;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,gBAAgB;IAChC,SAAS,EAAE,YAAY,CAAC;IACxB,OAAO,EAAE,WAAW,GAAG,WAAW,CAAC;IACnC,YAAY,EAAE,qBAAqB,CAAC;IACpC,KAAK,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAChD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,mBAAmB,CAClC,SAAS,EAAE,gBAAgB,EAC3B,WAAW,EAAE,MAAM,GACjB,gBAAgB,CAwClB"}

package/dist/types/lib/ground/polygon/polygon-construct-extruded.d.ts

@@ -0,0 +1,44 @@
+import type { RectangleRadians } from '../types';
+import type { PolygonHierarchy } from './polygon-hierarchy';
+/**
+ * 完整 prism 装配结果。
+ *
+ * 排列约定:
+ *   positions  = [
+ *     <cap top    顶点 0..capVertexCount-1>    (高度 = maximumHeight)
+ *     <cap bottom 顶点 0..capVertexCount-1>    (高度 = minimumHeight)
+ *     <wall_0 顶点 0..(2 × wallPerSide_0 - 1)>  (顺序由 constructPolygonWall 决定)
+ *     <wall_1 顶点 ...>
+ *     ...
+ *   ]
+ *   extrudeDirection 同序,Float32,长度同 positions。
+ *
+ *   indices = [
+ *     <cap top    三角形索引>       (引用 cap top 顶点 ID 0..capVertexCount-1)
+ *     <cap bottom 三角形索引(winding 反转 + 加 capVertexCount 偏移)>
+ *     <wall_0 索引(加 capVertexCount × 2 偏移)>
+ *     <wall_1 索引(加 capVertexCount × 2 + wall_0 顶点数 偏移)>
+ *     ...
+ *   ]
+ *
+ * polygonRectangle 是 outer ring 顶点的轴对齐经纬度外接矩形(弧度);
+ * 由 polygon-extents.ts / polygon-style-points.ts 在更上层使用。
+ */
+export interface ExtrudedPolygonResult {
+    positions: Float64Array;
+    extrudeDirection: Float32Array;
+    indices: Uint16Array | Uint32Array;
+    polygonRectangle: RectangleRadians;
+}
+/**
+ * 构造完整的 polygon shadow volume prism(顶面 + 底面 + 每个 ring 的侧墙)。
+ *
+ * @param hierarchy     Polygon hierarchy(Vector3 ECEF;由 polygon-hierarchy 校验过)。
+ * @param granularity   网格精度(弧度);≤ 0 抛错。
+ * @param minimumHeight 底面高度(米)。
+ * @param maximumHeight 顶面高度(米);必须 > minimumHeight。
+ * @returns             完整 prism 装配结果。
+ * @throws              granularity / 高度参数非法,或几何退化(ring < 3 顶点)。
+ */
+export declare function constructExtrudedPolygonShadowVolume(hierarchy: PolygonHierarchy, granularity: number, minimumHeight: number, maximumHeight: number): ExtrudedPolygonResult;
+//# sourceMappingURL=polygon-construct-extruded.d.ts.map

package/dist/types/lib/ground/polygon/polygon-construct-extruded.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"polygon-construct-extruded.d.ts","sourceRoot":"","sources":["../../../../../src/lib/ground/polygon/polygon-construct-extruded.ts"],"names":[],"mappings":"AA8BA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAEjD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAO5D;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,qBAAqB;IACrC,SAAS,EAAE,YAAY,CAAC;IACxB,gBAAgB,EAAE,YAAY,CAAC;IAC/B,OAAO,EAAE,WAAW,GAAG,WAAW,CAAC;IACnC,gBAAgB,EAAE,gBAAgB,CAAC;CACnC;AA+ID;;;;;;;;;GASG;AACH,wBAAgB,oCAAoC,CACnD,SAAS,EAAE,gBAAgB,EAC3B,WAAW,EAAE,MAAM,EACnB,aAAa,EAAE,MAAM,EACrB,aAAa,EAAE,MAAM,GACnB,qBAAqB,CAkIvB"}