ecef

高性能 ECEF 坐标转换库（基于简化球模型）

支持 JWH（经纬度高程）与 XYZ（ECEF）坐标双向转换，提供单个坐标转换和批量 Float64Array 转换接口。

特性

• 支持多种模块格式：ESM、CJS 和 IIFE。
• 提供单个坐标和批量数据的高效转换。
• 内置单位法向量计算、距离计算等辅助功能。
• 严格的输入校验，确保数据有效性。

安装

使用 npm 或 yarn

npm install ecef

或者

yarn add ecef

直接引入 UMD 构建文件

你可以通过 <script> 标签直接在浏览器中使用本库，全局变量名为 ecef。

<script src="https://unpkg.com/ecef/dist/ecef.iife.js"></script>
<script>
  const jwh = { longitude: 120, latitude: 30, height: 0 };
  const xyz = ecef.fromDegree(jwh);
  console.log(xyz);
</script>

使用方法

ESM 和 CJS

引入模块

// ESM
import { fromDegree, toDegree, distance } from 'ecef';

// CJS
const { fromDegree, toDegree, distance } = require('ecef');

示例代码

将大地坐标（JWH）转换为 ECEF 坐标（XYZ）：

const jwh = { longitude: 120, latitude: 30, height: 0 };
const xyz = fromDegree(jwh);
console.log(xyz); // { x, y, z }

将 ECEF 坐标（XYZ）转换为大地坐标（JWH）：

const xyz = { x: 1000000, y: 2000000, z: 3000000 };
const jwh = toDegree(xyz);
console.log(jwh); // { longitude, latitude, height }

计算两个 ECEF 坐标之间的直线距离：

const pointA = { x: 1000000, y: 2000000, z: 3000000 };
const pointB = { x: 1500000, y: 2500000, z: 3500000 };
const dist = distance(pointA, pointB);
console.log(dist); // 距离（米）

IIFE（浏览器环境）

在浏览器环境中，可以通过全局变量 ecef 使用所有导出的方法：

<script src="https://unpkg.com/ecef/dist/ecef.iife.js"></script>
<script>
  const jwh = { longitude: 120, latitude: 30, height: 0 };
  const xyz = ecef.fromDegree(jwh);
  console.log(xyz);

  const jwhBack = ecef.toDegree(xyz);
  console.log(jwhBack);

  const pointA = { x: 1000000, y: 2000000, z: 3000000 };
  const pointB = { x: 1500000, y: 2500000, z: 3500000 };
  const dist = ecef.distance(pointA, pointB);
  console.log(dist);
</script>

API 文档

核心转换函数

• fromDegree(jwh: JWH, radius?: number): XYZ
  将大地坐标（JWH）转换为 ECEF 坐标（XYZ）。
  参数：

  • jwh: 大地坐标对象 { longitude, latitude, height }
  • radius: 球体半径，默认为 SphereRadius.WGS84_SEMIMAJOR

• toDegree(xyz: XYZ, radius?: number): JWH
  将 ECEF 坐标（XYZ）转换为大地坐标（JWH）。
  参数：

  • xyz: ECEF 坐标对象 { x, y, z }
  • radius: 球体半径，默认为 SphereRadius.WGS84_SEMIMAJOR

批量处理函数

• fromDegrees(jwhArray: Float64Array, radius?: number): Float64Array
  批量将大地坐标数组转换为 ECEF 坐标数组。
  输入格式：[longitude0, latitude0, height0, ...]
  输出格式：[x0, y0, z0, ...]

• toDegrees(xyzArray: Float64Array, radius?: number): Float64Array
  批量将 ECEF 坐标数组转换为大地坐标数组。
  输入格式：[x0, y0, z0, ...]
  输出格式：[longitude0, latitude0, height0, ...]

辅助计算函数

• distance(a: XYZ, b: XYZ): number
  计算两个 ECEF 坐标之间的直线距离。

• center(points: XYZ[]): XYZ
  计算多个 ECEF 坐标的中心点。

• distanceArray(a: Float64Array, b: Float64Array): number
  计算两个 Float64Array 存储的 ECEF 坐标之间的距离。

类型检查工具

• isJWH(value: unknown): boolean
  检查是否为有效的大地坐标对象。

• isXYZ(value: unknown): boolean
  检查是否为有效的 ECEF 坐标对象。

许可证

MIT