GDAL OGRLayer C++ API 深度指南:图层读写、空间/属性过滤、事务与能力检测实战

原创2026-10-11 17:50:421,348 阅读
文章标签:GIS数据处理

GDAL OGRLayer C++ API 深度指南:图层读写、空间/属性过滤、事务与能力检测实战

本篇指南以 GDAL 官方 API 参考页 ogrlayer_cpp.rst 为主线,系统讲解矢量图层抽象类 OGRLayer 的 C++ 接口:如何遍历与随机读取要素、如何用空间与属性过滤器缩小结果集、如何写入要素与管理字段、如何使用事务,以及如何通过 TestCapability() 探测驱动能力。读完本文,你将掌握基于 GDAL C++ API 编写完整矢量图层处理程序的能力,并能结合 ogrsf_frmts.h 与 ogrlayer.cpp 的源码理解其底层实现机制。

一、OGRLayer 是什么:API 参考页背后的类

OGRLayer 是 GDAL 中简单要素(Simple Features)图层的统一抽象。无论底层是 Shapefile、GeoPackage、PostGIS,还是内存数据集,矢量数据都以"数据集(GDALDataset)→ 图层(OGRLayer)→ 要素(OGRFeature)→ 几何(OGRGeometry)"的层级组织,其中 OGRLayer 正是衔接数据集与要素的核心枢纽。

1.1 包含文件与类声明位置

官方 API 参考页明确指出,使用 OGRLayer 只需包含一个头文件:

