0
# Geometric Operations
1

2
Advanced geometric operations for creating, modifying, and combining geographic features including buffers, intersections, unions, and spatial transformations. These operations create new geometries from existing ones.
3

4
## Capabilities
5

6
### Buffer Operations
7

8
Create buffer zones around geometric features.
9

10
```typescript { .api }
11
/**
12
 * Calculates a buffer for input features for a given radius. Units supported are miles, kilometers, and degrees.
13
 */
14
function buffer(
15
  geojson: FeatureCollection<any> | Feature<any> | Geometry,
16
  radius: number,
17
  options?: { units?: Units; steps?: number }
18
): FeatureCollection<Polygon> | Feature<Polygon>;
19
```
20

21
**Usage Examples:**
22

23
```typescript
24
import { buffer, point, lineString, polygon } from "@turf/turf";
25

26
// Buffer around a point
27
const pt = point([-90.548630, 14.616599]);
28
const bufferedPoint = buffer(pt, 500, { units: 'meters' });
29

30
// Buffer around a line
31
const line = lineString([[-90.548630, 14.616599], [-90.560837, 14.613841]]);
32
const bufferedLine = buffer(line, 0.5, { units: 'kilometers' });
33

34
// Buffer around a polygon with custom steps (more steps = smoother curves)
35
const poly = polygon([[[100, 0], [101, 0], [101, 1], [100, 1], [100, 0]]]);
36
const bufferedPoly = buffer(poly, 2, { units: 'kilometers', steps: 64 });
37

38
console.log('Buffered point:', bufferedPoint);
39
console.log('Buffered line:', bufferedLine);
40
```
41

42
### Set Operations
43

44
Perform geometric set operations between polygons.
45

46
```typescript { .api }
47
/**
48
 * Takes two polygons and finds their intersection.
49
 */
50
function intersect(
51
  feature1: Feature<Polygon | MultiPolygon>,
52
  feature2: Feature<Polygon | MultiPolygon>,
53
  options?: { properties?: GeoJsonProperties }
54
): Feature<Polygon | MultiPolygon> | null;
55

56
/**
57
 * Takes input features and returns a combined polygon. If the input features are not contiguous, this function returns a MultiPolygon feature.
58
 */
59
function union(...features: Feature<Polygon | MultiPolygon>[]): Feature<Polygon | MultiPolygon> | null;
60

61
/**
62
 * Finds the difference between two polygons by clipping the second polygon from the first.
63
 */
64
function difference(
65
  feature1: Feature<Polygon | MultiPolygon>,
66
  feature2: Feature<Polygon | MultiPolygon>,
67
  options?: { properties?: GeoJsonProperties }
68
): Feature<Polygon | MultiPolygon> | null;
69
```
70

71
**Usage Examples:**
72

73
```typescript
74
import { intersect, union, difference, polygon } from "@turf/turf";
75

76
const poly1 = polygon([[[0, 0], [0, 5], [5, 5], [5, 0], [0, 0]]]);
77
const poly2 = polygon([[[3, 3], [3, 8], [8, 8], [8, 3], [3, 3]]]);
78
const poly3 = polygon([[[6, 6], [6, 9], [9, 9], [9, 6], [6, 6]]]);
79

80
// Find intersection (overlapping area)
81
const intersection = intersect(poly1, poly2);
82

83
// Create union (combined area) 
84
const unionResult = union(poly1, poly2, poly3);
85

86
// Find difference (poly1 with poly2 removed)
87
const differenceResult = difference(poly1, poly2);
88

89
console.log('Intersection area:', intersection);
90
console.log('Union result:', unionResult);
91
console.log('Difference result:', differenceResult);
92
```
93

94
### Hull Operations
95

96
Create convex and concave hulls around point sets.
97

