0
# Coordinate and Projection Operations
1

2
Functions for transforming coordinates, changing projections, and manipulating geometric positioning. These operations modify the spatial position and orientation of geographic features.
3

4
## Capabilities
5

6
### Geometric Transformations
7

8
Apply spatial transformations to features including translation, rotation, and scaling.
9

10
```typescript { .api }
11
/**
12
 * Moves any GeoJSON Feature or Geometry of a specified distance along a Rhumb Line
13
 * on the provided direction angle.
14
 */
15
function transformTranslate<G>(
16
  geojson: FeatureCollection<G> | Feature<G> | G,
17
  distance: number,
18
  direction: number,
19
  options?: { units?: Units; zTranslation?: number; mutate?: boolean }
20
): FeatureCollection<G> | Feature<G>;
21

22
/**
23
 * Rotates any GeoJSON Feature or Geometry of a specified angle, around its centroid or a given pivot point.
24
 */
25
function transformRotate<G>(
26
  geojson: FeatureCollection<G> | Feature<G> | G,
27
  angle: number,
28
  options?: { pivot?: Coord; mutate?: boolean }
29
): FeatureCollection<G> | Feature<G>;
30

31
/**
32
 * Scale a GeoJSON from a given point by a factor of scaling (ex: factor=2 would make the GeoJSON 200% larger).
33
 */
34
function transformScale<G>(
35
  geojson: FeatureCollection<G> | Feature<G> | G,
36
  factor: number,
37
  options?: { origin?: string | Coord; mutate?: boolean }
38
): FeatureCollection<G> | Feature<G>;
39
```
40

41
**Usage Examples:**
42

43
```typescript
44
import { transformTranslate, transformRotate, transformScale, polygon, point } from "@turf/turf";
45

46
const poly = polygon([[[0, 29], [3.5, 29], [2.5, 32], [0, 29]]]);
47

48
// Translate (move) polygon 100km northeast
49
const translated = transformTranslate(poly, 100, 45, { 
50
  units: 'kilometers' 
51
});
52

53
// Rotate polygon 90 degrees around its centroid
54
const rotated = transformRotate(poly, 90);
55

56
// Rotate around specific pivot point
57
const pivotPoint = point([0, 30]);
58
const rotatedAroundPivot = transformRotate(poly, 45, { 
59
  pivot: pivotPoint 
60
});
61

62
// Scale polygon to 150% of original size
63
const scaled = transformScale(poly, 1.5);
64

65
// Scale from specific origin point
66
const scaledFromOrigin = transformScale(poly, 2, { 
67
  origin: [0, 29] 
68
});
69

70
console.log('Translated polygon:', translated);
71
console.log('Rotated polygon:', rotated);
72
console.log('Scaled polygon:', scaled);
73
```
74

75
### Coordinate System Projections
76

77
Convert between different coordinate reference systems.
78

79
```typescript { .api }
80
/**
81
 * Converts a WGS84 GeoJSON object into Mercator projection.
82
 */
83
function toMercator<G>(geojson: G, options?: { mutate?: boolean }): G;
84

85
/**
86
 * Converts a Mercator GeoJSON object to WGS84 projection.
87
 */
88
function toWgs84<G>(geojson: G, options?: { mutate?: boolean }): G;
89
```
90

91
**Usage Examples:**
92

93
```typescript
94
import { toMercator, toWgs84, point, polygon } from "@turf/turf";
95

96
// WGS84 coordinates (longitude, latitude)
97
const wgs84Point = point([-7.936523, 37.344592]);
98
const wgs84Polygon = polygon([[[2, 2], [8, 2], [8, 8], [2, 8], [2, 2]]]);
99

100
// Convert to Mercator projection
101
const mercatorPoint = toMercator(wgs84Point);
102
const mercatorPolygon = toMercator(wgs84Polygon);
103

104
// Convert back to WGS84
105
const backToWgs84Point = toWgs84(mercatorPoint);
106

107
console.log('WGS84 point:', wgs84Point.geometry.coordinates);
108
console.log('Mercator point:', mercatorPoint.geometry.coordinates);
109
console.log('Back to WGS84:', backToWgs84Point.geometry.coordinates);
110

111
// Mutate original (modify in place)
112
const originalPoly = polygon([[[0, 0], [1, 0], [1, 1], [0, 1], [0, 0]]]);
113
toMercator(originalPoly, { mutate: true });
114
console.log('Mutated polygon:', originalPoly.geometry.coordinates);
115
```
116