在该头文件中,OGRLayer 继承自 GDALMajorObject(见 ogrsf_frmts.h#L60),并声明了完整的成员方法。值得注意的是头文件中有两条重要的开发约定(ogrsf_frmts.h#L57-L58):

  • 任何新增的虚拟方法都必须同步添加到 OGRLayerDecorator 与 OGRMutexedLayer 两个包装类中;
  • 类禁止拷贝构造与拷贝赋值(CPL_DISALLOW_COPY_ASSIGN)。

1.2 文档生成机制

该 RST 参考页本身采用 Breathe 扩展从 Doxygen 注释自动生成(见 ogrlayer_cpp.rst 开头的注释)。也就是说,OGRLayer 每个方法完整的行为说明、参数含义、返回值与 C 函数对照,都写在 ogrlayer.cpp(8700 余行,默认实现集中地)以及各驱动子类的源码注释中。因此"读 API 参考页"与"读源码注释"在 GDAL 中是同一件事。

二、获取图层对象与生命周期管理

2.1 从数据集获取图层

OGRLayer 实例通常不直接构造,而是从已打开的 GDALDataset 获取:

#include "ogrsf_frmts.h"

int main()
{
    GDALAllRegister();

    GDALDataset *poDS = static_cast<GDALDataset *>(
        GDALOpenEx("data/poly.shp", GDAL_OF_VECTOR, nullptr, nullptr, nullptr));
    if (poDS == nullptr)
        return 1;

    // 按索引或名称取图层
    OGRLayer *poLayer = poDS->GetLayer(0);
    // 或 poDS->GetLayerByName("poly");

    if (poLayer != nullptr)
    {
        printf("Layer: %s, 字段数: %d\n",
               poLayer->GetName(),
               poLayer->GetLayerDefn()->GetFieldCount());
    }

    GDALClose(poDS);
    return 0;
}

图层的生命周期由数据集管理:关闭数据集时其所有图层一并销毁,调用方不得单独 delete 一个从数据集取得的 OGRLayer 指针。

2.2 智能指针与引用计数

仓库为图层提供了两个现代 C++ 辅助设施(均位于 ogrsf_frmts.h):

  • OGRLayerUniquePtr(GDAL 3.2+):using OGRLayerUniquePtr = std::unique_ptr<OGRLayer>;(ogrsf_frmts.h#L494),用于持有驱动按需创建、生命周期自管的图层对象;
  • Reference() / Dereference() / GetRefCount():图层自身的引用计数管理,C 接口对应 OGR_L_Reference() / OGR_L_Dereference() / OGR_L_GetRefCount()(实现见 ogrlayer.cpp#L95-L163)。

三、核心读取操作:顺序遍历与随机读取

3.1 顺序读取:ResetReading() 与 GetNextFeature()

所有驱动子类必须实现两个纯虚方法:

virtual void ResetReading() = 0;
virtual OGRFeature *GetNextFeature() = 0;
  • ResetReading():将读取游标重置到图层起点;
  • GetNextFeature():返回下一个要素,到达末尾返回 nullptr。返回值由调用方所有,用完后必须释放。

由于要素返回的是裸指针,现代代码推荐使用范围 for 循环 + 迭代器。OGRLayer 提供了 begin() / end() 成员及配套的自由函数(ogrsf_frmts.h#L191-L203):

for (auto &&poFeature : *poLayer)
{
    // poFeature 是 OGRFeatureUniquePtr 的引用
    OGRGeometry *poGeom = poFeature->GetGeometryRef();
    if (poGeom != nullptr)
        printf("FID=%lld, 几何类型=%s\n",
               static_cast<long long>(poFeature->GetFID()),
               poGeom->getGeometryName());
}

源码注释给出了三条使用约束(ogrsf_frmts.h#L191-L199):

  1. 标准范围 for 循环安全,但一次只应解引用一个迭代器步——底层 OGRFeatureUniquePtr 引用会被复用;
  2. 同一时刻每个图层只能有一个迭代器处于活跃状态;
  3. 迭代器实现内部复用要素容器,勿将迭代器保存到循环之外长期使用。

3.2 随机读取:GetFeature() 与 SetNextByIndex()

GetFeature(GIntBig nFID) 按要素 ID 随机读取。其默认实现(ogrlayer.cpp#L942-L972)非常具有参考价值:

  1. 先保存当前属性过滤字符串与空间过滤几何(并克隆一份),记录当前几何字段过滤索引;
  2. 清除两个过滤器;
  3. 顺序遍历全部要素,比对 GetFID() == nFID 命中即取出;
  4. 恢复原过滤器。

即"无 OLCRandomRead 能力时也能工作,只是靠扫描实现"。官方注释同时强调:GetFeature() 的成败不受空间/属性过滤器影响;顺序读取通常会被 GetFeature() 调用"打断"。

SetNextByIndex(GIntBig nIndex) 将读取游标移到结果集的第 n 个要素,默认实现同样以"重置 + 顺序跳过"的方式兜底,OLCFastSetNextByIndex 能力为 TRUE 时驱动才会给出高效实现。

3.3 要素统计:GetFeatureCount() 与 GetExtent()

  • GetFeatureCount(int bForce):返回图层要素数,计数会考虑当前空间过滤器。默认实现中 bForce = FALSE 时直接返回 -1(表示"未知"),bForce = TRUE 时完整扫描一遍图层并随后调用 ResetReading()(ogrlayer.cpp#L204-L219)。部分驱动实现会移动读取游标。
  • GetExtent(OGREnvelope *psExtent, bool bForce = true) / GetExtent(iGeomField, ...):获取图层数据的最小包围盒(MBR)。bForce = FALSE 且计算成本高时返回 OGRERR_FAILURE;TRUE 时扫描全层计算。注意:返回的范围是否考虑空间过滤器取决于驱动,官方建议在未设置空间过滤时调用 GetExtent()(ogrlayer.cpp#L266-L279)。
  • GetExtent3D():返回 3D 包围盒(OGREnvelope3D)。
  • GetFeaturesRead():返回本图层已被读取的要素数(ogrlayer.cpp#L4562)。

四、空间过滤与属性过滤

过滤器是 OGRLayer 最高频的实战特性,它作用于后续所有 GetNextFeature() / 迭代 / GetFeatureCount() 调用。

4.1 空间过滤:SetSpatialFilter() 与 SetSpatialFilterRect()

OGRErr SetSpatialFilter(const OGRGeometry *poFilter);
OGRErr SetSpatialFilter(int iGeomField, const OGRGeometry *poFilter);
OGRErr SetSpatialFilterRect(double dfMinX, double dfMinY,
                            double dfMaxX, double dfMaxY);
OGRErr SetSpatialFilterRect(int iGeomField, double dfMinX, double dfMinY,
                            double dfMaxX, double dfMaxY);
OGRGeometry *GetSpatialFilter();

关键行为(ogrlayer.cpp#L3496-L3551):

  • 只有与过滤几何几何相交的要素会被返回;
  • 实现上基于包络线(envelope)重叠判定:所有与过滤几何包络线重叠的要素都会被返回,因此可能比严格相交返回更多要素;
  • 方法会内部复制传入几何,调用方可安全销毁自己的几何;
  • 传入 nullptr 表示清除当前空间过滤;
  • 当前要求过滤几何与对应几何字段定义使用同一 SRS(官方注明未来可能放宽);
  • 即使对多个 iGeomField 连续调用,只应用最后一次设置的空间过滤;
  • 空/无效几何的要素永远不会匹配空间过滤器。

SetSpatialFilterRect() 是便捷方法:内部构造一个矩形多边形再交给 SetSpatialFilter()(ogrlayer.cpp#L3722),省去手工创建 OGRGeometry 的样板代码。

调用链上还有一个值得注意的源码细节:SetSpatialFilter() 会先做几何字段索引校验(ValidateGeometryFieldIndexForSetSpatialFilter),再委托给 ISetSpatialFilter();而 ISetSpatialFilter() 是 GDAL 3.11 起引入的虚方法,驱动如需覆写,必须调用基类方法 OGRLayer::ISetSpatialFilter()(ogrlayer.cpp#L3557-L3583)。

4.2 属性过滤:SetAttributeFilter()

OGRErr SetAttributeFilter(const char *pszQuery);
const char *GetAttrQueryString();  // 取回当前查询串
  • 查询串为 SQL WHERE 子句格式,例如 "POPULATION > 1000000 AND POPULATION < 5000000";
  • 传入 nullptr 或空串清除当前查询;
  • 安装查询通常会重置读取位置(相当于 ResetReading());
  • 底层通过 OGRFeatureQuery::Compile() 编译查询表达式(ogrlayer.cpp#L752-L790),编译失败返回错误码并释放内部查询对象;
  • 对于 RDBMS 后端驱动(PostgreSQL、SQLite、GeoPackage 等),WHERE 子句可能交给数据库原生引擎解释,能力比纯 OGR SQL 方言更广;
  • 若属性过滤表达式引用了 OGR_GEOMETRY、OGR_GEOM_WKT、OGR_GEOM_AREA 等特殊几何字段,层会通过 AttributeFilterEvaluationNeedsGeometry() 标记"求值需要几何"(ogrlayer.cpp#L824-L834)。

4.3 组合过滤的迭代示例

// 只保留经纬度盒内、且人口大于 10 万的要素
poLayer->SetSpatialFilterRect(-180.0, -90.0, 180.0, 90.0);
poLayer->SetAttributeFilter("POPULATION > 100000");

GIntBig nCount = poLayer->GetFeatureCount(TRUE);   // 强制统计,考虑过滤器
printf("匹配要素数: %lld\n", static_cast<long long>(nCount));

for (auto &&poFeature : *poLayer)
{
    // 每个要素均已同时通过空间与属性过滤
}

// 清理过滤器
poLayer->SetSpatialFilter(nullptr);
poLayer->SetAttributeFilter(nullptr);

五、图层结构与元数据访问

方法 作用 默认实现要点(ogrlayer.cpp)
GetLayerDefn() 图层要素定义(字段、几何字段、名称),纯虚,驱动必须实现 返回 OGRFeatureDefn *
GetName() 图层名 L4804
GetGeomType() 图层几何类型(如 wkbPolygon) L4867
GetSpatialRef() 图层空间参考系 L3136
GetFIDColumn() 底层数据库 FID 列名,不支持时返回 "" L4594
GetGeometryColumn() 底层几何列名;多几何字段时仅返回第一个,无几何字段返回 "" L4642
GetDataset() 所属数据集 L8671
FindFieldIndex() 按名称查字段索引,支持精确/近似匹配 头文件声明
GetStyleTable() / SetStyleTable() 图层样式表(OGR STYLE) 头文件声明

注意:GetLayerDefn() 返回的对象由图层内部持有,应用不应直接修改 OGRFeatureDefn;所有字段结构变更都应通过 CreateField()、DeleteField() 等方法完成(见下节)。

六、图层写入:要素与字段管理

6.1 写入要素

  • CreateFeature(OGRFeature *):向图层追加一个新要素(而非覆盖既有要素)。若传入要素的 FID 不是 OGRNullFID,驱动可能采纳为新 FID,成功返回后要素对象会被更新为新 FID。基类 CreateFeature() 会先做 ConvertGeomsIfNecessary()(必要时转换几何维度/坐标),再委托给驱动实现的 ICreateFeature()(ogrlayer.cpp#L1537-L1572)。
  • CreateFeature(std::unique_ptr<OGRFeature>, GIntBig *pnFID):GDAL 3.13+ 的移动语义版本,把要素所有权转移给图层(ogrlayer.cpp#L1642)。
  • SetFeature(OGRFeature *):更新(覆盖)既有 FID 的要素。
  • UpsertFeature(OGRFeature *):存在则更新、不存在则创建。
  • UpdateFeature(OGRFeature *, ...):仅更新部分字段/几何字段的高效更新,需 OLCUpdateFeature 能力。
  • DeleteFeature(GIntBig nFID):按 FID 删除要素(需 OLCDeleteFeature 能力;基类默认实现返回 OGRERR_UNSUPPORTED_OPERATION,见 ogrlayer.cpp#L4517)。

是否可写需用 TestCapability() 判断:OLCSequentialWrite(能否 CreateFeature)、OLCRandomWrite(能否 SetFeature)、OLCUpsertFeature。同一驱动类的不同图层实例可能读写性不同(如文件只读打开时返回 FALSE)。

6.2 字段结构管理

方法 对应能力 说明
CreateField(OGRFieldDefn *, int bApproxOK = TRUE) OLCCreateField 新建字段;bApproxOK = TRUE 时允许驱动按格式限制做近似调整(如截断宽度、类型降级)
CreateGeomField(OGRGeomFieldDefn *, int bApproxOK = TRUE) OLCCreateGeomField 新建几何字段(GDAL 1.11+)
DeleteField(int iField) OLCDeleteField 删除字段;字段结构变更后,之前取得的字段定义对象不得再使用
ReorderFields(int *panMap) / ReorderField() OLCReorderFields 重排字段顺序
AlterFieldDefn(int iField, OGRFieldDefn *, int nFlagsIn) OLCAlterFieldDefn 修改字段定义
AlterGeomFieldDefn(...) OLCAlterGeomFieldDefn 修改几何字段定义
Rename(const char *pszNewName) OLCRename(GDAL 3.5+) 重命名图层;重名时报错;成功后 GetName() 与 GetLayerDefn()->GetName() 均更新

基类默认实现中,CreateField() 与 DeleteField() 直接报告 CPLE_NotSupported 并返回 OGRERR_UNSUPPORTED_OPERATION(ogrlayer.cpp#L2077-L2177),是否支持完全看驱动。官方还特别警告:字段结构变更期间不应存在由旧图层定义创建出的要素对象。

七、事务与同步

virtual OGRErr StartTransaction();
virtual OGRErr CommitTransaction();
virtual OGRErr RollbackTransaction();
virtual OGRErr SyncToDisk();

基类默认行为(ogrlayer.cpp#L2779-L2917):

  • StartTransaction() / CommitTransaction():默认返回 OGRERR_NONE(不支持事务时为空操作);
  • RollbackTransaction():默认返回 OGRERR_UNSUPPORTED_OPERATION;
  • 支持与否用 OLCTransactions 能力检测。

官方文档明确给出两条实战建议(见 ogrlayer.cpp#L2796):

  1. 优先使用数据集级事务 GDALDataset::StartTransaction()——大多数驱动只支持数据集级事务,只有极少数驱动真正支持图层级事务;
  2. 在事务内修改字段结构(如 DeleteField)时,必须在 RollbackTransaction() 之前销毁该事务期间创建的要素对象,否则要素内部的字段数组与回滚后的图层定义不一致,处于非法状态(源码注释中给出了正反两例)。

SyncToDisk() 将缓冲的写入强制落盘;关闭数据集前调用可确保数据一致。

八、能力检测:TestCapability() 完整清单

TestCapability(const char *pszCap) 是图层能力探测的统一入口,对所有未识别字符串一律返回 FALSE。能力常量定义于 ogr_core.h#L977-L1036,含义详解见 ogrlayer.cpp#L3145-L3242:

能力常量(字符串值) 含义
OLCRandomRead("RandomRead") GetFeature() 有高效实现(否则靠扫描兜底)
OLCSequentialWrite("SequentialWrite") CreateFeature() 可用,即图层可追加写
OLCRandomWrite("RandomWrite") SetFeature() 可用,即图层可随机改
OLCUpsertFeature("UpsertFeature") UpsertFeature() 可用
OLCUpdateFeature("UpdateFeature") 部分字段更新 UpdateFeature() 可用
OLCFastSpatialFilter("FastSpatialFilter") 空间过滤有高效实现;否则建议应用自建空间索引
OLCFastFeatureCount("FastFeatureCount") GetFeatureCount() 无需扫描即可返回;装过滤器后可能变为 FALSE
OLCFastGetExtent / OLCFastGetExtent3D GetExtent() 可高效返回;同上可能受过滤器影响
OLCFastSetNextByIndex("FastSetNextByIndex") SetNextByIndex() 高效
OLCCreateField / OLCCreateGeomField 可新建(几何)字段
OLCDeleteField / OLCReorderFields 可删除 / 重排字段
OLCAlterFieldDefn / OLCAlterGeomFieldDefn 可修改(几何)字段定义
OLCDeleteFeature("DeleteFeature") DeleteFeature() 受支持
OLCTransactions("Transactions") 事务三方法有实际语义
OLCIgnoreFields("IgnoreFields") SetIgnoredFields() 真正生效(字段/几何/样式会被省略读取)
OLCStringsAsUTF8("StringsAsUTF8") 字符串字段保证为 UTF-8
OLCCurveGeometries / OLCMeasuredGeometries / OLCZGeometries 图层支持曲线 / 带 M / 带 Z 几何
OLCRename("Rename") 图层可重命名
OLCFastGetArrowStream / OLCFastWriteArrowBatch Arrow 流读写有高效实现

九、高级特性:忽略字段、样式表与 Arrow 流

9.1 SetIgnoredFields():按需裁剪读取

SetIgnoredFields(CSLConstList papszFields) 让支持 OLCIgnoreFields 的驱动在后续 GetFeature() / GetNextFeature() 中省略指定字段,节省处理时间与网络带宽。源码实现(ogrlayer.cpp#L4943-L4987):

  • 支持特殊名称 "OGR_GEOMETRY"(忽略几何)与 "OGR_STYLE"(忽略样式);
  • 普通字段名会先在字段中查找、再在几何字段中查找,找不到返回 OGRERR_FAILURE;
  • 传 nullptr 清除忽略列表;默认不忽略任何字段;
  • 官方警告:被属性过滤引用到的字段一般不应设为忽略,否则依赖 OGR SQL 引擎的驱动无法正确求值过滤条件。

9.2 样式表

GetStyleTable() / SetStyleTable() / SetStyleTableDirectly() 管理图层的 OGR 样式表;每要素样式字符串可与图层级样式表配合渲染。

9.3 Arrow 内存流集成

OGRLayer 还内置了 Apache Arrow 零拷贝互操作接口(声明见 ogrsf_frmts.h#L223-L233):

  • GetArrowStream(struct ArrowArrayStream *, CSLConstList papszOptions):以 Arrow C Stream 接口导出图层数据;
  • WriteArrowBatch(...):从 Arrow 数组写入图层;
  • CreateFieldFromArrowSchema(...):按 Arrow Schema 创建字段;
  • IsArrowSchemaSupported(...):探测驱动是否支持某 Arrow Schema。

相关的两个常量(ogrsf_frmts.h#L419-L424):当图层未设置 FID 列与几何列名时,Arrow 导出默认使用 OGC_FID 与 wkb_geometry 作为列名。Arrow 的批处理大小、FID 名称等可通过 papszOptions 控制(如 MAX_FEATURES_IN_BATCH,参见 test_ogr.cpp#L2425-L2426 中的用法)。

十、驱动扩展机制:从源码理解 OGRLayer 的可扩展性

OGRLayer 之所以能统一几十种矢量格式,得益于以下设计:

10.1 "I 前缀"虚拟方法约定

基类大量使用 I* 前缀虚方法作为驱动挂钩:ICreateFeature()、ISetFeature()、IUpsertFeature()、IUpdateFeature()、ISetSpatialFilter()、IGetExtent()、IGetExtent3D() 等。公开方法负责参数校验、几何转换等通用逻辑,随后委托给 I* 方法,驱动只需覆写 I* 版本(见 ogrlayer.cpp#L1567-L1572 的 ICreateFeature 示例)。

10.2 OGRGetNextFeatureThroughRaw:过滤的自动套用

模板类 OGRGetNextFeatureThroughRaw<BaseLayer>(ogrsf_frmts.h#L508-L536)为驱动提供现成的 GetNextFeature():驱动只需实现 GetNextRawFeature() 返回原始要素,模板会自动完成空间过滤(FilterGeometry)与属性过滤(m_poAttrQuery->Evaluate)两道判定,不匹配的要素自动释放。配套宏 DEFINE_GET_NEXT_FEATURE_THROUGH_RAW 一键生成覆写。

10.3 装饰器与线程安全包装

十一、测试验证:OGRLayer 行为在仓库中的印证

仓库测试覆盖了本文涉及的核心行为,可作为二次开发与验证的参考:

  • C++ 单元测试 test_ogr.cpp:覆盖图层 CreateFeature()、GetFeatureCount()、GetNextFeature() 与 Arrow 流导出(OGR_L_GetArrowStream、批大小 MAX_FEATURES_IN_BATCH 等,见 test_ogr.cpp#L2374-L2437);
  • Python 自动化测试 ogr_basic_test.py:test_spatial_filter_use_after_dataset_close(L1470-L1482)演示了 SetSpatialFilterRect(0, 0, 1, 1) 的典型用法,并验证数据集关闭后过滤器几何对象被正确失效,印证了"过滤器内部持有几何副本"的实现语义。

十二、总结:OGRLayer C++ API 实战要点

  1. 包含头文件只需 #include "ogrsf_frmts.h",类声明位于 ogrsf_frmts.h,默认实现与完整 API 语义文档位于 ogrlayer.cpp;
  2. 读取三件套:ResetReading() + GetNextFeature() 顺序读,GetFeature() 随机读,begin()/end() 迭代器满足现代 C++ 风格;GetFeatureCount()、GetExtent() 受过滤器影响,注意 bForce 语义;
  3. 过滤:SetSpatialFilter(Rect) 做包络级相交判定、内部复制几何;SetAttributeFilter() 接受 SQL WHERE 子句;两者均会重置读取游标;
  4. 写入:CreateFeature / SetFeature / UpsertFeature / DeleteFeature + 字段管理系列,能力由 TestCapability() 事先探测,基类默认对不支持的操作用 OGRERR_UNSUPPORTED_OPERATION 兜底;
  5. 事务优先用数据集级 GDALDataset::StartTransaction();图层级默认是空操作/不支持,需 OLCTransactions 能力确认;
  6. 扩展:驱动通过 I* 虚方法与 OGRGetNextFeatureThroughRaw 模板接入,应用层可通过 OGRLayerDecorator/OGRMutexedLayer 实现透明包装。
登录后查看全文
gdal