0
# Spatial Predicates
1

2
Boolean tests for spatial relationships between geometries and properties of individual geometries. These functions support both individual geometry objects and arrays of geometries for vectorized operations.
3

4
## Capabilities
5

6
### Binary Spatial Predicates
7

8
Test spatial relationships between two geometries.
9

10
```python { .api }
11
def contains(a, b, **kwargs) -> bool:
12
    """
13
    Test if geometry A contains geometry B.
14
    
15
    Parameters:
16
    - a: first geometry or array of geometries
17
    - b: second geometry or array of geometries
18
    
19
    Returns:
20
    bool or ndarray of bool
21
    """
22

23
def intersects(a, b, **kwargs) -> bool:
24
    """
25
    Test if geometry A intersects geometry B.
26
    
27
    Parameters:
28
    - a: first geometry or array of geometries
29
    - b: second geometry or array of geometries
30
    
31
    Returns:
32
    bool or ndarray of bool
33
    """
34

35
def within(a, b, **kwargs) -> bool:
36
    """
37
    Test if geometry A is within geometry B.
38
    
39
    Parameters:
40
    - a: first geometry or array of geometries
41
    - b: second geometry or array of geometries
42
    
43
    Returns:
44
    bool or ndarray of bool
45
    """
46

47
def touches(a, b, **kwargs) -> bool:
48
    """
49
    Test if geometry A touches geometry B.
50
    
51
    Parameters:
52
    - a: first geometry or array of geometries
53
    - b: second geometry or array of geometries
54
    
55
    Returns:
56
    bool or ndarray of bool
57
    """
58

59
def crosses(a, b, **kwargs) -> bool:
60
    """
61
    Test if geometry A crosses geometry B.
62
    
63
    Parameters:
64
    - a: first geometry or array of geometries
65
    - b: second geometry or array of geometries
66
    
67
    Returns:
68
    bool or ndarray of bool
69
    """
70

71
def overlaps(a, b, **kwargs) -> bool:
72
    """
73
    Test if geometry A overlaps geometry B.
74
    
75
    Parameters:
76
    - a: first geometry or array of geometries
77
    - b: second geometry or array of geometries
78
    
79
    Returns:
80
    bool or ndarray of bool
81
    """
82

83
def disjoint(a, b, **kwargs) -> bool:
84
    """
85
    Test if geometry A is disjoint from geometry B.
86
    
87
    Parameters:
88
    - a: first geometry or array of geometries
89
    - b: second geometry or array of geometries
90
    
91
    Returns:
92
    bool or ndarray of bool
93
    """
94

95
def equals(a, b, **kwargs) -> bool:
96
    """
97
    Test if geometry A equals geometry B spatially.
98
    
99
    Parameters:
100
    - a: first geometry or array of geometries
101
    - b: second geometry or array of geometries
102
    
103
    Returns:
104
    bool or ndarray of bool
105
    """
106
```
107

108
**Usage Example:**
109

110
```python
111
import shapely
112
from shapely.geometry import Point, Polygon
113

114
# Individual geometries
115
point = Point(1, 1)
116
polygon = Polygon([(0, 0), (2, 0), (2, 2), (0, 2)])
117

118
print(polygon.contains(point))  # True
119
print(point.within(polygon))    # True
120
print(polygon.intersects(point)) # True
121

122
# Array operations
123
points = shapely.points([(1, 1), (3, 3), (0.5, 0.5)])
124
contains_results = shapely.contains(polygon, points)
125
print(contains_results)  # [True, False, True]
126
```
127

128
### Advanced Binary Predicates
129

130
More specialized spatial relationship tests.
131

