turfpy.measurement module

This module implements some of the spatial analysis techniques and processes used to understand the patterns and relationships of geographic features. This is mainly inspired by turf.js. link: http://turfjs.org/

turfpy.measurement.bearing(start, end, final=False)

Takes two Point and finds the geographic bearing between them.

Parameters

• start (geojson.feature.Feature) – A object of Point to represent start point.

• end (geojson.feature.Feature) – A object of Point to represent end point.

• final – A boolean calculates the final bearing if True.

Returns

A float calculated bearing.

Return type

float

Example:

>>> from geojson import Point, Feature
>>> from turfpy import measurement
>>> start = Feature(geometry=Point((-75.343, 39.984)))
>>> end = Feature(geometry=Point((-75.534, 39.123)))
>>> measurement.bearing(start,end)

turfpy.measurement._calculate_final_bearing(start, end)

#TODO: Add description

Return type

float

turfpy.measurement.distance(point1, point2, units='km')

Calculates distance between two Points. A point is containing latitude and logitude in decimal degrees and unit is optional.

It calculates distance in units such as kilometers, meters, miles, feet and inches.

Parameters

• point1 (geojson.feature.Feature) – first point; tuple of (latitude, longitude) in decimal degrees.

• point2 (geojson.feature.Feature) – second point; tuple of (latitude, longitude) in decimal degrees.

• units (str) – A string containing unit, E.g. kilometers = ‘km’, miles = ‘mi’, meters = ‘m’, feet = ‘ft’, inches = ‘in’.

Returns

The distance between the two points in the requested unit, as a float.

Example:

>>> from turfpy import measurement
>>> from geojson import Point, Feature
>>> start = Feature(geometry=Point((-75.343, 39.984)))
>>> end = Feature(geometry=Point((-75.534, 39.123)))
>>> measurement.distance(start,end)

turfpy.measurement.area(geojson)

This function calculates the area of the Geojson object given as input.

Parameters

geojson (Union[geojson.geometry.Point, geojson.geometry.LineString, geojson.geometry.Polygon, geojson.geometry.MultiPoint, geojson.geometry.MultiLineString, geojson.geometry.MultiPolygon, geojson.feature.Feature, geojson.feature.FeatureCollection]) – Geojson object for which area is to be found.

Returns

area for the given Geojson object in square meters.

Example:

>>> from turfpy.measurement import area
>>> from geojson import Feature, FeatureCollection
>>> geometry_1 = {"coordinates": [[[0, 0], [0, 10], [10, 10], [10, 0], [0, 0]]],"type": "Polygon"}  # noqa E501
>>> geometry_2 = {"coordinates": [[[2.38, 57.322], [23.194, -20.28], [-120.43, 19.15],[2.38, 57.322]]], "type": "Polygon"}  # noqa E501
>>> feature_1 = Feature(geometry=geometry_1)
>>> feature_2 = Feature(geometry=geometry_2)
>>> feature_collection = FeatureCollection([feature_1, feature_2])

>>> area(feature_collection)

turfpy.measurement.bbox(geojson)

This function is used to generate bounding box coordinates for given geojson.

Parameters

geojson – Geojson object for which bounding box is to be found.

Returns

bounding box for the given Geojson object.

Example :

>>> from turfpy.measurement import bbox
>>> from geojson import Polygon

>>> p = Polygon([(2.38, 57.322), (23.194, -20.28), (-120.43, 19.15),(2.38, 57.322)])
>>> bb = bbox(p)

turfpy.measurement.bbox_polygon(bbox, properties={})

To generate a Polygon Feature for the bounding box generated using bbox.

Parameters

• bbox (list) – bounding box generated for a geojson.

• properties (dict) – properties to be added to the returned feature.

Returns

polygon for the given bounding box coordinates.

Return type

geojson.feature.Feature

Example :

>>> from turfpy.measurement import bbox_polygon, bbox
>>> from geojson import Polygon

>>> p = Polygon([((2.38, 57.322), (23.194, -20.28), (-120.43, 19.15),
... (2.38, 57.322))])
>>> bb = bbox(p)
>>> feature = bbox_polygon(bb)

turfpy.measurement.center(geojson, properties=None)

Takes a Feature or FeatureCollection and returns the absolute center point of all features.

Parameters

• geojson – GeoJSON for which centered to be calculated.

• properties (Optional[dict]) – Optional parameters to be set to the generated feature.

Returns

Point feature for the center.

Return type

geojson.feature.Feature

