0
# Geometry Introspection
1

2
Functions for accessing and examining geometric properties, dimensions, coordinate information, and structural details of geometry objects. These functions provide detailed insight into geometry composition and characteristics.
3

4
## Capabilities
5

6
### Dimension and Coordinate Information
7

8
Get dimensional properties and coordinate counts of geometries.
9

10
```python { .api }
11
def get_coordinate_dimension(geometry, **kwargs):
12
    """
13
    Get the coordinate dimension of geometries.
14
    
15
    Parameters:
16
    - geometry: geometry or array of geometries
17
    
18
    Returns:
19
    int or ndarray of coordinate dimensions (2 for 2D, 3 for 3D)
20
    """
21

22
def get_dimensions(geometry, **kwargs):
23
    """
24
    Get the geometric dimension of geometries.
25
    
26
    Parameters:
27
    - geometry: geometry or array of geometries
28
    
29
    Returns:
30
    int or ndarray of dimensions (0=point, 1=line, 2=area)
31
    """
32

33
def get_num_coordinates(geometry, **kwargs):
34
    """
35
    Get the number of coordinate points in geometries.
36
    
37
    Parameters:
38
    - geometry: geometry or array of geometries
39
    
40
    Returns:
41
    int or ndarray of coordinate counts
42
    """
43
```
44

45
**Usage Example:**
46

47
```python
48
import shapely
49

50
# Create various geometries
51
point = shapely.Point(1, 1)
52
line = shapely.LineString([(0, 0), (1, 1), (2, 0)])
53
poly = shapely.Polygon([(0, 0), (2, 0), (2, 2), (0, 2)])
54

55
# Get dimensions
56
print(shapely.get_coordinate_dimension(point))  # 2 (2D coordinates)
57
print(shapely.get_dimensions(point))           # 0 (point)
58
print(shapely.get_dimensions(line))            # 1 (line)
59
print(shapely.get_dimensions(poly))            # 2 (area)
60

61
# Get coordinate counts
62
print(shapely.get_num_coordinates(point))      # 1
63
print(shapely.get_num_coordinates(line))       # 3
64
print(shapely.get_num_coordinates(poly))       # 5 (including closing point)
65
```
66

67
### Geometry Structure Analysis
68

69
Examine the internal structure and composition of complex geometries.
70

71
```python { .api }
72
def get_num_geometries(geometry, **kwargs):
73
    """
74
    Get the number of geometries in multi-geometries or collections.
75
    
76
    Parameters:
77
    - geometry: geometry or array of geometries
78
    
79
    Returns:
80
    int or ndarray of geometry counts
81
    """
82

83
def get_num_interior_rings(geometry, **kwargs):
84
    """
85
    Get the number of interior rings (holes) in polygon geometries.
86
    
87
    Parameters:
88
    - geometry: polygon geometry or array of polygons
89
    
90
    Returns:
91
    int or ndarray of hole counts
92
    """
93

94
def get_num_points(geometry, **kwargs):
95
    """
96
    Get the number of points in linestring or linearring geometries.
97
    
98
    Parameters:
99
    - geometry: linestring/linearring geometry or array
100
    
101
    Returns:
102
    int or ndarray of point counts
103
    """
104
```
105

106
### Geometry Part Extraction
107

108
Extract component parts and rings from complex geometries.
109

110
```python { .api }
111
def get_parts(geometry, return_index=False):
112
    """
113
    Extract individual geometry parts from multi-geometries and collections.
114
    
115
    Parameters:
116
    - geometry: geometry or array of geometries
117
    - return_index: if True, return indices indicating source geometry
118
    
119
    Returns:
120
    ndarray of individual geometries, optionally with indices
121
    """
122

123
def get_rings(geometry, return_index=False):
124
    """
125
    Extract rings (exterior and interior) from polygon geometries.
126
    
127
    Parameters:
128
    - geometry: polygon geometry or array of polygons
129
    - return_index: if True, return indices indicating source geometry
130
    
131
    Returns:
132
    ndarray of LinearRing objects, optionally with indices
133
    """
134
```
135

136
**Usage Example:**
137

138
```python
139
import shapely
140

141
# Create multi-geometry
142
points = [shapely.Point(0, 0), shapely.Point(1, 1), shapely.Point(2, 2)]
143
multipoint = shapely.MultiPoint(points)
144

145
# Extract parts
146
parts = shapely.get_parts(multipoint)
147
print(len(parts))  # 3
148

149
# Create polygon with hole
150
exterior = [(0, 0), (4, 0), (4, 4), (0, 4)]
151
hole = [(1, 1), (3, 1), (3, 3), (1, 3)]
152
poly_with_hole = shapely.Polygon(exterior, [hole])
153

154
# Extract rings
155
rings = shapely.get_rings(poly_with_hole)
156
print(len(rings))  # 2 (exterior + interior)
157
```
158

159
### Type and Identification
160

161
Get geometry type information and identifiers.
162

163
```python { .api }
164
def get_type_id(geometry, **kwargs):
165
    """
166
    Get the geometry type ID of geometries.
167
    
168
    Parameters:
169
    - geometry: geometry or array of geometries
170
    
171
    Returns:
172
    int or ndarray of geometry type IDs (see GeometryType enum)
173
    """
174
```
175

176
### Individual Component Access
177

178
Access specific components of geometries by index.
179

