企业官网建设流程全解析

• GIS
• 遥感
• 数据工程

导读

本文以 raster_api.rst 文档为核心骨架，系统梳理 GDAL Python 绑定中围绕栅格数据模型（Raster Data Model）提供的核心 API：驱动管理（Driver）、栅格数据集（Dataset）、波段（Band）、波段代数（Band Algebra）以及地理变换与栅格元数据等辅助设施。读完本文，你将掌握用osgeo.gdal模块打开、创建、读写栅格数据，利用惰性求值的波段代数表达式完成逐像素运算，并通过 ColorTable、RasterAttributeTable、GCP 等对象管理与栅格关联的元数据的完整实战路径。

一、文档性质：由 Python Docstring 自动生成的 API 参考

本页面属于 GDAL 官方文档的 Python API 章节（doc/source/api/python/index.rst 的 toctree 之一）。页首注释明确说明：该页内容由 Python docstring 自动生成（Sphinxautoclass/autofunction指令），而非手工撰写。

这意味着页面内容真正的"源头"不在 RST 文件里，而是散落在 SWIG 绑定接口文件中。撰写 docstring 的接口文件全部位于 swig/include/python/docs，与本文主题一一对应：

• gdal_driver_docs.i：Driver类及AllRegister、GetDriver等驱动管理函数；
• gdal_dataset_docs.i：Dataset类及Open、OpenEx、OpenShared等函数；
• gdal_band_docs.i：Band类及RegenerateOverview(s)函数；
• gdal_algorithm_docs.i 与 gdal_operations_docs.i：波段代数与相关栅格操作；
• gdal_rat_docs.i：RasterAttributeTable类。

理解这一生成机制很重要：如果你想查阅某个方法最权威的参数说明，可以直接在上述.i文件中按类名/方法名定位，文档正文与源码 docstring 始终同步。

二、准备工作：导入与数据模型

raster_api.rst所属的 Python API 章节默认使用.. py:currentmodule:: osgeo.gdal指令，因此页面中所有Driver、Dataset、Band等符号均指osgeo.gdal模块下的成员。典型用法：

from osgeo import gdal # 栅格 API 主模块 from osgeo import gdalconst # 常量（数据类型、颜色解释等） import numpy as np # 可选，用于读写 NumPy 数组

栅格数据模型的核心组织方式为"数据集（Dataset）→ 波段（Band）→ 像素块（Block）"三层结构。在 Python 绑定中，Dataset自 GDAL 3.8 起支持上下文管理器语法，退出with块时数据集会被关闭并将数据写入磁盘，见 gdal_dataset_docs.i 中GDALDatasetShadow的类文档。

三、Driver：驱动管理与数据集创建

3.1 驱动注册与查找

GDAL 通过驱动（Driver）抽象实现"同一套 API、上百种格式"。Python 侧提供以下驱动管理函数：

典型用法：

gtiff_driver = gdal.GetDriverByName('GTiff') print(gtiff_driver.ShortName) # 'GTiff' print(gtiff_driver.LongName) # 'GeoTIFF'

3.2 Driver 类核心方法

Driver是GDALDriver的 Python 代理，常用方法如下：

• Create(path, xsize, ysize, bands=1, eType=GDT_Byte, options=None)：用该驱动新建栅格数据集。xsize/ysize为像素宽高；创建矢量数据集时传入(0, 0, 0, GDT_Unknown)；eType可以是gdal.GDT_*整数或 NumPy dtype；options接受驱动相关的['NAME=VALUE']列表或字典，例如{'COMPRESS': 'DEFLATE'}。官方 docstring 给出的示例：

>>> with gdal.GetDriverByName('GTiff').Create( ... 'test.tif', 12, 4, 2, gdal.GDT_Float32, ... {'COMPRESS': 'DEFLATE'}) as ds: ... print(gdal.Info(ds)) ... Driver: GTiff/GeoTIFF Files: test.tif Size is 12, 4 Image Structure Metadata: INTERLEAVE=PIXEL Band 1 Block=12x4 Type=Float32, ColorInterp=Gray Band 2 Block=12x4 Type=Float32, ColorInterp=Undefined

