or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

advanced-analysis.mdboolean-operations.mdcoordinate-operations.mddata-generation.mddata-utilities.mdgeometric-operations.mdhelpers.mdindex.mdinvariant.mdline-processing.mdmeasurement.mdmeta.mdspatial-analysis.md
tile.json

tessl/npm-turf--turf

A JavaScript library for performing geospatial operations with GeoJSON data

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@turf/turf@7.2.x

To install, run

npx @tessl/cli install tessl/npm-turf--turf@7.2.0

index.mddocs/

Turf.js

Turf.js is a comprehensive modular geospatial analysis engine written in JavaScript that enables developers to perform advanced spatial analysis and geometric operations using GeoJSON data. The library provides over 100 specialized functions for creating geographic data, performing spatial analysis, data classification, and statistical operations on geographic features like points, lines, and polygons.

Package Information

  • Package Name: @turf/turf
  • Package Type: npm
  • Language: JavaScript/TypeScript
  • Installation: npm install @turf/turf

Core Imports

import * as turf from "@turf/turf";

For selective imports:

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

For CommonJS:

const turf = require("@turf/turf");     // Full library
const { point, polygon, distance } = require("@turf/turf");  // Selective

Basic Usage

import { point, polygon, distance, area, buffer, booleanPointInPolygon } from "@turf/turf";

// Create GeoJSON geometries
const pt1 = point([-75.343, 39.984]);
const pt2 = point([-75.534, 39.123]);
const poly = polygon([[
  [-5, -5], [5, -5], [5, 5], [-5, 5], [-5, -5]
]]);

// Perform spatial calculations
const dist = distance(pt1, pt2, { units: 'miles' });
const polyArea = area(poly);
const buffered = buffer(pt1, 1, { units: 'kilometers' });

// Spatial relationships
const pointInside = booleanPointInPolygon(pt1, poly);

console.log(`Distance: ${dist} miles`);
console.log(`Area: ${polyArea} square meters`);
console.log(`Point inside polygon: ${pointInside}`);

Architecture

Turf.js is built around several key components:

  • Foundational Helpers: Core GeoJSON creation functions and utilities (@turf/helpers, @turf/meta, @turf/invariant)
  • Spatial Measurement: Distance, area, length, and bearing calculations
  • Geometric Operations: Buffer, intersection, union, difference operations using JSTS engine
  • Boolean Operations: Spatial relationship testing (contains, intersects, touches, etc.)
  • Data Transformation: Coordinate transformation, projection, and geometry manipulation
  • Spatial Analysis: Clustering, interpolation, statistical analysis, and grid generation
  • Type System: Full TypeScript support with GeoJSON-compliant type definitions

All functions expect data in WGS84 longitude/latitude coordinates and return GeoJSON-compliant data structures.

Capabilities

Foundational Helpers

Core GeoJSON creation functions, coordinate utilities, and foundational type definitions that support all other Turf operations.

// GeoJSON Feature creation
function point<P>(coordinates: Position, properties?: P, options?: {bbox?: BBox; id?: Id}): Feature<Point, P>;
function polygon<P>(coordinates: Position[][], properties?: P, options?: {bbox?: BBox; id?: Id}): Feature<Polygon, P>;
function lineString<P>(coordinates: Position[], properties?: P, options?: {bbox?: BBox; id?: Id}): Feature<LineString, P>;
function featureCollection<G, P>(features: Array<Feature<G, P>>, options?: {bbox?: BBox; id?: Id}): FeatureCollection<G, P>;

// Unit conversion utilities
function convertLength(length: number, originalUnit?: Units, finalUnit?: Units): number;
function convertArea(area: number, originalUnit?: AreaUnits, finalUnit?: AreaUnits): number;
function radiansToLength(radians: number, units?: Units): number;
function lengthToRadians(distance: number, units?: Units): number;

// Coordinate utilities
function bearingToAzimuth(bearing: number): number;
function azimuthToBearing(angle: number): number;
function radiansToDegrees(radians: number): number;
function degreesToRadians(degrees: number): number;

Foundational Helpers

Geometry Iteration and Manipulation

Utilities for iterating over and manipulating GeoJSON geometries, coordinates, and properties using functional programming patterns.