Example :

>>> from turfpy.measurement import center
>>> from geojson import Feature, FeatureCollection, Point

>>> f1 = Feature(geometry=Point((-97.522259, 35.4691)))
>>> f2 = Feature(geometry=Point((-97.502754, 35.463455)))
>>> f3 = Feature(geometry=Point((-97.508269, 35.463245)))
>>> feature_collection = FeatureCollection([f1, f2, f3])
>>> feature = center(feature_collection)

turfpy.measurement.envelope(geojson)

Takes any number of features and returns a rectangular Polygon that encompasses all vertices.

Parameters

geojson – geojson input features for which envelope to be generated.

Returns

returns envelope i.e bounding box polygon.

Return type

geojson.feature.Feature

Example :

>>> from turfpy.measurement import envelope
>>> from geojson import Feature, FeatureCollection, Point

>>> f1 = Feature(geometry=Point((-97.522259, 35.4691)))
>>> f2 = Feature(geometry=Point((-97.502754, 35.463455)))
>>> f3 = Feature(geometry=Point((-97.508269, 35.463245)))
>>> feature_collection = FeatureCollection([f1, f2, f3])
>>> feature = envelope(feature_collection)

turfpy.measurement.length(geojson, units='km')

Takes a geojson and measures its length in the specified units.

Parameters

• geojson – geojson for which the length is to be determined.

• units (str) – units in which length is to be returned.

Returns

length of the geojson in specified units.

Example:

>>> from turfpy.measurement import length
>>> from geojson import LineString
>>> ls = LineString([(115, -32), (131, -22), (143, -25), (150, -34)])
>>> length(ls)

turfpy.measurement.destination(origin, distance, bearing, options={})

Takes a Point and calculates the location of a destination point given a distance in degrees, radians, miles, or kilometers and bearing in degrees.

Parameters

• origin (Union[geojson.feature.Feature, geojson.geometry.Point]) – Start point.

• distance – distance upto which the destination is from origin.

• bearing – Direction in which is the destination is from origin.

• options (dict) – Option like units of distance and properties to be passed to destination point feature, value for units are ‘mi’, ‘km’, ‘deg’ and ‘rad’.

Returns

Feature: destination point in at the given distance and given direction.

Return type

geojson.feature.Feature

Example:

>>> from turfpy.measurement import destination
>>> from geojson import Point, Feature
>>> origin = Feature(geometry=Point([-75.343, 39.984]))
>>> distance = 50
>>> bearing = 90
>>> options = {'units': 'mi'}
>>> destination(origin,distance,bearing,options)

turfpy.measurement.centroid(geojson, properties=None)

Takes one or more features and calculates the centroid using the mean of all vertices.

Parameters

• geojson – Input features

• properties (Optional[dict]) – Properties to be set to the output Feature point

Returns

Feature: Point feature which is the centroid of the given features

Return type

geojson.feature.Feature

Example:

>>> from turfpy.measurement import centroid
>>> from geojson import Polygon
>>> polygon = Polygon([((-81, 41), (-88, 36), (-84, 31), (-80, 33), (-77, 39),
(-81, 41))])
>>> centroid(polygon)

turfpy.measurement.along(line, dist, unit='km')

This function is used identify a Point at a specified distance along a LineString.

Parameters

• line (geojson.feature.Feature) – LineString on which the point to be identified

• dist – Distance from the start of the LineString

• unit (str) – unit of distance

Returns

Feature : Point at the distance on the LineString passed

Return type

geojson.feature.Feature

Example :

>>> from turfpy.measurement import along
>>> from geojson import LineString, Feature
>>> ls = Feature(geometry=LineString([(-83, 30), (-84, 36), (-78, 41)]))
>>> along(ls,200,'mi')

turfpy.measurement.midpoint(point1, point2)

This function is used to get midpoint between any the two points.

Parameters

• point1 (geojson.feature.Feature) – First point.

• point2 (geojson.feature.Feature) – Second point.

Returns

Feature: Point which is the midpoint of the two points given as input.

Return type

geojson.feature.Feature

Example:

>>> from turfpy.measurement import midpoint
>>> from geojson import Point, Feature
>>> point1 = Feature(geometry=Point((144.834823, -37.771257)))
>>> point2 = Feature(geometry=Point((145.14244, -37.830937)))
>>> midpoint(point1, point2)

turfpy.measurement.nearest_point(target_point, points)

Takes a reference Point Feature and FeatureCollection of point features and returns the point from the FeatureCollection closest to the reference Point Feature.

