GDAL Skill

GDAL技能

Use GDAL command line tools for common raster and vector geospatial workflows.

使用GDAL命令行工具完成常见的栅格和矢量地理空间工作流。

Tools

工具

Prefer the smallest tool that fits the task:

```
gdalinfo
```
```
ogrinfo
```
```
gdalwarp
```
```
gdal_translate
```
```
gdalbuildvrt
```
```
gdaladdo
```
```
gdaltindex
```
```
gdal_rasterize
```
```
gdal2tiles.py
```
```
ogr2ogr
```

If GDAL is not installed, ask the user to install it before continuing.

优先选择最适合任务的最小工具：

```
gdalinfo
```
```
ogrinfo
```
```
gdalwarp
```
```
gdal_translate
```
```
gdalbuildvrt
```
```
gdaladdo
```
```
gdaltindex
```
```
gdal_rasterize
```
```
gdal2tiles.py
```
```
ogr2ogr
```

如果未安装GDAL，请先要求用户安装后再继续。

Workflow

工作流程

1. Inspect first

1. 先检查数据

bash

gdalinfo INPUT.tif
ogrinfo INPUT.shp -so -al

One full

gdalinfo

dump on unknown data is worth it; after that, grep for the lines you need (

Size is|Origin|Pixel Size|Band|Overviews|ID\[

) — full WKT dumps are large. For vectors,

-so -al

prints the layer summary; bare

-so

without

-al

or a layer name prints nothing useful.

bash

gdalinfo INPUT.tif
ogrinfo INPUT.shp -so -al

对未知数据执行一次完整的

gdalinfo

输出是很有必要的；之后可以通过grep筛选所需行（

Size is|Origin|Pixel Size|Band|Overviews|ID\[

）——完整的WKT输出内容很大。对于矢量数据，

-so -al

会打印图层摘要；仅使用

-so

而不加

-al

或图层名称不会输出有用信息。

2. Pick raster vs vector path

2. 选择栅格或矢量处理路径

Raster tasks:

gdalwarp

,

gdal_translate

,

gdalbuildvrt

,

gdal_rasterize

,

gdal2tiles.py

Vector tasks:
```
ogr2ogr
```
,
```
ogrinfo
```
,
```
gdaltindex
```

栅格任务：

gdalwarp

、

gdal_translate

、

gdalbuildvrt

、

gdal_rasterize

、

gdal2tiles.py

矢量任务：
```
ogr2ogr
```
、
```
ogrinfo
```
、
```
gdaltindex
```

3. Write a new output

3. 生成新输出文件

prefer new output files
preserve CRS and nodata intentionally
use compression for large rasters

优先生成新的输出文件
有意保留坐标参考系统（CRS）和无数据值（nodata）
对大型栅格使用压缩

4. Validate output

4. 验证输出结果

Use the check that matches the operation — improvising verification is where runs go wrong:

bash

undefined

使用与操作匹配的检查方法——随意的验证会导致运行出错：

bash

undefined

Any lossless conversion or mosaic: band checksums must match the input

任何无损转换或镶嵌：输出波段的校验和必须与输入一致

gdalinfo -checksum INPUT.tif | grep Checksum gdalinfo -checksum OUTPUT.tif | grep Checksum

COG: quick layout check, then real validation

COG：先快速检查布局，再进行正式验证

gdalinfo OUTPUT.tif | grep -E "LAYOUT|Block=|Overviews" rio cogeo validate OUTPUT.tif # via

uv run --with rio-cogeo

if not installed

gdalinfo OUTPUT.tif | grep -E "LAYOUT|Block=|Overviews" rio cogeo validate OUTPUT.tif # 若未安装，可通过

uv run --with rio-cogeo

运行

Warp/clip: CRS, resolution, per-band min/max in one call

重投影/裁剪：一次调用即可检查CRS、分辨率及各波段的最小值/最大值

gdalinfo -mm OUTPUT.tif

Mosaic seamlessness: each quadrant bit-identical to its source tile

镶嵌无缝性：每个象限与源瓦片完全一致

(explicit offsets per tile — avoid shell arrays, the login shell may be zsh)

（为每个瓦片指定明确偏移量——避免使用shell数组，登录shell可能是zsh）

gdal_translate -q -of VRT -srcwin 0 0 256 256 MOSAIC.tif /tmp/quad.vrt gdalinfo -checksum /tmp/quad.vrt | grep Checksum # compare vs TILE_0.tif

gdal_translate -q -of VRT -srcwin 0 0 256 256 MOSAIC.tif /tmp/quad.vrt gdalinfo -checksum /tmp/quad.vrt | grep Checksum # 与TILE_0.tif对比

Vector: layer summary + SQLite-dialect counts

矢量数据：图层摘要 + SQLite方言统计

ogrinfo OUTPUT.gpkg LAYER -so ogrinfo OUTPUT.gpkg -dialect SQLite -sql "SELECT COUNT(*) FROM layer"


`gdaladdo` on a writable GeoTIFF builds internal overviews; `-ro` forces an external `.ovr` sidecar — so the absence of a `.ovr` file next to the output proves the overviews are internal.

ogrinfo OUTPUT.gpkg LAYER -so ogrinfo OUTPUT.gpkg -dialect SQLite -sql "SELECT COUNT(*) FROM layer"


对可写入的GeoTIFF执行`gdaladdo`会构建内部概览；`-ro`参数会强制生成外部`.ovr`辅助文件——因此输出文件旁若没有`.ovr`文件，说明概览是存储在内部的。

Quick Reference

快速参考

bash

undefined

bash

undefined

Inspect

检查数据

gdalinfo INPUT.tif ogrinfo INPUT.shp -so

Vector conversion and clipping

矢量转换与裁剪

ogr2ogr -f GeoJSON -t_srs epsg:4326 OUTPUT.geojson INPUT.shp gdaltindex -t_srs epsg:4326 -f GeoJSON OUTPUT_EXTENT.geojson INPUT_RASTER.tif ogr2ogr -f GeoJSON -clipsrc OUTPUT_EXTENT.geojson OUTPUT_CLIPPED.geojson INPUT.shp

Raster reprojection (choose -r intentionally: bilinear/cubic for continuous, near for categorical)

栅格重投影（需有意选择-r参数：连续数据用bilinear/cubic，分类数据用near）

gdalwarp -t_srs EPSG:XXXX -tr XRES YRES -r bilinear -co TILED=YES -co COMPRESS=DEFLATE -co PREDICTOR=2 INPUT.tif OUTPUT.tif

Raster clipping

栅格裁剪

gdal_translate -srcwin XOFF YOFF XSIZE YSIZE INPUT.tif OUTPUT.tif # by pixel window (exact, no resampling) gdal_translate -projwin ULX ULY LRX LRY INPUT.tif OUTPUT.tif # by georeferenced bounds gdalwarp -cutline INPUT.shp -crop_to_cutline -dstalpha INPUT.tif OUTPUT.tif # by polygon

gdal_translate -srcwin XOFF YOFF XSIZE YSIZE INPUT.tif OUTPUT.tif # 按像素窗口裁剪（精确，无重采样） gdal_translate -projwin ULX ULY LRX LRY INPUT.tif OUTPUT.tif # 按地理参考范围裁剪 gdalwarp -cutline INPUT.shp -crop_to_cutline -dstalpha INPUT.tif OUTPUT.tif # 按多边形裁剪

Raster conversion

栅格转换

gdal_translate -b 1 -b 2 -b 3 INPUT.tif OUTPUT.tif gdal_translate -b 1 -b 2 -b 3 -of JPEG -outsize 400 0 INPUT.tif OUTPUT.jpg

Mosaic and stack

镶嵌与堆叠

gdalbuildvrt OUTPUT.vrt path/to/tiffs/*.tif gdal_translate -co TILED=YES -co BIGTIFF=YES -co NUM_THREADS=ALL_CPUS -co COMPRESS=LZW -co PREDICTOR=2 OUTPUT.vrt OUTPUT.tif

Internal overviews on an existing GeoTIFF (-r near for categorical; -ro writes external .ovr instead)

为现有GeoTIFF添加内部概览（分类数据用-r near；-ro参数会写入外部.ovr文件）

gdaladdo -r average OUTPUT.tif 2 4 8

Rasterize and tile

栅格化与切片

gdal_rasterize -burn 1.0 -ot Byte -of GTiff -co COMPRESS=LZW -co BIGTIFF=YES INPUT.shp OUTPUT.tif gdal2tiles.py -z 10-16 INPUT_BYTE.tif OUTPUT/

COG (format-only conversion — smallest tool that fits)

COG（仅格式转换——选择最适合的最小工具）

gdal_translate -of COG -co COMPRESS=LZW -co PREDICTOR=2 -co NUM_THREADS=ALL_CPUS INPUT.tif OUTPUT.tif

use gdalwarp -of COG only when also reprojecting in the same step

仅当同时进行重投影时，才使用gdalwarp -of COG

Vector SQL: OGR's default dialect has no GROUP BY, window, or spatial functions —

矢量SQL：OGR默认方言不支持GROUP BY、窗口函数或空间函数——

pass -dialect SQLite for anything beyond simple SELECT/WHERE

若需执行简单SELECT/WHERE之外的操作，请传入-dialect SQLite参数

ogr2ogr -f GPKG OUT.gpkg IN.shp -dialect SQLite
-sql "SELECT *, ST_Area(ST_Transform(geometry, EPSG)) AS area_m2 FROM layer WHERE landuse IN ('ag')"
-t_srs EPSG:XXXX -nln layername

undefined

ogr2ogr -f GPKG OUT.gpkg IN.shp -dialect SQLite
-sql "SELECT *, ST_Area(ST_Transform(geometry, EPSG)) AS area_m2 FROM layer WHERE landuse IN ('ag')"
-t_srs EPSG:XXXX -nln layername

undefined

References

参考资料

```
references/gdal-recipes.md
```
(the only reference file)

```
references/gdal-recipes.md
```
（唯一参考文件）

gdal

Original

Translation

GDAL Skill

GDAL技能

Tools

工具

Workflow

工作流程

1. Inspect first

1. 先检查数据

2. Pick raster vs vector path

2. 选择栅格或矢量处理路径

3. Write a new output

3. 生成新输出文件

4. Validate output

4. 验证输出结果

Any lossless conversion or mosaic: band checksums must match the input

任何无损转换或镶嵌：输出波段的校验和必须与输入一致

COG: quick layout check, then real validation

COG：先快速检查布局，再进行正式验证

Warp/clip: CRS, resolution, per-band min/max in one call

重投影/裁剪：一次调用即可检查CRS、分辨率及各波段的最小值/最大值

Mosaic seamlessness: each quadrant bit-identical to its source tile

镶嵌无缝性：每个象限与源瓦片完全一致

(explicit offsets per tile — avoid shell arrays, the login shell may be zsh)

（为每个瓦片指定明确偏移量——避免使用shell数组，登录shell可能是zsh）

Vector: layer summary + SQLite-dialect counts

矢量数据：图层摘要 + SQLite方言统计

Quick Reference

快速参考

Inspect

检查数据

Vector conversion and clipping

矢量转换与裁剪

Raster reprojection (choose -r intentionally: bilinear/cubic for continuous, near for categorical)

栅格重投影（需有意选择-r参数：连续数据用bilinear/cubic，分类数据用near）

Raster clipping

栅格裁剪

Raster conversion

栅格转换

Mosaic and stack

镶嵌与堆叠

Internal overviews on an existing GeoTIFF (-r near for categorical; -ro writes external .ovr instead)

为现有GeoTIFF添加内部概览（分类数据用-r near；-ro参数会写入外部.ovr文件）

Rasterize and tile

栅格化与切片

COG (format-only conversion — smallest tool that fits)

COG（仅格式转换——选择最适合的最小工具）

use gdalwarp -of COG only when also reprojecting in the same step

仅当同时进行重投影时，才使用gdalwarp -of COG

Vector SQL: OGR's default dialect has no GROUP BY, window, or spatial functions —

矢量SQL：OGR默认方言不支持GROUP BY、窗口函数或空间函数——

pass -dialect SQLite for anything beyond simple SELECT/WHERE

若需执行简单SELECT/WHERE之外的操作，请传入-dialect SQLite参数

References

参考资料