gdal

---

name: gdal description: "Use when processing geospatial raster/vector data via command line — format conversion (Shapefile to GeoJSON), reprojection, DEM analysis, NDVI calculation, mosaicking. GDAL/OGR CLI: the industry standard for batch geospatial data processing with 50+ command-line tools (ogr2ogr, gdalwarp, gdal_translate, gdal_calc)."

tags:

• gdal
• ogr
• cli
• raster
• vector
• conversion
• reprojection
• gis
• geospatial

---

项目地址： https://github.com/OSGeo/gdal

官方文档： https://gdal.org/en/latest/

源码命令文档： https://gdal.org/en/latest/programs/

许可证： MIT

概述

GDAL 是地理空间数据处理的事实标准库。它提供了 50+ 个命令行工具，分为两大类：

• OGR 工具（开放地理数据模型）：处理矢量数据（点、线、面）
• GDAL 工具：处理栅格数据（卫星影像、DEM、栅格地图）

---

环境准备

前置条件

GDAL 3.0+ 已预装在大多数 Linux 发行版的地理信息处理环境中。确保工具在 PATH 中：

gdalinfo --version   # 验证 GDAL 版本
ogrinfo --version    # 验证 OGR 版本

安装方法

Linux (Debian/Ubuntu)

apt-get update
apt-get install gdal-bin python3-gdal

Linux (CentOS/RHEL)

yum install gdal gdal-devel

macOS (Homebrew)

brew install gdal

Conda

conda install -c conda-forge gdal

Docker

docker run -it osgeo/gdal:latest bash

Python 绑定（可选）

某些 GDAL 工具（如 gdal_calc, gdal_merge, gdal_grid, gdal_polygonize）是 Python 脚本，需要安装 Python 绑定：

pip install GDAL
# 或
conda install -c conda-forge gdal

---

核心命令结构

新式 CLI (GDAL 3.9+)

GDAL 3.9 引入了统一的 CLI 接口（最新稳定版 3.13.3，2026-08，见 下载页），并在后续版本持续完善，新增 gdal vector concave-hull/convex-hull/dissolve/sort、gdal dataset check 等子命令：

gdal <command> <subcommand> [options] <inputs>

主要命令：

• gdal info — 获取数据信息（自动检测栅格或矢量）
• gdal vector — 矢量操作入口
• gdal raster — 栅格操作入口
• gdal dataset — 数据集管理

传统 CLI（广泛使用）

ogrinfo <datasource> [layer]
ogr2ogr <output> <input> [options]
gdalinfo <raster_file>
gdal_translate <input> <output> [options]
gdalwarp <input> <output> [options]

---

矢量数据工具（OGR）

完整参数表和高级示例见 reference/vector-tools.md

ogrinfo — 矢量数据信息查询

# 列出所有图层
ogrinfo mydata.shp

# 获取特定图层摘要
ogrinfo mydata.shp layername -so

# JSON 格式输出（GDAL 3.7+）
ogrinfo -json mydata.shp

# 显示所有要素及其属性
ogrinfo -al -geom=YES mydata.shp

# 按属性过滤
ogrinfo mydata.shp -where "AREA > 1000"

ogr2ogr — 矢量数据格式转换和处理

# 格式转换（Shapefile → GeoJSON）
ogr2ogr output.geojson input.shp

# 指定输出格式（Shapefile → GeoPackage）
ogr2ogr -f GPKG output.gpkg input.shp

# 重投影（WGS84 → Web Mercator）
ogr2ogr -t_srs EPSG:3857 output.shp input.shp

# 属性过滤
ogr2ogr output.shp input.shp -where "area > 1000"

# 选择特定字段
ogr2ogr output.shp input.shp -select "id,name,geometry"

---

栅格数据工具（GDAL）

完整参数表和高级用法见 reference/raster-tools.md

gdalinfo — 栅格数据信息查询

# 基本信息
gdalinfo dem.tif

# JSON 输出
gdalinfo -json dem.tif

# 显示统计信息
gdalinfo -stats dem.tif

gdal_translate — 栅格格式转换和重采样

# 格式转换（GeoTIFF → PNG）
gdal_translate input.tif output.png

# 格式转换（带压缩）
gdal_translate -co COMPRESS=DEFLATE input.tif output.tif

# 重采样（降低分辨率）
gdal_translate -outsize 50% 50% input.tif output.tif