• CreateCopy(path, src, strict=1, options=None, callback=None, callback_data=None)：从已有数据集复制生成新数据集。strict=1表示输出必须与原数据集严格等价，否则允许按目标格式做适应性转换。
• CreateVector(path)：Create(name, 0, 0, 0, gdal.GDT_Unknown)的别名，专用于创建矢量数据集。
• Delete(path)：删除数据集（返回CE_None或CE_Failure）。
• Rename(newName, oldName)/CopyFiles(newName, oldName)：重命名 / 复制数据集关联的所有文件。
• Register()/Deregister()：注册 / 注销驱动。
• TestCapability(cap)：检测驱动是否支持某项能力，例如ogr.ODrCCreateDataSource。docstring 示例中'ESRI Shapefile'与'GTiff'均返回True。
• HasOpenOption(openOptionName)：检测驱动是否支持某个打开选项，如gdal.GetDriverByName('GPKG').HasOpenOption('PRELUDE_STATEMENTS')返回True。

3.3 从源码看 Python 侧实现

值得留意的是，Python 绑定通过 SWIG 把 C++ 的GDALDriver类包装为GDALDriverShadow，ShortName、LongName、HelpTopic等属性分别对应GDALGetDriverShortName、GDALGetDriverLongName、GDALGetDriverHelpTopic底层函数（见 gdal_driver_docs.i）。因此驱动相关的所有行为都与 C++ 层完全一致，Python 只是"翻译层"。

四、Dataset：打开、创建与读写栅格

4.1 打开数据集

ds = gdal.Open('byte.tif', gdal.GA_ReadOnly) print(ds.RasterXSize, ds.RasterYSize) # 像素宽、高 print(ds.RasterCount) # 波段数

4.2 Dataset 常用属性与方法

Dataset是栅格操作的主入口，其成员在 gdal_dataset_docs.i 中有完整说明，核心成员包括：

尺寸与波段

• RasterXSize/RasterYSize：栅格宽度与高度（像素）。
• RasterCount：波段数量。
• GetRasterBand(nBand)：获取第nBand（从 1 起）个波段，返回Band或None。

地理参考（Geo-referencing）

• GetGeoTransform(can_return_null=False)：返回 6 元组仿射变换系数(originX, pixelWidth, rotation1, originY, rotation2, pixelHeight)；当数据集未定义变换时，若can_return_null=True则返回None，否则返回默认变换。
• SetGeoTransform(argin)：设置 6 元组变换系数，返回CE_None/CE_Failure。
• GetProjection()/GetProjectionRef()：返回数据集空间参考的 WKT 字符串。
• SetProjection(prj)：接受 WKT 或 PROJ.4 格式字符串。
• GetSpatialRef()/SetSpatialRef(srs)：直接以osr.SpatialReference对象读写空间参考（新式 API）。
• GetGCPCount()/GetGCPs()/SetGCPs()：读写地面控制点，GetGCPs()返回GCP对象元组。
• GetExtent(srs=None)（3.12 新增）：返回(minx, maxx, miny, maxy)范围；GetExtentWGS84LongLat()返回 WGS84 经纬度范围。

读写与缓存

