osgeo/proj

PROJ Docker镜像文档

镜像概述和主要用途

PROJ是一款通用坐标转换软件，用于在不同坐标参考系统（CRS）之间进行坐标转换，涵盖地图投影及大地测量转换功能。本Docker镜像是PROJ的自动化构建版本，主要用于测试和验证场景，提供便捷的隔离环境以运行PROJ工具链及验证坐标转换功能。

核心功能和特性

核心功能

• 坐标参考系统转换：支持不同CRS之间的精确坐标转换，包括地图投影与大地测量转换。
• 命令行工具集：提供以下实用工具：
  • proj：大地坐标的地图投影计算
  • cs2cs：不同CRS间的坐标转换
  • geod：大地线（大圆）计算
  • cct：通用坐标转换与变换
  • gie：地理空间完整性检测环境
  • projinfo：大地测量对象及坐标操作查询
  • projsync：同步PROJ基准面及转换支持数据

关键特性

• 数据文件灵活性：支持本地部署proj-data数据包或通过PROJ CDN动态获取资源文件。
• 网络支持：网络启用版本可自动从CDN（[***]）拉取本地缺失的资源文件。
• 跨平台兼容：Docker镜像封装了运行所需依赖，确保在不同环境中行为一致。

使用场景和适用范围

适用场景

• 开发测试：在隔离环境中验证PROJ工具功能及坐标转换逻辑。
• CI/CD流程集成：作为自动化测试环节的一部分，验证依赖PROJ的应用兼容性。
• 功能验证：快速部署PROJ工具链，验证特定坐标转换场景（如自定义CRS参数、数据文件加载）。
• 临时环境：无需本地安装，通过容器快速使用PROJ工具进行坐标转换计算。

使用方法和配置说明

基础使用（Docker Run）

1. 启动交互式终端

通过以下命令启动容器并进入交互式终端，直接运行PROJ工具：

bash
docker run -it --rm docker.xuanyuan.run/osgeo/proj:latest /bin/bash

进入容器后，可直接执行工具命令（如proj --version查看版本）。

2. 运行特定工具命令

无需进入终端，直接在宿主机器执行PROJ工具命令：

bash
# 示例：使用cs2cs进行坐标转换（WGS84到UTM 32N）
docker run --rm docker.xuanyuan.run/osgeo/proj:latest cs2cs +proj=latlong +datum=WGS84 +to +proj=utm +zone=32 +datum=WGS84

输入坐标（如55.75 12.58），将返回转换结果。

数据文件配置

PROJ依赖基准面转换网格文件及参数文件，支持两种获取方式：

1. 本地数据文件挂载

将proj-data包（需预先下载，版本与PROJ匹配）挂载至容器内PROJ_LIB目录：

bash
# 假设宿主机器proj-data路径为/path/to/proj-data
docker run -it --rm \
  -v /path/to/proj-data:/usr/local/share/proj \
  docker.xuanyuan.run/osgeo/proj:latest /bin/bash

容器内PROJ_LIB默认路径为/usr/local/share/proj，挂载后PROJ将优先使用本地数据文件。

2. 网络动态获取（默认启用）

网络启用的PROJ构建会自动从PROJ CDN拉取缺失的资源文件，无需本地部署数据包。容器需具备网络访问权限（默认允许）。

环境变量配置

Docker Compose配置示例

通过docker-compose.yml定义包含数据卷挂载的服务：

yaml
version: '3'
services:
  proj:
    image: docker.xuanyuan.run/osgeo/proj:latest
    volumes:
      - ./proj-data:/usr/local/share/proj  # 挂载本地proj-data目录
    environment:
      - PROJ_NETWORK=ON  # 启用网络资源获取（可选，默认启用）
    command: cs2cs +proj=latlong +datum=WGS84 +to +proj=utm +zone=32 +datum=WGS84

启动服务：

bash
docker-compose up

注意事项

• 版本兼容性：proj-data包版本需与PROJ主程序版本匹配（如PROJ 9.x对应proj-data 1.1.x），否则可能导致数据文件不兼容。
• 网络依赖：禁用网络（PROJ_NETWORK=OFF）且未挂载本地数据时，涉及基准面转换的功能可能失效。
• 数据文件更新：可使用projsync工具同步数据文件（需在容器内执行）：

  bash
  projsync --all  # 同步所有可用资源文件至PROJ_LIB