GDAL OGRLayer C++ API 深度指南:图层读写、空间/属性过滤、事务与能力检测实战
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 只需包含一个头文件:
- 头文件:ogrsf_frmts.h,即
#include "ogrsf_frmts.h"
在该头文件中,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):
- 标准范围 for 循环安全,但一次只应解引用一个迭代器步——底层
OGRFeatureUniquePtr引用会被复用; - 同一时刻每个图层只能有一个迭代器处于活跃状态;
- 迭代器实现内部复用要素容器,勿将迭代器保存到循环之外长期使用。
3.2 随机读取:GetFeature() 与 SetNextByIndex()
GetFeature(GIntBig nFID) 按要素 ID 随机读取。其默认实现(ogrlayer.cpp#L942-L972)非常具有参考价值:
- 先保存当前属性过滤字符串与空间过滤几何(并克隆一份),记录当前几何字段过滤索引;
- 清除两个过滤器;
- 顺序遍历全部要素,比对
GetFID() == nFID命中即取出; - 恢复原过滤器。
即"无 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):
- 优先使用数据集级事务
GDALDataset::StartTransaction()——大多数驱动只支持数据集级事务,只有极少数驱动真正支持图层级事务; - 在事务内修改字段结构(如
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 装饰器与线程安全包装
OGRLayerDecorator(ogrlayerdecorator.h#L20):代理转发到被装饰图层的通用包装基类;OGRMutexedLayer(ogrmutexedlayer.h#L28):为图层方法加互斥锁的线程安全包装,基于OGRLayerDecorator;OGRLayerPool(ogrlayerpool.h):图层对象池。
十一、测试验证: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 实战要点
- 包含头文件只需
#include "ogrsf_frmts.h",类声明位于 ogrsf_frmts.h,默认实现与完整 API 语义文档位于 ogrlayer.cpp; - 读取三件套:
ResetReading()+GetNextFeature()顺序读,GetFeature()随机读,begin()/end()迭代器满足现代 C++ 风格;GetFeatureCount()、GetExtent()受过滤器影响,注意bForce语义; - 过滤:
SetSpatialFilter(Rect)做包络级相交判定、内部复制几何;SetAttributeFilter()接受 SQL WHERE 子句;两者均会重置读取游标; - 写入:
CreateFeature/SetFeature/UpsertFeature/DeleteFeature+ 字段管理系列,能力由TestCapability()事先探测,基类默认对不支持的操作用OGRERR_UNSUPPORTED_OPERATION兜底; - 事务优先用数据集级
GDALDataset::StartTransaction();图层级默认是空操作/不支持,需OLCTransactions能力确认; - 扩展:驱动通过
I*虚方法与OGRGetNextFeatureThroughRaw模板接入,应用层可通过OGRLayerDecorator/OGRMutexedLayer实现透明包装。