# 裁剪到范围
gdal_translate -projwin -180 90 -170 80 input.tif output.tif

gdalwarp — 栅格重投影和镶嵌

# 重投影（UTM 50N → WGS84）
gdalwarp -t_srs EPSG:4326 input_utm.tif output_wgs84.tif

# 镶嵌多个文件
gdalwarp input1.tif input2.tif input3.tif output_mosaic.tif

# 重采样并重投影
gdalwarp -tr 30 30 -t_srs EPSG:4326 input.tif output.tif

# 用矢量边界裁剪
gdalwarp -cutline clip_boundary.shp -crop_to_cutline input.tif output.tif

gdal_merge.py — 栅格镶嵌融合

# 基本合并
gdal_merge.py -o output.tif input1.tif input2.tif input3.tif

# 分离波段（创建多波段文件）
gdal_merge.py -separate -o rgb.tif r.tif g.tif b.tif

gdal_calc.py — 栅格计算器

# 两个栅格平均
gdal_calc.py -A input1.tif -B input2.tif --calc="(A+B)/2" --outfile=mean.tif

# 计算 NDVI（植被指数）
gdal_calc.py -A nir.tif -B red.tif \
  --calc="(A-B)/(A+B)" --outfile=ndvi.tif

gdal_contour — 等值线提取

# 提取等高线（10 米间隔）
gdal_contour -a elevation dem.tif contours.shp -i 10

# 输出为 GeoJSON
gdal_contour -f GeoJSON dem.tif contours.geojson -i 50

gdal_grid — 从散点数据创建网格

# 基本网格化（使用平均值）
gdal_grid -a average input_points.shp output_dem.tif

# 反距离加权（IDW）插值
gdal_grid -a invdist:power=2:smoothing=0 input_points.shp output_dem.tif

gdal_polygonize.py — 栅格转矢量

# 基本转换
gdal_polygonize.py input.tif output.shp

# 指定输出格式
gdal_polygonize.py input.tif -f GeoJSON output.geojson

gdaltindex — 创建栅格瓦片索引

# 基本索引
gdaltindex index.shp *.tif

# 输出为 GeoPackage
gdaltindex -of GPKG index.gpkg *.tif

gdal_edit.py — 编辑栅格元数据

# 设置坐标参考系
gdal_edit.py -a_srs EPSG:4326 input.tif

# 设置 NoData 值
gdal_edit.py -a_nodata 0 input.tif

nearblack — 清理黑白边界

# 清理黑色边界（默认）
nearblack input.tif -o output.tif

# 搜索白色边界
nearblack -white input.tif -o output.tif

---

常用环境变量和配置

GDAL 环境变量

变量	说明	示例
GDAL_DATA	GDAL 数据文件目录	/usr/share/gdal/
PROJ_LIB	PROJ 数据文件目录	/usr/share/proj/
CPL_DEBUG	调试日志级别	ON / OFF
GDAL_CACHEMAX	块缓存大小（MB）	512
GDAL_NUM_THREADS	线程数	4 / ALL_CPUS
GDAL_DISABLE_READDIR_ON_OPEN	禁用目录读取	YES
GDAL_HTTP_TIMEOUT	HTTP 超时（秒）	30
GDAL_HTTP_MAX_RETRY	HTTP 重试次数	3
CPL_VSIL_CURL_ALLOWED_EXTENSIONS	允许的远程文件扩展名	.tif,.tiff,.vrt
AWS_ACCESS_KEY_ID	AWS 密钥 ID	用于 S3 访问
AWS_SECRET_ACCESS_KEY	AWS 密钥	用于 S3 访问
GOOGLE_APPLICATION_CREDENTIALS	Google Cloud 凭证文件	/path/to/credentials.json

使用环境变量

# 启用多线程处理
export GDAL_NUM_THREADS=ALL_CPUS

# 增加块缓存
export GDAL_CACHEMAX=1024

# 启用调试
export CPL_DEBUG=ON

# 访问 S3 上的栅格
export AWS_ACCESS_KEY_ID=xxxxx
export AWS_SECRET_ACCESS_KEY=xxxxx
gdalinfo /vsis3/bucket/key.tif

# 运行命令
gdalwarp input.tif output.tif

---

数据格式支持

矢量格式