180
```python { .api }
181
def get_geometry(geometry, index, **kwargs):
182
    """
183
    Get a specific geometry from a multi-geometry or collection by index.
184
    
185
    Parameters:
186
    - geometry: multi-geometry or collection
187
    - index: index of geometry to extract
188
    
189
    Returns:
190
    Individual geometry at the specified index
191
    """
192

193
def get_point(geometry, index, **kwargs):
194
    """
195
    Get a specific point from a linestring geometry by index.
196
    
197
    Parameters:
198
    - geometry: linestring or linearring geometry
199
    - index: index of point to extract
200
    
201
    Returns:
202
    Point geometry at the specified index
203
    """
204

205
def get_exterior_ring(geometry, **kwargs):
206
    """
207
    Get the exterior ring of polygon geometries.
208
    
209
    Parameters:
210
    - geometry: polygon geometry or array of polygons
211
    
212
    Returns:
213
    LinearRing representing the exterior boundary
214
    """
215

216
def get_interior_ring(geometry, index, **kwargs):
217
    """
218
    Get a specific interior ring (hole) from polygon geometries.
219
    
220
    Parameters:
221
    - geometry: polygon geometry or array of polygons
222
    - index: index of interior ring to extract
223
    
224
    Returns:
225
    LinearRing representing the interior hole
226
    """
227
```
228

229
### Coordinate Access
230

231
Direct access to coordinate values from point geometries.
232

233
```python { .api }
234
def get_x(point, **kwargs):
235
    """
236
    Get the x-coordinate of point geometries.
237
    
238
    Parameters:
239
    - point: point geometry or array of points
240
    
241
    Returns:
242
    float or ndarray of x-coordinates
243
    """
244

245
def get_y(point, **kwargs):
246
    """
247
    Get the y-coordinate of point geometries.
248
    
249
    Parameters:
250
    - point: point geometry or array of points
251
    
252
    Returns:
253
    float or ndarray of y-coordinates
254
    """
255

256
def get_z(point, **kwargs):
257
    """
258
    Get the z-coordinate of 3D point geometries.
259
    
260
    Parameters:
261
    - point: 3D point geometry or array of 3D points
262
    
263
    Returns:
264
    float or ndarray of z-coordinates
265
    """
266

267
def get_m(point, **kwargs):
268
    """
269
    Get the m-coordinate (measure) of point geometries (requires GEOS 3.12.0+).
270
    
271
    Parameters:
272
    - point: point geometry with m-coordinate
273
    
274
    Returns:
275
    float or ndarray of m-coordinates
276
    """
277
```
278

279
### Precision and SRID
280

281
Access and modify geometry precision and spatial reference information.
282

283
```python { .api }
284
def get_precision(geometry, **kwargs):
285
    """
286
    Get the precision of geometries.
287
    
288
    Parameters:
289
    - geometry: geometry or array of geometries
290
    
291
    Returns:
292
    float or ndarray of precision values
293
    """
294

295
def set_precision(geometry, grid_size, mode='valid_output', **kwargs):
296
    """
297
    Set the precision of geometries.
298
    
299
    Parameters:
300
    - geometry: geometry or array of geometries
301
    - grid_size: precision grid size
302
    - mode: precision mode ('valid_output', 'pointwise', 'keep_collapsed')
303
    
304
    Returns:
305
    Geometry with modified precision
306
    """
307

308
def get_srid(geometry, **kwargs):
309
    """
310
    Get the SRID (Spatial Reference ID) of geometries.
311
    
312
    Parameters:
313
    - geometry: geometry or array of geometries
314
    
315
    Returns:
316
    int or ndarray of SRID values
317
    """
318

319
def set_srid(geometry, srid, **kwargs):
320
    """
321
    Set the SRID (Spatial Reference ID) of geometries.
322
    
323
    Parameters:
324
    - geometry: geometry or array of geometries
325
    - srid: spatial reference identifier
326
    
327
    Returns:
328
    Geometry with modified SRID
329
    """
330
```
331

332
### Force Dimensionality
333

334
Control the dimensionality of geometries.
335

336
```python { .api }
337
def force_2d(geometry, **kwargs):
338
    """
339
    Force geometries to 2D by removing z-coordinates.
340
    
341
    Parameters:
342
    - geometry: geometry or array of geometries
343
    
344
    Returns:
345
    2D geometry with z-coordinates removed
346
    """
347

348
def force_3d(geometry, z=0.0, **kwargs):
349
    """
350
    Force geometries to 3D by adding z-coordinates.
351
    
352
    Parameters:
353
    - geometry: geometry or array of geometries
354
    - z: default z-coordinate value to add
355
    
356
    Returns:
357
    3D geometry with z-coordinates added
358
    """
359
```
360

361
**Usage Example:**
362

363
```python
364
import shapely
365

366
# Create 3D point
367
point_3d = shapely.Point(1, 1, 5)
368

369
# Get coordinates
370
print(shapely.get_x(point_3d))  # 1.0
371
print(shapely.get_y(point_3d))  # 1.0
372
print(shapely.get_z(point_3d))  # 5.0
373

374
# Force to 2D
375
point_2d = shapely.force_2d(point_3d)
376
print(shapely.get_coordinate_dimension(point_2d))  # 2
377

378
# Set precision
379
precise_point = shapely.set_precision(point_3d, 0.1)
380
print(shapely.get_precision(precise_point))  # 0.1
381
```
382

383
## Types
384

385
```python { .api }
386
# Precision mode enumeration
387
class SetPrecisionMode:
388
    valid_output = 0    # Ensure output is valid (default)
389
    pointwise = 1       # Apply precision pointwise
390
    keep_collapsed = 2  # Keep collapsed geometries
391
```