• ReadAsArray(...)/WriteArray(...)：以 NumPy 数组读写（见下文 Band 与性能注意）。
• FlushCache()：将写缓存刷入磁盘。
• BuildOverviews(resampling, overviewlist, callback=None, callback_data=None, options=None)：为所有波段构建金字塔概览，overviewlist传空列表可清除已有概览。docstring 示例：构建[2, 4]两个概览层后GetOverviewCount()返回2。
• AddBand(datatype, options=None)：追加波段（并非所有驱动支持）。
• CreateMaskBand(flags)：为数据集创建掩膜波段。
• Close()：强制关闭数据集释放资源；文档推荐优先使用with上下文管理器，而不是手工调用Close()。
• GetDriver()：获取打开/创建该数据集的驱动。
• GetFileList()：返回该数据集关联的所有文件列表（如.tif旁的.tfw、.aux.xml）。
• GetLayerCount()/GetLayerByIndex(index)/GetLayerByName(name)/CreateLayer(...)：矢量层面的图层管理（GDAL 3.x 起统一数据集模型）。
• StartTransaction()/CommitTransaction()/RollbackTransaction()/TestCapability(cap)：事务支持，TestCapability(ogr.ODsCTransactions)可先探测驱动是否支持事务。

上下文管理器写法（GDAL 3.8+）

with gdal.GetDriverByName('GTiff').Create('out.tif', 100, 100, 1, gdal.GDT_Float32) as ds: band = ds.GetRasterBand(1) band.WriteArray(np.arange(100 * 100).reshape(100, 100)) # 退出 with 块后自动关闭并落盘

五、Band：波段读写、统计与元数据

5.1 基本读写

Band是GDALRasterBand的 Python 代理（见 gdal_band_docs.i），通过ds.GetRasterBand(i)获取。最常用的读写接口是ReadAsArray与WriteArray（由 SWIG typemap 映射到 C++ 的GDALRasterIO，底层实现见 gdal_python.i 中ReadRaster1/ReadBlock的 buffer 获取与对齐检查逻辑）：

band = ds.GetRasterBand(1) data = band.ReadAsArray(buf_xsize=None, buf_ysize=None, buf_obj=None) # 整波段读为 ndarray window = band.ReadAsArray(win_xoff=0, win_yoff=0, win_xsize=256, win_ysize=256, buf_xsize=256, buf_ysize=256) band.WriteArray(np.ones((256, 256), dtype=np.uint8), xoff=0, yoff=0)

参数含义：win_*指定源窗口（像素坐标），buf_*指定输出缓冲区尺寸（可实现重采样缩放）；buf_obj可传入预先分配的缓冲区对象以避免重复分配内存。注意，Python 绑定会对buf_obj执行可写缓冲区检查，并对数据类型做字节对齐校验（如GDT_Float32要求 4 字节对齐），不符合时会报错（对应源码getAlignment()与readraster_acquirebuffer()）。

5.2 块（Block）机制

• GetBlockSize()：返回[blockXSize, blockYSize]自然块尺寸。
• GetActualBlockSize(nXBlockOff, nYBlockOff)：返回指定块的实际有效尺寸（边缘块可能小于自然块）。
• ReadBlock(xoff, yoff, buf_obj=None)：读取单个块。

块是 GDAL 缓存与 I/O 调度的基本单元，理解块尺寸有助于优化读写性能。

5.3 统计信息

docstring 中的完整示例（确定性随机数）：

>>> np.random.seed(123) >>> ds = gdal.GetDriverByName('MEM').Create('', 10, 10, eType=gdal.GDT_Float32) >>> ds.WriteArray(np.random.normal(size=100).reshape(10, 10)) 0 >>> ds.GetRasterBand(1).GetHistogram(min=-3.5, max=3.5, buckets=13, approx_ok=False) [0, 2, 1, 6, 17, 18, 13, 14, 16, 8, 5, 0, 0]

5.4 像元语义元数据

• NoData：SetNoDataValue/GetNoDataValue/DeleteNoDataValue；64 位整型波段还有GetNoDataValueAsInt64、GetNoDataValueAsUInt64。设置 NoData 后，掩膜波段会自动联动（见下）。
• Scale/Offset：GetScale()/SetScale(val)、GetOffset()/SetOffset(val)，用于表达存储值到物理值（如辐射亮度）的线性换算。
• 单位：GetUnitType()/SetUnitType(val)，示例中SetUnitType('ft')后GetUnitType()返回'ft'。
• 类别名：GetCategoryNames()/SetCategoryNames(list)（GetRasterCategoryNames为别名）。
• 颜色解释：GetColorInterpretation()/SetColorInterpretation(val)，取值如gdal.GCI_RedBand、gdal.GCI_Undefined；GetRasterColorInterpretation为旧别名。
• 颜色表：GetColorTable()/SetColorTable(arg)（旧别名GetRasterColorTable/SetRasterColorTable）。