格式	扩展名	说明
Shapefile	.shp	ESRI 标准格式
GeoJSON	.geojson	Web 标准 JSON
GeoPackage	.gpkg	SQLite 基础，推荐
KML	.kml	Google Maps 格式
PostGIS	N/A	数据库矢量存储
GML	.gml	ISO 标准 XML
CSV	.csv	点数据
DXF	.dxf	CAD 格式
MapInfo	.tab	MapInfo 格式

栅格格式

格式	扩展名	说明
GeoTIFF	.tif, .tiff	标准地理栅格（推荐）
PNG	.png	Web 图像
JPEG	.jpg, .jpeg	有损压缩
COG	.tif	云优化 GeoTIFF
NetCDF	.nc	科学数据
HDF5	.h5, .he5	多维数据
ASCII Grid	.asc	简单栅格（DEM）
JPEG2000	.jp2	高质量压缩
ECW	.ecw	ERDAS ECW 格式

---

常见使用模式

模式 1: 批量格式转换

#!/bin/bash
# 将目录内所有 Shapefile 转换为 GeoJSON

for shp in *.shp; do
  base="${shp%.shp}"
  ogr2ogr -f GeoJSON "$base.geojson" "$shp"
done

模式 2: 批量重投影

#!/bin/bash
# 重投影所有 GeoTIFF 为 Web Mercator (EPSG:3857)

for tif in *.tif; do
  base="${tif%.tif}"
  gdalwarp -t_srs EPSG:3857 "$tif" "${base}_3857.tif"
done

模式 3: 创建 DEM 等值线

#!/bin/bash
# 从 DEM 提取等高线（10 米间隔）

gdal_contour -a elev dem.tif -i 10 contours.shp

# 转换为 GeoJSON
ogr2ogr -f GeoJSON contours.geojson contours.shp

模式 4: 计算 NDVI

#!/bin/bash
# 从多光谱影像计算 NDVI

gdal_calc.py \
  -A nir_band.tif \
  -B red_band.tif \
  --calc="(A-B)/(A+B)" \
  --outfile=ndvi.tif

模式 5: 镶嵌和重投影

#!/bin/bash
# 合并多个影像并重投影到 WGS84

gdalwarp -t_srs EPSG:4326 \
  image1.tif image2.tif image3.tif \
  output_mosaic_wgs84.tif

模式 6: 创建栅格瓦片索引

#!/bin/bash
# 为目录内所有 GeoTIFF 创建索引

gdaltindex -recursive -of GPKG \
  tile_index.gpkg /path/to/rasters/

---

AI 使用建议

推荐工作流

1. 探索数据：

   gdalinfo input.tif  # 栅格信息
   ogrinfo input.shp   # 矢量信息
   

2. 检查支持的格式和驱动：

   gdalinfo --formats
   ogrinfo --formats
   

3. 分步处理（避免大内存操作）：

   # 不要直接镶嵌所有文件
   # 改为逐个处理和合并
   

4. 使用 JSON 输出（便于解析）：

   gdalinfo -json input.tif | jq '.coordinateSystem'
   ogrinfo -json input.shp | jq '.layers[0].featureCount'
   

5. 优化性能：

   # 启用多线程、内存缓存、COG 格式
   export GDAL_NUM_THREADS=ALL_CPUS
   export GDAL_CACHEMAX=2048
   

关键注意事项

• 始终备份：GDAL 可以就地修改文件（如 gdal_edit.py）
• 使用绝对路径：避免工作目录问题
• 验证坐标系：重投影前确认源和目标坐标系
• 测试小数据：在大数据集上运行前，用小样本测试
• 使用 VRT（虚拟数据集）：避免创建多个副本
• 环境变量：设置适当的 GDAL_CACHEMAX 和 GDAL_NUM_THREADS

---

相关技能

• gdal-api — GDAL 编程 API（C/C++/Python/.NET）：../gdal-api/SKILL.md
• qgis-process — QGIS 命令行批处理：../qgis-process/SKILL.md
• pyqgis — QGIS Python 二次开发：../pyqgis/SKILL.md
• postgis — PostgreSQL 空间数据库：../postgis/SKILL.md
• opengis-all — 一站式 GIS 全流程：../opengis-all/SKILL.md

参考资源

• 官方文档与资源： https://gdal.org/ | 命令行工具 | API | GitHub
• 矢量工具详细参考： reference/vector-tools.md
• 栅格工具详细参考： reference/raster-tools.md