98
```typescript { .api }
99
/**
100
 * Takes a set of points and returns a concave hull Polygon or MultiPolygon.
101
 * A concave hull, by contrast to a convex hull, can describe the shape of a point set.
102
 */
103
function concave(
104
  geojson: FeatureCollection<Point>,
105
  maxEdge: number,
106
  options?: { units?: Units; properties?: GeoJsonProperties }
107
): Feature<Polygon> | null;
108

109
/**
110
 * Takes a Feature or a FeatureCollection and returns a convex hull Polygon.
111
 * A convex hull is the smallest convex polygon that contains all the given points.
112
 */
113
function convex(
114
  geojson: FeatureCollection<any> | Feature<any> | Geometry,
115
  options?: { concavity?: number; properties?: GeoJsonProperties }
116
): Feature<Polygon>;
117
```
118

119
**Usage Examples:**
120

121
```typescript
122
import { concave, convex, featureCollection, point } from "@turf/turf";
123

124
// Create point collection
125
const points = featureCollection([
126
  point([10.195312, 43.755225]),
127
  point([10.404052, 43.8424511]),
128
  point([10.579833, 43.659924]),
129
  point([10.360107, 43.516688]),
130
  point([10.14038, 43.588348]),
131
  point([10.195312, 43.755225])
132
]);
133

134
// Create convex hull (always convex)
135
const convexHull = convex(points);
136

137
// Create concave hull (can follow point distribution shape)
138
const concaveHull = concave(points, 50, { units: 'kilometers' });
139

140
console.log('Convex hull:', convexHull);
141
console.log('Concave hull:', concaveHull);
142
```
143

144
### Envelope and Bounding Operations
145

146
Create bounding shapes around features.
147

148
```typescript { .api }
149
/**
150
 * Takes any number of features and returns a rectangular Polygon that encompasses all vertices.
151
 */
152
function envelope(geojson: AllGeoJSON): Feature<Polygon>;
153

154
/**
155
 * Takes a bounding box and uses it to clip a GeoJSON Feature or FeatureCollection.
156
 */
157
function bboxClip<G>(
158
  feature: Feature<G> | G,
159
  bbox: BBox
160
): Feature<G>;
161

162
/**
163
 * Takes a bbox and returns an equivalent polygon.
164
 */
165
function bboxPolygon(bbox: BBox, options?: { properties?: GeoJsonProperties; id?: Id }): Feature<Polygon>;
166
```
167

168
**Usage Examples:**
169

170
```typescript
171
import { envelope, bboxClip, bboxPolygon, polygon, lineString } from "@turf/turf";
172

173
const line = lineString([[-2, -1], [4, 6], [8, 2], [3, -4]]);
174
const poly = polygon([[[2, 2], [2, 8], [8, 8], [8, 2], [2, 2]]]);
175

176
// Create envelope around features
177
const env = envelope(line);
178

179
// Create polygon from bounding box
180
const bboxPoly = bboxPolygon([-4, -4, 4, 4]);
181

182
// Clip geometry to bounding box
183
const clipped = bboxClip(poly, [0, 0, 5, 5]);
184

185
console.log('Envelope:', env);
186
console.log('Clipped polygon:', clipped);
187
```
188

189
### Circle and Ellipse Creation
190

191
Create circular and elliptical polygon approximations.
192

193
```typescript { .api }
194
/**
195
 * Takes a Point and calculates the circle polygon given a radius in degrees, radians, miles, or kilometers; and steps for precision.
196
 */
197
function circle(
198
  center: Feature<Point> | Point | number[],
199
  radius: number,
200
  options?: { steps?: number; units?: Units; properties?: GeoJsonProperties }
201
): Feature<Polygon>;
202

203
/**
204
 * Takes a Point and calculates the ellipse polygon given two semi-axes expressed in miles, kilometers, or degrees.
205
 */
206
function ellipse(
207
  center: Feature<Point> | Point | number[],
208
  xSemiAxis: number,
209
  ySemiAxis: number,
210
  options?: { angle?: number; pivot?: Coord; steps?: number; units?: Units; properties?: GeoJsonProperties }
211
): Feature<Polygon>;
212

213
/**
214
 * Creates a circular sector of a circle of given radius and center Point,
215
 * between (clockwise) bearing1 and bearing2; 0 bearing is North of center point, positive clockwise.
216
 */
217
function sector(
218
  center: Coord,
219
  radius: number,
220
  bearing1: number,
221
  bearing2: number,
222
  options?: { units?: Units; steps?: number; properties?: GeoJsonProperties }
223
): Feature<Polygon>;
224
```
225

