GIS【免费下载链接】h3Hexagonal hierarchical geospatial indexing system项目地址https://gitcode.com/gh_mirrors/h3/h3点击查看免费下载本篇技术指南以 H3Hexagonal Hierarchical Geospatial Indexing System开源仓库根目录下的 CHANGELOG.md 为主体系统梳理该库从 3.0 首版到当前 4.5.0 的完整演进脉络重点剖析 4.0 系列引入的 H3Error 错误处理体系、函数命名重构与 Vertex 模式并逐条解读 4.5.0 与 Unreleased 中的新特性、修复及其底层源码实现。读完本文你将掌握 H3 各版本的能力边界、破坏性变更的来龙去脉并学会从 Change Log 出发溯源到 h3api.h.in、核心源码与测试用例为升级、选型与二次开发提供依据。版本纪律Change Log 与公共 API 边界CHANGELOG.md 明确声明该库遵循 Semantic Versioning语义化版本并给出了公共 API的权威定义The public API of this library consists of the functions declared in file h3api.h.in。这意味着主版本Major号只在公共 API 发生不兼容变更时递增例如 4.0.0 的函数重命名、H3Error 返回值、int64_t单元计数等公共 API 的权威清单是 src/h3lib/include/h3api.h.in。该文件通过 CMakeLists.txt 中的configure_file生成src/h3lib/include/h3api.h并安装到prefix/include/h3/h3api.h文件头部注释也写明对其中函数的不兼容修改必须提升主版本号文件中的H3_EXPORT(name)宏还支持通过H3_PREFIXCMake 选项对所有导出函数统一加前缀重命名避免与其他库符号冲突见 h3api.h.in。版本号的维护流程记录在 RELEASE.md发布时先把 CHANGELOG.md 的[Unreleased]段改成[X.Y.Z] YYYY-MM-DD然后在build目录运行make update-version调用 scripts/update_version.sh更新 VERSION 文件。当前仓库的 VERSION 文件内容为4.5.0与 CHANGELOG 中最新的正式版本 4.5.02026-05-21一致。4.0 里程碑错误处理、命名与 CLI 的三重重构4.0.0 于 2022-08-23 正式发布是 H3 历史上最大的一次破坏性变更。它包含三个主线错误处理体系、术语重命名体系、Vertex 模式与 CLI 应用。错误处理以 H3Error 返回码为核心Change Log 的 Breaking changes 中写道Functions that can experience errors now have anH3Errorreturn value.这一设计决策的完整推演过程记录在 dev-docs/RFCs/v4.0.0/error-handling-rfc.md官方用户文档见 website/docs/library/errors.md。RFC 的动机在于H3 此前大量函数返回void当发生内部错误或输入非法时无法通过返回值向调用方传达信息而输出缓冲区的内容又无法区分正确结果与无输出。RFC 对比了六种候选方案方案形式主要缺陷Return code返回码err latLngToCell(..., result)需同时返回状态与数据Return code unsafe 版本额外提供unsafe_*无错误版本两套 API 并存Return code GetError通过h3GetError()取附加信息只能返回最近一次错误有线程安全问题GetError only函数返回数据错误另取调用方需查文档才知道何时检查错误Error parameter错误出参result latLngToCell(..., err)与多数语言绑定习惯不一致setjmp/longjmp异常式跳转无法被其他语言绑定支持最终采纳的方案是Return code返回码理由是可让 API 消费者从函数签名直接看出错误的存在且跨语言绑定友好。类型定义H3Error为 32 位无符号整数uint32_t值 0 表示成功任何合法错误码都不会设置最高位因此不会与H3Index中的Mode 位段冲突应用可以安全地把错误码与索引混放在同一缓冲区中见 src/h3lib/include/h3api.h.in。错误码表完整的H3ErrorCodes枚举定义在 h3api.h.in从E_SUCCESS 0到E_DELETED_DIGIT 19末尾有哨兵值H3_ERROR_END最后一个合法错误码之后一位便于遍历。其中 4.0.0 引入 0–14 号错误码4.0.0-rc2 新增E_OPTION_INVALID4.4.0 又新增E_BASE_CELL_DOMAIN、E_DIGIT_DOMAIN、E_DELETED_DIGIT与H3_ERROR_END。Change Log 明确要求未识别的新错误码应按E_FAILED处理保证向前兼容。错误描述describeH3Error返回错误码对应的可读字符串实现位于 src/h3lib/lib/h3Index.c——一张H3ErrorDescriptions字符串数组且对err H3_ERROR_END的越界值返回Invalid error code。RFC 中还给出了典型错误码示例部分转写为 4.x 命名latLngToCell(latInfinity, lng0, res0, out) E_LATLNG_DOMAIN latLngToCell(lat0, lng0, res-1, out) E_RES_DOMAIN cellToLatLng(index0, out) E_CELL_INVALID compact({AN_INDEX, AN_INDEX}, out, n) E_DUPLICATE_INPUT h3IndexesAreNeighbors(远距离索引) E_NOT_NEIGHBORS h3IndexesAreNeighbors(不同分辨率索引) E_RES_MISMATCH在 C 代码中典型调用方式为H3Error err; H3Index result; err latLngToCell(lat, lng, res, result); if (err) { fprintf(stderr, Error: %d (%s), err, describeH3Error(err)); }命名体系重写遵循术语 RFC4.0 的另一项破坏性变更来自术语 RFC仓库中的 dev-docs/RFCs/v4.0.0/names_for_concepts_types_functions.md将 API 全面统一为对象 操作的 cell/edge/vertex 命名坐标与单元geoToH3→latLngToCellh3ToGeo→cellToLatLngh3ToGeoBoundary→cellToBoundary网格算法polyfill→polygonToCellskRing/hexRange系列 →gridDisk/gridRing系列h3Line→gridPathCellsh3Distance→gridDistance本地坐标系4.0.0-rc2 起experimentalH3ToLocalIj/experimentalLocalIjToH3更名为cellToLocalIj/localIjToCell并新增mode参数以备将来扩展h3ToCenterChild更名为cellToCenterChild且改为返回错误码距离与长度4.0.0-rc4 起distance*更名为greatCircleDistance*4.0.0-rc5 起exactEdgeLength*更名为edgeLength*其他约定全局以lng取代lon单元格计数参数由int改为int64_tpolygonToCells新增flags参数当前传 0为将来扩展保留E_MEMORY更名为E_MEMORY_ALLOC。这些重命名全部同步反映在 src/h3lib/include/h3api.h.in 的公开函数签名中例如H3_EXPORT(gridDisk)(H3Index origin, int k, H3Index *out)与H3_EXPORT(polygonToCells)(const GeoPolygon *geoPolygon, int res, uint32_t flags, H3Index *out)。Vertex 模式与 h3 CLI4.0 的两项新能力4.0.0含 rc1新增了Vertex 模式与配套函数cellToVertex(cell, vertexNum)取指定单元格的第 N 个顶点以 H3Index 表示cellToVertexes(cell, out)取单元格全部顶点vertexToLatLng(vertex, out)顶点坐标转经纬度isValidVertex(vertex)校验顶点索引。顶点同样是 H3Index 编码的 64 位索引Mode 位段区分 cell / directed edge / vertex相关 API 与文档见 src/h3lib/include/h3api.h.in。仓库自带的 H3 网格探索器界面直观展示了顶点模式下六边形六个顶点的可视化与十六进制顶点索引如下图所示同时 4.0.0 引入了h3CLI 应用源码在 src/apps/filters/h3.c把绝大多数 C 库函数暴露为 shell 可调用的子命令方便脚本化使用该功能在 4.2.0 中被标记为ready for use可用于 shell 脚本。CLI 的每个子命令都对应一份 golden 测试输出存放在 tests/cli 目录如gridDistance.txt、stringToInt.txt、intToString.txt。4.0.0-rc1 → rc5 的收敛过程与 4.0.1 补强4.0 系列经历了五个 RC 版本的收敛rc1 引入重命名、H3Error、int64_t、flags 参数与 Vertex/CLIrc2 完成 localIj 重命名与E_OPTION_INVALIDrc3 修复 polyfill 顶点纬度等于单元中心的 bugrc4 统一greatCircleDistance*命名rc5 完成edgeLength*命名并让polygonToCells对 Infinity 输入返回错误。正式版 4.0.12022-09-15则集中修复了一批经单元测试与模糊测试发现的问题包括float→double提升地理坐标输出精度、压缩分辨率 0 单元格的所有子单元、maxGridDiskSize与h3NeighborRotations的符号整数溢出、cellToVertex未初始化值、localIjToCell越界读、compactCells与cellsToLinkedMultiPolygon内存泄漏、areNeighborCells越界读等同时在 CI 中自动运行模糊测试套件并新增了针对内部 algos.c 的 fuzzerfuzzerInternalAlgos.c。4.1–4.4层级查询、实验算法与错误码扩展4.1.02023-01-18单元层级定位函数新增cellToChildPos与childPosToCell把子单元映射到其在父单元全部子单元有序列表中的位置或反向从位置还原子单元见 h3api.h.in修复h3NeighborRotations与localIjToCell可能的符号整数溢出对未覆盖的防御性代码块补充assertclang-format 升级到 v11。4.2.02024-12-04实验性 polygonToCells 与 h3 CLI 就绪新增实验算法polygonToCellsExperimental支持更多 containment 标志ContainmentMode枚举CONTAINMENT_CENTER/CONTAINMENT_FULL/CONTAINMENT_OVERLAPPING/CONTAINMENT_OVERLAPPING_BBOX定义见 h3api.h.in且内存效率更高配套maxPolygonToCellsSizeExperimental。该 API 属于实验性质允许在 minor 版本中变更h3CLI 二进制进入可用状态#818、#826、#846、#923、#924、#931、#933修复压缩全部或大量分辨率 1 单元的问题compactCells内部改用int64_t数组索引测试重组为公共 / 内部两类见 CMakeTests.cmake修复此前未真正测试分辨率 15 的测试aarch64 性能增强可能惠及其他平台clang-format 升级至 v14使用CMAKE_INSTALL_LIBDIR决定库文件安装目录。4.2.12025-03-10稳定性与枚举迁移修复 MSVC/WIN32 下的 CMake 检查#981与polygonStringToGeoPolygon潜在内存泄漏#976isValidCell更快#968将polygonToCellsExperimental的ContainmentMode枚举迁入公共头文件 h3api.h.in#958CI 增加 arm64 测试。4.3.02025-06-17gridRing 支持五边形失真新增gridRing函数即便遇到五边形导致的网格失真也能正确返回空心环hollow ring。配套有maxGridRingSize与gridRingUnsafe声明见 h3api.h.in。4.4.02025-11-06索引内省三件套与错误码扩展getIndexDigit内省 H3 索引在指定分辨率1–15第 1 位从分辨率 1 开始的索引数字isValidIndex校验索引对任意模式cell / directed edge / vertex是否合法constructCell由(res, baseCellNumber, digits)三个分量直接构造合法单元索引新增错误码E_BASE_CELL_DOMAIN、E_DIGIT_DOMAIN、E_DELETED_DIGIT及H3_ERROR_END哨兵见 h3api.h.in对应测试用例在 testIndexDigits.c 与 testConstructCell.c。4.4.12025-11-11版本号修正修复 VERSION 文件未正确设置版本号的问题#1091保证版本元数据与 CHANGELOG 一致。4.5.0当前版本的核心新特性4.5.02026-05-21是当前仓库 VERSION 指向的正式版本其新增与重构如下。cellsToMultiPolygon新的多边形输出管线新增cellsToMultiPolygon当前为内部函数未来版本才会进入公共 API它把一组单元索引转换为GeoMultiPolygon可直接索引、带元素数量的数组结构并配套destroyGeoMultiPolygon释放内存与内部geoLoopArea面积函数核心实现在 src/h3lib/lib/cellsToMultiPoly.c先由validateCellSet校验输入负数数量返回E_DOMAIN、无效单元返回E_CELL_INVALID、分辨率不一致返回E_RES_MISMATCH、重复单元返回E_DUPLICATE_INPUT、分配失败返回E_MEMORY_ALLOC再构建弧线集ArcSet基于 SplitMix64 哈希 线性探测的桶表、用reverseDirectedEdge抵消相邻单元格的共享边union-find 合并连通分量、最后按外环面积降序组装多边形多边形遵循右手规则外环逆时针、内环洞顺时针空输入返回一个由 8 个三角形表示整个地球的 GeoMultiPolygon见createGlobeMultiPolygon。cellsToLinkedMultiPolygon 行为变更cellsToLinkedMultiPolygon内部改用cellsToMultiPolygon#1126、#1133、#1136且两个函数现在会对**无效单元E_CELL_INVALID、混合分辨率E_RES_MISMATCH、重复单元E_DOMAIN**返回错误而不是像旧版那样产生未定义输出destroyLinkedMultiPolygon变为幂等重复调用安全#1136cellAreaRads2改用geoLoopArea计算#1101。reverseDirectedEdge 与双向 gridPathCells新增reverseDirectedEdge(edge, out)返回源单元与目标单元互换的有向边见 h3api.h.in由cellsToMultiPolygon内部使用gridPathCells变为双向#1111gridPathCellsSize(start, end, size)与gridPathCells(start, end, out)同时支持从 end 向 start 回溯的路径不再要求特定方向。h3.pc pkg-config 支持新增 h3.pc.in pkg-config 模板#1115CMake 会将其配置为h3.pc并安装到${CMAKE_INSTALL_LIBDIR}/pkgconfig便于pkg-config --cflags --libs h3方式接入第三方构建系统。索引代码重构与 CLI 修复索引代码重构为使用 Vec3d#1145、#1155CoordIJK 代码改为可内联#1154属于内部实现优化CLI 修复处理无效单元输入不再异常#1125、#1124stringToInt子命令修复 16 位索引有向边、顶点被截断的问题gridDistance子命令由十六进制输出改为十进制输出。Unreleased下一版本的修复清单CHANGELOG 的[Unreleased]段预告了下一版本的四个修复均为明确的正确性/工程性修补maxPolygonToCellsSize顶点计数符号整数溢出#1204累积顶点数量时避免 signed 溢出polygonToCellsfuzzer 回归测试端序可移植#964改用显式 double 字面量而非重解释原始字节确保在大端/小端平台结果一致CMake 格式化/静态检查警告收敛#1158当用户显式设置ENABLE_FORMATOFF/ENABLE_LINTINGOFF时不再提示缺少clang-format/clang-tidy。该逻辑在 CMakeLists.txt 中通过format_explicitly_disabled/linting_explicitly_disabled标志实现_baseCellToCCWrot60越界读#978当传入等于NUM_ICOSA_FACES的面编号时修复越界读取CLI 输出正确性#1243stringToInt不再截断 16 位索引gridDistance以十进制而非十六进制打印距离。3.x 演进为 4.0 铺路的迭代史3.x 系列2018-01-08 首版至 2021-07-15 最后一版为 4.0 的重构积累了算法、构建与测试基础。下表按版本梳理全部里程碑版本日期核心内容3.0.02018-01-08首个公开版本3.0.12018-01-18新增make install目标Windows 构建兼容3.0.22018-01-24移除内部H3IndexFat结构简化 Windows 构建修复 ARM 测试3.0.32018-03-19CMake config 安装第三方 CMake 项目可find_packagetoolchain 文件clang-tidy 集成最小 CMake 3.1CMAKE_C_STANDARD11移除H3_COMPILER/BUILD_STATIC/ENABLE_TESTS选项3.0.42018-04-16堆内存分配断言大部分内部内存分配转移到栈3.0.52018-04-27修复 class III 六边形h3ToGeoBoundary重复顶点新增发布指南3.0.62018-06-01h3NeighborRotations内部签名变更绑定不再要求支持hexRange系列geoToH3核心索引逻辑性能提升3.0.72018-06-08faceCenterPoint 表与每分辨率索引数生成器WARNINGS_AS_ERRORS、TEST_WRAPPER选项Vec3d 结构迁入 vec3d.h边源/目标输入校验3.0.82018-07-18Direction 枚举取代 int 常量清理五边形子单元未用内存修复 segfault3.1.02018-08-03新增h3Distance网格距离、内部h3ToIjkIJK 坐标与ijkDistanceh3ToIjkfilter 应用不再强制要求 C 编译器3.1.12018-08-29修复跨反子午线多边形 bbox输出对齐 GeoJSON 规范每个多边形一个外环 洞经度保证落在 [-Pi, Pi]maxKringSize闭式公式3.2.02018-10-04experimentalH3ToLocalIj/experimentalLocalIjToH3kRing 基准测试3.3.02018-12-25h3Line/h3LineSize网格路径函数被删除的五边形子序列索引不再视为合法3.4.02019-01-23getRes0Indexes/res0IndexCount库版本常量3.4.1/3.4.22019-02binding-functions构建目标修复out-of-source、Windows ASCII 输出3.4.32019-05-02localIjToH3filterkRingfilter 距离打印选项更灵活的参数解析uncompact全零输入不再报错3.4.42019-05-30局部坐标空间不可跨越多个 icosahedron 边动态内存分配统一移到堆3.5.02019-07-22h3GetFaces/maxFaceCounticosahedron 面查询CMake 新增排除 filter/benchmark 的选项3.6.02019-08-12h3ToCenterChildgetPentagonIndexes/pentagonIndexCount3.6.12019-11-11compact零长度输入bboxHexRadius缩放因子保证 polyfill 包含性polyfill 新算法宣称最高 3x 性能提升KML 生成 CMake 目标修复3.6.22019-12-09回退 polyfill 新算法待问题修复3.6.32020-01-21compact检测重复输入索引h3IsValid对保留位非零或高位被置位的索引返回 false3.6.42020-06-19H3_MEMORY_PREFIXCMake 选项替换内存管理函数配套 RFC 见 dev-docs/RFCs/v4.0.0/overrideable-allocators-rfc.mdDebian 包构建H3_DIGIT_MASK_NEGATIVE宏修复重新实现 polyfill 新算法3.7.02020-09-28面积与 haversine 距离函数cellAreaRads2/Km2/M2、pointDist*、exactEdgeLength*getH3UnidirectionalEdgeBoundary小分辨率精度重构约 3x 加速为 Vertex 模式打基础3.7.12020-10-05无效边边界不再崩溃FreeBSD 构建修复3.7.22021-07-15gridDisk对无效索引不崩溃可以看到 3.x 的两条暗线一是内存管理栈↔堆的反复权衡最终在 3.4.4 定稿为动态分配统一上堆并配合H3_MEMORY_PREFIX可插拔分配器二是polyfill 算法的迭代3.6.1 引入、3.6.2 回退、3.6.4 重写最终在 4.0 中演变为polygonToCells与 4.2.0 的polygonToCellsExperimental。从 Change Log 追溯验证构建、测试与 CLI 实践CHANGELOG 的每一条目都可以在仓库中找到可验证的证据。常用验证手段包括构建与运行按 README.md 的说明执行mkdir build cd build cmake -DCMAKE_BUILD_TYPERelease .. make然后通过./bin/h3src/apps/filters/h3.c调用任意子命令。例如./bin/latLngToCell --resolution 10 --latitude 40.689167 --longitude -74.044444得到索引8a2a1072b59ffffCLI 输出对照tests/cli目录存放了全部子命令的 golden 输出例如 gridDistance.txt 可直接验证十进制距离输出修复stringToInt.txt 可验证 16 位索引往返测试套件make test运行全部测试、make test-fast跳过最昂贵的用例与 4.x 相关的内部算法测试位于 src/apps/testapps如 testGridRing.c、testCellsToLinkedMultiPolygon.c、testDescribeH3Error.c模糊测试与基准BUILD_FUZZERS默认 ON构建 src/apps/fuzzers 下 20 个 fuzzer harness可配合 libFuzzer 或 afl对应 CMake 选项ENABLE_LIBFUZZERmake benchmarks运行 src/apps/benchmarks 的计时基准CMake 选项映射CHANGELOG 中反复出现的构建行为均可映射到 CMakeLists.txt 的option(...)BUILD_FILTERS、BUILD_BENCHMARKS、BUILD_FUZZERS、ENABLE_FORMAT、ENABLE_LINTING、ENABLE_COVERAGE、WARNINGS_AS_ERRORS、ENABLE_COUNTRY_BENCHMARKS等文档生成与可视化make docs生成 Doxygen 文档make kml用 h3ToHier 串联cellToBoundary/cellToLatLng生成前 3 级分辨率的 KML 网格文件写入 KML 目录内含示例icosa.kml。结语Change Log 即演进路线图H3 的 CHANGELOG 不仅仅是一份变更记录它完整映射了库的架构决策从 3.x 对内存管理、polyfill 算法、面积/距离计算的打磨到 4.0 以H3Error返回码 术语重构 Vertex 模式重塑公共 API 边界再到 4.1–4.5 持续补充层级定位cellToChildPos、实验多边形算法polygonToCellsExperimental、五边形安全的gridRing、索引内省getIndexDigit/isValidIndex/constructCell与新的多边形输出管线cellsToMultiPolygon。对于正在使用或计划集成 H3 的开发者这份 Change Log 配合 h3api.h.in、dev-docs/RFCs/v4.0.0 下的 RFC 文档与各模块测试就是最可靠的升级对照表与实现说明书。赞分享GIS【免费下载链接】h3Hexagonal hierarchical geospatial indexing system项目地址https://gitcode.com/gh_mirrors/h3/h3点击查看免费下载相关推荐ExplorerPatcher 恢复 Win10 右键菜单完整流程ExplorerPatcher 恢复 Win10 右键菜单完整流程 Win11 的右键菜单做了精简文件被压缩过多少次之后解压缩到此处压缩为 zip 文桌面应用系统编程EcoPaste 版本演进深度解析从 1.0 重构版到 1.1 更新的关键特性与实现原理EcoPaste 版本演进深度解析从 1.0 重构版到 1.1 更新的关键特性与实现原理 EcoPaste 是一个跨平台的剪贴板管理工具其 CHANGELO桌面应用SQLAlchemy 0.9 版本演进全解析新特性、ORM/SQL 重构与多方言行为变更深度解读SQLAlchemy 0.9 版本演进全解析新特性、ORM/SQL 重构与多方言行为变更深度解读 本文基于 SQLAlchemy 仓库中的 0.9 系列完整变数据库后端ORM上一篇MCP Python SDK 客户端传输层完全指南Streamable HTTP、stdio 与进程内传输下一篇如何用Rockpack快速构建AI友好的React项目零基础入门指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考