0
# Boolean Spatial Operations
1

2
Functions for testing spatial relationships between geometric features, including intersections, containment, topology validation, and directional analysis. These operations return boolean values based on geometric relationships.
3

4
## Capabilities
5

6
### Point-in-Polygon Testing
7

8
Determine if a point is inside a polygon.
9

10
```typescript { .api }
11
/**
12
 * Takes a Point and a Polygon or MultiPolygon and determines if the point
13
 * resides inside the polygon. The polygon can be convex or concave.
14
 */
15
function booleanPointInPolygon(
16
  point: Coord,
17
  polygon: Feature<Polygon | MultiPolygon> | Polygon | MultiPolygon,
18
  options?: { ignoreBoundary?: boolean }
19
): boolean;
20
```
21

22
**Usage Examples:**
23

24
```typescript
25
import { booleanPointInPolygon, point, polygon } from "@turf/turf";
26

27
const pt = point([-77, 44]);
28
const poly = polygon([[
29
  [-81, 41], [-81, 47], [-72, 47], [-72, 41], [-81, 41]
30
]]);
31

32
const inside = booleanPointInPolygon(pt, poly);
33
console.log(`Point is inside polygon: ${inside}`); // true
34

35
// Test point on boundary
36
const boundaryPt = point([-81, 44]);
37
const onBoundary = booleanPointInPolygon(boundaryPt, poly);
38
const ignoreBoundary = booleanPointInPolygon(boundaryPt, poly, { ignoreBoundary: true });
39

40
console.log(`On boundary (default): ${onBoundary}`); // true
41
console.log(`On boundary (ignored): ${ignoreBoundary}`); // false
42
```
43

44
### Point-on-Line Testing
45

46
Determine if a point lies on a line.
47

48
```typescript { .api }
49
/**
50
 * Returns true if a point is on a line. Accepts a optional parameter to ignore the
51
 * start and end vertices of the linestring.
52
 */
53
function booleanPointOnLine(
54
  pt: Coord,
55
  line: Feature<LineString> | LineString,
56
  options?: { ignoreEndVertices?: boolean }
57
): boolean;
58
```
59

60
**Usage Examples:**
61

62
```typescript
63
import { booleanPointOnLine, point, lineString } from "@turf/turf";
64

65
const line = lineString([[-1, -1], [1, 1], [1.5, 2.2]]);
66
const pt1 = point([0, 0]); // On line
67
const pt2 = point([1.5, 2.2]); // End vertex
68
const pt3 = point([1, 2]); // Not on line
69

70
console.log(`Point 1 on line: ${booleanPointOnLine(pt1, line)}`); // true
71
console.log(`Point 2 on line: ${booleanPointOnLine(pt2, line)}`); // true
72
console.log(`Point 2 on line (ignore ends): ${booleanPointOnLine(pt2, line, { ignoreEndVertices: true })}`); // false
73
console.log(`Point 3 on line: ${booleanPointOnLine(pt3, line)}`); // false
74
```
75

76
### Containment Testing
77

78
Determine if one feature completely contains another.
79

80
```typescript { .api }
81
/**
82
 * Boolean-contains returns True if the first geometry completely contains the second geometry.
83
 */
84
function booleanContains(feature1: Feature<any>, feature2: Feature<any>): boolean;
85

86
/**
87
 * Boolean-within returns True if the first geometry is completely within the second geometry.
88
 */
89
function booleanWithin(feature1: Feature<any>, feature2: Feature<any>): boolean;
90
```
91

92
**Usage Examples:**
93

94
```typescript
95
import { booleanContains, booleanWithin, polygon, point } from "@turf/turf";
96

97
const outerPoly = polygon([[
98
  [0, 0], [0, 10], [10, 10], [10, 0], [0, 0]
99
]]);
100

101
const innerPoly = polygon([[
102
  [2, 2], [2, 8], [8, 8], [8, 2], [2, 2]
103
]]);
104

105
const pt = point([5, 5]);
106

107
console.log(`Outer contains inner: ${booleanContains(outerPoly, innerPoly)}`); // true
108
console.log(`Inner within outer: ${booleanWithin(innerPoly, outerPoly)}`); // true
109
console.log(`Outer contains point: ${booleanContains(outerPoly, pt)}`); // true
110
```
111

112
### Intersection Testing
113

114
Determine if two features intersect.
115

116
```typescript { .api }
117
/**
118
 * Boolean-intersects returns true if the intersection of the two geometries
119
 * is not empty.
120
 */
121
function booleanIntersects(feature1: Feature<any>, feature2: Feature<any>): boolean;
122

123
/**
124
 * Boolean-disjoint returns true if the intersection of the two geometries is empty.
125
 */
126
function booleanDisjoint(feature1: Feature<any>, feature2: Feature<any>): boolean;
127
```
128

129
**Usage Examples:**
130

131
```typescript
132
import { booleanIntersects, booleanDisjoint, polygon, lineString } from "@turf/turf";
133

134
const poly1 = polygon([[[0, 0], [0, 5], [5, 5], [5, 0], [0, 0]]]);
135
const poly2 = polygon([[[3, 3], [3, 8], [8, 8], [8, 3], [3, 3]]]);
136
const poly3 = polygon([[[10, 10], [10, 15], [15, 15], [15, 10], [10, 10]]]);
137

138
console.log(`Poly1 intersects Poly2: ${booleanIntersects(poly1, poly2)}`); // true (overlapping)
139
console.log(`Poly1 intersects Poly3: ${booleanIntersects(poly1, poly3)}`); // false (separate)
140
console.log(`Poly1 disjoint from Poly3: ${booleanDisjoint(poly1, poly3)}`); // true (separate)
141
```
142

