Spatial Measurement

/**
 * Calculates the distance between two coordinates in degrees, radians, miles, or kilometers.
 * This uses the Haversine formula to account for global curvature.
 */
function distance(
  from: Coord,
  to: Coord,
  options?: { units?: Units }
): number;

import { distance, point } from "@turf/turf";

const from = point([-75.343, 39.984]);
const to = point([-75.534, 39.123]);

// Calculate distance in different units
const distKm = distance(from, to, { units: 'kilometers' });
const distMiles = distance(from, to, { units: 'miles' });
const distMeters = distance(from, to, { units: 'meters' });

console.log(`Distance: ${distKm} km, ${distMiles} miles, ${distMeters} meters`);

/**
 * Calculates the geodesic area in square meters of one or more polygons.
 */
function area(geojson: Feature<any> | FeatureCollection<any> | Geometry): number;

import { area, polygon } from "@turf/turf";

const poly = polygon([[[125, -15], [113, -22], [154, -27], [144, -15], [125, -15]]]);
const areaSquareMeters = area(poly);
const areaSquareKm = areaSquareMeters / 1000000;

console.log(`Area: ${areaSquareMeters} m², ${areaSquareKm} km²`);

/**
 * Takes a GeoJSON and measures its length in the specified units (by default in kilometers).
 */
function length(
  geojson: Feature<LineString | MultiLineString | Polygon | MultiPolygon>,
  options?: { units?: Units }
): number;

import { length, lineString, polygon } from "@turf/turf";

const line = lineString([[-77.031669, 38.878605], [-77.029609, 38.881946], [-77.020339, 38.884084]]);
const lengthKm = length(line, { units: 'kilometers' });
const lengthMiles = length(line, { units: 'miles' });

// Length also works with polygons (perimeter)
const poly = polygon([[[0, 0], [0, 1], [1, 1], [1, 0], [0, 0]]]);
const perimeter = length(poly, { units: 'kilometers' });

console.log(`Line length: ${lengthKm} km, ${lengthMiles} miles`);
console.log(`Polygon perimeter: ${perimeter} km`);

/**
 * Takes two points and finds the geographic bearing between them,
 * i.e. the angle measured in degrees from the north line (0 degrees)
 */
function bearing(
  start: Coord,
  end: Coord,
  options?: { final?: boolean }
): number;

import { bearing, point } from "@turf/turf";

const point1 = point([-75.343, 39.984]);
const point2 = point([-75.534, 39.123]);

// Calculate initial bearing
const initialBearing = bearing(point1, point2);

// Calculate final bearing (bearing when arriving at destination)
const finalBearing = bearing(point1, point2, { final: true });

console.log(`Initial bearing: ${initialBearing}°`);
console.log(`Final bearing: ${finalBearing}°`);

/**
 * Finds the angle formed by three points.
 */
function angle(
  start: Coord,
  vertex: Coord,
  end: Coord,
  options?: { explementary?: boolean; mercator?: boolean }
): number;

import { angle, point } from "@turf/turf";

const start = point([5, 5]);
const vertex = point([0, 0]);
const end = point([0, 5]);

// Calculate angle at vertex
const angleValue = angle(start, vertex, end);

// Calculate explementary angle (360° - angle)
const explementaryAngle = angle(start, vertex, end, { explementary: true });

console.log(`Angle: ${angleValue}°`);
console.log(`Explementary angle: ${explementaryAngle}°`);

/**
 * Takes a LineString and returns a Point at a specified distance along the line.
 */
function along(
  line: Feature<LineString> | LineString,
  distance: number,
  options?: { units?: Units }
): Feature<Point>;

import { along, lineString } from "@turf/turf";

const line = lineString([[-83, 30], [-84, 36], [-78, 41]]);

// Get point 200 km along the line
const pointAlong = along(line, 200, { units: 'kilometers' });

// Get point halfway along the line
const totalLength = length(line, { units: 'kilometers' });
const midpoint = along(line, totalLength / 2, { units: 'kilometers' });

console.log('Point 200km along:', pointAlong.geometry.coordinates);
console.log('Midpoint:', midpoint.geometry.coordinates);

/**
 * Calculates the distance along a rhumb line between two points in degrees, radians,
 * miles, or kilometers.
 */
function rhumbDistance(
  from: Coord,
  to: Coord,
  options?: { units?: Units }
): number;

/**
 * Takes two points and finds the bearing angle between them along a Rhumb line
 * i.e. the angle measured in degrees start the north line (0 degrees).
 */
function rhumbBearing(start: Coord, end: Coord, options?: { final?: boolean }): number;

/**
 * Returns the destination Point having travelled the given distance along a Rhumb line
 * from the origin Point with the (varant) given bearing.
 */
function rhumbDestination(
  origin: Coord,
  distance: number,
  bearing: number,
  options?: { units?: Units; properties?: GeoJsonProperties }
): Feature<Point>;