117
### Coordinate Manipulation
118

119
Modify coordinate arrays and geometric properties.
120

121
```typescript { .api }
122
/**
123
 * Takes a Feature or FeatureCollection and truncates the precision of the geometry.
124
 */
125
function truncate<G>(
126
  geojson: FeatureCollection<G> | Feature<G> | G,
127
  options?: { precision?: number; coordinates?: number; mutate?: boolean }
128
): FeatureCollection<G> | Feature<G>;
129

130
/**
131
 * Flips the coordinates of any GeoJSON Feature or Geometry.
132
 */
133
function flip<G>(
134
  geojson: FeatureCollection<G> | Feature<G> | G,
135
  options?: { mutate?: boolean }
136
): FeatureCollection<G> | Feature<G>;
137

138
/**
139
 * Rewinds the coordinates of any GeoJSON Polygon, MultiPolygon, or LineString 
140
 * to be counter-clockwise for exterior rings and clockwise for interior rings (holes).
141
 */
142
function rewind<G>(
143
  geojson: FeatureCollection<G> | Feature<G> | G,
144
  options?: { reverse?: boolean; mutate?: boolean }
145
): FeatureCollection<G> | Feature<G];
146

147
/**
148
 * Removes redundant coordinates from any GeoJSON Geometry.
149
 */
150
function cleanCoords<G>(
151
  geojson: FeatureCollection<G> | Feature<G> | G,
152
  options?: { mutate?: boolean }
153
): FeatureCollection<G> | Feature<G>;
154
```
155

156
**Usage Examples:**
157

158
```typescript
159
import { truncate, flip, rewind, cleanCoords, polygon, lineString } from "@turf/turf";
160

161
// High precision coordinates
162
const precisePoly = polygon([[[
163
  1.123456789, 2.987654321
164
], [
165
  3.555555555, 4.444444444
166
], [
167
  5.111111111, 6.222222222
168
], [
169
  1.123456789, 2.987654321
170
]]]);
171

172
// Truncate to 3 decimal places
173
const truncated = truncate(precisePoly, { precision: 3 });
174

175
// Flip coordinates (longitude, latitude) to (latitude, longitude)
176
const flipped = flip(precisePoly);
177

178
// Create polygon with wrong winding order
179
const wrongWinding = polygon([[[0, 0], [0, 1], [1, 1], [1, 0], [0, 0]]]);
180
const rewound = rewind(wrongWinding, { reverse: false });
181

182
// Line with redundant coordinates
183
const redundantLine = lineString([
184
  [0, 0], [1, 1], [1, 1], [2, 2], [2, 2], [3, 3]
185
]);
186
const cleaned = cleanCoords(redundantLine);
187

188
console.log('Original precision:', precisePoly.geometry.coordinates[0][0]);
189
console.log('Truncated:', truncated.geometry.coordinates[0][0]);
190
console.log('Flipped coordinates:', flipped.geometry.coordinates[0][0]);
191
console.log('Original line length:', redundantLine.geometry.coordinates.length);
192
console.log('Cleaned line length:', cleaned.geometry.coordinates.length);
193
```
194

195
### Point Positioning
196

197
Calculate positions relative to features and find specific points.
198

199
```typescript { .api }
200
/**
201
 * Takes a Point and calculates the location of a destination point given a distance
202
 * in degrees, radians, miles, or kilometers; and bearing in degrees.
203
 */
204
function destination(
205
  origin: Coord,
206
  distance: number,
207
  bearing: number,
208
  options?: { units?: Units; properties?: GeoJsonProperties }
209
): Feature<Point>;
210

211
/**
212
 * Takes any Feature or a FeatureCollection and returns a Point guaranteed to be on the surface of the feature.
213
 */
214
function pointOnFeature<P>(
215
  geojson: FeatureCollection<any, P> | Feature<any, P>
216
): Feature<Point, P>;
217

218
/**
219
 * Takes a Feature or FeatureCollection and calculates the centroid using the mean of all vertices.
220
 */
221
function centroid<P>(
222
  geojson: AllGeoJSON,
223
  options?: { properties?: P }
224
): Feature<Point, P>;
225

226
/**
227
 * Takes one or more features and calculates the absolute center point of all features.
228
 */
229
function center<P>(
230
  geojson: AllGeoJSON,
231
  options?: { properties?: P }
232
): Feature<Point, P>;
233
```
234