5.5 掩膜与概览

• GetMaskBand()/GetMaskFlags()/CreateMaskBand(nFlags)：访问/创建掩膜波段。GetMaskFlags() == gdal.GMF_ALL_VALID表示全部有效；设置 NoData 后掩膜标志变为GMF_NODATA。docstring 示例演示了设置 NoData 后掩膜波段读出0（无效）与255（有效）的过程。
• GetOverviewCount()/GetOverview(i)：访问概览波段。
• HasArbitraryOverviews()：检测是否存在任意概览。
• GetDataCoverageStatus(nXOff, nYOff, nXSize, nYSize, nMaskFlagStop=0)：判断窗口内数据覆盖情况，返回(flags, pct)，其中flags是GDAL_DATA_COVERAGE_STATUS_DATA/GDAL_DATA_COVERAGE_STATUS_EMPTY/GDAL_DATA_COVERAGE_STATUS_UNIMPLEMENTED的按位或，pct为有效像元百分比。docstring 示例中分别对含数据块、空块、跨四块窗口返回100.0、0.0、25.0。
• Fill(real_fill, imag_fill=0.0)：用常量填充整个波段。
• Checksum(xoff=0, yoff=0, xsize=None, ysize=None)：计算区域校验和（-1 表示出错），常用于快速比对两个波段是否一致。

5.6 概览重建函数

raster_api.rst在 Band 一节还列出了两个模块级函数：

• gdal.RegenerateOverview(src_band, overview_band, resampling_alg='average', callback=None, callback_data=None)：从源波段重建单个概览波段。
• gdal.RegenerateOverviews(src_band, overview_bands, resampling_alg='average', callback=None, callback_data=None)：批量重建多个概览。

六、Band Algebra：惰性求值的波段代数

6.1 ComputedBand 与惰性求值

ComputedBand是波段代数运算结果的载体。所有代数操作返回的都是惰性求值的Band对象——表达式构造时并不真正读取像元，只有最终执行 I/O（如ReadAsArray()）时才触发计算。这使复杂的多波段表达式可以组合成"计算图"一次性执行。

Python 绑定为此在 gdal_python.i 中为Band实现了丰富运算符：+ - * /（含__radd__等反向运算）、比较运算符> >= < <= == !=，以及模块级函数。运算对象可以是Band、NumPy 数组或数值常量；数组会被_get_as_band_if_possible自动转为单波段Band（底层调用gdal_array.OpenArray）。

ndvi = (nir_band - red_band) / (nir_band + red_band) ndvi_array = ndvi.ReadAsArray() # 此时才真正执行逐像元计算

6.2 一元与二元函数

raster_api.rst的 Band Algebra 一节列出的函数（均返回惰性Band）：

例如gdal.minimum(band1, band2, 0)等价于"逐像元取band1、band2、0中的最小值"；gdal.where(dem > 100, dem, 0)可实现阈值截断。各函数还提供了Abs、Sqrt、Log、Log10、Pow、Maximum、Minimum、Mean、LogicalAnd、LogicalOr、LogicalNot、Where等大写别名。

这些 Python 层包装最终调用 C++ 的Band_BinaryOpBand、Band_BinaryOpDouble、Band_BinaryOpDoubleToBand、Band_UnaryOp等函数（见 gdal_python.i），计算时保持波段间的父子引用关系（_add_parent_references），确保临时波段在表达式求值前不会被垃圾回收。

七、Other：地理变换、栅格属性表与颜色表