// Coordinate iteration
function coordEach(geojson: AllGeoJSON, callback: (currentCoord: number[], coordIndex: number, featureIndex: number, multiFeatureIndex: number, geometryIndex: number) => void, excludeWrapCoord?: boolean): void;
function coordReduce<Reducer>(geojson: AllGeoJSON, callback: (previousValue: Reducer, currentCoord: number[], coordIndex: number, featureIndex: number, multiFeatureIndex: number, geometryIndex: number) => Reducer, initialValue?: Reducer): Reducer;

// Feature iteration  
function featureEach<G, P>(geojson: Feature<G, P> | FeatureCollection<G, P> | Feature<GeometryCollection, P>, callback: (currentFeature: Feature<G, P>, featureIndex: number) => void): void;
function featureReduce<Reducer, G, P>(geojson: Feature<G, P> | FeatureCollection<G, P> | Feature<GeometryCollection, P>, callback: (previousValue: Reducer, currentFeature: Feature<G, P>, featureIndex: number) => Reducer, initialValue?: Reducer): Reducer;

// Geometry iteration
function geomEach<G, P>(geojson: Feature<G, P> | FeatureCollection<G, P> | G | GeometryCollection | Feature<GeometryCollection, P>, callback: (currentGeometry: G, featureIndex: number, featureProperties: P, featureBBox: BBox, featureId: Id) => void): void;
function geomReduce<Reducer, G, P>(geojson: Feature<G, P> | FeatureCollection<G, P> | G | GeometryCollection | Feature<GeometryCollection, P>, callback: (previousValue: Reducer, currentGeometry: G, featureIndex: number, featureProperties: P, featureBBox: BBox, featureId: Id) => Reducer, initialValue?: Reducer): Reducer;

Geometry Iteration

Input Validation and Data Extraction

Utilities for validating GeoJSON inputs and extracting coordinates and geometries safely with type checking.

function getCoord(coord: Feature<Point> | Point | number[]): number[];
function getCoords<G>(coords: any[] | Feature<G> | G): any[];
function getGeom<G>(geojson: Feature<G> | G): G;
function getType(geojson: Feature<any> | FeatureCollection<any> | Geometry, name?: string): string;
function geojsonType(value: any, type: string, name: string): void;
function featureOf(feature: Feature<any>, type: string, name: string): void;
function collectionOf(featureCollection: FeatureCollection<any>, type: string, name: string): void;

Input Validation

Spatial Measurement

Functions for calculating distances, areas, lengths, angles, and bearings between geographic features using geodesic calculations.

function distance(from: Coord, to: Coord, options?: {units?: Units}): number;
function area(geojson: Feature<any> | FeatureCollection<any> | Geometry): number;
function length(geojson: Feature<LineString | MultiLineString | Polygon | MultiPolygon>, options?: {units?: Units}): number;
function bearing(start: Coord, end: Coord, options?: {final?: boolean}): number;
function angle(start: Coord, vertex: Coord, end: Coord, options?: {explementary?: boolean; mercator?: boolean}): number;

Spatial Measurement

Boolean Spatial Operations

Functions for testing spatial relationships between geometric features, including intersections, containment, and topology validation.

function booleanPointInPolygon(point: Coord, polygon: Feature<Polygon | MultiPolygon> | Polygon | MultiPolygon, options?: {ignoreBoundary?: boolean}): boolean;
function booleanContains(feature1: Feature<any>, feature2: Feature<any>): boolean;
function booleanIntersects(feature1: Feature<any>, feature2: Feature<any>): boolean;
function booleanOverlap(feature1: Feature<any>, feature2: Feature<any>): boolean;
function booleanCrosses(feature1: Feature<any>, feature2: Feature<any>): boolean;
function booleanDisjoint(feature1: Feature<any>, feature2: Feature<any>): boolean;
function booleanTouches(feature1: Feature<any>, feature2: Feature<any>): boolean;
function booleanWithin(feature1: Feature<any>, feature2: Feature<any>): boolean;
function booleanEqual(feature1: Feature<any>, feature2: Feature<any>): boolean;

Boolean Operations

Geometric Operations

Advanced geometric operations for creating, modifying, and combining geographic features including buffers, intersections, and unions.