235
**Usage Examples:**
236

237
```typescript
238
import { destination, pointOnFeature, centroid, center, point, polygon } from "@turf/turf";
239

240
const origin = point([-75.343, 39.984]);
241
const complexPoly = polygon([[[
242
  [0, 0], [10, 0], [10, 10], [5, 15], [0, 10], [0, 0]
243
]]]);
244

245
// Calculate destination point
246
const dest = destination(origin, 50, 90, { 
247
  units: 'kilometers',
248
  properties: { type: 'destination' }
249
});
250

251
// Find point guaranteed to be on feature surface
252
const surfacePoint = pointOnFeature(complexPoly);
253

254
// Calculate geometric centroid (mean of vertices)
255
const geometricCenter = centroid(complexPoly);
256

257
// Calculate absolute center (center of bounding box)
258
const absoluteCenter = center(complexPoly);
259

260
console.log('Destination point:', dest.geometry.coordinates);
261
console.log('Point on feature:', surfacePoint.geometry.coordinates);
262
console.log('Centroid:', geometricCenter.geometry.coordinates);
263
console.log('Absolute center:', absoluteCenter.geometry.coordinates);
264
```
265

266
### Coordinate Validation and Utilities
267

268
Validate and manipulate coordinate precision and format.
269

270
```typescript { .api }
271
/**
272
 * Takes a Point and a Polygon or MultiPolygon and determines if the point
273
 * resides inside the polygon.
274
 */
275
function pointsWithinPolygon<G, P>(
276
  points: FeatureCollection<Point, P> | Feature<Point, P>,
277
  polygon: Feature<Polygon | MultiPolygon> | Polygon | MultiPolygon
278
): FeatureCollection<Point, P>;
279

280
/**
281
 * Calculates the distance from a point to a line segment.
282
 */
283
function pointToLineDistance(
284
  pt: Coord,
285
  line: Feature<LineString> | LineString,
286
  options?: { units?: Units; method?: 'geodesic' | 'planar' }
287
): number;
288

289
/**
290
 * Calculates the shortest distance from a Point to a Polygon outlines.
291
 */
292
function pointToPolygonDistance(
293
  point: Coord,
294
  polygon: Feature<Polygon | MultiPolygon> | Polygon | MultiPolygon,
295
  options?: { units?: Units }
296
): number;
297
```
298

299
**Usage Examples:**
300

301
```typescript
302
import { pointsWithinPolygon, pointToLineDistance, pointToPolygonDistance, point, polygon, lineString, randomPoint } from "@turf/turf";
303

304
// Generate random points
305
const randomPoints = randomPoint(100, { bbox: [-5, -5, 5, 5] });
306

307
// Define test polygon
308
const testPoly = polygon([[[0, 0], [0, 3], [3, 3], [3, 0], [0, 0]]]);
309

310
// Find points within polygon
311
const pointsInside = pointsWithinPolygon(randomPoints, testPoly);
312

313
// Calculate distances
314
const testPoint = point([1, 1]);
315
const testLine = lineString([[0, 0], [2, 2], [4, 0]]);
316

317
const distanceToLine = pointToLineDistance(testPoint, testLine, { 
318
  units: 'kilometers' 
319
});
320

321
const distanceToPolygon = pointToPolygonDistance(testPoint, testPoly, { 
322
  units: 'meters' 
323
});
324

325
console.log(`Found ${pointsInside.features.length} points inside polygon`);
326
console.log(`Distance to line: ${distanceToLine} km`);
327
console.log(`Distance to polygon: ${distanceToPolygon} meters`);
328
```