# ecef

**Repository Path**: cesiumjs/ecef

## Basic Information

- **Project Name**: ecef
- **Description**: 高性能ECEF坐标转换库（基于简化球模型），支持JWH(经纬度高程)与XYZ(ECEF)坐标双向转换，提供单个坐标和批量数据处理接口。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-15
- **Last Updated**: 2025-10-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ecef

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

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

## 特性

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

## 安装

### 使用 npm 或 yarn

```bash
npm install ecef
```

或者

```bash
yarn add ecef
```

### 直接引入 UMD 构建文件

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

```html
<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

#### 引入模块

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

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

#### 示例代码

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

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

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

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

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

```javascript
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` 使用所有导出的方法：

```html
<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](file://d:\jvy\JVY\100个人\code\gitee\ecef\src\index.ts#L317-L332)  
  计算多个 ECEF 坐标的中心点。

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

### 类型检查工具

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

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

## 许可证

MIT