function buffer(geojson: FeatureCollection<any> | Feature<any> | Geometry, radius: number, options?: {units?: Units; steps?: number}): FeatureCollection<Polygon> | Feature<Polygon>;
function intersect(feature1: Feature<Polygon | MultiPolygon>, feature2: Feature<Polygon | MultiPolygon>, options?: {properties?: GeoJsonProperties}): Feature<Polygon | MultiPolygon> | null;
function union(...features: Feature<Polygon | MultiPolygon>[]): Feature<Polygon | MultiPolygon> | null;
function difference(feature1: Feature<Polygon | MultiPolygon>, feature2: Feature<Polygon | MultiPolygon>, options?: {properties?: GeoJsonProperties}): Feature<Polygon | MultiPolygon> | null;
function convex(geojson: FeatureCollection<any> | Feature<any> | Geometry, options?: {concavity?: number; properties?: GeoJsonProperties}): Feature<Polygon>;
function concave(geojson: FeatureCollection<Point>, maxEdge: number, options?: {units?: Units; properties?: GeoJsonProperties}): Feature<Polygon> | null;

Geometric Operations

Data Generation and Grids

Functions for generating geometric data including grids, random features, and structured spatial patterns.

function pointGrid(bbox: BBox, cellSide: number, options?: {units?: Units; mask?: Feature<Polygon | MultiPolygon>; properties?: GeoJsonProperties}): FeatureCollection<Point>;
function squareGrid(bbox: BBox, cellSide: number, options?: {units?: Units; mask?: Feature<Polygon | MultiPolygon>; properties?: GeoJsonProperties}): FeatureCollection<Polygon>;
function hexGrid(bbox: BBox, cellSide: number, options?: {units?: Units; properties?: GeoJsonProperties; mask?: Feature<Polygon | MultiPolygon>; triangles?: boolean}): FeatureCollection<Polygon>;
function triangleGrid(bbox: BBox, cellSide: number, options?: {units?: Units; properties?: GeoJsonProperties; mask?: Feature<Polygon | MultiPolygon>}): FeatureCollection<Polygon>;

// Random generation
function randomPoint(count?: number, options?: {bbox?: BBox}): FeatureCollection<Point>;
function randomPolygon(count?: number, options?: {bbox?: BBox; num_vertices?: number; max_radial_length?: number}): FeatureCollection<Polygon>;
function randomLineString(count?: number, options?: {bbox?: BBox; num_vertices?: number; max_length?: number; max_rotation?: number}): FeatureCollection<LineString>;

Data Generation

Spatial Analysis and Statistics

Advanced spatial analysis functions including clustering, interpolation, statistical analysis, and spatial autocorrelation.

function clustersDbscan(points: FeatureCollection<Point>, maxDistance: number, options?: {units?: Units; minPoints?: number; mutate?: boolean}): FeatureCollection<Point>;
function clustersKmeans<P>(points: FeatureCollection<Point, P>, options?: {numberOfClusters?: number; mutate?: boolean}): FeatureCollection<Point, P>;
function interpolate(points: FeatureCollection<Point>, cellSize: number, options?: {gridType?: 'point' | 'square' | 'hex' | 'triangle'; property?: string; units?: Units; weight?: number}): FeatureCollection<Point>;
function isobands(pointGrid: FeatureCollection<Point>, breaks: number[], options?: {zProperty?: string; commonProperties?: GeoJsonProperties; breaksProperties?: GeoJsonProperties[]}): FeatureCollection<Polygon>;
function isolines(pointGrid: FeatureCollection<Point>, breaks: number[], options?: {zProperty?: string; commonProperties?: GeoJsonProperties; breaksProperties?: GeoJsonProperties[]}): FeatureCollection<LineString>;

Spatial Analysis

Line Processing

Specialized functions for working with LineString geometries including splitting, slicing, offsetting, and intersection operations.

function lineSlice(startPt: Coord, stopPt: Coord, line: Feature<LineString> | LineString): Feature<LineString>;
function lineSliceAlong(line: Feature<LineString> | LineString, startDist: number, stopDist: number, options?: {units?: Units}): Feature<LineString>;
function lineSplit(line: FeatureCollection<LineString> | Feature<LineString> | LineString, splitter: FeatureCollection | Feature<any> | Geometry): FeatureCollection<LineString>;
function lineOffset(geojson: Feature<LineString | MultiLineString> | LineString | MultiLineString, distance: number, options?: {units?: Units}): FeatureCollection<LineString>;
function lineIntersect(line1: FeatureCollection | Feature<LineString | MultiLineString | Polygon | MultiPolygon> | LineString | MultiLineString | Polygon | MultiPolygon, line2: FeatureCollection | Feature<LineString | MultiLineString | Polygon | MultiPolygon> | LineString | MultiLineString | Polygon | MultiPolygon, options?: {removeDuplicates?: boolean}): FeatureCollection<Point>;

Line Processing

Coordinate and Projection Operations

