0
# Foundational Helpers
1

2
Core GeoJSON creation functions, coordinate utilities, and foundational type definitions that support all other Turf operations. This module provides the building blocks for creating and manipulating GeoJSON data structures.
3

4
## Capabilities
5

6
### GeoJSON Feature Creation
7

8
Functions for creating GeoJSON Features and FeatureCollections from coordinate data.
9

10
```typescript { .api }
11
/**
12
 * Wraps a GeoJSON Geometry in a GeoJSON Feature.
13
 */
14
function feature<G, P>(
15
  geom: G | null,
16
  properties?: P,
17
  options?: { bbox?: BBox; id?: Id }
18
): Feature<G, P>;
19

20
/**
21
 * Creates a GeoJSON Geometry from a Geometry string type & coordinates.
22
 */
23
function geometry(
24
  type: "Point" | "LineString" | "Polygon" | "MultiPoint" | "MultiLineString" | "MultiPolygon",
25
  coordinates: any[],
26
  options?: Record<string, never>
27
): Geometry;
28

29
/**
30
 * Creates a Point Feature from a Position.
31
 */
32
function point<P>(
33
  coordinates: Position,
34
  properties?: P,
35
  options?: { bbox?: BBox; id?: Id }
36
): Feature<Point, P>;
37

38
/**
39
 * Creates a Point FeatureCollection from an Array of Point coordinates.
40
 */
41
function points<P>(
42
  coordinates: Position[],
43
  properties?: P,
44
  options?: { bbox?: BBox; id?: Id }
45
): FeatureCollection<Point, P>;
46

47
/**
48
 * Creates a Polygon Feature from an Array of LinearRings.
49
 */
50
function polygon<P>(
51
  coordinates: Position[][],
52
  properties?: P,
53
  options?: { bbox?: BBox; id?: Id }
54
): Feature<Polygon, P>;
55

56
/**
57
 * Creates a Polygon FeatureCollection from an Array of Polygon coordinates.
58
 */
59
function polygons<P>(
60
  coordinates: Position[][][],
61
  properties?: P,
62
  options?: { bbox?: BBox; id?: Id }
63
): FeatureCollection<Polygon, P>;
64

65
/**
66
 * Creates a LineString Feature from an Array of Positions.
67
 */
68
function lineString<P>(
69
  coordinates: Position[],
70
  properties?: P,
71
  options?: { bbox?: BBox; id?: Id }
72
): Feature<LineString, P>;
73

74
/**
75
 * Creates a LineString FeatureCollection from an Array of LineString coordinates.
76
 */
77
function lineStrings<P>(
78
  coordinates: Position[][],
79
  properties?: P,
80
  options?: { bbox?: BBox; id?: Id }
81
): FeatureCollection<LineString, P>;
82

83
/**
84
 * Creates a MultiLineString Feature based on a coordinate array.
85
 */
86
function multiLineString<P>(
87
  coordinates: Position[][],
88
  properties?: P,
89
  options?: { bbox?: BBox; id?: Id }
90
): Feature<MultiLineString, P>;
91

92
/**
93
 * Creates a MultiPoint Feature based on a coordinate array.
94
 */
95
function multiPoint<P>(
96
  coordinates: Position[],
97
  properties?: P,
98
  options?: { bbox?: BBox; id?: Id }
99
): Feature<MultiPoint, P>;
100

101
/**
102
 * Creates a MultiPolygon Feature based on a coordinate array.
103
 */
104
function multiPolygon<P>(
105
  coordinates: Position[][][],
106
  properties?: P,
107
  options?: { bbox?: BBox; id?: Id }
108
): Feature<MultiPolygon, P>;
109

110
/**
111
 * Creates a Feature<GeometryCollection> based on a coordinate array.
112
 */
113
function geometryCollection<P>(
114
  geometries: Array<Point | LineString | Polygon | MultiPoint | MultiLineString | MultiPolygon>,
115
  properties?: P,
116
  options?: { bbox?: BBox; id?: Id }
117
): Feature<GeometryCollection, P>;
118

119
/**
120
 * Takes one or more Features and creates a FeatureCollection.
121
 */
122
function featureCollection<G, P>(
123
  features: Array<Feature<G, P>>,
124
  options?: { bbox?: BBox; id?: Id }
125
): FeatureCollection<G, P>;
126
```
127

128
**Usage Examples:**
129

130
```typescript
131
import { point, polygon, lineString, featureCollection } from "@turf/turf";
132

133
// Create basic geometries
134
const pt = point([102, 0.5], { name: "Sample Point" });
135
const line = lineString([[102, -10], [103, 1], [104, 0], [130, 4]]);
136
const poly = polygon([[[100, 0], [101, 0], [101, 1], [100, 1], [100, 0]]]);
137

138
// Create collections
139
const collection = featureCollection([pt, line, poly]);
140

141
// Add metadata
142
const pointWithBbox = point([102, 0.5], { name: "Tagged Point" }, { 
143
  bbox: [101, 0, 103, 1], 
144
  id: "point-001" 
145
});
146
```
147

148
### Unit Conversion Utilities
149

150
Functions for converting between different measurement units and coordinate systems.
151

