SuperAPI AI Directory

geometry-api-java

Coding & development

View repository

Updated 10-16 09:45

About this skill

Project address: https://github.com/Esri/geometry-api-java

Maven Central: com.esri.geometry:esri-geometry-api

License: 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

  1. Consistent Coordinate Systems: Before performing spatial operations, ensure that all geometry objects use the same SpatialReference。
  2. Simplify Geometry: After importing external data, use GeometryEngine.simplify() to ensure topological correctness.
  3. Geodesic vs Planar: When performing area/length calculations on geographic coordinates (longitude and latitude), preferentially use geodesicArea() / geodesicLength() to obtain accurate ellipsoidal results.
  4. Performance Optimization: For batch operations, it is recommended to use OperatorFactoryLocal + GeometryCursor, rather than calling GeometryEngine static methods one by one.
  5. Thread Safety:GeometryEngine static methods are thread-safe.

Reference Links