ECEF坐标转换库

ecef

高性能ECEF坐标转换库（基于简化球模型），支持JWH(经纬度高程)与XYZ(ECEF)坐标双向转换，提供单个坐标和批量数据处理接口。

安装

npm install ecef --save

支持的模块格式

• ESM: import { fromDegree } from 'ecef'
• CommonJS: const { fromDegree } = require('ecef')
• IIFE (浏览器): <script src="node_modules/ecef/dist/iife/ecef.js"></script> (暴露为全局变量 ecef)

类型定义

JWH

大地坐标接口（经纬度/高程）

interface JWH {lon: number;  // 经度（°，范围：-180~180，东为正）lat: number;  // 纬度（°，范围：-90~90，北为正）h: number;    // 高程（m，球面以上为正）
}

XYZ

ECEF坐标接口

interface XYZ {x: number;  // X轴坐标（m，指向本初子午线-赤道交点）y: number;  // Y轴坐标（m，赤道平面内逆时针90°）z: number;  // Z轴坐标（m，指向地球北极）
}

SphereRadius

球体半径预设（单位：米）

enum SphereRadius {WGS84_SEMIMAJOR = 6378137,  // WGS84长半轴（默认）WGS84_AVERAGE = 6371008,    // WGS84平均半径EARTH_MEAN = 6371000        // 地球平均半径（近似值）
}

核心API

单个坐标转换

fromDegree(jwh: JWH, radius?: number): XYZ

大地坐标(度)转XYZ坐标（ECEF）

import { fromDegree, SphereRadius } from 'ecef';const jwh = { lon: 116.4, lat: 39.9, h: 50 };
const xyz = fromDegree(jwh, SphereRadius.WGS84_SEMIMAJOR);
// { x: 2170370.54, y: 4426523.48, z: 4044135.31 }

toDegree(xyz: XYZ, radius?: number): JWH

XYZ坐标（ECEF）转大地坐标(度)

import { toDegree } from 'ecef';const xyz = { x: 2170370.54, y: 4426523.48, z: 4044135.31 };
const jwh = toDegree(xyz);
// { lon: 116.4, lat: 39.9, h: 50 }

批量坐标转换（高性能）

fromDegrees(jwhArray: Float64Array, radius?: number): Float64Array

批量大地坐标转XYZ坐标，输入输出均为Float64Array

import { fromDegrees } from 'ecef';// 输入格式: [lon0, lat0, h0, lon1, lat1, h1, ...]
const jwhData = new Float64Array([116.4, 39.9, 50, 121.5, 31.2, 100]);
const xyzData = fromDegrees(jwhData);
// 输出格式: [x0, y0, z0, x1, y1, z1, ...]

toDegrees(xyzArray: Float64Array, radius?: number): Float64Array

批量XYZ坐标转大地坐标，输入输出均为Float64Array

import { toDegrees } from 'ecef';// 输入格式: [x0, y0, z0, x1, y1, z1, ...]
const xyzData = new Float64Array([2170370.54, 4426523.48, 4044135.31, ...]);
const jwhData = toDegrees(xyzData);
// 输出格式: [lon0, lat0, h0, lon1, lat1, h1, ...]

辅助函数

distance(a: XYZ, b: XYZ): number

计算两个XYZ坐标之间的直线距离（米）

const dist = distance(xyz1, xyz2);

center(points: XYZ[]): XYZ

计算多个XYZ坐标的中心坐标

const centerPoint = center([xyz1, xyz2, xyz3]);

distanceArray(a: Float64Array, b: Float64Array): number

计算两个Float64Array存储的XYZ坐标之间的距离

const dist = distanceArray(xyzArray.subarray(0, 3), xyzArray.subarray(3, 6));

类型检查工具

• isJWH(value: unknown): value is JWH - 检查是否为有效的大地坐标
• isXYZ(value: unknown): value is XYZ - 检查是否为有效的XYZ坐标

性能特点

• 高性能，基于简化球模型
• 局部变量缓存，减少属性访问开销
• 预计算常量，避免重复计算
• 提供Float64Array批量处理接口，适合大数据量场景

适用场景

• 低精度地理信息可视化
• 实时轨迹处理
• 高频次坐标转换场景
• 批量地理数据处理

许可证

MIT