152
```typescript { .api }
153
/**
154
 * Convert a distance measurement from radians to a more friendly unit.
155
 */
156
function radiansToLength(radians: number, units?: Units): number;
157

158
/**
159
 * Convert a distance measurement from a real-world unit into radians.
160
 */
161
function lengthToRadians(distance: number, units?: Units): number;
162

163
/**
164
 * Convert a distance measurement from a real-world unit into degrees.
165
 */
166
function lengthToDegrees(distance: number, units?: Units): number;
167

168
/**
169
 * Converts a length from one unit to another.
170
 */
171
function convertLength(
172
  length: number,
173
  originalUnit?: Units,
174
  finalUnit?: Units
175
): number;
176

177
/**
178
 * Converts an area from one unit to another.
179
 */
180
function convertArea(
181
  area: number,
182
  originalUnit?: AreaUnits,
183
  finalUnit?: AreaUnits
184
): number;
185
```
186

187
**Usage Examples:**
188

189
```typescript
190
import { convertLength, convertArea, radiansToLength } from "@turf/turf";
191

192
// Convert between length units
193
const kilometers = convertLength(1, "miles", "kilometers"); // ~1.609
194
const meters = convertLength(100, "feet", "meters"); // ~30.48
195

196
// Convert between area units
197
const squareKm = convertArea(1, "acres", "kilometers"); // ~0.004
198
const hectares = convertArea(100, "acres", "hectares"); // ~40.47
199

200
// Convert from radians
201
const miles = radiansToLength(0.1, "miles"); // Distance in miles
202
```
203

204
### Coordinate System Utilities
205

206
Functions for working with bearings, angles, and coordinate transformations.
207

208
```typescript { .api }
209
/**
210
 * Converts any bearing angle from the north line direction (positive clockwise)
211
 * and returns an angle between 0-360 degrees (positive clockwise).
212
 */
213
function bearingToAzimuth(bearing: number): number;
214

215
/**
216
 * Converts any azimuth angle from the north line direction (positive clockwise)
217
 * and returns an angle between -180 and +180 degrees (positive clockwise).
218
 */
219
function azimuthToBearing(angle: number): number;
220

221
/**
222
 * Converts an angle in radians to degrees.
223
 */
224
function radiansToDegrees(radians: number): number;
225

226
/**
227
 * Converts an angle in degrees to radians.
228
 */
229
function degreesToRadians(degrees: number): number;
230

231
/**
232
 * Round number to precision.
233
 */
234
function round(num: number, precision?: number): number;
235
```
236

237
**Usage Examples:**
238

239
```typescript
240
import { bearingToAzimuth, azimuthToBearing, degreesToRadians, round } from "@turf/turf";
241

242
// Convert between bearing systems
243
const azimuth = bearingToAzimuth(-45); // 315 degrees
244
const bearing = azimuthToBearing(315); // -45 degrees
245

246
// Convert angle units
247
const radians = degreesToRadians(90); // π/2
248
const rounded = round(3.14159265, 2); // 3.14
249
```
250

251
### Data Validation Utilities
252

253
Functions for validating and testing data types.
254

255
```typescript { .api }
256
/**
257
 * Validates if input is a number.
258
 */
259
function isNumber(num: any): boolean;
260

261
/**
262
 * Validates if input is an object (not array/function).
263
 */
264
function isObject(input: any): boolean;
265

266
/**
267
 * Validates BBox format.
268
 * @throws {Error} if BBox is not valid
269
 */
270
function validateBBox(bbox: any): void;
271

272
/**
273
 * Validates GeoJSON ID format.
274
 * @throws {Error} if Id is not valid
275
 */
276
function validateId(id: any): void;
277
```
278

279
### Constants
280

281
```typescript { .api }
282
/**
283
 * The Earth radius in meters. Used by Turf modules that model the Earth as a sphere.
284
 * The mean radius was selected because it is recommended by the Haversine formula.
285
 */
286
const earthRadius: 6371008.8;
287

288
/**
289
 * Unit of measurement factors based on earthRadius.
290
 * Keys are the name of the unit, values are the number of that unit in a single radian.
291
 */
292
const factors: Record<Units, number>;
293

294
/**
295
 * Area of measurement factors based on 1 square meter.
296
 */
297
const areaFactors: Record<AreaUnits, number>;
298
```
299

300
## Types
301

302
```typescript { .api }
303
// Core coordinate and unit types
304
type Coord = Feature<Point> | Point | Position;
305
type Units = "meters" | "metres" | "millimeters" | "millimetres" | "centimeters" | "centimetres" | "kilometers" | "kilometres" | "miles" | "nauticalmiles" | "inches" | "yards" | "feet" | "radians" | "degrees";
306
type AreaUnits = Exclude<Units, "radians" | "degrees"> | "acres" | "hectares";
307
type Grid = "point" | "square" | "hex" | "triangle";
308
type Corners = "sw" | "se" | "nw" | "ne" | "center" | "centroid";
309
type Lines = LineString | MultiLineString | Polygon | MultiPolygon;
310
type AllGeoJSON = Feature | FeatureCollection | Geometry | GeometryCollection;
311
type Id = string | number;
312
```