@sparta-utils/gps-transform-utils/README.md

一个支持三参数与七参数的 GPS 坐标转换工具，适用于 WGS84 转 CGCS2000、北京54 等坐标系的正向与反向平面投影计算。

# @sparta-utils/gps-transform-utils

一个支持 **三参数 / 七参数** 的 GPS 坐标转换工具，可用于 **WGS84 → CGCS2000 / 北京54** 的投影转换，并支持反向坐标还原。

> 基于 [proj4js](https://github.com/proj4js/proj4js)，适用于地理信息系统、测绘数据校正等场景。

---

## 📦 安装方式

```bash
npm install @sparta-utils/gps-transform-utils

```

## ✨ 功能特色
✅ 支持 三参数（ΔX, ΔY, ΔZ）转换

✅ 支持 七参数（含旋转角、比例）转换

✅ 自动判断中央经线（三度带）

✅ 支持反向投影（平面 → GPS 坐标）

✅ 支持 CGCS2000 / 北京54 坐标系

✅ TypeScript 强类型定义

## 🚀 使用示例
# 1️⃣ 三参数转换
```ts
import { gpsToPlaneBy3Params } from '@sparta-utils/gps-transform-utils';

const gps = { lng: 117.1234, lat: 39.1234 };
const params = { dx: 15, dy: -154, dz: -82 };

const result = gpsToPlaneBy3Params('北京54', params, gps);
console.log('三参数坐标:', result);
```

# 2️⃣ 七参数转换
```ts
import { gpsToPlaneBy7Params } from '@sparta-utils/gps-transform-utils';

const gps = { lng: 117.1234, lat: 39.1234 };
const params = {
  dx: 15,
  dy: -154,
  dz: -82,
  rx: 0.0,   // 秒
  ry: 0.0,
  rz: 0.0,
  scale: 0.0 // ppm
};

const result = gpsToPlaneBy7Params('北京54', params, gps);
console.log('七参数坐标:', result);
```
# 3️⃣ 反向还原（平面坐标 → GPS 坐标）
```ts
import { planeToGps } from '@sparta-utils/gps-transform-utils';

const plane = { x: 500320.888, y: 4321939.137 };
const gps = planeToGps('北京54', { dx: 15, dy: -154, dz: -82 }, plane, 117);
console.log('还原坐标:', gps);
```

## 🧾 参数说明
# GPS 坐标对象（输入）
| 字段    | 类型       | 说明         |
| ----- | -------- | ---------- |
| `lng` | `number` | 经度，单位：十进制度 |
| `lat` | `number` | 纬度，单位：十进制度 |


# 三参数（适用于 gpsToPlaneBy3Params）
| 字段   | 类型       | 说明      |
| ---- | -------- | ------- |
| `dx` | `number` | X轴偏移（米） |
| `dy` | `number` | Y轴偏移（米） |
| `dz` | `number` | Z轴偏移（米） |

# 七参数（适用于 gpsToPlaneBy7Params）
| 字段      | 类型       | 说明              |
| ------- | -------- | --------------- |
| `dx`    | `number` | X轴偏移（米）         |
| `dy`    | `number` | Y轴偏移（米）         |
| `dz`    | `number` | Z轴偏移（米）         |
| `rx`    | `number` | X轴旋转（秒）         |
| `ry`    | `number` | Y轴旋转（秒）         |
| `rz`    | `number` | Z轴旋转（秒）         |
| `scale` | `number` | 比例缩放（ppm，百万分之一） |

# 返回坐标（平面坐标）
| 字段  | 类型       | 说明     |
| --- | -------- | ------ |
| `x` | `number` | 东坐标（米） |
| `y` | `number` | 北坐标（米） |


## 📌 中央经线说明
工具自动按三度带判断中央经线：
```ts
// 例如经度 117.5 会被判定为中央经线 120°
centralMeridian = Math.floor(lng / 3 + 1) * 3;
```
如需手动指定，可在方法中传入 centralMeridian 参数。
## 🔗 依赖说明
proj4