143
### Overlap Testing
144

145
Determine if two features overlap.
146

147
```typescript { .api }
148
/**
149
 * Boolean-overlap returns True if the intersection of the two geometries
150
 * is of the same dimension but is not equal to either of the given geometries.
151
 */
152
function booleanOverlap(feature1: Feature<any>, feature2: Feature<any>): boolean;
153
```
154

155
**Usage Examples:**
156

157
```typescript
158
import { booleanOverlap, polygon } from "@turf/turf";
159

160
const poly1 = polygon([[[0, 0], [0, 5], [5, 5], [5, 0], [0, 0]]]);
161
const poly2 = polygon([[[3, 3], [3, 8], [8, 8], [8, 3], [3, 3]]]);
162
const poly3 = polygon([[[1, 1], [1, 4], [4, 4], [4, 1], [1, 1]]]);
163

164
console.log(`Poly1 overlaps Poly2: ${booleanOverlap(poly1, poly2)}`); // true (partial overlap)
165
console.log(`Poly1 overlaps Poly3: ${booleanOverlap(poly1, poly3)}`); // false (contains, not overlap)
166
```
167

168
### Topology Testing
169

170
Test various topological relationships.
171

172
```typescript { .api }
173
/**
174
 * Boolean-crosses returns True if the intersection results in a geometry whose
175
 * dimension is one less than the maximum dimension of the two source Geometries.
176
 */
177
function booleanCrosses(feature1: Feature<any>, feature2: Feature<any>): boolean;
178

179
/**
180
 * Boolean-touches returns True if the geometries have at least one point in common,
181
 * but their interiors do not intersect.
182
 */
183
function booleanTouches(feature1: Feature<any>, feature2: Feature<any>): boolean;
184

185
/**
186
 * Boolean-equal returns true if the two geometries are exactly equal.
187
 */
188
function booleanEqual(feature1: Feature<any>, feature2: Feature<any>): boolean;
189
```
190

191
**Usage Examples:**
192

193
```typescript
194
import { booleanCrosses, booleanTouches, booleanEqual, lineString, polygon } from "@turf/turf";
195

196
const line1 = lineString([[0, 0], [5, 5]]);
197
const line2 = lineString([[0, 5], [5, 0]]);
198
const poly = polygon([[[0, 0], [0, 5], [5, 5], [5, 0], [0, 0]]]);
199

200
console.log(`Lines cross: ${booleanCrosses(line1, line2)}`); // true
201
console.log(`Line touches polygon: ${booleanTouches(line1, poly)}`); // depends on exact position
202
console.log(`Lines are equal: ${booleanEqual(line1, line2)}`); // false
203
```
204

205
### Geometric Property Testing
206

207
Test geometric properties of features.
208

209
```typescript { .api }
210
/**
211
 * Takes a ring and return true or false whether or not the ring is clockwise or counter-clockwise.
212
 */
213
function booleanClockwise(line: Feature<LineString> | LineString): boolean;
214

215
/**
216
 * Takes a polygon and returns true or false as to whether it is concave or not.
217
 */
218
function booleanConcave(polygon: Feature<Polygon>): boolean;
219

220
/**
221
 * Boolean-valid checks if the geometry is a valid according to the OGC Simple Feature Specification.
222
 */
223
function booleanValid(feature: Feature<any>): boolean;
224
```
225

226
**Usage Examples:**
227

228
```typescript
229
import { booleanClockwise, booleanConcave, booleanValid, polygon, lineString } from "@turf/turf";
230

231
// Test clockwise orientation
232
const clockwiseRing = lineString([[0, 0], [5, 0], [5, 5], [0, 5], [0, 0]]);
233
const counterClockwiseRing = lineString([[0, 0], [0, 5], [5, 5], [5, 0], [0, 0]]);
234

235
console.log(`Ring 1 is clockwise: ${booleanClockwise(clockwiseRing)}`);
236
console.log(`Ring 2 is clockwise: ${booleanClockwise(counterClockwiseRing)}`);
237

238
// Test concave polygon
239
const concavePoly = polygon([[[0, 0], [2, 0], [1, 1], [2, 2], [0, 2], [0, 0]]]);
240
const convexPoly = polygon([[[0, 0], [2, 0], [2, 2], [0, 2], [0, 0]]]);
241

242
console.log(`Polygon 1 is concave: ${booleanConcave(concavePoly)}`);
243
console.log(`Polygon 2 is concave: ${booleanConcave(convexPoly)}`);
244

245
// Test validity
246
console.log(`Polygon is valid: ${booleanValid(convexPoly)}`);
247
```
248

249
### Line Relationship Testing
250

251
Test relationships between linear features.
252

253
```typescript { .api }
254
/**
255
 * Boolean-parallel returns True if each segment of `line1` is parallel to the correspondent
256
 * segment of `line2`.
257
 */
258
function booleanParallel(
259
  line1: Feature<LineString> | LineString,
260
  line2: Feature<LineString> | LineString
261
): boolean;
262
```
263

264
**Usage Examples:**
265

266
```typescript
267
import { booleanParallel, lineString } from "@turf/turf";
268

269
const line1 = lineString([[0, 0], [0, 1]]);
270
const line2 = lineString([[1, 0], [1, 1]]);
271
const line3 = lineString([[0, 0], [1, 1]]);
272

273
console.log(`Lines 1 and 2 are parallel: ${booleanParallel(line1, line2)}`); // true
274
console.log(`Lines 1 and 3 are parallel: ${booleanParallel(line1, line3)}`); // false
275
```