0
# Multi-Geometry Collections
1

2
The Elasticsearch Geo library provides collection classes for grouping multiple geometries of the same or different types. These collections enable efficient representation of complex spatial datasets and support the visitor pattern for type-safe processing.
3

4
## Capabilities
5

6
### GeometryCollection Base Class
7
Generic collection for any geometry types with common collection operations.
8

9
```java { .api }
10
/**
11
 * Creates a geometry collection from a list of geometries
12
 * @param geometries list of geometries to include in collection
13
 */
14
public GeometryCollection(List<T> geometries)
15

16
/**
17
 * Gets the number of geometries in the collection
18
 * @return number of geometries
19
 */
20
public int size()
21

22
/**
23
 * Gets a geometry by index
24
 * @param i index of geometry to retrieve
25
 * @return geometry at specified index
26
 * @throws IndexOutOfBoundsException if index is invalid
27
 */
28
public T get(int i)
29

30
/**
31
 * Checks if collection is empty
32
 * @return true if collection contains no geometries
33
 */
34
public boolean isEmpty()
35

36
// Empty collection constant
37
public static final GeometryCollection EMPTY
38
```
39

40
### MultiPoint Collections
41
Collection specifically for Point geometries with optimized access patterns.
42

43
```java { .api }
44
/**
45
 * Creates a multi-point collection from a list of points
46
 * @param points list of Point geometries
47
 */
48
public MultiPoint(List<Point> points)
49

50
// Inherits all methods from GeometryCollection<Point>
51
// Additional type safety for Point-specific operations
52

53
// Empty multi-point constant  
54
public static final MultiPoint EMPTY
55

56
// Example usage:
57
List<Point> points = Arrays.asList(
58
    new Point(-73.935242, 40.730610),
59
    new Point(-73.945242, 40.740610), 
60
    new Point(-73.925242, 40.720610)
61
);
62
MultiPoint multiPoint = new MultiPoint(points);
63

64
// Access individual points
65
Point firstPoint = multiPoint.get(0);
66
int pointCount = multiPoint.size();
67
```
68

69
### MultiLine Collections  
70
Collection for Line geometries representing multiple disconnected line strings.
71

72
```java { .api }
73
/**
74
 * Creates a multi-line collection from a list of lines
75
 * @param lines list of Line geometries
76
 */
77
public MultiLine(List<Line> lines)
78

79
// Inherits all methods from GeometryCollection<Line>
80
// Type-safe access to Line-specific functionality
81

82
// Empty multi-line constant
83
public static final MultiLine EMPTY
84

85
// Example usage:
86
double[] lons1 = {-74.0, -73.9, -73.8};
87
double[] lats1 = {40.7, 40.75, 40.8};
88
Line line1 = new Line(lons1, lats1);
89

90
double[] lons2 = {-73.7, -73.6};  
91
double[] lats2 = {40.6, 40.65};
92
Line line2 = new Line(lons2, lats2);
93

94
List<Line> lines = Arrays.asList(line1, line2);
95
MultiLine multiLine = new MultiLine(lines);
96

97
// Access individual lines
98
Line firstLine = multiLine.get(0);
99
int lineCount = multiLine.size();
100
```
101

102
### MultiPolygon Collections
103
Collection for Polygon geometries representing multiple disconnected polygonal areas.
104

105
```java { .api }
106
/**
107
 * Creates a multi-polygon collection from a list of polygons
108
 * @param polygons list of Polygon geometries  
109
 */
110
public MultiPolygon(List<Polygon> polygons)
111

112
// Inherits all methods from GeometryCollection<Polygon>
113
// Type-safe access to Polygon-specific functionality
114

115
// Empty multi-polygon constant
116
public static final MultiPolygon EMPTY
117

118
// Example usage:
119
// Create first polygon
120
double[] lons1 = {-74.0, -73.9, -73.9, -74.0, -74.0};
121
double[] lats1 = {40.7, 40.7, 40.8, 40.8, 40.7};
122
LinearRing ring1 = new LinearRing(lons1, lats1);
123
Polygon polygon1 = new Polygon(ring1);
124

125
// Create second polygon
126
double[] lons2 = {-73.8, -73.7, -73.7, -73.8, -73.8};
127
double[] lats2 = {40.6, 40.6, 40.65, 40.65, 40.6};
128
LinearRing ring2 = new LinearRing(lons2, lats2);
129
Polygon polygon2 = new Polygon(ring2);
130

131
List<Polygon> polygons = Arrays.asList(polygon1, polygon2);
132
MultiPolygon multiPolygon = new MultiPolygon(polygons);
133

134
// Access individual polygons
135
Polygon firstPolygon = multiPolygon.get(0);
136
int polygonCount = multiPolygon.size();
137
```
138

139
### Generic Geometry Collections
140
Collections that can hold mixed geometry types for complex spatial datasets.
141

