geoshift v1.0.0

GeoShift

转换中国地区不同坐标系统的工具库，支持 WGS84(GPS)、GCJ02(高德)和 BD09(百度) 坐标系统之间的互相转换

特性

• 🚀 支持主流坐标系统互转（WGS84、GCJ02、BD09）
• 💪 TypeScript 编写，提供完整类型定义
• 🎯 高精度转换算法，采用迭代逼近法
• 📦 支持 ESM 和 CommonJS 两种模块规范
• 🔒 内置坐标验证，异常处理
• 🪶 零依赖，轻量级实现
• 🧩 支持多种坐标输入/输出格式

安装

npm install geoshift -S

使用方法

基础用法

import {
  baiduToGCJ02,
  gpsToGCJ02,
  CoordinateSystem,
  convert,
} from 'geoshift';

// 使用单一转换方法
const gcj02Point = baiduToGCJ02(116.404, 39.915);
console.log('百度坐标转高德坐标:', gcj02Point);

// 使用通用转换方法
const point = [116.404, 39.915];
const wgs84Point = convert(
  point,
  CoordinateSystem.BD09,
  CoordinateSystem.WGS84,
);
console.log('百度坐标转GPS坐标:', wgs84Point);

支持的转换方法

// 百度坐标 (BD09) 转 高德坐标 (GCJ02)
baiduToGCJ02(longitude: number, latitude: number): [number, number]

// 高德坐标 (GCJ02) 转 百度坐标 (BD09)
GCJ02ToBaidu(longitude: number, latitude: number): [number, number]

// GPS坐标 (WGS84) 转 高德坐标 (GCJ02)
gpsToGCJ02(longitude: number, latitude: number): [number, number]

// 高德坐标 (GCJ02) 转 GPS坐标 (WGS84)
GCJ02ToGps(longitude: number, latitude: number): [number, number]

// 百度坐标 (BD09) 转 GPS坐标 (WGS84)
baiduToGps(longitude: number, latitude: number): [number, number]

// GPS坐标 (WGS84) 转 百度坐标 (BD09)
gpsToBaidu(longitude: number, latitude: number): [number, number]

// 通用转换方法
convert(point: [number, number], from: CoordinateSystem, to: CoordinateSystem): [number, number]

坐标系统枚举

enum CoordinateSystem {
  WGS84 = 'WGS84', // GPS坐标系
  GCJ02 = 'GCJ02', // 高德坐标系
  BD09 = 'BD09', // 百度坐标系
}

注意事项

1. 坐标转换仅适用于中国大陆地区，海外地区的坐标转换会直接返回原坐标。

2. 坐标系统说明：

   • WGS84：GPS 全球定位系统使用的标准坐标系
   • GCJ02：中国国测局制定的加密坐标系，高德、腾讯等地图使用
   • BD09：百度地图使用的坐标系，在 GCJ02 基础上再次加密

3. 转换精度：

   • 保留小数点后 6 位
   • 由于加密算法的特性，坐标转换存在一定的误差

错误处理

该库会对无效的坐标输入进行验证，并抛出相应的错误：

try {
  const result = baiduToGCJ02(181, 91);
} catch (error) {
  console.error(error.message); // 坐标超出有效范围: 经度应在[-180, 180]之间，纬度应在[-90, 90]之间
}

高级功能

除了基本的坐标转换功能外，GeoShift 还提供了一系列实用的地理计算功能，帮助开发者更便捷地处理地理空间数据：

距离计算

import { getDistance, CoordSystem } from 'geoshift';

// 计算两点之间的距离（米）
const point1 = { longitude: 116.404, latitude: 39.915 };
const point2 = { longitude: 116.410, latitude: 39.920 };

// 默认使用 WGS84 坐标系
const distance = getDistance(point1, point2);

// 指定坐标系
const distanceInGCJ02 = getDistance(point1, point2, CoordSystem.GCJ02);

点与多边形关系

import { isPointInPolygon, CoordSystem } from 'geoshift';

const point = { longitude: 116.404, latitude: 39.915 };
const polygon = [
  { longitude: 116.400, latitude: 39.910 },
  { longitude: 116.410, latitude: 39.910 },
  { longitude: 116.410, latitude: 39.920 },
  { longitude: 116.400, latitude: 39.920 }
];

// 判断点是否在多边形内
const isInside = isPointInPolygon(point, polygon);

面积计算

import { calculatePolygonArea, CoordSystem } from 'geoshift';

const polygon = [
  { longitude: 116.400, latitude: 39.910 },
  { longitude: 116.410, latitude: 39.910 },
  { longitude: 116.410, latitude: 39.920 },
  { longitude: 116.400, latitude: 39.920 }
];

// 计算多边形面积（平方米）
const area = calculatePolygonArea(polygon);

偏移计算

import { getOffsetCoordinate, CoordSystem } from 'geoshift';

const point = { longitude: 116.404, latitude: 39.915 };

// 计算从给定点出发，沿指定方向和距离的新坐标
// 参数：坐标点、距离(米)、方向角度(0-360，正北为0，顺时针)
const newPoint = getOffsetCoordinate(point, 1000, 90); // 向东1公里

边界框计算

import { createBoundingBox } from 'geoshift';

const points = [
  { longitude: 116.400, latitude: 39.910 },
  { longitude: 116.410, latitude: 39.920 },
  { longitude: 116.420, latitude: 39.915 }
];

// 计算一组点的边界框
const bbox = createBoundingBox(points);
// 结果: { minLat: 39.91, maxLat: 39.92, minLng: 116.4, maxLng: 116.42 }

批量坐标转换

import { transformer, CoordSystem } from 'geoshift';

// 批量转换多个坐标点
const coordinates = [
  { longitude: 116.404, latitude: 39.915 },
  { longitude: 116.405, latitude: 39.916 },
  { longitude: 116.406, latitude: 39.917 }
];

// 批量从WGS84转换到GCJ02
const gcj02Coords = transformer.batchTransform(
  coordinates, 
  CoordSystem.WGS84, 
  CoordSystem.GCJ02
);

格式转换

import { toPoint, toLatLng } from 'geoshift';

const coord = { longitude: 116.404, latitude: 39.915 };

// 转换为坐标点数组 [经度, 纬度]
const point = toPoint(coord); // [116.404, 39.915]

// 转换为LatLng格式 {lat, lng}
const latlng = toLatLng(coord); // {lat: 39.915, lng: 116.404}

浏览器兼容性

该库支持所有现代浏览器，包括：

• Chrome 60+
• Firefox 55+
• Safari 11+
• Edge 16+

对于需要支持旧版浏览器的场景，建议使用 Babel 进行转译。

常见问题

为什么需要进行坐标转换？

由于国家安全考虑，中国大陆地区的地图使用经过加密的坐标系统（GCJ02、BD09），与国际标准的WGS84坐标系存在偏移。在开发涉及地图的应用时，需要进行坐标转换以确保位置准确性。

坐标转换的精度如何？

GeoShift 采用迭代逼近法进行坐标转换，精度可达厘米级别。在实际应用中，转换误差通常在1-2米以内，满足绝大多数应用场景需求。

如何处理大量坐标点的转换？

对于大量坐标点的转换，建议使用 batchTransform 方法，它比循环调用单点转换方法更高效。