Apache Commons Geometry 1.0 介绍与选型指南

目标：本文为认知篇（A1），基于 Apache Commons 官网、官方 Release History、Maven Central 与 GitHub 仓库联网溯源编写，关键论断随文标注来源与查询日期（2026-10-18），不做本地安装实测。

一、信息基准

1.1 查询信息说明

• 查询日期：2026-10-18（本文所有版本号、发布日期、社区数据均以该日联网实查为准）
• 版本依据：Apache Commons Geometry 官网组件页标注「Last Published: 20 August 2021 / Version: 1.0」（来源：commons.apache.org/proper/commons-geometry/，查询日期 2026-10-18）；官方 Release History 表确认 1.0 发布于 2021-08-21，1.0-beta1 发布于 2020-07-20（来源：commons.apache.org/proper/commons-geometry/release-history.html）
• Maven Central 实查：org.apache.commons:commons-geometry-core 最新版本 1.0（search.maven.org，查询日期 2026-10-18），与官网一致，即 1.0 为当前最新稳定版

1.2 官方来源清单

1.3 版本基准表

二、软件概述

Apache Commons Geometry 1.0（2021-08-21 发布，Apache License 2.0）是 Apache Software Foundation 旗下的通用 Java 几何处理库，官方定位为「提供一组数学上正确、数值上精确、易用且高性能的几何类型与工具」（官网首页原文意译：mathematically correct, numerically accurate, easy to use, and performant）。

其独特价值在于：以浮点等价性（precision/epsilon）模型贯穿 API 设计，显式处理浮点几何计算中的误差问题；支持无限尺寸几何元素与区域布尔运算，并以 BSP 树作为区域运算的底层引擎。该项目自 1.0（2021-08）后未再发版，社区以低频维护状态运行（GitHub 仓库 2026-10-17 仍有推送，2026-10-18 实查），选型时应将其视为「稳定但演进停滞」的库。

三、核心架构

3.1 模块划分

官网 Project Modules 页列出的模块（来源：commons.apache.org/proper/commons-geometry/modules.html，查询日期 2026-10-18）：

3.2 核心概念

• Precision 体系：Precision.DoubleEquivalence 以 epsilon 定义浮点比较语义，所有几何类型通过它判定点/面是否重合，这是本库区别于一般几何库的设计核心（官网首页示例开头即构造 precision 实例）。
• 欧氏空间：1/2/3 维向量、点、直线/射线、平面、区域（RegionBSPTree1D/2D/3D）等；球面空间：大圆、球面点/区域。
• BSP 树区域引擎：二叉空间分割树表示任意维度的封闭/开放区域，布尔运算（union/intersection/difference/xor）在树上完成；官网提供 BSP 树与实体几何（茶壶建模）两个教程。
• 边界表示与网格：区域可导出三角网格（TriangleMesh）并经 commons-geometry-io-euclidean 写为 STL/OBJ。

四、功能特性

依据官网首页功能清单（查询日期 2026-10-18）：

1. 欧氏空间支持：1、2、3 维。
2. 球面空间支持：1、2 维。
3. 无限尺寸几何元素：直线、平面等无限元素作为一等公民参与运算。
4. 区域布尔运算：union（并）、intersection（交）、difference（差）、xor（异或）。
5. 常见几何数据格式读写：STL 与 OBJ。
6. 单一外部依赖：仅依赖 commons-numbers（Apache Commons 数值库）。
7. 数值稳健性：以 Precision 等价类处理浮点边界，减少经典浮点几何的判定抖动。

五、快速上手

5.1 Maven 依赖

核心模块坐标（来源：Maven Central，artifact：org.apache.commons:commons-geometry-core，查询日期 2026-10-18）：

<dependency>
    <groupId>org.apache.commons</groupId>
    <artifactId>commons-geometry-core</artifactId>
    <version>1.0</version>
</dependency>

