ccvt

命令行坐标转换工具，解决中国地图坐标系互转（WGS84 / GCJ02 / BD09）。库 + CLI 双暴露，管道优先，零依赖 binary，下载即用。

简介

ccvt 是一个面向命令行与数据管道的中国地图坐标转换工具。无论是把数据库里的 WGS84 坐标转成高德/百度地图用的坐标系，还是在脚本里批量处理 GPS 日志，一条命令即可完成。

适合的场景：

• 地图 / 位置服务开发 — 后端存 WGS84，前端用高德/百度
• GIS / 数据处理 — 地理数据坐标系统一、批量清洗

文档

文档	内容
API 文档	完整 API 说明：CLI 全部参数、输入/输出格式、退出码、Rust 库、完整示例
设计文档	定位、算法、精度、性能、项目结构、v1/v2/v3 路线

支持的坐标系

坐标系	说明
wgs84	GPS 原始坐标，国际标准
gcj02	火星坐标，高德/腾讯地图
bd09	百度坐标，在 GCJ02 上再加偏移

6 个转换方向，无 API 依赖，基于公开算法。v1 不含 CGCS2000。

支持的输入 / 输出

方向	格式	说明
输入	text（默认）	空格 / 逗号分隔，可用 --sep 指定分隔符
输入	csv	自动检测表头列名，可 --lat/--lng 指定
输入	json	单点对象或点数组
输出	text（默认）	lng lat，按 --order 排序
输出	json	统一 {"lng":…,"lat":…}

坐标顺序

默认经度在前（lng,lat）——高德/腾讯/百度 API 全部是 (lng,lat)，与核心用户存量数据一致。用 --order latlng 切换纬度在前（Google 系习惯）。

• text 输入默认 lng,lat（用 --order 切换）；JSON 一律用字段名 lng/lat 区分，不依赖顺序。
• 转换结果一律按 --order 指定的顺序写出，避免管道下游拿到错位坐标。

安装

下载即用，无运行时依赖（不需要装 Rust / Cargo）。

从 GitHub Release 下载预编译制品（由 GitHub Actions 构建）：

平台	架构	制品
macOS	arm64（Apple Silicon）/ x86_64（Intel）	ccvt-aarch64-apple-darwin.tar.gz / ccvt-x86_64-apple-darwin.tar.gz
Windows	64 位 / 32 位	ccvt-x86_64-pc-windows-msvc.zip / ccvt-i686-pc-windows-msvc.zip
Linux	x86_64 / arm64 / 32 位	ccvt-x86_64-unknown-linux-gnu.tar.gz 等

以 macOS arm64 为例：

curl -LO https://github.com/Angryshark128/ccvt/releases/download/v0.1.0/ccvt-aarch64-apple-darwin.tar.gz
tar -xzf ccvt-aarch64-apple-darwin.tar.gz
sudo mv ccvt /usr/local/bin/   # 或放进任意 PATH 目录

下载最新版时，把链接里的 v0.1.0 换成最新的 tag 版本号即可。 也可以在 GitHub Releases 页面手动下载各平台制品。

Windows 下载 zip 解压后，将 ccvt.exe 加入 PATH 即可。

若愿意装 Rust 工具链，也可 cargo install --path . 从源码构建。

发布流程

打 tag 即自动构建全部平台制品并发布到 GitHub Release：

git tag v0.1.0
git push origin v0.1.0

也可在仓库 Actions 页面手动触发 release workflow。

用法

# 最简（text 输入，默认空格/逗号分隔）
echo "116.3975 39.9087" | ccvt -f wgs84 -t gcj02

# CSV 输入（自动检测表头列名）
cat db.csv | ccvt -f wgs84 -t gcj02 -i csv

# 指定列名
ccvt -f bd09 -t wgs84 -i csv --lat 纬度 --lng 经度

# JSON 输入输出
echo '{"lng":116.3975,"lat":39.9087}' | ccvt -f wgs84 -t gcj02 -i json -o json

# 指定分隔符
cat gps.tsv | ccvt -f wgs84 -t gcj02 -s "\t"

# 严格模式（部分失败退出码 1）
ccvt -f wgs84 -t gcj02 --strict < bad.txt

# 辅助命令
ccvt list / ccvt version

示例文件

仓库 examples/ 提供了可直接试跑的样例数据：

文件	内容
examples/points.csv	标准表头（lng,lat），7 个城市点
examples/points_cn.csv	中文表头（经度,纬度），演示 --lng/--lat
examples/gps.log	GPS 日志（text 格式，空格分隔）
examples/point.json	单点 JSON 对象
examples/points.json	JSON 点数组