132
```python { .api }
133
def contains_properly(a, b, **kwargs) -> bool:
134
    """
135
    Test if geometry A properly contains geometry B.
136
    B is properly contained if it is contained and does not touch the boundary of A.
137
    
138
    Parameters:
139
    - a: first geometry or array of geometries
140
    - b: second geometry or array of geometries
141
    
142
    Returns:
143
    bool or ndarray of bool
144
    """
145

146
def covers(a, b, **kwargs) -> bool:
147
    """
148
    Test if geometry A covers geometry B.
149
    
150
    Parameters:
151
    - a: first geometry or array of geometries  
152
    - b: second geometry or array of geometries
153
    
154
    Returns:
155
    bool or ndarray of bool
156
    """
157

158
def covered_by(a, b, **kwargs) -> bool:
159
    """
160
    Test if geometry A is covered by geometry B.
161
    
162
    Parameters:
163
    - a: first geometry or array of geometries
164
    - b: second geometry or array of geometries
165
    
166
    Returns:
167
    bool or ndarray of bool
168
    """
169

170
def equals_exact(a, b, tolerance=0.0, *, normalize=False, **kwargs) -> bool:
171
    """
172
    Test if geometry A equals geometry B exactly within tolerance.
173
    
174
    Parameters:
175
    - a: first geometry or array of geometries
176
    - b: second geometry or array of geometries
177
    - tolerance: coordinate tolerance for comparison
178
    - normalize: normalize geometries before comparison
179
    
180
    Returns:
181
    bool or ndarray of bool
182
    """
183

184
def dwithin(a, b, distance, **kwargs) -> bool:
185
    """
186
    Test if geometry A is within distance of geometry B.
187
    
188
    Parameters:
189
    - a: first geometry or array of geometries
190
    - b: second geometry or array of geometries
191
    - distance: maximum distance
192
    
193
    Returns:
194
    bool or ndarray of bool
195
    """
196
```
197

198
### Point-in-Geometry Tests
199

200
Efficient tests for point containment without creating Point objects.
201

202
```python { .api }
203
def contains_xy(geometry, x, y=None, **kwargs) -> bool:
204
    """
205
    Test if geometry contains points at coordinates (x, y).
206
    
207
    Parameters:
208
    - geometry: geometry or array of geometries
209
    - x: x-coordinate(s) or array of (x, y) coordinates
210
    - y: y-coordinate(s) (optional if x contains both coordinates)
211
    
212
    Returns:
213
    bool or ndarray of bool
214
    """
215

216
def intersects_xy(geometry, x, y=None, **kwargs) -> bool:
217
    """
218
    Test if geometry intersects points at coordinates (x, y).
219
    
220
    Parameters:
221
    - geometry: geometry or array of geometries
222
    - x: x-coordinate(s) or array of (x, y) coordinates
223
    - y: y-coordinate(s) (optional if x contains both coordinates)
224
    
225
    Returns:
226
    bool or ndarray of bool
227
    """
228
```
229

230
**Usage Example:**
231

232
```python
233
import shapely
234

235
# Create polygon
236
polygon = shapely.box(0, 0, 2, 2)
237

238
# Test multiple points efficiently
239
x_coords = [1, 3, 0.5]
240
y_coords = [1, 3, 0.5]
241
results = shapely.contains_xy(polygon, x_coords, y_coords)
242
print(results)  # [True, False, True]
243

244
# Alternative syntax with coordinate pairs
245
coords = [(1, 1), (3, 3), (0.5, 0.5)]
246
results = shapely.contains_xy(polygon, coords)
247
```
248

249
### Geometry Property Tests
250

251
Test properties of individual geometries.
252

253
```python { .api }
254
def is_empty(geometry, **kwargs) -> bool:
255
    """Test if geometry is empty."""
256

257
def is_valid(geometry, **kwargs) -> bool:
258
    """Test if geometry is topologically valid."""
259

260
def is_simple(geometry, **kwargs) -> bool:
261
    """Test if geometry is simple (no self-intersections)."""
262

263
def is_closed(geometry, **kwargs) -> bool:
264
    """Test if linestring geometry is closed."""
265

266
def is_ring(geometry, **kwargs) -> bool:
267
    """Test if linestring is a valid ring (closed and simple)."""
268

269
def is_ccw(geometry, **kwargs) -> bool:
270
    """Test if ring is oriented counter-clockwise."""
271

272
def has_z(geometry, **kwargs) -> bool:
273
    """Test if geometry has Z (3D) coordinates."""
274

275
def has_m(geometry, **kwargs) -> bool:
276
    """Test if geometry has M (measure) coordinates. Requires GEOS 3.12.0+."""
277
```
278