7.1 仿射变换：ApplyGeoTransform 与 InvGeoTransform

这两个模块级函数用于在像元坐标与地理坐标之间转换（GDAL文档将其放在 Dataset 的 GeoTransform 概念之下）：

• gdal.ApplyGeoTransform(gt, x, y)：给定 6 元组仿射变换gt（与GetGeoTransform()返回结构一致），将像元/地理坐标(x, y)变换为另一个坐标系的(x', y')，返回(x', y')。
• gdal.InvGeoTransform(gt)：求仿射变换的逆变换，返回新的 6 元组；gt不可逆时返回None。

配合使用即可在"行/列 ↔ 投影坐标"之间互转：

gt = ds.GetGeoTransform() inv_gt = gdal.InvGeoTransform(gt) # 地理 → 像素 x_geo, y_geo = gdal.ApplyGeoTransform(gt, col, row) # 像素 → 地理 col, row = gdal.ApplyGeoTransform(inv_gt, x_geo, y_geo)

7.2 RasterAttributeTable：栅格属性表

RasterAttributeTable（RAT）用于把栅格像元值映射到分类/属性（如土地利用分类、DEM 分级），是GDALRasterAttributeTable的 Python 代理（文档见 gdal_rat_docs.i）。典型获取方式：ds.GetRasterBand(1).GetDefaultRAT()。

核心成员：

• 列管理：CreateColumn(pszName, eType, eUsage)新建列（追加为最后一列，默认值''或 0）；GetColumnCount()、GetNameOfCol(iCol)、GetTypeOfCol(iCol)（GFT_Integer/GFT_Real/GFT_String）、GetUsageOfCol(iCol)（如gdal.GFU_Name、gdal.GFU_Red）；GetColOfUsage(eUsage)返回首个指定用途的列索引，找不到返回-1。
• 行管理：SetRowCount(nCount)调整行数；GetRowCount()；SetTableType(eTableType)设置主题（GRTT_THEMATIC）或非主题（GRTT_ATHEMATIC）表。
• 单元格读写：GetValueAsInt/AsDouble/AsString(iRow, iCol)与SetValueAsInt/AsDouble/AsString(...)。当iRow等于当前行数时，写入会自动把表扩一行；但批量插入前先SetRowCount效率更高。
• 批量读取：ReadValuesIOAsInteger(iField, iStartRow=0, iLength=None)、ReadValuesIOAsDouble(...)、ReadValuesIOAsString(...)，把整列读成列表。
• 查找与分箱：GetRowOfValue(dfValue)返回对应值的行索引（-1表示未找到）；SetLinearBinning(dfRow0Min, dfBinSize)/GetLinearBinning()提供等宽分箱的快速查找——注意分箱信息必须与实际行定义一致，否则查找结果会出错（docstring 有明确警告）。
• 其他：Clone()、DumpReadable()（返回 XML 表示）、RemoveStatistics()。

docstring 示例（testrat.tif的默认 RAT 共 9 列）：

>>> [rat.GetNameOfCol(i) for i in range(rat.GetColumnCount())] ['VALUE', 'COUNT', 'CLASS', 'Red', 'Green', 'Blue', 'OtherInt', 'OtherReal', 'OtherStr'] >>> rat.GetValueAsString(rat.GetRowOfValue(2), 2) 'my class2'

RAT 的底层 C++ 实现在 gcore/gdal_rat.cpp（含 Vat 的 DBF 落盘逻辑），Python 侧全部方法与之对应。

7.3 ColorTable 与 ColorEntry：调色板

ColorTable用于调色板（Palette）型影像，把像元值映射为 RGBA 颜色；ColorEntry是表中单个颜色条目（RGBA 四分量）。常用模式：

ct = gdal.ColorTable() ct.CreateColorRamp(0, gdal.ColorEntry(0, 0, 255, 255), 255, gdal.ColorEntry(255, 0, 0, 255)) band.SetColorTable(ct)

