Project address: https://github.com/Esri/geometry-api-java
Maven Central:
com.esri.geometry:esri-geometry-apiLicense: Apache License 2.0
Overview
Esri Geometry API for Java is a self-contained spatial geometry computation library that provides the ability to create, parse, and serialize 2D and 3D geometry objects, as well as perform spatial relationship operations. It requires no external GIS dependencies and can be directly embedded in Java applications, Hadoop MapReduce, Hive UDF, Spark, and other big data processing frameworks.
Quick Integration
Maven
<dependency>
<groupId>com.esri.geometry</groupId>
<artifactId>esri-geometry-api</artifactId>
<version>2.2.4</version>
</dependency>
Gradle
implementation 'com.esri.geometry:esri-geometry-api:2.2.4'
Environmental requirements: JDK 1.7+; runtime dependency on jackson-core(JSON processing).
Core Classes at a Glance
| Class | Package | Purpose |
|---|---|---|
GeometryEngine |
com.esri.core.geometry |
Recommended entry point--provides static convenience methods for geometry operations |
OperatorFactoryLocal |
com.esri.core.geometry |
Operator factory, suitable for high-performance batch processing |
SpatialReference |
com.esri.core.geometry |
Spatial reference / coordinate system (created via WKID or WKT) |
MapGeometry |
com.esri.core.geometry |
Packages Geometry and SpatialReference together |
Point |
com.esri.core.geometry |
Point (0-dimensional) |
MultiPoint |
com.esri.core.geometry |
Multipoint collection (0-dimensional) |
Polyline |
com.esri.core.geometry |
Polyline / path collection (1-dimensional) |
Polygon |
com.esri.core.geometry |
Polygon / ring collection (2-dimensional) |
Envelope |
com.esri.core.geometry |
Envelope (2-dimensional) |
Creating Geometry Objects
import com.esri.core.geometry.*;
// 点
Point pt = new Point(116.4, 39.9); // 2D
Point pt3d = new Point(116.4, 39.9, 50.0); // 3D
// 折线
Polyline line = new Polyline();
line.startPath(0, 0);
line.lineTo(10, 10);
line.lineTo(20, 0);
// 面
Polygon polygon = new Polygon();
polygon.startPath(0, 0);
polygon.lineTo(10, 0);
polygon.lineTo(10, 10);
polygon.lineTo(0, 10);
// 自动闭合
// 外接矩形
Envelope env = new Envelope(0, 0, 10, 10);
// 多点
MultiPoint mp = new MultiPoint();
mp.add(1, 2);
mp.add(3, 4);
Spatial Reference
// 按 WKID 创建(WGS 84 = 4326)
SpatialReference srWGS84 = SpatialReference.create(4326);
// 按 WKT 字符串创建
SpatialReference srCustom = SpatialReference.create("GEOGCS[\"GCS_WGS_1984\",...]]");
// 与几何对象绑定
MapGeometry mapGeom = new MapGeometry(pt, srWGS84);
Spatial Operations (via GeometryEngine)
Set Operations
SpatialReference sr = SpatialReference.create(4326);
// 缓冲区
Geometry buffered = GeometryEngine.buffer(point, sr, 100.0);
// 交集
Geometry inter = GeometryEngine.intersect(polygon1, polygon2, sr);
// 合并
Geometry united = GeometryEngine.union(new Geometry[]{poly1, poly2, poly3}, sr);
// 差集
Geometry diff = GeometryEngine.difference(polygon1, polygon2, sr);
// 对称差
Geometry symDiff = GeometryEngine.symmetricDifference(geom1, geom2, sr);
// 裁剪(按矩形)
Geometry clipped = GeometryEngine.clip(geometry, envelope, sr);
// 切割(用折线切割面或线)
Geometry[] parts = GeometryEngine.cut(polygon, cuttingLine, sr);
Distance and Proximity
double dist = GeometryEngine.distance(geom1, geom2, sr);
Spatial Relationship Determination
boolean eq = GeometryEngine.equals(g1, g2, sr);
boolean wn = GeometryEngine.within(point, polygon, sr);
boolean ct = GeometryEngine.contains(polygon, point, sr);
boolean ix = GeometryEngine.intersects(g1, g2, sr);
boolean dj = GeometryEngine.disjoint(g1, g2, sr);
boolean tc = GeometryEngine.touches(g1, g2, sr);
boolean cr = GeometryEngine.crosses(line, polygon, sr);
boolean ol = GeometryEngine.overlaps(poly1, poly2, sr);
// DE-9IM 关系矩阵
boolean rel = GeometryEngine.relate(g1, g2, sr, "T*F**FFF*");
Geometry Analysis
// 凸包
Geometry hull = GeometryEngine.convexHull(geometry);
// 简化
Geometry simplified = GeometryEngine.simplify(geometry, sr);
// 泛化(简化顶点)
Geometry generalized = GeometryEngine.generalize(geometry, maxDeviation, true, sr);
// 质心 / 标注点
Point centroid = GeometryEngine.getLabelPoint(polygon, sr);
Geodesic Measurement (Ellipsoidal Calculations)
// 大地测量缓冲区(结果更精确,适用于地理坐标系)
Geometry geoBuffer = GeometryEngine.geodesicBuffer(geometry, sr, 1000.0);
// 大地测量长度
double geoLen = GeometryEngine.geodesicLength(polyline, sr, null);
// 大地测量面积
double geoArea = GeometryEngine.geodesicArea(polygon, sr, null);
Format Conversion
JSON(Esri JSON)
// 导入
MapGeometry mg = GeometryEngine.jsonToGeometry(jsonString);
Geometry geom = mg.getGeometry();
SpatialReference sr = mg.getSpatialReference();
// 导出(附带 WKID)
String json = GeometryEngine.geometryToJson(4326, geometry);
GeoJSON
// 导入
MapGeometry mg = GeometryEngine.geoJsonToGeometry(geoJsonString, 0, Geometry.Type.Unknown);
// 导出
String geoJson = GeometryEngine.geometryToGeoJson(geometry);
WKT(Well-Known Text)
// 导入
Geometry geom = GeometryEngine.geometryFromWkt(
"POLYGON((0 0,10 0,10 10,0 10,0 0))",
0,
Geometry.Type.Polygon
);
// 导出
String wkt = GeometryEngine.geometryToWkt(geometry, 0);
WKB(Well-Known Binary)
// 导入
Geometry geom = GeometryEngine.geometryFromWkb(byteBuffer, Geometry.Type.Unknown);
// 导出
ByteBuffer wkb = GeometryEngine.geometryToWkb(geometry, 0);
Esri Shape
// 导入
Geometry geom = GeometryEngine.geometryFromEsriShape(byteBuffer, Geometry.Type.Polygon);
// 导出
byte[] shape = GeometryEngine.geometryToEsriShape(geometry);
Advanced Usage: Direct Operator Calls
When large numbers of geometry objects need to be processed in batches, using OperatorFactoryLocal to obtain an operator and combining it with GeometryCursor can achieve better performance:
OperatorFactoryLocal factory = OperatorFactoryLocal.getInstance();
OperatorBuffer bufferOp = (OperatorBuffer) factory.getOperator(Operator.Type.Buffer);
// 使用 SimpleGeometryCursor 包装输入
SimpleGeometryCursor inputCursor = new SimpleGeometryCursor(geometryArray);
double[] distances = {100.0};
GeometryCursor resultCursor = bufferOp.execute(inputCursor, sr, distances, false, null);
// 逐个取出结果
Geometry result;
while ((result = resultCursor.next()) != null) {
// 处理每个缓冲区结果
}
Geometry Type Determination
Geometry.Type type = geometry.getType();
switch (type) {
case Point: Point p = (Point) geometry; break;
case Polygon: Polygon pg = (Polygon) geometry; break;
case Polyline: Polyline pl = (Polyline) geometry; break;
case MultiPoint: MultiPoint mp = (MultiPoint) geometry; break;
case Envelope: Envelope ev = (Envelope) geometry; break;
}
// 按维度判断
boolean isPoint = Geometry.isPoint(type.value());
boolean isLinear = Geometry.isLinear(type.value());
boolean isArea = Geometry.isArea(type.value());
Vertex Attributes (Z / M / ID)
// 检查属性
geometry.hasZ();
geometry.hasM();
geometry.hasID();
// 添加属性
geometry.addAttribute(VertexDescription.Semantics.Z);
geometry.addAttribute(VertexDescription.Semantics.M);
Typical Application Scenarios
| Scenario | Key Methods |
|---|---|
| Geofencing / point-in-polygon determination | GeometryEngine.contains() or within() |
| Calculate the distance between two points | GeometryEngine.distance() or geodesicLength() |
| Create a buffer (e.g., the surrounding range of a POI) | GeometryEngine.buffer() or geodesicBuffer() |
| Polygon intersection / overlay analysis | GeometryEngine.intersect() / union() / difference() |
| Coordinate format conversion | jsonToGeometry() / geometryToGeoJson() / geometryFromWkt() etc. |
| Geometry validity checking and repair | GeometryEngine.simplify() |
| Hadoop / Spark spatial processing | Use with Operator + GeometryCursor for batch processing |
Common Considerations
- Consistent Coordinate Systems: Before performing spatial operations, ensure that all geometry objects use the same
SpatialReference。 - Simplify Geometry: After importing external data, use
GeometryEngine.simplify()to ensure topological correctness. - Geodesic vs Planar: When performing area/length calculations on geographic coordinates (longitude and latitude), preferentially use
geodesicArea()/geodesicLength()to obtain accurate ellipsoidal results. - Performance Optimization: For batch operations, it is recommended to use
OperatorFactoryLocal+GeometryCursor, rather than callingGeometryEnginestatic methods one by one. - Thread Safety:
GeometryEnginestatic methods are thread-safe.
Reference Links
- GitHub repository: https://github.com/Esri/geometry-api-java
- Official Wiki: https://github.com/Esri/geometry-api-java/wiki
- Javadoc: http://Esri.github.io/geometry-api-java/javadoc/
- Maven Central: https://repo1.maven.org/maven2/com/esri/geometry/
- Related project — Spatial Framework for Hadoop: https://github.com/Esri/spatial-framework-for-hadoop