0
# Elasticsearch Geo
1
2
The Elasticsearch Geo library is a Java geometry library providing comprehensive geometric shapes and spatial utility classes for Elasticsearch's geo-spatial functionality. It offers zero-dependency geometric primitives with built-in validation, standardization utilities, and efficient operations for handling geospatial data processing workflows.
3
4
## Package Information
5
6
- **Package Name**: `org.elasticsearch:elasticsearch-geo`
7
- **Language**: Java
8
- **Installation**: Add to Maven `pom.xml`:
9
```xml
10
<dependency>
11
<groupId>org.elasticsearch</groupId>
12
<artifactId>elasticsearch-geo</artifactId>
13
<version>9.1.3</version>
14
</dependency>
15
```
16
17
## Core Imports
18
19
```java { .api }
20
// Core geometry classes
21
import org.elasticsearch.geometry.Point;
22
import org.elasticsearch.geometry.Circle;
23
import org.elasticsearch.geometry.Polygon;
24
import org.elasticsearch.geometry.Rectangle;
25
import org.elasticsearch.geometry.Line;
26
import org.elasticsearch.geometry.LinearRing;
27
28
// Multi-geometry collections
29
import org.elasticsearch.geometry.MultiPoint;
30
import org.elasticsearch.geometry.MultiLine;
31
import org.elasticsearch.geometry.MultiPolygon;
32
import org.elasticsearch.geometry.GeometryCollection;
33
34
// Base interfaces and visitor pattern
35
import org.elasticsearch.geometry.Geometry;
36
import org.elasticsearch.geometry.GeometryVisitor;
37
import org.elasticsearch.geometry.ShapeType;
38
39
// Utility classes
40
import org.elasticsearch.geometry.utils.WellKnownText;
41
import org.elasticsearch.geometry.utils.WellKnownBinary;
42
import org.elasticsearch.geometry.utils.Geohash;
43
import org.elasticsearch.geometry.utils.GeometryValidator;
44
import org.elasticsearch.geometry.utils.StandardValidator;
45
import org.elasticsearch.geometry.utils.GeographyValidator;
46
import org.elasticsearch.geometry.utils.SpatialEnvelopeVisitor;
47
import org.elasticsearch.geometry.utils.CircleUtils;
48
import org.elasticsearch.geometry.utils.BitUtil;
49
```
50
51
## Basic Usage
52
53
```java { .api }
54
// Create a simple point geometry
55
Point point = new Point(-73.935242, 40.730610); // longitude, latitude
56
57
// Create a circle around the point with 1000 meter radius
58
Circle circle = new Circle(-73.935242, 40.730610, 1000.0);
59
60
// Create a polygon with a linear ring
61
double[] lons = {-74.0, -73.9, -73.9, -74.0, -74.0};
62
double[] lats = {40.7, 40.7, 40.8, 40.8, 40.7};
63
LinearRing ring = new LinearRing(lons, lats);
64
Polygon polygon = new Polygon(ring);
65
66
// Convert geometry to Well-Known Text format
67
String wkt = WellKnownText.toWKT(point);
68
// Result: "POINT(-73.935242 40.730610)"
69
70
// Parse WKT back to geometry
71
GeometryValidator validator = StandardValidator.instance(true);
72
Geometry parsed = WellKnownText.fromWKT(validator, false, "POINT(-73.935242 40.730610)");
73
```
74
75
## Architecture
76
77
The library is built around several core concepts:
78
79
- **Geometry Interface**: Base interface implemented by all geometry types, providing type information and visitor pattern support
80
- **Visitor Pattern**: Type-safe processing of different geometry types through the `GeometryVisitor` interface
81
- **Shape Types**: Enumeration defining all supported geometry types (Point, Polygon, Circle, etc.)
82
- **Format Support**: Utilities for converting between geometry objects and standard formats (WKT, WKB, GeoHash)
83
- **Validation Framework**: Pluggable validation system for ensuring geometric validity
84
- **Simplification Framework**: Memory-efficient algorithms for reducing geometry complexity while preserving essential features
85
86
## Capabilities
87
88
### Core Geometry Types
89
Create and manipulate fundamental geometric shapes including points, circles, rectangles, lines, and polygons with support for 2D and 3D coordinates.
90
91
```java { .api }
92
// Basic 2D point
93
Point point2d = new Point(-73.935242, 40.730610);
94
95
// 3D point with altitude
96
Point point3d = new Point(-73.935242, 40.730610, 150.0);
97
98
// Circle with radius in meters
99
Circle circle = new Circle(-73.935242, 40.730610, 1000.0);
100
101
// Rectangle (bounding box)
102
Rectangle bbox = new Rectangle(-74.0, -73.9, 40.8, 40.7); // minX, maxX, maxY, minY
103
104
// Line with multiple points
105
double[] lons = {-74.0, -73.9, -73.8};
106
double[] lats = {40.7, 40.75, 40.8};
107
Line line = new Line(lons, lats);
108
```
109
110
[Core Geometry Types](./core-geometry.md)
111
112
### Multi-Geometry Collections
113
Work with collections of geometries including MultiPoint, MultiPolygon, and generic geometry collections.
114
115
```java { .api }
116
// Collection of points
117
List<Point> points = Arrays.asList(
118
new Point(-73.935242, 40.730610),
119
new Point(-73.935242, 40.730610)
120
);
121
MultiPoint multiPoint = new MultiPoint(points);
122
123
// Collection of polygons
124
List<Polygon> polygons = Arrays.asList(polygon1, polygon2);
125
MultiPolygon multiPolygon = new MultiPolygon(polygons);
126
127
// Generic geometry collection
128
List<Geometry> geometries = Arrays.asList(point, circle, polygon);
129
GeometryCollection<Geometry> collection = new GeometryCollection<>(geometries);
130
```
131
132
[Multi-Geometry Collections](./multi-geometry.md)
133
134
### Format Conversion
135
Convert geometries to and from standard geospatial formats including Well-Known Text (WKT), Well-Known Binary (WKB), and GeoHash.
136
137
```java { .api }
138
// WKT conversion
139
String wkt = WellKnownText.toWKT(geometry);
140
Geometry geometry = WellKnownText.fromWKT(validator, false, wktString);
141
142
// WKB conversion
143
byte[] wkb = WellKnownBinary.toWKB(geometry, ByteOrder.BIG_ENDIAN);
144
145
// GeoHash operations
146
String geohash = Geohash.stringEncode(-73.935242, 40.730610, 12);
147
Point point = Geohash.toPoint(geohash);
148
Rectangle bounds = Geohash.toBoundingBox(geohash);
149
```
150
151
[Format Conversion](./format-conversion.md)
152
153
### Visitor Pattern Processing
154
Process different geometry types in a type-safe manner using the visitor pattern, enabling extensible operations on geometric data.
155
156
```java { .api }
157
// Custom visitor implementation
158
public class AreaCalculator implements GeometryVisitor<Double, RuntimeException> {
159
@Override
160
public Double visit(Circle circle) {
161
return Math.PI * Math.pow(circle.getRadiusMeters(), 2);
162
}
163
164
@Override
165
public Double visit(Rectangle rectangle) {
166
double width = rectangle.getMaxX() - rectangle.getMinX();
167
double height = rectangle.getMaxY() - rectangle.getMinY();
168
return width * height;
169
}
170
171
// ... implement other visit methods
172
}
173
174
// Use visitor
175
AreaCalculator calculator = new AreaCalculator();
176
Double area = geometry.visit(calculator);
177
```
178
179
[Visitor Pattern Processing](./visitor-pattern.md)
180
181
### Validation Framework
182
Validate geometries using pluggable validation framework with standard and geography-specific validators.
183
184
```java { .api }
185
// Standard validation
186
GeometryValidator validator = StandardValidator.instance(false);
187
validator.validate(geometry); // throws IllegalArgumentException if invalid
188
189
// Geography validation (lat/lon bounds checking)
190
GeometryValidator geoValidator = GeographyValidator.instance(false);
191
geoValidator.validate(geometry);
192
193
// No-op validator
194
GeometryValidator noop = GeometryValidator.NOOP;
195
```
196
197
[Validation Framework](./validation.md)
198
199
### Spatial Utilities
200
Additional spatial utility functions for envelope calculation, circle conversion, and bit manipulation operations.
201
202
```java { .api }
203
// Calculate spatial envelope (bounding box) of geometry
204
Optional<Rectangle> envelope = SpatialEnvelopeVisitor.visit(geometry);
205
206
// Convert circle to regular polygon
207
Polygon circlePolygon = CircleUtils.createRegularGeoShapePolygon(circle, 64);
208
209
// Bit manipulation for spatial indexing
210
long interleaved = BitUtil.interleave(xBits, yBits);
211
int deinterleaved = BitUtil.deinterleave(interleavedValue);
212
```
213
214
[Spatial Utilities](./spatial-utilities.md)
215
216
### Geometry Simplification
217
Simplify complex geometries using memory-efficient algorithms while preserving essential geometric features.
218
219
```java { .api }
220
// Use built-in error calculator
221
SimplificationErrorCalculator calculator = SimplificationErrorCalculator.TRIANGLE_AREA;
222
223
// Create streaming simplifier for coordinate processing
224
StreamingGeometrySimplifier<Polygon> streamingSimplifier =
225
new StreamingGeometrySimplifier<>(1000, calculator, null);
226
227
// Process coordinates one by one (memory efficient)
228
streamingSimplifier.addPoint(-74.0, 40.7, Double.NaN);
229
streamingSimplifier.addPoint(-73.9, 40.7, Double.NaN);
230
// ... add more points
231
Polygon simplified = streamingSimplifier.finish();
232
233
// Get error calculator by name
234
SimplificationErrorCalculator heightCalculator =
235
SimplificationErrorCalculator.byName("triangleheight");
236
```
237
238
[Geometry Simplification](./simplification.md)