ColorTable的完整成员（Clone、CreateColorRamp、GetColorEntry、GetColorEntryCount、ReadAsArray等）同样由 docstring 自动生成，可在 swig/include 对应的ColorTable.i及其_docs.i中查阅。底层类实现在 gcore/gdal_colortable.cpp。

7.4 GCP：地面控制点

GCP对象描述一个地面控制点，字段包括Id、GCPPixel、GCPLine（像元行列）、GCPX、GCPY、GCPZ（地理坐标）与Info。Python 绑定为其增强了两个便利方法（见 gdal_python.i 的%extend GDAL_GCP）：

• __str__：格式化输出，如'0 (12.00P,34.00L) -> (-117.0000000E,33.0000000N,0.00) '；
• serialize(with_Z=0)：把 GCP 序列化为 XML 元素树结构，可用于写入 GCP 元数据。

结合Dataset的SetGCPs()/GetGCPs()/GetGCPProjection()使用，即可在像元坐标与地理坐标之间建立稀疏控制点映射。

八、性能注意：ReadAsArray 与内存

官方文档（swig/python/README.rst 的 Performance Notes）对 Python 栅格读取给出明确提醒：

• Dataset.ReadAsArray()/Band.ReadAsArray()默认会整份复制一个波段或整个数据集到内存。对大型栅格，这种写法可能造成难以承受的内存占用。
• 建议在调用时显式指定子窗口（win_xoff/win_yoff/win_xsize/win_ysize），或使用buf_obj复用预分配缓冲区，按块（Block）或按行分批读取。
• 只有在显式子集化时，ReadAsArray才不会一次性拷贝全图。

此外，NumPy 集成是 Python 绑定独有的高级特性：ReadAsArray返回的ndarray可直接交给 SciPy、NumPy 等生态工具做数值处理；若仅需要 NumPy 数组读写，可先通过pip install numpy安装依赖（osgeo.gdal_array模块的构建强依赖 NumPy）。Python 绑定的构建与安装细节（源码构建、PyPI 安装、Conda 安装、NumPy 2.0 兼容注意事项）同样可参考 swig/python/README.rst。

九、验证与更多资料

• 示例数据：本文 docstring 示例大量使用byte.tif（GDAL 自带测试数据，如 doc/source/api/python/data/byte.tif）与testrat.tif（含默认 RAT 的测试栅格，见 autotest 相关用例）。
• 回归测试：GDAL 绝大多数回归测试用 Python 编写，位于 autotest（alg、gcore、gdrivers等目录），其中包含了Dataset、Band、ReadAsArray、BuildOverviews、RAT、ColorTable 等 API 的行为验证。
• 算法示例：gdal.FillNodata、gdal.ReprojectImage、gdal.IsLineOfSightVisible等栅格操作函数的完整参数说明见 gdal_operations_docs.i（如FillNodata支持{'INTERPOLATION': 'NEAREST'}选项）。
• 相邻章节：矢量 API 见 doc/source/api/python/vector_api.rst，空间参考 API 见 doc/source/api/python/spatial_ref_api.rst，多维栅格 API 见 doc/source/api/python/mdim_api.rst，Python 绑定行为差异见 doc/source/api/python/python_gotchas.rst。

小结

raster_api.rst虽然是一份"自动生成的索引页"，但它精确划定了 GDAL Python 栅格编程的完整 API 边界：从Driver的注册与创建、Dataset的打开/创建/地理参考/事务，到Band的分块读写、统计直方图、掩膜概览与 NoData/Scale 元数据，再到惰性求值的Band Algebra表达式，以及ApplyGeoTransform、RasterAttributeTable、ColorTable、GCP等辅助设施。对照 swig/include/python/docs 下的 docstring 源文件阅读本页，可以同时获得"接口定义"与"实现行为"两方面的完整信息——这正是高效使用 GDAL Python 绑定编写栅格处理管线的基础。

• GIS
• 遥感
• 数据工程