★ FEATURED ARTICLE GIS遥感数据工程【免费下载链接】gdalGDAL is an open source MIT licensed translator library for raster and vector geospatial data formats.项目地址https://gitcode.com/gh_mirrors/gd/gdal点击查看免费下载导读gdal vector convert是 GDAL3.11 起新增提供的矢量数据格式转换子命令其定位是新一代ogr2ogr风格的声明式转换工具一条命令即可完成 Shapefile、GeoPackage、GeoJSON、FileGDB 等格式间的互转并支持追加、覆盖、更新、Upsert插入或更新、多图层选择与出错跳过等高级写入策略。本文以 doc/source/programs/gdal_vector_convert.rst 官方文档为核心结合其底层算法源码apps/gdalalg_vector_convert.cpp、apps/gdalalg_vector_write.cpp与自动化测试autotest/utilities/test_gdalalg_vector_convert.py系统讲解该命令的全部标准选项、典型用法、底层工作原理与易错点读者阅读后可直接上手完成各种矢量转换任务。命令概览与适用场景gdal vector convert文档见 doc/source/programs/gdal_vector_convert.rst源码见 apps/gdalalg_vector_convert.h用于在不同格式之间转换矢量数据Convert a vector dataset。它隶属于 GDAL 3.11 引入的新一代命令体系gdal vector *从源码结构看该命令本质上是一个“转发器”在 apps/gdalalg_vector_convert.cpp 的GDALVectorConvertAlgorithm::RunStep()中代码只是把输入数据集直接设置为输出数据集注释明确写道Do nothing but forwarding the input dataset to the output. Real job is done by GDALVectorWrite.真正执行转换、写入、覆盖等逻辑的是矢量流水线中的write步骤apps/gdalalg_vector_write.cpp。这一设计带来两个重要的使用含义gdal vector convert可以看作gdal vector pipeline中read ! write的简写形式。需要多步骤处理时如转换同时重投影、筛选可直接改用 gdal vector pipeline 文档 组合各步骤。它复用了write步骤的完整写入能力包括数据集/图层创建选项、追加、覆盖、Upsert、跳过错误、--no-create-empty-layers等参数由 apps/gdalalg_vector_output_abstract.cpp 的AddAllOutputArgs()统一注册。此外该算法在注册表中带有隐藏别名translate见 apps/gdalalg_vector_convert.h 中GetAliasesStatic()说明它承接了部分传统ogr2ogr的转换语义。仓库当前版本为 3.14.0见 VERSION。命令行语法Synopsis通过--help-doc可查看完整在线帮助$ gdal vector convert --help-doc其基本用法形如$ gdal vector convert [OPTIONS] INPUT OUTPUTINPUT输入矢量数据集可以是文件路径也可以是连接字符串如MongoDBv3:tmp/foo。OUTPUT输出矢量数据集路径。若省略-f/--of命令会依据输出文件名后缀自动猜测驱动无法猜测时会报错Cannot guess driver for name对应测试test_gdalalg_vector_convert_output_format_not_guessed。标准选项详解以下选项均来自官方文档doc/source/programs/gdal_vector_convert.rst以.. include::方式引用的标准选项文件位于 doc/source/programs/gdal_options/下表为速览随后逐个展开选项别名作用--append—允许向已有图层追加要素不存在时同时创建输出数据集-f, --of, --format, --output-format—指定输出矢量格式--co, --creation-option—数据集创建选项DSCO可重复--lco, --layer-creation-option—图层创建选项可重复--oo, --open-option—输入数据集打开选项可重复--output-open-option, --output-oo—输出数据集打开选项3.12 起可重复--if, --input-format—指定输入驱动候选可重复--input-layer—指定要处理的输入图层可多个默认处理全部图层--output-layer—指定输出图层名默认与输入图层同名--overwrite—允许覆盖已存在的目标文件/数据集--overwrite-layer—允许覆盖已存在的输出图层--update—以更新模式打开已存在的输出数据集--skip-errors—忽略写入失败3.12 起--upsert—使用 Upsert 插入或更新要素3.12 起--no-create-empty-layers—避免创建无要素写入的图层3.13 起-q, --quiet—抑制进度条与部分警告1.--append追加要素到已有图层来自 doc/source/programs/gdal_options/append_vector.rst是否允许将要素追加append到已有图层。若输出数据集尚不存在该选项也会先创建输出数据集。从源码看apps/gdalalg_vector_output_abstract.cpp--append存在一个关键副作用设置它时会自动把--update置为 trueAddAction([updateArg] { updateArg.Set(true); })即以更新模式打开输出数据集再在目标图层上执行追加写入。2.-f/--of/--format/--output-format选择输出格式来自 doc/source/programs/gdal_options/of_vector.rst指定输出矢量格式允许的值可用以下命令查看$ gdal --formats | grep vector | grep rw | sort若不指定命令会根据输出文件后缀自动猜测驱动见 apps/gdalalg_vector_output_abstract.cpp 中GDALGetOutputDriversForDatasetName(..., bSingleMatch true, bWarn true)的调用逻辑。测试用例test_gdalalg_vector_convert_output_format_multiple_layers也验证了不同驱动的多图层能力差异——例如 GeoJSON 驱动不支持多图层报GeoJSON driver does not support multiple layers而 GPKG、ESRI Shapefile、CSV、MapInfo File 可以。3.--co/--creation-option数据集创建选项来自 doc/source/programs/gdal_options/co_vector.rst许多格式支持一个或多个数据集创建选项DSCO用于控制生成文件的细节。例如 GeoPackage 驱动可用创建选项控制 OGC GeoPackage 版本。选项可重复指定不同驱动支持的选项各不相同简单格式可能完全没有创建选项。可用--formats列出某格式支持的选项但各驱动文档才是合法选项的权威来源见 矢量驱动文档。数据集创建选项与图层创建选项--lco是两回事不可混用。典型示例对应测试test_gdalalg_vector_convert_dsco$ gdal vector convert poly.shp output.gpkg --co ADD_GPKG_OGR_CONTENTSNO4.--lco/--layer-creation-option图层创建选项来自 doc/source/programs/gdal_options/lco.rst控制新建图层细节例如 GeoPackage 驱动可借此设置要素标识列FID 列、几何列名、图层标识符与描述等。可重复指定。对应测试test_gdalalg_vector_convert_lco验证了--lco FIDmy_fid可将输出图层的 FID 列命名为my_fid$ gdal vector convert poly.shp output.gpkg --lco FIDmy_fid5.--oo/--open-option输入打开选项来自 doc/source/programs/gdal_options/oo.rst格式相关的输入数据集打开选项可重复。典型场景如 CSV 多几何列读取测试test_gdalalg_vector_convert_multiple_geometry_fields使用--oo KEEP_GEOM_COLUMNSNO。6.--output-open-option/--output-oo输出打开选项来自 doc/source/programs/gdal_options/output_oo.rstGDAL 3.12 新增格式相关的输出数据集打开选项可重复用于控制以何种方式打开已存在的输出数据集。7.--if/--input-format指定输入驱动来自 doc/source/programs/gdal_options/if.rst指定用于打开输入文件的驱动名。通常无需指定GDAL 会自动探测但当自动探测选择错误驱动时可显式指定跳过探测。可重复指定多个候选驱动注意该选项并不强制这些驱动打开数据集某些驱动对文件扩展名仍有要求。8.--input-layer选择输入图层来自 doc/source/programs/gdal_options/input_layer_no_active_layer.rst指定要处理的一个或多个图层名称默认处理全部图层。若图层名不存在会报错测试用例验证错误信息为Cannot find source layer invalid。9.--output-layer指定输出图层名来自 doc/source/programs/gdal_options/output_layer.rst指定要素写入的图层名未指定时输出图层名与输入图层名相同。该参数在源码中另有别名--nln见 apps/gdalalg_vector_output_abstract.cpp 中AddOutputLayerNameArg(m_outputLayerName).AddAlias(nln)。关于默认图层名的补充细节源码行为apps/gdalalg_vector_output_abstract.cpp对于 ESRI Shapefile 输出若文件扩展名为.shp且图层数 ≤ 1输出图层名会被强制设为文件名基名若未指定且输出数据集恰好只有 1 个图层则采用该图层的名字作为默认输出图层名。10.--overwrite覆盖整个目标来自 doc/source/programs/gdal_options/overwrite.rst允许覆盖已存在的目标文件或数据集否则默认情况下目标已存在会直接报错。测试test_gdalalg_vector_convert_base验证了不指定--overwrite直接写入已存在文件会报already exists指定后要素数恢复为 10。另外 apps/gdalalg_vector_output_abstract.cpp 表明--overwrite与--update互斥同一MutualExclusionGroup(overwrite-update)。11.--overwrite-layer覆盖已有图层来自 doc/source/programs/gdal_options/overwrite_layer.rst是否允许覆盖已存在的输出矢量图层。源码逻辑apps/gdalalg_vector_output_abstract.cpp 的SetupOutputDataset()为若目标图层已存在且指定了--overwrite-layer则先DeleteLayer再重建若未指定且未--append则报错提示指定--overwrite-layer覆盖或--append追加若指定了--append或--overwrite-layer却找不到该图层则报Cannot find layer name。12.--update更新模式打开输出来自 doc/source/programs/gdal_options/update.rst是否以更新update模式打开已存在的输出数据集。与--overwrite互斥。典型场景是向已有 GeoPackage 中添加新图层见下方示例 2测试test_gdalalg_vector_convert_base验证了--update --nln layer2会保留原图层并新增layer2。13.--skip-errors忽略要素写入失败来自 doc/source/programs/gdal_options/skip_errors.rstGDAL 3.12 新增是否忽略写入要素失败。重要性能提示该选项会把事务单元大小设为“一次一个要素”transaction unit one feature at a time向数据库插入时可能造成严重性能下降。测试test_gdalalg_vector_convert_skip_errors验证写入含无法表示几何如 Shapefile 不支持 LINESTRING 场景下的数据时不指定该选项会报Failed to write layer test. Use --skip-errors指定后跳过失败要素并成功写出其余要素。14.--upsert插入或更新要素来自 doc/source/programs/gdal_options/upsert.rstGDAL 3.12 新增是--append的变体使用OGRLayer::UpsertFeature操作而非CreateFeature来插入或更新要素。当前仅少数驱动实现GPKG、Elasticsearch、MongoDBv3实现 upsert 的驱动会暴露GDAL_DCAP_UPSERT能力。测试test_gdalalg_vector_convert_upsert验证 SQLite 驱动会报SQLite driver does not support upsert而 GPKG 可以正常 Upsert。键的规则Upsert 以输入要素的 FID当 FID 已设置且 FID 列名非空字符串作为更新已有要素的键因此必须保证源与目标图层的 FID 一致。对于 GPKG 驱动当存在非整型主键的 UNIQUE 列时还可以 Upsert FID 未设置或不重要的要素可用gdal vector edit --unset-fid见 gdal_vector_edit 文档忽略源要素的 FID。15.--no-create-empty-layers避免创建空图层来自 doc/source/programs/gdal_options/no_create_empty_layers.rstGDAL 3.13 新增避免创建没有任何要素写入的图层。其底层实现在 apps/gdalalg_vector_write.cpp 的GDALReadBufferedDataset会预读每个图层的第一条要素PeekNextFeature()过滤掉空图层后再交给写入逻辑。若源数据集支持随机图层读取ODsCRandomLayerRead会发出警告并退化为按图层逐层读取测试test_gdalalg_vector_pipeline_no_create_empty_layers_random_layer_read_warning验证了该警告test_gdalalg_vector_convert_no_create_empty_layers验证过滤效果。16.-q/--quiet静默模式来自 doc/source/programs/gdal_options/quiet.rst抑制进度条与部分警告信息。例如向不支持曲线几何的输出格式写入曲线要素时非静默模式会告警Attempt to write curve geometries静默模式则无告警测试test_gdalalg_vector_convert_warn_no_curve_support。当输出到/vsistdout/时静默模式会被自动开启测试test_gdalalg_vector_convert_to_stdout验证。典型实战示例示例 1将 Shapefile 转换为 GeoPackage$ gdal vector convert poly.shp output.gpkg输出驱动由.gpkg后缀自动判定为 GPKG。图层默认保持原名poly全部要素测试数据poly.shp共 10 个要素被写入output.gpkg。示例 2向已有 GeoPackage 添加新图层并重命名$ gdal vector convert --update --output-layerlines line.shp output.gpkg--update以更新模式打开已存在的output.gpkg避免“目标已存在”报错。--output-layerlines将源图层line写入后命名为lines。测试验证该组合会保留既有图层poly要素数不变并新增layer2/lines图层。示例 3向已有图层追加要素静默模式$ gdal vector convert --quiet --append --output-layerpoly poly2.shp output.gpkg--append允许追加并自动启用--update目标图层poly追加来自poly2.shp的要素。--quiet抑制进度条。测试test_gdalalg_vector_convert_base中两次追加后poly图层要素数从 10 变为 20。底层工作原理从算法到write步骤gdal vector convert的完整执行链路可结合 apps/gdalalg_vector_convert.cpp 与 apps/gdalalg_vector_write.cpp 阅读参数解析与校验GDALVectorConvertAlgorithm继承自GDALVectorPipelineStepAlgorithm注册为独立步骤convert见 apps/gdalalg_vector_convert.h并声明SetNoCreateEmptyLayersArgument(true)与SetStandaloneStep(true)。输入转发RunStep()校验输入唯一后将输入数据集直接赋给输出m_outputDataset.Set(poSrcDS)。写入执行真正的转换由write步骤GDALVectorWriteAlgorithm完成——它把各选项翻译成GDALVectorTranslateOptions最终调用GDALVectorTranslate()apps/gdalalg_vector_write.cpp 中RunStep()。选项映射关系包括--overwrite→-overwrite/--no-overwrite、--overwrite-layer→-overwrite、--append→-append、--upsert→-upsert、--co→-dsco、--lco→-lco、--output-layer→-nln、--skip-errors→-skipfailures、-q→-q。输出数据集准备SetupOutputDataset()apps/gdalalg_vector_output_abstract.cpp负责驱动猜测、数据集创建poDriver-Create、图层存在性检查以及覆盖/追加分支处理。空图层过滤可选--no-create-empty-layers时GDALReadBufferedDataset会预读每层首个要素以剔除空图层。常见错误信息与排查指引错误信息节选触发条件解决办法Cannot guess driver for name输出文件名无法推断驱动显式指定-f/--of FORMAT... already exists ...目标已存在且未指定覆盖/更新选项加--overwrite整体覆盖或--update更新模式Layer name already exists. Specify the --overwrite-layer option to overwrite it, or --append to append to it.目标图层已存在未指定覆盖或追加按提示加--overwrite-layer或--appendCannot find layer name指定了--append/--overwrite-layer但找不到目标图层检查--output-layer名称与源图层名Cannot find source layer name--input-layer指定的输入图层不存在用ogrinfo确认源图层名Failed to write layer name. Use --skip-errors to ignore errors存在无法写入的要素加--skip-errors跳过注意数据库场景的性能代价SQLite driver does not support upsert目标驱动无 Upsert 能力改用支持GDAL_DCAP_UPSERT的驱动GPKG/Elasticsearch/MongoDBv3与相关命令的关系gdal vector pipelineconvert可等价视为流水线read ! write的简写。需要叠加 reproject、clip、filter 等步骤时参考 gdal vector pipeline 文档 与各步骤文档如 gdal_vector_reproject、gdal_vector_filter。从源码看convert算法是 pipeline 步骤体系中的一员注册表见 apps/gdalalg_vector_pipeline.cpp 的RegisterAlgorithms()。ogr2ogrgdal vector convert在功能上继承并规范化了ogr2ogr的核心转换语义其隐藏别名translate也印证了这一点同时融入新命令体系统一的参数风格。gdal vector edit当需要先忽略源要素 FID 再执行 Upsert 时可配合 gdal_vector_edit 文档 的--unset-fid使用。总结gdal vector convert提供了统一、可组合、语义清晰的矢量格式转换入口格式自动探测与显式-f双通道、数据集与图层两级创建选项、覆盖/更新/追加/Upsert 四种写入模式以及--skip-errors、--no-create-empty-layers等容错与优化开关。其底层复用write步骤与GDALVectorTranslate()实现行为既有传统ogr2ogr的兼容性又具备流水线化的扩展空间。官方测试autotest/utilities/test_gdalalg_vector_convert.py覆盖了覆盖、追加、图层重命名、Upsert、多图层、stdout 输出、错误处理等主要路径可作为验证自身用法的参考基线。赞分享GIS遥感数据工程【免费下载链接】gdalGDAL is an open source MIT licensed translator library for raster and vector geospatial data formats.项目地址https://gitcode.com/gh_mirrors/gd/gdal点击查看免费下载相关推荐GDAL gdal raster convert 命令详解栅格格式转换、子数据集追加与 COG 输出实战GDAL gdal raster convert 命令详解栅格格式转换、子数据集追加与 COG 输出实战 本文基于 GDAL 仓库当前版本 VERSIONGIS遥感数据工程GDAL gdal convert 命令详解一次调用自动完成栅格与矢量格式转换GDAL gdal convert 命令详解一次调用自动完成栅格与矢量格式转换 gdal convert 是 GDAL 3.11 起引入的顶层转换命令它本身GIS遥感数据工程GDAL gdal vector rename-layer 子命令完全指南重命名矢量图层与批量清洗图层名GDAL gdal vector rename layer 子命令完全指南重命名矢量图层与批量清洗图层名 GDAL 3.13 新增的 gdal vectorGIS遥感数据工程上一篇Cheerio.js 使用与安装教程下一篇apt-fast: 加速您的Linux包管理体验创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
