GIS遥感数据工程【免费下载链接】gdalGDAL is an open source MIT licensed translator library for raster and vector geospatial data formats.项目地址https://gitcode.com/gh_mirrors/gd/gdal点击查看免费下载本文以 doc/source/development/dev_practices.rst 为核心骨架系统梳理 GDAL 开源库的开发约束与实践规范包括小改动与大改动的提交流程RFC 机制、CPL 可移植库的使用准则、C99/C17 语言标准、适应式匈牙利命名法、.clang-format/Black 格式化与 pre-commit 钩子、以VSIMalloc2/3为核心的安全内存分配实践、新增驱动程序的全套要求、Git 分支与回移植工作流以及完整的源码树布局。读完本文读者不仅能照规范向 GDAL 提交合格代码还能理解仓库各目录的职责划分与底层设计取舍。变更流程小改动走 Pull Request大改动走 RFC在 GDAL 中怎么改代码取决于改动的规模小改动例如缺陷修复可以直接在 GitHub 上打开 Pull Request 提交。大改动应当先在gdal-dev邮件列表listserv上展开讨论并通常需要起草一份 RFCRequest For Comment文档经项目成员评审后再进入实现阶段。对于实质性的大段代码新增GDAL 有一份专门的成文政策RFC 85: Policy regarding substantial code additions其要点包括每个新驱动必须指定一名负责的联系人maintainer并纳入项目维护者清单跟踪。新增贡献必须遵循其他 RFC 规定的开发规则并附带测试脚本与足够的使用/构建文档。如果驱动依赖不可免费下载或需要复杂注册流程的二进制 SDKGDAL 团队大概率不会接受其进入主线。新驱动应尽可能支持多个操作系统至少应在文档声明的受支持系统的最新发行版上工作。二进制 SDK 停止维护、无法适配现代编译器时相关驱动可能被移除此规则同样适用于不再维护的开源依赖。驱动若有未解决缺陷、破坏持续集成CI、导致 CI 片段被禁用、或长期未跟上 API 变更将被移出默认构建脚本关键阻塞问题两个月内未修复的驱动可能被整个从源码树中移除。重大代码新增的贡献者需要持续参与项目日常沟通issue 跟踪、邮件列表维护者则需负责缺陷分诊、PR/RFC 评审、功能增强、版本测试与文档改进。此外GDAL 还专门制定了 AI/LLM 工具使用政策见 doc/source/community/ai_tool_policy.rst由 RFC 111 引入允许有限度使用 LLM 辅助贡献但人类贡献者必须是主要作者、必须完全理解提交的每一行代码与消息且禁止vibe-coding式不加理解的照搬提交。政策的核心考量是LLM 让写代码变得廉价而开源项目的稀缺资源变成了维护——评审、精简、重构与保护系统不被破坏的时间无节制的 LLM 提交会消耗这一资源。可移植性优先使用 CPL 公共可移植库GDAL 的目标是广泛移植到 32 位与 64 位计算环境以及小端little-endian与大端big-endian两种字节序的 CPU。为此仓库的port目录提供了 CPLCommon Portability Library函数用于抽象平台相关操作。实践准则非常明确凡是 CPL 已有等价功能的场景优先使用 CPL 函数而不是直接调用操作系统函数覆盖的操作包括内存分配如CPLMalloc/VSIMalloc家族路径解析文件系统 I/O使用VSILFILE*/VSIVirtualFile*抽象句柄ODBC 访问等。从源码层面看字节序适配的机制在 port/cpl_port.h 中定义通过CPL_LSB/CPL_MSB宏区分字节序默认假定小端Intel 顺序当检测到WORDS_BIGENDIAN时自动切换为CPL_MSB并可由调用方显式覆盖。这套机制让同一份栅格/矢量读写代码在 x86 与 PowerPC/SPARC 等大端平台上保持一致的行为。C/C 标准C99 与 C17GDAL/OGR 当前采用的 C 与 C 标准分别是C99与C17最后一次更新依据是 RFC 98。该 RFC 同时将 GDAL 3.9 的构建要求提升为C 17、CMake 3.16、PROJ 6.3.1若干可选依赖的最低版本同步上调Python 3.8、GEOS 3.8、Poppler 0.86、libtiff 4.1、libcurl 7.68、libpng 1.6.0、libsqlite3 3.31、libopenjp2 2.3.1、libnetcdf 4.7需启用 NC4、libhdf5 1.10。升级到 C17 的动机包括最新的 Poppler、PDFium、PoDoFo、TileDB、libarrow-cpp 等依赖要求 C17C17 也允许代码库清理旧工作区如用[[fallthrough]]取代CPL_FALLTHROUGH、用[[maybe_unused]]取代CPL_UNUSED、用结构化绑定简化std::map迭代、用std::make_unique取代cpl::make_unique。值得注意的边界是库对外导出的头文件暂只暴露至多 C11 特性以减少对 GDAL C 使用方的扰动。变量命名适应式匈牙利命名法GDAL/OGR 现有代码大量使用一种适应式匈牙利命名法adapted Hungarian notation。文档明确说明这套约定并非强制但当你维护使用该约定的既有代码时应当继续遵循最重要的是不要错误地使用它因为误用比不用更令人困惑。匈牙利命名法中前缀揭示变量的类型乃至语义。GDAL/OGR 中常见前缀如下前缀含义典型示例a数组arraypaah数组的数组的句柄指针bC/Cbool在早于 C99 的 C 代码中也用于仅取 TRUE/FALSE 的intbReadOnlyby字节GByte/unsigned charpabyHeaderdf双精度浮点doubledfNoDatae枚举enumerationeAccessi用作从零开始的数组/循环索引的整数iBandf单精度浮点floatfToleranceh不透明句柄如GDALDatasetHhDShf半精度浮点half precisionhfValuen整数大小未指定nBandsoC 对象poBandosCPLString或std::stringosFilenamep指针pointerpszNamepsz指向以 null 结尾的字符串的指针char *pszName;sz以 null 结尾的字符串固定缓冲char szName[100];k编译期常量knMaxSize前缀可以堆叠。原文档给出的几个有意义的组合示例char **papszTokens指向字符串数组的指针pointer to array of stringsint *panBands指向数字数组首元素的指针double *padfScanline指向 double 数组首元素的指针double *pdfMeanRet指向单个 double 的指针Ret暗示返回值语义GDALRasterBand *poBand指向单个 C 对象的指针GByte *pabyHeader指向字节数组的指针。这些前缀在真实源码中随处可见例如 alg/gdalapplyverticalshiftgrid.cpp 中的papszOptions选项列表、padfSrcNoDataReal/padfDstNoDataReal双精度 NoData 数组等。此外变量名的标准约定是每个单词首字母大写如panBands、poBand。函数与类命名避免符号冲突函数与类应当处于一个足够有区分度的命名空间中以避免符号冲突要么使用 GDAL 或 OGR 前缀要么使用 C 命名空间。这一点对 GDAL 这种同时导出 C 与 C 双 API、并被大量第三方语言绑定SWIG Python/Java/C#的大型库尤其重要。文件命名与代码格式化文件层面的硬性要求有三条所有源文件.h、.c、.cpp、.py等都应有包含版权归属与 GDAL X/MIT 许可证文本的文件头。仓库的实际头文件已采用 SPDX 标注例如 gcore/gdaldataset.cpp 顶部即为Copyright (c) 1998, 2003, Frank Warmerdam ...与SPDX-License-Identifier: MIT。文件名一律小写。C 文件使用.cpp扩展名而不是.cc。格式化规则方面C/C 代码的格式规则由仓库根目录的 .clang-format 定义。该配置基于 LLVM 风格做了大量定制缩进 4 空格、ColumnLimit: 80、PointerAlignment: Right、BreakBeforeBraces: Allman、UseTab: Never、Standard: Cpp11等。这意味着所有新提交的 C/C 代码都必须按此风格排版。Python 代码的格式化由Black强制执行。建议使用pre-commit工具自动执行上述格式化检查。仓库自带的 .pre-commit-config.yaml 实际注册了以下钩子fix-gdal-headers运行 scripts/fix_gdal_block_headers.py 统一 GDAL 风格文件头、check-rst-files运行 scripts/check_doc_rst_errors.py 检查 RST 文档错误、sphinx-lint、black、isort、flake8以及clang-format后者排除了autotest/cpp/data/、swig/、third_party/、各第三方内嵌库与doc/source/等无需格式化的目录。内存分配实践VSIMalloc家族与溢出防护GDAL 对大规模内存分配有明确的安全准则大规模内存分配应使用VSIMalloc系列函数它们在分配失败时返回nullptr而不是崩溃或未定义行为。依据 RFC 19: Safer memory allocation in GDAL当分配大小由乘法计算得出时应使用VSIMalloc2(x, y)替代CPLMalloc(x * y)或VSIMalloc(x * y)使用VSIMalloc3(x, y, z)替代CPLMalloc(x * y * z)。这两个函数会检测乘法溢出通过校验((a*b)/b) a来发现溢出一旦发生溢出或分配失败即返回 NULL 指针并经由CPLError()抛出CE_Failure任一参数为 0 时同样返回 NULL。由于不依赖变量类型的宽度与符号性假设该检测方式非常稳健。这两个函数在 port/cpl_vsi.h 中声明VSIMalloc本体在 port/cpl_vsi.h。在 GDAL 栅格驱动中x、y通常对应栅格尺寸或栅格块尺寸因此这种溢出防护对抵御超大尺寸导致缓冲不足的崩溃例如损坏文件或恶意构造的 WMS 栅格元数据非常关键。仓库中的实际调用印证了这套实践gcore/gdalrasterband.cpp 在计算直方图桶数组时使用VSIMalloc2(sizeof(GUIntBig), nBuckets)frmts/hf2/hf2dataset.cpp 使用VSIMalloc3(sizeof(float), nRasterXSize, nMaxTileHeight)分配瓦片数据frmts/webp/webpdataset.cpp 同样用VSIMalloc3分配整幅解码缓冲。此外对于std::vector等标准库容器——其内存分配失败会抛出std::bad_alloc——文档要求在可能分配大量内存的代码块周围使用 try/catch 包裹。仓库中已有先例例如 gcore/multidim/gdalmultidim_array_gltorthorectification.cpp 中catch (const std::bad_alloc e)的处理模式。新增一个驱动程序全套要求向 GDAL 添加新驱动raster 或 vector时文档给出了如下检查清单第三方依赖如果驱动依赖第三方库其编译必须以该库的存在为条件conditional compilation。驱动应尽量复用已有库依赖例如用 Expat 做 SAX XML 解析避免为单一驱动引入重复依赖。打开识别能力selectivity与健壮性robustness对于矢量驱动需检查驱动常委托给数据源的Open()方法的识别是否足够挑剔——不会接受本不属于该驱动的数据文件同时要足够健壮——面对与已识别内容仅有细微差异的输入时不会崩溃并能处理不常见的文件名。对于 GDAL 栅格驱动需做类似检查并同样验证可选的Identify()方法。测试应在 Python 测试套件中为新驱动添加一组测试适当情况下可将小型样例数据放入autotest/gdrivers/data或autotest/ogr/data。apps/test_ogrsf.cpp 提供的test_ogrsf工具与GDALTest类可简化基本驱动功能的测试。文档必须为新驱动创建文档页面至少简要描述该驱动的格式处理能力并在相关时说明连接字符串、创建选项creation options、配置选项configuration options的语法文档还应链接到更详细的格式说明并列出所需的第三方库。GDALTest类定义于 autotest/pymod/gdaltest.py其构造函数接收驱动名、文件名、波段号与校验和chksum等参数可自动完成打开、读取、校验值比对与重开后比对chksum_after_reopening。典型用法见 autotest/gdrivers/aaigrid.pytst gdaltest.GDALTest(aaigrid, aaigrid/pixel_per_line.asc, 1, 1123)编写测试新代码必须配套测试。GDAL 的自动化测试体系详见 doc/source/development/testing.rst核心事实包括测试套件由Pythonpytest与Cgtest混合实现以 CMake 构建默认开启-DBUILD_TESTINGON后可运行ctest -V --output-on-failure执行全套测试ctest 会自动设置环境变量使测试针对刚构建的 GDAL而非系统安装版可用ctest -N列出全部测试、-R用正则选择子集如ctest -R autotest运行 Python 测试、-E排除子集如ctest -E gdrivers需要更高粒度的定位时可直接调用 pytest例如pytest autotest/gcore/vrt_read.py或pytest autotest/gcore/vrt_read.py -k test_vrt_read_non_existing_source也可用pytest --collect-only autotest -k tiff只收集不运行注意并非所有 Python 测试都可以独立运行部分测试依赖同文件内前序测试设定的状态autotest/README.md 也做了同样提醒还可以用 Valgrind 检测内存泄漏与非法读写测试套件在 Valgrind 下约慢一个数量级建议只跑子集。Git 使用最佳实践本节集中了 GDAL 开发者在日常 Git 工作流上的建议覆盖从初始化仓库到回移植backport的完整链路。初始化你的工作仓库从 GitHub UI ForkOSGeo/gdal然后git clone https://github.com/OSGeo/gdal cd gdal git remote add my_user_name gitgithub.com:my_user_name/gdal.git在功能分支上工作git checkout master # 视需要先将本地 master 与上游同步见下文 git checkout -b my_new_feature_branch # 开展工作例如 git add my_new_file git add my_modifid_message git rm old_file git commit -a # 若分支创建后上游新增了需要的缺陷修复或新能力需要重新同步 git fetch origin git rebase origin/master # 工作收尾时把不重要的零散提交折叠成一致的历史 git rebase -i master # 例如用 fixup 合并多个提交用 reword 修改提交信息 # 或者当提交数量很多、逐个标记 fixup 过于繁琐时 git fetch origin git rebase origin/master git reset --soft origin/master git commit -a -m Put here the synthetic commit message # 推送你的分支 git push my_user_name my_new_feature_branch之后从 GitHub UI 发起 Pull Request。如果 PR 讨论或自动化检查要求修改就本地提交并推送为了保持合理的历史你可能需要再次git rebase -i master合并提交此时需要强制推送git push -f my_user_name my_new_feature_branch让本地 master 跟上上游git checkout master git fetch origin # 注意这会丢失你当前可能做的所有本地改动 git reset --hard origin/master提交信息格式提交信息应包含组件名例如驱动名、一段简短描述并在相关时引用 issue 编号确实修复该 issue 时使用fixes #COMPONENT_NAME: fix bla bla (fixes #1234) Details here...Commit hooks提交钩子GDAL 随仓库提供 pre-commit 钩子用于在提交前运行代码格式化与 lint。安装方式python3 -m pip install pre-commit pre-commit install安装后也可手动运行全部钩子pre-commit run --all-files。Blame ignore 文件避免 git blame 误导由于 GDAL 3.7 开发期间做过全树代码重排git blame信息可能因此失真。要忽略这次全树重排的修订需按如下方式修改 Git 配置git config blame.ignoreRevsFile .git-blame-ignore-revs仓库根目录的 .git-blame-ignore-revs 文件保存了需要忽略的修订哈希列表当前共 201 条。将缺陷修复从 master 回移植到稳定分支git checkout master # 用 git log 找出要回移植的提交的 sha1 git checkout 2.2 # 例如回移植到 2.2 分支 git pull origin 2.2 # git checkout -b branch_name # 若打算以 PR 形式提交回移植 git cherry-pick the_sha1_sum git push ...若回移植后需要改动完成改动后执行git commit -a --amend。你绝对不应该做的事对任何拥有OSGeo/gdal推送权限的人而言永远不要修改已经推送到 GitHub 上游的任何提交或历史。符号链接symbolic link只允许在.github目录下提交以避免在 Windows 上引发潜在问题。源码树布局各目录的职责划分理解仓库结构是高效开发的前提。原文档给出了如下官方布局说明可与当前仓库实际内容互相印证目录职责alg/算法栅格化、多边形化polygonization、warper 引擎等如 alg/polygonize.cppapps/C 命令行工具gdal_translate、ogr2ogr、gdalwarp等autotest/回归测试套件C 与 Pythoncmake/CMake 模块与辅助函数doc/GDAL 文档源码与脚本docker/GDAL Docker 镜像的 Dockerfile见 docker/README.mdgcore/栅格核心功能GDALDataset、GDALRasterBand、GDALDriver基类、金字塔构建等frmts/GDAL/栅格驱动例外GDAL 的 GeoPackage 栅格支持位于ogr/ogrsf_frmts/gpkgfuzzers/GDAL OSS-Fuzz 集成的源码与脚本gnm/地理网络模型Geographic Network Model实现模型说明见 doc/source/user/gnm_data_model.rstogr/OGR 矢量核心类OGRFieldDefn、OGRGeomFieldDefn、OGRFeatureDefn、OGRGeometry及其派生类、OGR SQL 等ogr/ogrsf_frmts/OGR/矢量驱动ogr/ogrsf_frmts/generic/OGR 矢量核心类OGRLayer、OGR SQL generic layerport/CPLCommon Portability Library见上文可移植性一节perftests/检查 GDAL 各方面速度/性能的 C 与 Python 脚本scripts/持续集成、版本发布及其他辅助任务的工具脚本均非面向最终用户swig/includeSWIG Python、Java、C# 绑定的定义swig/python/gdal-utils/scripts已安装/公开的 GDAL Python 工具的启动脚本本身无实际功能swig/python/gdal-utils/osgeo_utilsGDAL Python 工具的核心代码随 PyPIgdal与gdal-utils包发布swig/python/gdal-utils/samples不安装、通常很少文档化的脚本可作为未来官方脚本的孵化区swig/python/gdal-utils/auxiliaryGDAL Python 工具使用的辅助方法与类third_party/libgdal 使用的第三方库其余内嵌第三方代码还散见于alg/internal_libqhull、apps/argparse、frmts/gtiff/libtiff、frmts/gtiff/libgeotiff、frmts/hdf4/hdf-eos、frmts/jpeg/libjpeg、frmts/jpeg/libjpeg12、frmts/grib/degrib/degrib、frmts/grib/degrib/g2clib、frmts/pcidsk/sdk、frmts/pcraster/libcsf、frmts/png/libpng、frmts/gif/giflib、frmts/zlib/、ogr/ogrsf_frmts/cad/libopencad、ogr/ogrsf_frmts/geojson/libjson、ogr/ogrsf_frmts/flatgeobuf/flatbuffers、ogr/ogrsf_frmts/pmtiles/pmtiles、ogr/ogrsf_frmts/sqlite/sqlite_rtree_bulk_load等小结综合来看GDAL 的开发实践可以概括为四条主线流程上小改动走 PR、大改动走 RFC 并受 RFC 85 与 AI/LLM 政策约束代码质量上遵循 C99/C17、适应式匈牙利命名法、.clang-format/Black 格式化和 pre-commit 自动检查安全性上以 CPL 可移植库与VSIMalloc2/3溢出防护作为内存分配的标准姿势工程协作上坚持功能分支、干净的提交历史、规范的提交信息与 blame ignore 配置。无论你是准备提交第一个缺陷修复还是计划贡献一个新的栅格/矢量驱动本文所整理的规范与源码证据dev_practices.rst 及其引用的 RFC 85、RFC 98、RFC 19、.clang-format、.pre-commit-config.yaml、.git-blame-ignore-revs都能作为你提交代码前的自检清单。赞分享GIS遥感数据工程【免费下载链接】gdalGDAL is an open source MIT licensed translator library for raster and vector geospatial data formats.项目地址https://gitcode.com/gh_mirrors/gd/gdal点击查看免费下载相关推荐Apache Beam Splittable DoFn 完全指南限制切分、并行读取与三语言实现Apache Beam Splittable DoFn 完全指南限制切分、并行读取与三语言实现 Splittable DoFn简称 SDF是 Apache批处理流处理大数据从代码到提交Coze Studio全流程开发规范实战指南从代码到提交Coze Studio全流程开发规范实战指南 在协作开发中统一的规范是提升效率、降低沟通成本的关键。Coze Studio作为AI Agent开人工智能AI Agent低代码RAG后端前端工作流自动化GDAL项目RFC流程详解如何规范提交重大代码变更GDAL项目RFC流程详解如何规范提交重大代码变更 什么是RFC流程 在GDAL项目中RFC Request For Comments 流程是针对重大代码变GIS遥感数据工程上一篇QKeyMapper终极指南Windows免费开源按键映射工具轻松实现手柄玩PC游戏下一篇Legacy iOS Kit终极指南一键降级越狱旧款iPhone/iPad设备创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考