@turf/helpers
    TypeScript icon, indicating that this package has built-in type declarations

    6.5.0 • Public • Published

    @turf/helpers

    earthRadius

    Earth Radius used with the Harvesine formula and approximates using a spherical (non-ellipsoid) Earth.

    factors

    Unit of measurement factors using a spherical (non-ellipsoid) earth radius.

    unitsFactors

    Units of measurement factors based on 1 meter.

    areaFactors

    Area of measurement factors based on 1 square meter.

    feature

    Wraps a GeoJSON Geometry in a GeoJSON Feature.

    Parameters

    • geometry Geometry input geometry
    • properties Object an Object of key-value pairs to add as properties (optional, default {})
    • options Object Optional Parameters (optional, default {})
      • options.bbox Array<number>? Bounding Box Array [west, south, east, north] associated with the Feature
      • options.id (string | number)? Identifier associated with the Feature

    Examples

    var geometry = {
      "type": "Point",
      "coordinates": [110, 50]
    };
    
    var feature = turf.feature(geometry);
    
    //=feature

    Returns Feature a GeoJSON Feature

    geometry

    Creates a GeoJSON Geometry from a Geometry string type & coordinates. For GeometryCollection type use helpers.geometryCollection

    Parameters

    • type string Geometry Type
    • coordinates Array<number> Coordinates
    • options Object Optional Parameters (optional, default {})
      • options.bbox Array<number>? Bounding Box Array [west, south, east, north] associated with the Geometry

    Examples

    var type = 'Point';
    var coordinates = [110, 50];
    
    var geometry = turf.geometry(type, coordinates);
    
    //=geometry

    Returns Geometry a GeoJSON Geometry

    point

    Creates a Point Feature from a Position.

    Parameters

    • coordinates Array<number> longitude, latitude position (each in decimal degrees)
    • properties Object an Object of key-value pairs to add as properties (optional, default {})
    • options Object Optional Parameters (optional, default {})
      • options.bbox Array<number>? Bounding Box Array [west, south, east, north] associated with the Feature
      • options.id (string | number)? Identifier associated with the Feature

    Examples

    var point = turf.point([-75.343, 39.984]);
    
    //=point

    Returns Feature<Point> a Point feature

    points

    Creates a Point FeatureCollection from an Array of Point coordinates.

    Parameters

    • coordinates Array<Array<number>> an array of Points
    • properties Object Translate these properties to each Feature (optional, default {})
    • options Object Optional Parameters (optional, default {})
      • options.bbox Array<number>? Bounding Box Array [west, south, east, north] associated with the FeatureCollection
      • options.id (string | number)? Identifier associated with the FeatureCollection

    Examples

    var points = turf.points([
      [-75, 39],
      [-80, 45],
      [-78, 50]
    ]);
    
    //=points

    Returns FeatureCollection<Point> Point Feature

    polygon

    Creates a Polygon Feature from an Array of LinearRings.

    Parameters

    • coordinates Array<Array<Array<number>>> an array of LinearRings
    • properties Object an Object of key-value pairs to add as properties (optional, default {})
    • options Object Optional Parameters (optional, default {})
      • options.bbox Array<number>? Bounding Box Array [west, south, east, north] associated with the Feature
      • options.id (string | number)? Identifier associated with the Feature

    Examples

    var polygon = turf.polygon([[[-5, 52], [-4, 56], [-2, 51], [-7, 54], [-5, 52]]], { name: 'poly1' });
    
    //=polygon

    Returns Feature<Polygon> Polygon Feature

    polygons

    Creates a Polygon FeatureCollection from an Array of Polygon coordinates.

    Parameters

    • coordinates Array<Array<Array<Array<number>>>> an array of Polygon coordinates
    • properties Object an Object of key-value pairs to add as properties (optional, default {})
    • options Object Optional Parameters (optional, default {})
      • options.bbox Array<number>? Bounding Box Array [west, south, east, north] associated with the Feature
      • options.id (string | number)? Identifier associated with the FeatureCollection

    Examples

    var polygons = turf.polygons([
      [[[-5, 52], [-4, 56], [-2, 51], [-7, 54], [-5, 52]]],
      [[[-15, 42], [-14, 46], [-12, 41], [-17, 44], [-15, 42]]],
    ]);
    
    //=polygons

    Returns FeatureCollection<Polygon> Polygon FeatureCollection

    lineString

    Creates a LineString Feature from an Array of Positions.

    Parameters

    • coordinates Array<Array<number>> an array of Positions
    • properties Object an Object of key-value pairs to add as properties (optional, default {})
    • options Object Optional Parameters (optional, default {})
      • options.bbox Array<number>? Bounding Box Array [west, south, east, north] associated with the Feature
      • options.id (string | number)? Identifier associated with the Feature

    Examples

    var linestring1 = turf.lineString([[-24, 63], [-23, 60], [-25, 65], [-20, 69]], {name: 'line 1'});
    var linestring2 = turf.lineString([[-14, 43], [-13, 40], [-15, 45], [-10, 49]], {name: 'line 2'});
    
    //=linestring1
    //=linestring2

    Returns Feature<LineString> LineString Feature

    lineStrings

    Creates a LineString FeatureCollection from an Array of LineString coordinates.

    Parameters

    • coordinates Array<Array<number>> an array of LinearRings
    • properties Object an Object of key-value pairs to add as properties (optional, default {})
    • options Object Optional Parameters (optional, default {})
      • options.bbox Array<number>? Bounding Box Array [west, south, east, north] associated with the FeatureCollection
      • options.id (string | number)? Identifier associated with the FeatureCollection

    Examples

    var linestrings = turf.lineStrings([
      [[-24, 63], [-23, 60], [-25, 65], [-20, 69]],
      [[-14, 43], [-13, 40], [-15, 45], [-10, 49]]
    ]);
    
    //=linestrings

    Returns FeatureCollection<LineString> LineString FeatureCollection

    featureCollection

    Takes one or more Features and creates a FeatureCollection.

    Parameters

    • features Array<Feature> input features
    • options Object Optional Parameters (optional, default {})
      • options.bbox Array<number>? Bounding Box Array [west, south, east, north] associated with the Feature
      • options.id (string | number)? Identifier associated with the Feature

    Examples

    var locationA = turf.point([-75.343, 39.984], {name: 'Location A'});
    var locationB = turf.point([-75.833, 39.284], {name: 'Location B'});
    var locationC = turf.point([-75.534, 39.123], {name: 'Location C'});
    
    var collection = turf.featureCollection([
      locationA,
      locationB,
      locationC
    ]);
    
    //=collection

    Returns FeatureCollection FeatureCollection of Features

    multiLineString

    Creates a Feature<MultiLineString> based on a coordinate array. Properties can be added optionally.

    Parameters

    • coordinates Array<Array<Array<number>>> an array of LineStrings
    • properties Object an Object of key-value pairs to add as properties (optional, default {})
    • options Object Optional Parameters (optional, default {})
      • options.bbox Array<number>? Bounding Box Array [west, south, east, north] associated with the Feature
      • options.id (string | number)? Identifier associated with the Feature

    Examples

    var multiLine = turf.multiLineString([[[0,0],[10,10]]]);
    
    //=multiLine
    • Throws Error if no coordinates are passed

    Returns Feature<MultiLineString> a MultiLineString feature

    multiPoint

    Creates a Feature<MultiPoint> based on a coordinate array. Properties can be added optionally.

    Parameters

    • coordinates Array<Array<number>> an array of Positions
    • properties Object an Object of key-value pairs to add as properties (optional, default {})
    • options Object Optional Parameters (optional, default {})
      • options.bbox Array<number>? Bounding Box Array [west, south, east, north] associated with the Feature
      • options.id (string | number)? Identifier associated with the Feature

    Examples

    var multiPt = turf.multiPoint([[0,0],[10,10]]);
    
    //=multiPt
    • Throws Error if no coordinates are passed

    Returns Feature<MultiPoint> a MultiPoint feature

    multiPolygon

    Creates a Feature<MultiPolygon> based on a coordinate array. Properties can be added optionally.

    Parameters

    • coordinates Array<Array<Array<Array<number>>>> an array of Polygons
    • properties Object an Object of key-value pairs to add as properties (optional, default {})
    • options Object Optional Parameters (optional, default {})
      • options.bbox Array<number>? Bounding Box Array [west, south, east, north] associated with the Feature
      • options.id (string | number)? Identifier associated with the Feature

    Examples

    var multiPoly = turf.multiPolygon([[[[0,0],[0,10],[10,10],[10,0],[0,0]]]]);
    
    //=multiPoly
    • Throws Error if no coordinates are passed

    Returns Feature<MultiPolygon> a multipolygon feature

    geometryCollection

    Creates a Feature<GeometryCollection> based on a coordinate array. Properties can be added optionally.

    Parameters

    • geometries Array<Geometry> an array of GeoJSON Geometries
    • properties Object an Object of key-value pairs to add as properties (optional, default {})
    • options Object Optional Parameters (optional, default {})
      • options.bbox Array<number>? Bounding Box Array [west, south, east, north] associated with the Feature
      • options.id (string | number)? Identifier associated with the Feature

    Examples

    var pt = {
        "type": "Point",
          "coordinates": [100, 0]
        };
    var line = {
        "type": "LineString",
        "coordinates": [ [101, 0], [102, 1] ]
      };
    var collection = turf.geometryCollection([pt, line]);
    
    //=collection

    Returns Feature<GeometryCollection> a GeoJSON GeometryCollection Feature

    round

    Round number to precision

    Parameters

    • num number Number
    • precision number Precision (optional, default 0)

    Examples

    turf.round(120.4321)
    //=120
    
    turf.round(120.4321, 2)
    //=120.43

    Returns number rounded number

    radiansToLength

    Convert a distance measurement (assuming a spherical Earth) from radians to a more friendly unit. Valid units: miles, nauticalmiles, inches, yards, meters, metres, kilometers, centimeters, feet

    Parameters

    • radians number in radians across the sphere
    • units string can be degrees, radians, miles, or kilometers inches, yards, metres, meters, kilometres, kilometers. (optional, default 'kilometers')

    Returns number distance

    lengthToRadians

    Convert a distance measurement (assuming a spherical Earth) from a real-world unit into radians Valid units: miles, nauticalmiles, inches, yards, meters, metres, kilometers, centimeters, feet

    Parameters

    • distance number in real units
    • units string can be degrees, radians, miles, or kilometers inches, yards, metres, meters, kilometres, kilometers. (optional, default 'kilometers')

    Returns number radians

    lengthToDegrees

    Convert a distance measurement (assuming a spherical Earth) from a real-world unit into degrees Valid units: miles, nauticalmiles, inches, yards, meters, metres, centimeters, kilometres, feet

    Parameters

    • distance number in real units
    • units string can be degrees, radians, miles, or kilometers inches, yards, metres, meters, kilometres, kilometers. (optional, default 'kilometers')

    Returns number degrees

    bearingToAzimuth

    Converts any bearing angle from the north line direction (positive clockwise) and returns an angle between 0-360 degrees (positive clockwise), 0 being the north line

    Parameters

    • bearing number angle, between -180 and +180 degrees

    Returns number angle between 0 and 360 degrees

    radiansToDegrees

    Converts an angle in radians to degrees

    Parameters

    • radians number angle in radians

    Returns number degrees between 0 and 360 degrees

    degreesToRadians

    Converts an angle in degrees to radians

    Parameters

    • degrees number angle between 0 and 360 degrees

    Returns number angle in radians

    convertLength

    Converts a length to the requested unit. Valid units: miles, nauticalmiles, inches, yards, meters, metres, kilometers, centimeters, feet

    Parameters

    • length number to be converted
    • originalUnit string of the length
    • finalUnit string returned unit (optional, default 'kilometers')

    Returns number the converted length

    convertArea

    Converts a area to the requested unit. Valid units: kilometers, kilometres, meters, metres, centimetres, millimeters, acres, miles, yards, feet, inches, hectares

    Parameters

    • area number to be converted
    • originalUnit string of the distance (optional, default 'meters')
    • finalUnit string returned unit (optional, default 'kilometers')

    Returns number the converted distance

    isNumber

    isNumber

    Parameters

    • num any Number to validate

    Examples

    turf.isNumber(123)
    //=true
    turf.isNumber('foo')
    //=false

    Returns boolean true/false

    isObject

    isObject

    Parameters

    • input any variable to validate

    Examples

    turf.isObject({elevation: 10})
    //=true
    turf.isObject('foo')
    //=false

    Returns boolean true/false


    This module is part of the Turfjs project, an open source module collection dedicated to geographic algorithms. It is maintained in the Turfjs/turf repository, where you can create PRs and issues.

    Installation

    Install this module individually:

    $ npm install @turf/helpers

    Or install the Turf module that includes it as a function:

    $ npm install @turf/turf

    Install

    npm i @turf/helpers

    DownloadsWeekly Downloads

    1,047,022

    Version

    6.5.0

    License

    MIT

    Unpacked Size

    93.6 kB

    Total Files

    10

    Last publish

    Collaborators

    • jamesmilneruk
    • rowanwins
    • tmcw
    • morganherlocker
    • tcql
    • deniscarriere
    • mdfedderly