# 用示例文件跑通各输入格式
cat examples/points.csv | ccvt -f wgs84 -t gcj02 -i csv
ccvt -f wgs84 -t gcj02 -i csv --lng 经度 --lat 纬度 < examples/points_cn.csv
ccvt -f wgs84 -t bd09 < examples/gps.log
ccvt -f wgs84 -t gcj02 -i json -o json < examples/point.json
ccvt -f wgs84 -t bd09 -i json -o json < examples/points.json

参数

参数	短写	必需	说明
--from	-f	是	源坐标系（wgs84/gcj02/bd09）
--to	-t	是	目标坐标系（wgs84/gcj02/bd09）
--input-format	-i	否	text（默认）/csv/json
--output-format	-o	否	text（默认）/json
--order	—	否	lnglat（默认，经度在前）/latlng
--lat	—	否	CSV 纬度列名，默认自动检测
--lng	—	否	CSV 经度列名，默认自动检测
--sep	-s	否	text 输入分隔符（默认空格/逗号）
--strict	—	否	严格模式，部分失败退出 1

JSON 字段映射

• 读取：lng/lat（优先），兼容 longitude/latitude、x/y 别名；数组形态 [lng,lat] 也接受。
• 写出：统一 {"lng":…,"lat":…}。

CSV 边界

• 无表头或表头无匹配列 → 报错退出 2，提示用 --lat/--lng。
• --lat/--lng 缺一个 → 报错退出 2。
• 列名自动检测：大小写不敏感，识别 lng/lon/longitude/x、lat/y。

批量任务与退出码

三态：ok（stdout）、warn（stderr）、skip（stderr）。

输出流规则：只有成功结果写 stdout；一切 warn/skip/报错只写 stderr，保证管道下游拿到干净的转换结果。

退出码	含义
0	至少一行成功
1	--strict 且部分失败
2	全部失败（或参数错误）

精度

• 正向（WGS84→GCJ02、GCJ02→BD09）：直接套用公开偏移公式，一次计算。
• 反向（GCJ02→WGS84、BD09→WGS84、BD09→GCJ02）：迭代逼近——用正向公式算偏移、修正输入、重复至收敛（阈值 1e-9°，通常 ≤5 次），达到机器精度。
• 输入精度多高，输出就多高，不额外截断。

性能

• 纯算法：百万点 <0.1s（Rust），比 Python/JS 快一个数量级。
• 含 I/O 管道：实测 0.9s / 100 万行（release），差距缩小至约 2-5x。

详细设计与验证结论见 docs/design.md；完整 API 说明与使用文档见 docs/api.md。

场景示例

# 1. 数据库导出（WGS84）→ 高德前端
cat db.csv | ccvt -f wgs84 -t gcj02 -i csv

# 2. GPS 日志 → 百度地图
cat gps.txt | ccvt -f wgs84 -t bd09

# 3. 高德坐标 → 数据库（转回 WGS84）
curl api | ccvt -f gcj02 -t wgs84 -i json -o json

# 4. 百度 → 高德
ccvt -f bd09 -t gcj02 -i csv < bd.csv

# 5. 非标准表头
ccvt -f wgs84 -t gcj02 -i csv --lat 纬度 --lng 经度 < china.csv

# 6. JSON API 坐标转换
curl api | ccvt -f wgs84 -t gcj02 -i json -o json

Rust 库

use ccvt::convert::wgs84_to_gcj02;
let (lng, lat) = wgs84_to_gcj02(116.3975, 39.9087);

库入口 convert::convert(lng, lat, from, to) 支持任意方向。也支持在 Python 中调用：

import subprocess
subprocess.run(["ccvt", "-f", "wgs84", "-t", "gcj02"], input="116.3975 39.9087")

测试

cargo test

内置已知坐标向量（北京、上海、广州等 7 个多地区固定点 × 6 方向），参考值来自独立实现 gcoord，并附交叉验证脚本（scripts/xcheck_gcoord.sh）防止算法回归。

技术选型

Rust + clap + serde。算法参考 Gcoord（JS，标准公开）的正向公式，反向用迭代法，无外部 API 依赖。

路线图

• v1（当前）：6 方向转换、库 + CLI、text/csv/json、管道、三态退出码、--order、已知向量测试
• v2：fmt 子命令（度分秒 / UTM / MGRS 互转），预留骨架已就位
• v3：批量文件（GPX/GeoJSON/KML 读写）

License

MIT