142
```java { .api }
143
// Mixed geometry collection
144
List<Geometry> mixedGeometries = Arrays.asList(
145
    new Point(-73.935242, 40.730610),
146
    new Circle(-73.945242, 40.740610, 500.0),
147
    polygon1,
148
    multiPoint
149
);
150
GeometryCollection<Geometry> mixed = new GeometryCollection<>(mixedGeometries);
151

152
// Type-safe access requires visitor pattern or type checking
153
for (int i = 0; i < mixed.size(); i++) {
154
    Geometry geom = mixed.get(i);
155
    ShapeType type = geom.type();
156
    
157
    switch (type) {
158
        case POINT:
159
            Point p = (Point) geom;
160
            // Handle point-specific logic
161
            break;
162
        case CIRCLE:
163
            Circle c = (Circle) geom;
164
            // Handle circle-specific logic  
165
            break;
166
        // ... handle other types
167
    }
168
}
169
```
170

171
## Collection Properties and Behavior
172

173
### Dimensional Consistency
174
Collections maintain dimensional consistency where applicable:
175

176
```java { .api }
177
// All geometries in collection should have same Z dimension
178
Point point2d = new Point(-73.935242, 40.730610);
179
Point point3d = new Point(-73.945242, 40.740610, 150.0);
180

181
// Mixed dimensions - generally allowed but may cause issues in some operations
182
List<Point> mixedDimensionPoints = Arrays.asList(point2d, point3d);
183
MultiPoint mixed = new MultiPoint(mixedDimensionPoints);
184

185
// Check if collection has Z dimension (true if any geometry has Z)
186
boolean hasZ = mixed.hasZ();
187
```
188

189
### Empty Collections
190
All collection types support empty states:
191

192
```java { .api }
193
// Create empty collections
194
MultiPoint emptyPoints = MultiPoint.EMPTY;
195
MultiLine emptyLines = MultiLine.EMPTY;
196
MultiPolygon emptyPolygons = MultiPolygon.EMPTY;
197
GeometryCollection<Geometry> emptyCollection = GeometryCollection.EMPTY;
198

199
// Check if collection is empty
200
boolean isEmpty = emptyPoints.isEmpty(); // true
201
int size = emptyPoints.size(); // 0
202

203
// Empty collections are safe to process
204
ShapeType type = emptyPoints.type(); // ShapeType.MULTIPOINT
205
```
206

207
### Visitor Pattern Support
208
Collections fully support the visitor pattern for type-safe processing:
209

210
```java { .api }
211
// Example visitor for calculating total area of all geometries
212
public class CollectionAreaCalculator implements GeometryVisitor<Double, RuntimeException> {
213
    
214
    @Override
215
    public Double visit(MultiPolygon multiPolygon) {
216
        double totalArea = 0.0;
217
        for (int i = 0; i < multiPolygon.size(); i++) {
218
            Polygon polygon = multiPolygon.get(i);
219
            // Calculate polygon area (simplified)
220
            totalArea += calculatePolygonArea(polygon);
221
        }
222
        return totalArea;
223
    }
224
    
225
    @Override
226
    public Double visit(GeometryCollection<?> collection) {
227
        double totalArea = 0.0;
228
        for (int i = 0; i < collection.size(); i++) {
229
            Geometry geometry = collection.get(i);
230
            totalArea += geometry.visit(this);
231
        }
232
        return totalArea;
233
    }
234
    
235
    // ... implement other visit methods
236
}
237

238
// Use visitor with collections
239
CollectionAreaCalculator calculator = new CollectionAreaCalculator();
240
Double totalArea = multiPolygon.visit(calculator);
241
```
242

243
## Usage Examples
244

245
```java
246
import org.elasticsearch.geometry.*;
247
import java.util.Arrays;
248
import java.util.List;
249

250
// Create multiple points
251
List<Point> points = Arrays.asList(
252
    new Point(-73.935242, 40.730610),
253
    new Point(-73.945242, 40.740610),
254
    new Point(-73.925242, 40.720610)
255
);
256
MultiPoint multiPoint = new MultiPoint(points);
257

258
// Access collection properties
259
int pointCount = multiPoint.size(); // 3
260
Point firstPoint = multiPoint.get(0);
261
boolean empty = multiPoint.isEmpty(); // false
262

263
// Create mixed geometry collection  
264
List<Geometry> geometries = Arrays.asList(
265
    new Point(-73.935242, 40.730610),
266
    new Circle(-73.945242, 40.740610, 1000.0),
267
    multiPoint
268
);
269
GeometryCollection<Geometry> collection = new GeometryCollection<>(geometries);
270

271
// Iterate through collection
272
for (int i = 0; i < collection.size(); i++) {
273
    Geometry geom = collection.get(i);
274
    System.out.println("Geometry " + i + " type: " + geom.type());
275
}
276

277
// Use visitor pattern for processing
278
SomeGeometryVisitor visitor = new SomeGeometryVisitor();
279
Object result = collection.visit(visitor);
280
```