279
**Usage Example:**
280

281
```python
282
import shapely
283
from shapely.geometry import LineString, Polygon
284

285
# Test line properties
286
line = LineString([(0, 0), (1, 1), (2, 0)])
287
print(shapely.is_simple(line))  # True
288
print(shapely.is_closed(line))  # False
289

290
# Test polygon validity
291
valid_poly = Polygon([(0, 0), (1, 0), (1, 1), (0, 1)])
292
invalid_poly = Polygon([(0, 0), (1, 1), (1, 0), (0, 1)])  # Self-intersecting
293
print(shapely.is_valid(valid_poly))    # True
294
print(shapely.is_valid(invalid_poly))  # False
295
```
296

297
### Object Type Tests
298

299
Test object types and states.
300

301
```python { .api }
302
def is_geometry(obj, **kwargs) -> bool:
303
    """Test if object is a geometry."""
304

305
def is_missing(obj, **kwargs) -> bool:
306
    """Test if object is None/missing."""
307

308
def is_valid_input(obj, **kwargs) -> bool:
309
    """Test if object is valid geometry input (geometry or None)."""
310

311
def is_prepared(geometry, **kwargs) -> bool:
312
    """Test if geometry is prepared for efficient operations."""
313
```
314

315
### Validity Analysis
316

317
Get detailed information about geometry validity.
318

319
```python { .api }
320
def is_valid_reason(geometry, **kwargs) -> str:
321
    """
322
    Get reason why geometry is invalid.
323
    
324
    Parameters:
325
    - geometry: geometry or array of geometries
326
    
327
    Returns:
328
    str or ndarray of str: reason for invalidity, or "Valid Geometry" if valid
329
    """
330
```
331

332
**Usage Example:**
333

334
```python
335
import shapely
336
from shapely.geometry import Polygon
337

338
# Create invalid polygon (self-intersecting)
339
invalid_poly = Polygon([(0, 0), (2, 2), (2, 0), (0, 2)])
340

341
print(shapely.is_valid(invalid_poly))  # False
342
print(shapely.is_valid_reason(invalid_poly))  # "Self-intersection[1 1]"
343
```
344

345
### Topological Relations
346

347
Get detailed topological relationship information.
348

349
```python { .api }
350
def relate(a, b, **kwargs) -> str:
351
    """
352
    Get DE-9IM intersection matrix string describing relationship between A and B.
353
    
354
    Parameters:
355
    - a: first geometry or array of geometries
356
    - b: second geometry or array of geometries
357
    
358
    Returns:
359
    str or ndarray of str: DE-9IM matrix string
360
    """
361

362
def relate_pattern(a, b, pattern, **kwargs) -> bool:
363
    """
364
    Test if relationship between A and B matches DE-9IM pattern.
365
    
366
    Parameters:
367
    - a: first geometry or array of geometries
368
    - b: second geometry or array of geometries
369
    - pattern: DE-9IM pattern string to match
370
    
371
    Returns:
372
    bool or ndarray of bool
373
    """
374
```
375

376
**Usage Example:**
377

378
```python
379
import shapely
380
from shapely.geometry import Point, Polygon
381

382
point = Point(1, 1)
383
polygon = Polygon([(0, 0), (2, 0), (2, 2), (0, 2)])
384

385
# Get full topological relationship
386
matrix = shapely.relate(point, polygon)
387
print(matrix)  # "0FFFFF212"
388

389
# Test specific pattern
390
is_inside = shapely.relate_pattern(point, polygon, "0FFFFF212")
391
print(is_inside)  # True
392
```