0
# Core Geometry Types
1

2
The Elasticsearch Geo library provides fundamental geometric shapes for representing spatial data. All geometry types implement the base `Geometry` interface and support both 2D and 3D coordinates with optional altitude values.
3

4
## Capabilities
5

6
### Point Geometry
7
Represents a single point in space with longitude/latitude coordinates and optional altitude.
8

9
```java { .api }
10
/**
11
 * Creates a 2D point with longitude and latitude coordinates
12
 * @param x longitude in decimal degrees
13
 * @param y latitude in decimal degrees
14
 */
15
public Point(double x, double y)
16

17
/**
18
 * Creates a 3D point with longitude, latitude, and altitude
19
 * @param x longitude in decimal degrees  
20
 * @param y latitude in decimal degrees
21
 * @param z altitude in meters
22
 */
23
public Point(double x, double y, double z)
24

25
// Coordinate getters
26
public double getX() // longitude
27
public double getY() // latitude  
28
public double getZ() // altitude
29
public double getLon() // alias for getX()
30
public double getLat() // alias for getY()
31
public double getAlt() // alias for getZ()
32

33
// Empty point constant
34
public static final Point EMPTY
35
```
36

37
### Circle Geometry
38
Represents a circular area defined by a center point and radius in meters.
39

40
```java { .api }
41
/**
42
 * Creates a 2D circle with center coordinates and radius
43
 * @param x center longitude in decimal degrees
44
 * @param y center latitude in decimal degrees  
45
 * @param radiusMeters radius in meters (must be positive)
46
 * @throws IllegalArgumentException if radius is negative
47
 */
48
public Circle(double x, double y, double radiusMeters)
49

50
/**
51
 * Creates a 3D circle with center coordinates, altitude, and radius
52
 * @param x center longitude in decimal degrees
53
 * @param y center latitude in decimal degrees
54
 * @param z center altitude in meters  
55
 * @param radiusMeters radius in meters (must be positive)
56
 */
57
public Circle(double x, double y, double z, double radiusMeters)
58

59
// Center coordinate getters
60
public double getX() // center longitude
61
public double getY() // center latitude
62
public double getZ() // center altitude
63
public double getLon() // alias for getX()
64
public double getLat() // alias for getY() 
65
public double getAlt() // alias for getZ()
66

67
// Radius getter
68
public double getRadiusMeters()
69

70
// Empty circle constant
71
public static final Circle EMPTY
72
```
73

74
### Rectangle Geometry
75
Represents a rectangular bounding box defined by minimum and maximum coordinates.
76

77
```java { .api }
78
/**
79
 * Creates a 2D rectangle with coordinate bounds
80
 * @param minX minimum longitude
81
 * @param maxX maximum longitude
82
 * @param maxY maximum latitude
83
 * @param minY minimum latitude
84
 * @throws IllegalArgumentException if maxY < minY
85
 */
86
public Rectangle(double minX, double maxX, double maxY, double minY)
87

88
/**
89
 * Creates a 3D rectangle with coordinate and altitude bounds
90
 * @param minX minimum longitude
91
 * @param maxX maximum longitude  
92
 * @param maxY maximum latitude
93
 * @param minY minimum latitude
94
 * @param minZ minimum altitude
95
 * @param maxZ maximum altitude
96
 * @throws IllegalArgumentException if maxY < minY or only one Z value specified
97
 */
98
public Rectangle(double minX, double maxX, double maxY, double minY, double minZ, double maxZ)
99

100
// Boundary getters
101
public double getMinX() // minimum longitude
102
public double getMaxX() // maximum longitude
103
public double getMinY() // minimum latitude
104
public double getMaxY() // maximum latitude
105
public double getMinZ() // minimum altitude
106
public double getMaxZ() // maximum altitude
107

108
// Alternative boundary getters
109
public double getMinLon() // alias for getMinX()
110
public double getMaxLon() // alias for getMaxX()
111
public double getMinLat() // alias for getMinY()
112
public double getMaxLat() // alias for getMaxY()
113
public double getMinAlt() // alias for getMinZ()
114
public double getMaxAlt() // alias for getMaxZ()
115

116
// Empty rectangle constant
117
public static final Rectangle EMPTY
118
```
119

120
### Line Geometry
121
Represents a line string composed of multiple connected points.
122