Parameters

• target_point (geojson.feature.Feature) – Feature Point of reference.

• points (geojson.feature.FeatureCollection) – FeatureCollection of points.

Returns

a Point Feature from the FeatureCollection which is closest to the reference Point.

Return type

geojson.feature.Feature

Example:

>>> from turfpy.measurement import nearest_point
>>> from geojson import Point, Feature, FeatureCollection
>>> f1 = Feature(geometry=Point((28.96991729736328,41.01190001748873)))
>>> f2 = Feature(geometry=Point((28.948459, 41.024204)))
>>> f3 = Feature(geometry=Point((28.938674, 41.013324)))
>>> fc = FeatureCollection([f1, f2 ,f3])
>>> t = Feature(geometry=Point((28.973865, 41.011122)))
>>> nearest_point(t ,fc)

turfpy.measurement.point_on_feature(geojson)

Takes a Feature or FeatureCollection and returns a Point guaranteed to be on the surface of the feature.

Parameters

geojson – Feature or FeatureCollection on which the Point is to be found.

Returns

Feature point which on the provided feature.

Return type

geojson.feature.Feature

Example:

>>> from turfpy.measurement import point_on_feature
>>> from geojson import  Polygon, Feature
>>> point = Polygon([((116, -36), (131, -32), (146, -43), (155, -25), (133, -9),
(111, -22), (116, -36))])
>>> feature = Feature(geometry=point)
>>> point_on_feature(feature)

turfpy.measurement._normalize(geojson)

turfpy.measurement._point_on_segment(x, y, x1, y1, x2, y2)

turfpy.measurement.boolean_point_in_polygon(point, polygon, ignore_boundary=False)

Takes a Point or a Point Feature and Polygon or Polygon Feature as input and returns True if Point is in given Feature.

Parameters

• point – Point or Point Feature.

• polygon – Polygon or Polygon Feature.

• ignore_boundary – [Optional] default value is False, specify whether to exclude boundary of the given polygon or not.

Returns

True if the given Point is in Polygons else False

Example:

>>> from turfpy.measurement import boolean_point_in_polygon
>>> from geojson import Point, MultiPolygon, Feature
>>> point = Feature(geometry=Point((-77, 44)))
>>> polygon = Feature(geometry=MultiPolygon([([(-81, 41), (-81, 47), (-72, 47),
(-72, 41), (-81, 41)],),
>>> ([(3.78, 9.28), (-130.91, 1.52), (35.12, 72.234), (3.78, 9.28)],)]))
>>> boolean_point_in_polygon(point, polygon)

turfpy.measurement.in_ring(pt, ring, ignore_boundary)

turfpy.measurement.in_bbox(pt, bbox)

turfpy.measurement.explode(geojson)

turfpy.measurement.polygon_tangents(point, polygon)

Finds the tangents of a (Multi)Polygon from a Point.

Parameters

• point – Point or Point Feature.

• polygon – (Multi)Polygon or (Multi)Polygon Feature.

Returns

FeatureCollection of two tangent Point Feature.

Example:

>>> from turfpy.measurement import polygon_tangents
>>> from geojson import Polygon, Point, Feature
>>> point = Feature(geometry=Point((61, 5)))
>>> polygon = Feature(geometry=Polygon([(11, 0), (22, 4), (31, 0), (31, 11),
...                                 (21, 15), (11, 11), (11, 0)]))
>>> polygon_tangents(point, polygon)

turfpy.measurement.process_polygon(polygon_coords, pt_coords, eprev, enext, rtan, ltan)

turfpy.measurement._is_above(point1, point2, point3)

turfpy.measurement._is_below(point1, point2, point3)

turfpy.measurement._is_left(point1, point2, point3)

turfpy.measurement.point_to_line_distance(point, line, units='km', method='geodesic')

Returns the minimum distance between a Point and any segment of the LineString.

Parameters

• point (geojson.feature.Feature) – Point Feature from which distance to be measured.

• line (geojson.feature.Feature) – Point LineString from which distance to be measured.

• units – units for distance ‘km’, ‘m’, ‘mi, ‘ft’, ‘in’, ‘deg’, ‘cen’, ‘rad’, ‘naut’, ‘yd’

• method – Method which is used to calculate, values can be ‘geodesic’ or ‘planar’

Returns

Approximate distance between the LineString and Point

Example:

>>> from turfpy.measurement import point_to_line_distance
>>> from geojson import LineString, Point, Feature
>>> point = Feature(geometry=Point((0, 0)))
>>> linestring = Feature(geometry=LineString([(1, 1),(-1, 1)]))
>>> point_to_line_distance(point, linestring)

turfpy.measurement.distance_to_segment(p, a, b, options)

turfpy.measurement._calc_distance(a, b, options)

turfpy.measurement._dot(u, v)

turfpy.measurement.rhumb_bearing(start, end, final=False)

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).

Parameters

• start – Start Point or Point Feature.

• end – End Point or Point Feature.

• final – Calculates the final bearing if true

Returns

bearing from north in decimal degrees, between -180 and 180 degrees (positive clockwise)

Example:

>>> from turfpy.measurement import rhumb_bearing
>>> from geojson import Feature, Point
>>> start = Feature(geometry=Point((-75.343, 39.984)))
>>> end = Feature(geometry=Point((-75.534, 39.123)))
>>> rhumb_bearing(start, end, True)

turfpy.measurement.calculate_rhumb_bearing(fro, to)

#TODO: Add description

turfpy.measurement.rhumb_destination(origin, distance, bearing, options={})

Returns the destination Point having travelled the given distance along a Rhumb line from the origin Point with the (varant) given bearing.

Parameters

• origin – Starting Point

• distance – Distance from the starting point

• bearing – Varant bearing angle ranging from -180 to 180 degrees from north

• options (dict) – A dict of two values ‘units’ for the units of distance provided and ‘properties’ that are to be passed to the Destination Feature Point Example :- {‘units’:’mi’, ‘properties’: {“marker-color”: “F00”}}

Returns

Destination Feature Point

Return type

geojson.feature.Feature

Example:

>>> from turfpy.measurement import rhumb_destination
>>> from geojson import Point, Feature
>>> start = Feature(geometry=Point((-75.343, 39.984)),
properties={"marker-color": "F00"})
>>> distance = 50
>>> bearing = 90
>>> rhumb_destination(start, distance, bearing, {'units':'mi',
'properties': {"marker-color": "F00"}})

turfpy.measurement._calculate_rhumb_destination(origin, distance, bearing, radius=None)

turfpy.measurement.rhumb_distance(start, to, units='km')

Calculates the distance along a rhumb line between two points in degrees, radians, miles, or kilometers.

Parameters

• start – Start Point or Point Feature from which distance to be calculated.

• to – End Point or Point Feature upto which distance to be calculated.

• units – Units in which distance to be calculated, values can be ‘deg’, ‘rad’, ‘mi’, ‘km’

Returns

Distance calculated from provided start to end Point.

Example:

>>> from turfpy.measurement import rhumb_distance
>>> from geojson import Point, Feature
>>> start = Feature(geometry=Point((-75.343, 39.984)))
>>> end = Feature(geometry=Point((-75.534, 39.123)))
>>> rhumb_distance(start, end,'mi')

turfpy.measurement._calculate_rhumb_distance(origin, destination_point, radius=None)

turfpy.measurement.square(bbox)

Takes a bounding box and calculates the minimum square bounding box that would contain the input.

Parameters

bbox (list) – Bounding box extent in west, south, east, north order

Returns

A square surrounding bbox

Example:

>>> from turfpy.measurement import square
>>> bbox = [-20, -20, -15, 0]
>>> square(bbox)

turfpy.measurement.points_within_polygon(points, polygons, chunk_size=1)

Find Point(s) that fall within (Multi)Polygon(s).

This function takes two inputs GeoJSON Feature geojson.Point or geojson.FeatureCollection of Points and GeoJSON Feature geojson.Polygon or Feature geojson.MultiPolygon or FeatureCollection of geojson.Polygon or Feature geojson.MultiPolygon. and returns all points with in in those Polygon(s) or (Multi)Polygon(s).

Parameters

• points (Union[geojson.feature.Feature, geojson.feature.FeatureCollection]) – A single GeoJSON Point feature or FeatureCollection of Points.

• polygons (Union[geojson.feature.Feature, geojson.feature.FeatureCollection]) – A Single GeoJSON Polygon/MultiPolygon or FeatureCollection of Polygons/MultiPolygons.

• chunk_size (int) – Number of chunks each process to handle. The default value is 1, for a large number of features please use chunk_size greater than 1 to get better results in terms of performance.

Returns

A geojson.FeatureCollection of Points.

Return type

geojson.feature.FeatureCollection

turfpy.measurement.check_each_point(point, polygons, results)