Functions for transforming coordinates, changing projections, and manipulating geometric positioning.

function transformTranslate<G>(geojson: FeatureCollection<G> | Feature<G> | G, distance: number, direction: number, options?: {units?: Units; zTranslation?: number; mutate?: boolean}): FeatureCollection<G> | Feature<G>;
function transformRotate<G>(geojson: FeatureCollection<G> | Feature<G> | G, angle: number, options?: {pivot?: Coord; mutate?: boolean}): FeatureCollection<G> | Feature<G>;
function transformScale<G>(geojson: FeatureCollection<G> | Feature<G> | G, factor: number, options?: {origin?: string | Coord; mutate?: boolean}): FeatureCollection<G> | Feature<G>;
function toMercator<G>(geojson: G, options?: {mutate?: boolean}): G;
function toWgs84<G>(geojson: G, options?: {mutate?: boolean}): G;

Coordinate Operations

Advanced Spatial Analysis

Statistical analysis functions for spatial pattern detection, nearest neighbor analysis, spatial autocorrelation, and sophisticated geospatial analytics.

function nearestNeighborAnalysis(dataset: FeatureCollection<Point>, options?: {studyArea?: Feature<Polygon> | Polygon | number; units?: Units}): NearestNeighborStatistics;
function quadratAnalysis(points: FeatureCollection<Point>, options?: {studyBbox?: BBox; quadratWidth?: number; quadratHeight?: number; units?: Units}): QuadratAnalysisResult;
function moranIndex(geojson: FeatureCollection<Polygon>, options?: {inputField: string; threshold?: number; p?: number}): {moranIndex: number; expectedMoranIndex: number; variance: number; zNorm: number};
function nearestPoint(targetPoint: Coord, points: FeatureCollection<Point>): Feature<Point>;
function standardDeviationalEllipse(points: FeatureCollection<Point>, options?: {weight?: string; steps?: number}): Feature<Polygon>;

Advanced Analysis

Data Utilities

Utility functions for manipulating, combining, and transforming GeoJSON data structures for spatial analysis and data preparation.

function collect(polygons: FeatureCollection<Polygon | MultiPolygon>, points: FeatureCollection<Point>, inProperty: string, outProperty: string): FeatureCollection<Polygon | MultiPolygon>;
function tag(points: FeatureCollection<Point>, polygons: FeatureCollection<Polygon | MultiPolygon>, field: string, outField?: string): FeatureCollection<Point>;
function combine<G>(fc: FeatureCollection<G>): FeatureCollection<G>;
function explode(geojson: AllGeoJSON): FeatureCollection<Point>;
function flatten<G>(geojson: any): FeatureCollection<G>;
function clone<T>(geojson: T): T;
function cleanCoords<T>(geojson: T, options?: {mutate?: boolean}): T;

Data Utilities

Types

// Core coordinate and unit types
type Coord = Feature<Point> | Point | Position;
type Units = "meters" | "metres" | "millimeters" | "millimetres" | "centimeters" | "centimetres" | "kilometers" | "kilometres" | "miles" | "nauticalmiles" | "inches" | "yards" | "feet" | "radians" | "degrees";
type AreaUnits = Exclude<Units, "radians" | "degrees"> | "acres" | "hectares";
type Grid = "point" | "square" | "hex" | "triangle";
type Corners = "sw" | "se" | "nw" | "ne" | "center" | "centroid";
type Lines = LineString | MultiLineString | Polygon | MultiPolygon;
type AllGeoJSON = Feature | FeatureCollection | Geometry | GeometryCollection;
type Id = string | number;

// Analysis result types
interface QuadratAnalysisResult {
  criticalValue: number;
  maxAbsoluteDifference: number;
  isRandom: boolean;
  observedDistribution: number[];
}

interface NearestNeighborStatistics {
  units: Units & AreaUnits;
  arealUnits: string;
  observedMeanDistance: number;
  expectedMeanDistance: number;
  nearestNeighborIndex: number;
  numberOfPoints: number;
  zScore: number;
}

// Additional analysis types
interface StandardDeviationalEllipseResult {
  centroid: Feature<Point>;
  ellipse: Feature<Polygon>;
  xStandardDistance: number;
  yStandardDistance: number;
  rotation: number;
}

// GeoJSON base types from @types/geojson
type Position = number[];
type BBox = [number, number, number, number] | [number, number, number, number, number, number];
type GeoJsonProperties = { [name: string]: any } | null;