项目地址: https://github.com/OSGeo/PROJ
官方文档: https://proj.org/
命令行文档: https://proj.org/en/stable/apps/index.html
最新版本: 9.9.0(截至 2026-11,GitHub Release)
许可证: MIT
概述
PROJ 是 OSGeo 维护的坐标转换与投影库,也是 GDAL、QGIS、PostGIS 等软件坐标运算的底层引擎。它将坐标系与转换参数存储于 SQLite 数据库 proj.db,并通过命令行工具暴露查询与转换能力:
projinfo— 查询 CRS 定义、查找两坐标系之间的转换操作、导出 WKT/PROJJSONcs2cs— 在任意两个可定义的坐标系之间做坐标转换(含基准面转换)proj— 在同一基准面内做地理坐标与投影坐标的正反算cct— 4D(含时间)坐标转换,输入为点列表projsync— 从 PROJ CDN 下载基准面转换所需的网格文件proj.db— SQLite 数据库,内含 EPSG 数据集与坐标转换记录
环境准备
验证安装
projinfo --version # 输出版本与 proj.db 路径,推荐用于验证
projinfo --searchpaths # 列出资源搜索路径
proj 直接执行会进入交互模式,不作为版本检查命令。
安装方法
Linux (Debian/Ubuntu)
apt-get update
apt-get install proj-bin proj-data
Linux (CentOS/RHEL/Fedora)
yum install proj proj-devel # 或 dnf install proj proj-devel
macOS (Homebrew)
brew install proj
Conda(跨平台)
conda install -c conda-forge proj
Docker
docker run -it osgeo/proj:latest bash
Windows
安装 OSGeo4W 或 conda 发行版;GDAL/QGIS 的 Windows 安装包已内置 PROJ,无需单独安装。
数据与网络配置
# PROJ 9.1 起使用 PROJ_DATA(旧名为 PROJ_LIB,9.1 仍兼容)
export PROJ_DATA=/usr/share/proj
# 允许按需从 CDN 下载转换网格
export PROJ_NETWORK=ON
proj.db 必须可读,库才能正常工作;若报 Cannot find proj.db,请核对 PROJ_DATA 指向的目录。
核心 API/命令
projinfo — CRS 与转换操作查询
查询单个对象(默认按 CRS 解释,-k 可指定 crs|operation|datum|ensemble|ellipsoid):
# 查询 CRS,输出 PROJ 字符串与 WKT2:2019
projinfo EPSG:4326
# 以 PROJJSON 输出(-q 仅输出字符串本体)
projinfo GDA94 -o PROJJSON -q
# WKT1:GDAL 单行输出
projinfo -o WKT1:GDAL --single-line EPSG:25832
# 按名称识别,给出最接近数据库对象的概率
projinfo --identify EPSG:4326
# 将 2D CRS 提升为 3D
projinfo EPSG:4326 --3d
查找两坐标系之间的坐标转换操作:
# -s 源 CRS,-t 目标 CRS
projinfo -s EPSG:4326 -t EPSG:32650
# 限定作用范围与输出摘要
projinfo -s NAD27 -t EPSG:4269 --area "USA - Missouri" --summary
列表与数据库结构:
# 列出符合条件的 CRS
projinfo --list-crs --area Taiwan
# 转储数据库结构(可交给 sqlite3 导入)
projinfo --dump-db-structure
-o 支持 all、default、PROJ、WKT_ALL、WKT2:2015、WKT2:2019、WKT1:GDAL、WKT1:ESRI、PROJJSON、SQL,格式前加 - 表示禁用。输入可为 proj 字符串、WKT、AUTHORITY:CODE、对象名称、PROJJSON 或 OGC URN。
cs2cs — 坐标系转换
# EPSG 代码:WGS 84 经纬度 → UTM 32N(EPSG:4326 轴序为纬度在前,故 56 是纬度、12 是经度)
echo 56 12 | cs2cs EPSG:4326 EPSG:25832
# 多行输入(45N 为纬度、2E 为经度)
cs2cs EPSG:4326 EPSG:32631 <<'EOF'
45N 2E
EOF
轴序要点: 输入
AUTHORITY:CODE或 WKT 时按该 CRS 定义的轴序解析,EPSG:4326是纬度在前;用-r反转输入、-s反转输出。下文示例一律先纬度后经度。
PROJ 字符串写法(+to 分隔源与目标):
cs2cs +proj=latlong +datum=NAD83 +to +proj=utm +zone=10 +datum=NAD27 -r <<EOF
45d15.551666667N -111d30
+45.25919444444 111d30'000w
EOF
常用选项:
| 选项 | 作用 |
|---|---|
-I |
反向转换(目标 CRS → 源 CRS) |
-r / -s |
反转输入 / 输出的前两位轴顺序(第三位高度不变) |
-f <fmt> |
printf 风格输出格式,默认 %.2f(逆算输出度) |
-d <n> |
输出保留小数位数 |
-E |
输出行前附加原始输入坐标 |
--3d |
启用三维转换 |
--only-best |
只使用精度最高的转换,网格缺失时报错而非退回 |
proj — 单基准面投影正反算
# 墨卡托投影(纬度 56.5° 为真比例)
echo 55.2 12.2 | proj +proj=merc +lat_ts=56.5 +ellps=GRS80
# UTM 12 带,输入纬度在前
proj +proj=utm +zone=12 -r <<EOF
45d15.551666667N -111d30
EOF
# 逆算(投影 → 地理),-V 输出带注释的详细参数
proj -I +proj=merc +lat_ts=56.5 +ellps=GRS80
# PROJ 9.3 起可直接接受 CRS(须为投影 CRS)
proj EPSG:6421 -V <<EOF
-120 35.8
EOF
# 列出可用投影标识
proj -l
proj -l=merc
proj.db — SQLite 数据库
proj.db 存储 CRS、基准面、坐标转换与网格信息,可直接用 sqlite3 查询。视图 crs_view 保存 CRS 定义,coordinate_operation_view 保存转换记录:
-- 查询 NAD27 → NAD83 的可用转换及其精度
SELECT auth_name, code, name, method_name, accuracy
FROM coordinate_operation_view
WHERE source_crs_auth_name = 'EPSG' AND source_crs_code = '4267'
AND target_crs_auth_name = 'EPSG' AND target_crs_code = '4269';
sqlite3 "$PROJ_DATA/proj.db" \
"SELECT auth_name, code, name FROM crs_view WHERE auth_name='EPSG' LIMIT 5;"
其他工具
# 4D 坐标转换(含时间维),输入为点列表
cct +proj=pipeline +step +proj=cart +ellps=GRS80
# 大地线(大圆)计算
geod +ellps=WGS84 -I <<EOF
-120 35 0 120 35
EOF
# 从 CDN 下载全部转换网格,或按机构/范围筛选
projsync --all
projsync --source-id fr_ign --bbox 2,49,2,49
projsync --list-files
典型工作流
模式 1:WGS 84 经纬度 → UTM / Web Mercator
# 先纬度后经度:39.907 是纬度、116.391 是经度(北京)
echo 39.907 116.391 | cs2cs EPSG:4326 EPSG:32650 # 北京 → UTM 50N
echo 39.907 116.391 | cs2cs EPSG:4326 EPSG:3857 # → Web Mercator
模式 2:CGCS2000 中国坐标系操作
# 查询 CGCS2000 地理坐标系
projinfo EPSG:4490
# 查询 3 度带高斯-克吕格投影(114E 中央经线,即 38 带)
projinfo EPSG:4547
# WGS 84 经纬度 → CGCS2000 3 度带投影(30.5N 114.0E,纬度在前)
echo 30.5 114.0 | cs2cs EPSG:4326 EPSG:4547
模式 3:查找并确认转换路径
# 先列出可用转换与精度
projinfo -s EPSG:4326 -t EPSG:4547 --summary
# 再用 cs2cs 执行,必要时强制使用最佳转换
echo 30.5 114.0 | cs2cs EPSG:4326 EPSG:4547 --only-best
模式 4:批量转换坐标文本
#!/bin/bash
# 输入文件每行 "lat lon"(纬度在前,与 EPSG:4326 轴序一致)
cs2cs EPSG:4326 EPSG:3857 points.txt > points_3857.txt
模式 5:为缺失网格下载数据
# 按目标区域下载转换网格后执行高精度转换
projsync --bbox 73,18,135,54
export PROJ_NETWORK=ON
echo 39.907 116.391 | cs2cs EPSG:4326 EPSG:4547 --only-best
最佳实践
- 优先使用权威代码而非 proj 字符串:
EPSG:4326等代码由proj.db完整描述基准面与轴序,proj 字符串会丢失精度信息(如+datum=的隐含假设)。 - 注意轴序:
AUTHORITY:CODE或 WKT 会强制其定义轴序,EPSG:4326为纬度在前;proj命令内部期望经度在前,需用-r调整。 - 转换前先验证:用
projinfo <code>确认 CRS 名称与轴序,用projinfo -s A -t B确认转换路径与精度。 - 显式指定
PROJ_DATA:多套 PROJ 共存时(如系统、conda、PostGIS 自带),指向错误目录会报proj.db版本不匹配。 - 高精度转换需网格:涉及基准面平移的转换依赖网格文件,用
projsync预取或设PROJ_NETWORK=ON,并用--only-best避免静默降级。 - 区分 PROJ 与 GDAL:重投影栅格/矢量文件用 GDAL(
gdalwarp/ogr2ogr),纯坐标点转换用cs2cs;两者共享PROJ_DATA。
常见问题
| 问题 | 解决 |
|---|---|
Cannot find proj.db |
检查 PROJ_DATA(PROJ 9.1 前为 PROJ_LIB)是否指向含 proj.db 的目录,用 projinfo --searchpaths 查看搜索路径 |
DATABASE.LAYOUT.VERSION 不匹配 |
多个 PROJ 副本(系统 / conda / PostGIS)混用,统一 PROJ_DATA 指向与所用库版本一致的 proj.db |
The EPSG code is unknown |
该代码不在本地 proj.db,升级 PROJ 或改用等效 WKT/PROJJSON;可先 projinfo --list-crs 确认是否存在 |
cs2cs 输出与预期轴序相反 |
EPSG:4326 等按定义轴序(纬度在前),用 -r 反转输入或 -s 反转输出 |
| 转换精度不足或结果偏差大 | 缺少高精度网格导致退回近似转换,用 projsync 下载网格、设 PROJ_NETWORK=ON,并加 --only-best 校验 |
proj 报参数错误或进入交互无输出 |
proj 需投影参数(如 +proj=...)或投影 CRS;直接运行会进入交互模式,请用管道或文件输入 |
| 查询 CRS 输出过多难以解析 | 加 -q 只输出字符串本体,或 -o PROJJSON -q 获取结构化结果,配合 jq 解析 |
| 命令找不到 / 版本过旧 | 用 projinfo --version 核对版本,安装 proj-bin、conda-forge proj 或使用 osgeo/proj 镜像 |
AI 使用建议
- 执行环境:命令在终端 / shell 中执行(Windows 用 PowerShell)。正文的
export PROJ_DATA=...在 PowerShell 写作$env:PROJ_DATA = "C:\OSGeo4W\share\proj";heredoc(<<EOF)在 PowerShell 中不可用,改用管道"56 12" | cs2cs EPSG:4326 EPSG:25832或先把输入写成文件再重定向。 - 先探测版本:
projinfo --version(同时打印proj.db路径)、projinfo --searchpaths;本技能按 PROJ 9.9.0 编写,低于 9.1 用PROJ_LIB而非PROJ_DATA,低于 9.3 的proj不能直接接受EPSG:xxxx。 - 验证转换:用已知点对拍——
echo "39.907 116.391" | cs2cs EPSG:4326 EPSG:32650应得到东坐标约 44 万、北坐标约 442 万,量级不对通常是轴序或单位问题;结构化核对用projinfo -o PROJJSON -q EPSG:4326,转换路径用projinfo -s A -t B --summary看候选操作与精度。 - 轴序与降级:
EPSG:4326纬度在前(输入先 lat 后 lon),proj命令内部经度在前要用-r;高精度转换加--only-best,否则缺网格时会静默退回精度更低的操作。 - 大输出处理:
projinfo EPSG:4326的 WKT 有上百行,重定向到文件再分段读取;批量转换把cs2cs EPSG:4326 EPSG:3857 points.txt一次跑完,不要逐行起进程。 - 安全与权限:
projsync --all会从 CDN 下载数 GB 网格、PROJ_NETWORK=ON也会联网,先确认网络与磁盘;sqlite3 proj.db只做只读查询,不要写库;改PROJ_DATA会影响同机 GDAL/PostGIS,先征得用户同意。
相关技能
- gdal — 栅格/矢量数据命令行处理,内部使用 PROJ 做坐标转换:../gdal/SKILL.md
- gdal-api — GDAL 编程 API(C/C++/Python/.NET):../gdal-api/SKILL.md
- postgis — PostgreSQL 空间数据库,
ST_Transform依赖 PROJ 数据:../postgis/SKILL.md - pyqgis — QGIS Python 二次开发,坐标系处理底层为 PROJ:../pyqgis/SKILL.md
参考资源
- 官方文档: https://proj.org/ | 命令行工具 | 快速上手 | 资源文件与 proj.db
- 工具手册: projinfo | cs2cs | proj | projsync
- 转换原理: https://proj.org/en/stable/operations/operations_computation.html
- EPSG 代码查询: https://epsg.io/
- 源码仓库: https://github.com/OSGeo/PROJ