💡 说明：欧氏原语与 STL/OBJ 读写分别位于 commons-geometry-euclidean、commons-geometry-io-euclidean 模块（官网 Project Modules 页），按需引入。

5.2 官方示例（原文引用）

以下代码引自官网组件首页的 API 示例（来源：commons.apache.org/proper/commons-geometry/ 首页代码块，查询日期 2026-10-18）：计算「单位立方体减去球体近似」并将结果导出为 OBJ 文件：

// construct a precision instance to handle floating-point comparisons
Precision.DoubleEquivalence precision = Precision.doubleEquivalenceOfEpsilon(1e-6);

// create a BSP tree representing the unit cube
RegionBSPTree3D tree = Parallelepiped.unitCube(precision).toTree();

// create a sphere centered on the origin
Sphere sphere = Sphere.from(Vector3D.ZERO, 0.65, precision);

// subtract a BSP tree approximation of the sphere containing 512 facets
// from the cube, modifying the cube tree in place
tree.difference(sphere.toTree(3));

// compute some properties of the resulting region
double size = tree.getSize();          // 0.11509505362599505
Vector3D centroid = tree.getCentroid(); // (0, 0, 0)

// convert to a triangle mesh
TriangleMesh mesh = tree.toTriangleMesh(precision);

// save as an OBJ file
IO3D.write(mesh, Paths.get("target/cube-minus-sphere.obj"));

💡 说明：以上为官网首页原样示例，本文未做本地运行实测；官方 User Guide 与 BSP 树/茶壶教程提供更完整的推导过程。

六、适用场景与限制

6.1 适用场景

• 需要实体几何布尔运算（CAD 式建模、切割、体积/质心计算）的 Java 程序。
• 需要球面几何（大圆、球面区域）的场景，如地理/天文邻域计算。
• 需要网格导出（STL/OBJ）对接 3D 打印或渲染管线的场景。
• 对浮点判定稳健性要求高的算法工程（Precision 体系内建支持）。

6.2 限制与注意

• 发版停滞：1.0（2021-08-21）后未再发版，官网页面同样停更于 2021-08；issue 修复依赖社区驱动，选型需评估长期风险。
• 无 2D/3D 拓扑分析 API：不做缓冲区（buffer）、空间索引（R-tree）、WKT 解析等 GIS 常用能力，这类需求 JTS 更合适。
• 性能定位：官网目标含 performant，但通用 BSP 树运算在极端规模下需自行压测。
• Java 8 基线：要求 Java 8+（官方 Release History），无更高基线的新 API。

七、同类选型对比

对比对象：locationtech JTS Topology Suite、Apache SIS、JDK 内置 java.awt.geom。社区数据均为 2026-10-18 联网实查（GitHub API / 官方 README）。

选型建议：需要 3D 实体布尔运算、球面几何与 STL/OBJ 网格导出时 Commons Geometry 几乎是 JVM 上的唯一纯 Java 开箱方案，但须接受其 2021 年后停更的现实；以 2D GIS 拓扑（缓冲区、空间关系谓词、WKT）为主则选 JTS；涉及坐标参考系、大地测量与地理数据格式则选 Apache SIS；仅做简单 2D 形状运算可直接用 JDK 内置 java.awt.geom.Area。

八、参考链接

1. Apache Commons Geometry 官网：https://commons.apache.org/proper/commons-geometry/
2. User Guide：https://commons.apache.org/proper/commons-geometry/userguide/index.html
3. Release History：https://commons.apache.org/proper/commons-geometry/release-history.html
4. Project Modules：https://commons.apache.org/proper/commons-geometry/modules.html
5. BSP 树教程：https://commons.apache.org/proper/commons-geometry/tutorials/bsp-tree.html
6. GitHub 仓库：https://github.com/apache/commons-geometry
7. Commons Numbers：https://commons.apache.org/proper/commons-numbers/
8. JTS Topology Suite：https://github.com/locationtech/jts
9. Apache SIS：https://sis.apache.org/