import { rhumbDistance, rhumbBearing, rhumbDestination, point } from "@turf/turf";

const from = point([-75.343, 39.984]);
const to = point([-75.534, 39.123]);

// Rhumb line calculations
const rhumbDist = rhumbDistance(from, to, { units: 'kilometers' });
const rhumbBear = rhumbBearing(from, to);

// Find destination along rhumb line
const destination = rhumbDestination(from, 100, 45, { 
  units: 'kilometers' 
});

console.log(`Rhumb distance: ${rhumbDist} km`);
console.log(`Rhumb bearing: ${rhumbBear}°`);
console.log('Destination:', destination.geometry.coordinates);

/**
 * Takes a Point and calculates the location of a destination point given a distance
 * in degrees, radians, miles, or kilometers; and bearing in degrees.
 */
function destination(
  origin: Coord,
  distance: number,
  bearing: number,
  options?: { units?: Units; properties?: GeoJsonProperties }
): Feature<Point>;

import { destination, point } from "@turf/turf";

const origin = point([-75.343, 39.984]);

// Calculate destination 50km northeast
const dest1 = destination(origin, 50, 45, { units: 'kilometers' });

// Calculate destination 100 miles due north
const dest2 = destination(origin, 100, 0, { units: 'miles' });

console.log('50km NE destination:', dest1.geometry.coordinates);
console.log('100mi N destination:', dest2.geometry.coordinates);

/**
 * Takes two points and returns a point midway between them.
 * The midpoint is calculated geodesically, meaning the curvature of the earth is taken into account.
 */
function midpoint(point1: Coord, point2: Coord): Feature<Point>;

import { midpoint, point } from "@turf/turf";

const pt1 = point([144.834823, -37.771257]);
const pt2 = point([145.14244, -37.830937]);

const mid = midpoint(pt1, pt2);

console.log('Midpoint:', mid.geometry.coordinates);

/**
 * Calculates the bounding box for any GeoJSON object, including FeatureCollection.
 */
function bbox(
  geojson: AllGeoJSON,
  options?: { recompute?: boolean }
): BBox;

import { bbox, lineString, bboxPolygon } from "@turf/turf";

const line = lineString([[-74, 40], [-78, 42], [-82, 35]]);
const bounds = bbox(line);

// Create polygon from bounding box
const bboxPoly = bboxPolygon(bounds);

console.log('Bounding box:', bounds); // [minX, minY, maxX, maxY]

/**
 * Takes a Feature or FeatureCollection and returns the mean center. Can be weighted.
 */
function centerMean<P>(
  geojson: any,
  options?: { properties?: P; bbox?: BBox; id?: Id; weight?: string }
): Feature<Point, P>;

/**
 * Takes a Feature or FeatureCollection and returns the median center.
 */
function centerMedian<P>(
  geojson: any,
  options?: { properties?: P; bbox?: BBox; id?: Id; weight?: string }
): Feature<Point, P>;

/**
 * Takes a Feature or FeatureCollection of Point, LineString, or Polygon features
 * and returns the center of mass using this formula: Centroid of Polygon.
 */
function centerOfMass<P>(
  geojson: any,
  options?: { properties?: P }
): Feature<Point, P>;

import { centerMean, centerMedian, centerOfMass, featureCollection, point } from "@turf/turf";

const features = featureCollection([
  point([-97.522259, 35.4691], { value: 10 }),
  point([-97.502754, 35.463455], { value: 3 }),
  point([-97.508269, 35.463245], { value: 5 })
]);

// Calculate different center types
const meanCenter = centerMean(features);
const weightedMeanCenter = centerMean(features, { weight: "value" });
const medianCenter = centerMedian(features);
const massCenter = centerOfMass(features);

console.log('Mean center:', meanCenter.geometry.coordinates);
console.log('Weighted mean center:', weightedMeanCenter.geometry.coordinates);
console.log('Median center:', medianCenter.geometry.coordinates);
console.log('Center of mass:', massCenter.geometry.coordinates);

/**
 * Takes a Feature or FeatureCollection and returns the centroid using 
 * the mean of all vertices.
 */
function centroid<P>(
  geojson: AllGeoJSON,
  options?: { properties?: P }
): Feature<Point, P>;

/**
 * Takes one or more features and returns their geometric center (centroid).
 */
function center<P>(
  geojson: AllGeoJSON,
  options?: { properties?: P }
): Feature<Point, P>;

import { centroid, center, polygon } from "@turf/turf";

const poly = polygon([[[0, 0], [0, 10], [10, 10], [10, 0], [0, 0]]]);

const centroidPt = centroid(poly);
const centerPt = center(poly);

console.log('Centroid:', centroidPt.geometry.coordinates);
console.log('Center:', centerPt.geometry.coordinates);