123
```java { .api }
124
/**
125
 * Creates a 2D line from coordinate arrays
126
 * @param x array of longitude coordinates
127
 * @param y array of latitude coordinates
128
 * @throws IllegalArgumentException if arrays are null, different lengths, or less than 2 points
129
 */
130
public Line(double[] x, double[] y)
131

132
/**
133
 * Creates a 3D line from coordinate arrays
134
 * @param x array of longitude coordinates
135
 * @param y array of latitude coordinates
136
 * @param z array of altitude coordinates (can be null)
137
 * @throws IllegalArgumentException if coordinate arrays have different lengths
138
 */
139
public Line(double[] x, double[] y, double[] z)
140

141
// Point access methods
142
public int length() // number of points in line
143
public double getX(int i) // longitude of point at index i
144
public double getY(int i) // latitude of point at index i
145
public double getZ(int i) // altitude of point at index i (NaN if no Z values)
146
public double getLon(int i) // alias for getX(int)
147
public double getLat(int i) // alias for getY(int)
148
public double getAlt(int i) // alias for getZ(int)
149

150
// Array getters (returns cloned arrays)
151
public double[] getX() // array of longitude coordinates
152
public double[] getY() // array of latitude coordinates  
153
public double[] getZ() // array of altitude coordinates (null if no Z values)
154
public double[] getLons() // alias for getX()
155
public double[] getLats() // alias for getY()
156
public double[] getAlts() // alias for getZ()
157

158
// Empty line constant
159
public static final Line EMPTY
160
```
161

162
### LinearRing Geometry
163
Represents a closed line where the first and last points are identical, used as polygon boundaries.
164

165
```java { .api }
166
/**
167
 * Creates a 2D linear ring from coordinate arrays
168
 * @param x array of longitude coordinates (first and last must be equal)
169
 * @param y array of latitude coordinates (first and last must be equal)
170
 * @throws IllegalArgumentException if ring is not closed or has less than 2 points
171
 */
172
public LinearRing(double[] x, double[] y)
173

174
/**
175
 * Creates a 3D linear ring from coordinate arrays  
176
 * @param x array of longitude coordinates (first and last must be equal)
177
 * @param y array of latitude coordinates (first and last must be equal)
178
 * @param z array of altitude coordinates (first and last must be equal, can be null)
179
 * @throws IllegalArgumentException if ring is not closed
180
 */
181
public LinearRing(double[] x, double[] y, double[] z)
182

183
// Inherits all methods from Line class
184
// Additional validation ensures ring closure
185

186
// Empty linear ring constant
187
public static final LinearRing EMPTY
188
```
189

190
### Polygon Geometry  
191
Represents a polygon with an outer ring and optional holes (inner rings).
192

193
```java { .api }
194
/**
195
 * Creates a polygon with only an outer boundary
196
 * @param polygon outer boundary as LinearRing
197
 */
198
public Polygon(LinearRing polygon)
199

200
/**
201
 * Creates a polygon with outer boundary and holes
202
 * @param polygon outer boundary as LinearRing
203
 * @param holes list of holes as LinearRings (cannot be null)
204
 * @throws IllegalArgumentException if holes is null or rings have different dimensions
205
 */
206
public Polygon(LinearRing polygon, List<LinearRing> holes)
207

208
// Structure access methods
209
public LinearRing getPolygon() // gets outer ring
210
public int getNumberOfHoles() // number of holes
211
public LinearRing getHole(int i) // gets hole by index
212
// @throws IllegalArgumentException if index is out of bounds
213

214
// Empty polygon constant
215
public static final Polygon EMPTY
216
```
217

218
## Common Geometry Interface Methods
219

220
All geometry types implement these base interface methods:
221

222
```java { .api }
223
/**
224
 * Returns the shape type of this geometry
225
 * @return ShapeType enum value (POINT, CIRCLE, POLYGON, etc.)
226
 */
227
ShapeType type()
228

229
/**
230
 * Accepts a visitor for type-safe processing
231
 * @param visitor the geometry visitor
232
 * @return result from visitor processing
233
 * @throws E exception type from visitor
234
 */
235
<T, E extends Exception> T visit(GeometryVisitor<T, E> visitor) throws E
236

237
/**
238
 * Checks if geometry represents an empty/null geometry
239
 * @return true if geometry is empty
240
 */
241
boolean isEmpty()
242

243
/**
244
 * Checks if geometry has altitude/Z dimension
245
 * @return true if geometry includes Z coordinates
246
 */
247
boolean hasZ()
248

249
/**
250
 * Alias for hasZ() method
251
 * @return true if geometry includes altitude values
252
 */
253
boolean hasAlt()
254
```
255

256
## Usage Examples
257

258
```java
259
import org.elasticsearch.geometry.*;
260

261
// Create various geometry types
262
Point point = new Point(-73.935242, 40.730610);
263
Circle circle = new Circle(-73.935242, 40.730610, 1000.0);
264

265
// Create polygon from coordinate arrays
266
double[] lons = {-74.0, -73.9, -73.9, -74.0, -74.0};
267
double[] lats = {40.7, 40.7, 40.8, 40.8, 40.7};
268
LinearRing ring = new LinearRing(lons, lats);
269
Polygon polygon = new Polygon(ring);
270

271
// Check geometry properties
272
boolean hasAltitude = point.hasZ(); // false for 2D point
273
ShapeType type = circle.type(); // ShapeType.CIRCLE
274
boolean empty = polygon.isEmpty(); // false
275

276
// Access coordinates
277
double lat = point.getLat(); // 40.730610
278
double radius = circle.getRadiusMeters(); // 1000.0
279
int vertices = ring.length(); // 5
280
```