226
**Usage Examples:**
227

228
```typescript
229
import { circle, ellipse, sector, point } from "@turf/turf";
230

231
const center = point([-75.343, 39.984]);
232

233
// Create circle
234
const circleShape = circle(center, 5, { 
235
  steps: 32, 
236
  units: 'kilometers' 
237
});
238

239
// Create ellipse
240
const ellipseShape = ellipse(center, 5, 3, {
241
  angle: 45,
242
  steps: 32,
243
  units: 'kilometers'
244
});
245

246
// Create sector (pie slice)
247
const sectorShape = sector(center, 5, 45, 135, {
248
  units: 'kilometers',
249
  steps: 32
250
});
251

252
console.log('Circle:', circleShape);
253
console.log('Ellipse:', ellipseShape);
254
console.log('Sector:', sectorShape);
255
```
256

257
### Geometric Simplification
258

259
Simplify complex geometries by reducing coordinate density.
260

261
```typescript { .api }
262
/**
263
 * Takes a GeoJSON object and returns a simplified version. Internally uses simplify-js to perform simplification using the Ramer-Douglas-Peucker algorithm.
264
 */
265
function simplify<G>(
266
  geojson: FeatureCollection<G> | Feature<G> | G,
267
  options?: { tolerance?: number; highQuality?: boolean; mutate?: boolean }
268
): FeatureCollection<G> | Feature<G>;
269
```
270

271
**Usage Examples:**
272

273
```typescript
274
import { simplify, lineString } from "@turf/turf";
275

276
// Complex line with many points
277
const complexLine = lineString([
278
  [0, 0], [0.1, 0.1], [0.2, 0.05], [0.3, 0.15], [0.4, 0.1],
279
  [0.5, 0.2], [0.6, 0.15], [0.7, 0.25], [0.8, 0.2], [0.9, 0.3], [1, 0.25]
280
]);
281

282
// Simplify with different tolerance levels
283
const simplified1 = simplify(complexLine, { tolerance: 0.01 });
284
const simplified2 = simplify(complexLine, { tolerance: 0.05, highQuality: true });
285

286
console.log('Original points:', complexLine.geometry.coordinates.length);
287
console.log('Simplified (0.01):', simplified1.geometry.coordinates.length);
288
console.log('Simplified (0.05):', simplified2.geometry.coordinates.length);
289
```
290

291
### Dissolve Operations
292

293
Combine overlapping or adjacent polygons.
294

295
```typescript { .api }
296
/**
297
 * Dissolves overlapping LineString or Polygon features into a single geometry.
298
 */
299
function dissolve<P>(
300
  geojson: FeatureCollection<Polygon | MultiPolygon, P>,
301
  options?: { propertyName?: keyof P }
302
): FeatureCollection<Polygon | MultiPolygon, P>;
303
```
304

305
**Usage Examples:**
306

307
```typescript
308
import { dissolve, polygon, featureCollection } from "@turf/turf";
309

310
// Create overlapping polygons
311
const poly1 = polygon([[[0, 0], [0, 5], [5, 5], [5, 0], [0, 0]]], { region: 'A' });
312
const poly2 = polygon([[[3, 3], [3, 8], [8, 8], [8, 3], [3, 3]]], { region: 'A' });
313
const poly3 = polygon([[[10, 0], [10, 5], [15, 5], [15, 0], [10, 0]]], { region: 'B' });
314

315
const collection = featureCollection([poly1, poly2, poly3]);
316

317
// Dissolve all polygons
318
const dissolved = dissolve(collection);
319

320
// Dissolve by property (group by region)
321
const dissolvedByRegion = dissolve(collection, { propertyName: 'region' });
322

323
console.log('Dissolved all:', dissolved);
324
console.log('Dissolved by region:', dissolvedByRegion);
325
```