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)[source]¶
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)[source]¶
#TODO: Add description
- Return type
float
- turfpy.measurement.distance(point1, point2, units='km')[source]¶
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)[source]¶
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)[source]¶
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={})[source]¶
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)[source]¶
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)[source]¶
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')[source]¶
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={})[source]¶
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)[source]¶
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')[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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.boolean_point_in_polygon(point, polygon, ignore_boundary=False)[source]¶
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.polygon_tangents(point, polygon)[source]¶
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.point_to_line_distance(point, line, units='km', method='geodesic')[source]¶
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.rhumb_bearing(start, end, final=False)[source]¶
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.rhumb_destination(origin, distance, bearing, options={})[source]¶
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.rhumb_distance(start, to, units='km')[source]¶
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.square(bbox)[source]¶
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)[source]¶
Find Point(s) that fall within (Multi)Polygon(s).
This function takes two inputs GeoJSON Feature
geojson.Point
orgeojson.FeatureCollection
of Points and GeoJSON Featuregeojson.Polygon
or Featuregeojson.MultiPolygon
or FeatureCollection ofgeojson.Polygon
or Featuregeojson.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