turfpy.transformation 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.transformation.circle(center, radius, steps=64, units='km', **kwargs)

Takes a Point and calculates the circle polygon given a radius in degrees, radians, miles, or kilometers; and steps for precision.

Parameters

• center (geojson.feature.Feature) – A Point object representing center point of circle.

• radius (int) – An int representing radius of the circle.

• steps (int) – An int representing number of steps.

• units (str) – A string representing units of distance e.g. ‘mi’, ‘km’, ‘deg’ and ‘rad’.

• kwargs – A dict representing additional properties.

Returns

A polygon feature object.

Return type

geojson.geometry.Polygon

Example:

>>> from turfpy.transformation import circle
>>> from geojson import Feature, Point
>>> circle(center=Feature(geometry=Point((-75.343, 39.984))), radius=5, steps=10)

turfpy.transformation.bbox_clip(geojson, bbox)

Takes a Feature or geometry and a bbox and clips the feature to the bbox :param geojson: Geojson data :param bbox: Bounding Box which is used to clip the geojson :return: Clipped geojson

Example:

>>> from turfpy.transformation import bbox_clip
>>> from geojson import Feature
>>> f = Feature(geometry={"coordinates": [[[2, 2], [8, 4],
>>> [12, 8], [3, 7], [2, 2]]], "type": "Polygon"})
>>> bbox = [0, 0, 10, 10]
>>> clip = bbox_clip(f, bbox)

Parameters

• geojson (geojson.feature.Feature) –

• bbox (list) –

Return type

geojson.feature.Feature

turfpy.transformation.intersect(features)

Takes polygons and finds their intersection :param features: List of features of Feature Collection :return: Intersection Geojson Feature

Example:

>>> from turfpy.transformation import intersect
>>> from geojson import Feature
>>> f = Feature(geometry={"coordinates": [
>>> [[-122.801742, 45.48565], [-122.801742, 45.60491],
>>> [-122.584762, 45.60491], [-122.584762, 45.48565],
>>> [-122.801742, 45.48565]]], "type": "Polygon"})
>>> b = Feature(geometry={"coordinates": [
>>> [[-122.520217, 45.535693], [-122.64038, 45.553967],
>>> [-122.720031, 45.526554], [-122.669906, 45.507309],
>>> [-122.723464, 45.446643], [-122.532577, 45.408574],
>>> [-122.487258, 45.477466], [-122.520217, 45.535693]
>>> ]], "type": "Polygon"})
>>> inter = intersect([f, b])

Parameters

features (Union[List[geojson.feature.Feature], geojson.feature.FeatureCollection]) –

Return type

geojson.feature.Feature

turfpy.transformation.bezier_spline(line, resolution=10000, sharpness=0.85)

Takes a line and returns a curved version by applying a Bezier spline algorithm :param line: LineString Feature which is used to draw the curve :param resolution: time in milliseconds between points :param sharpness: a measure of how curvy the path should be between splines :return: Curve as LineString Feature

Example:

>>> from geojson import LineString, Feature
>>> from turfpy.transformation import bezier_spline
>>> ls = LineString([(-76.091308, 18.427501),
>>>                     (-76.695556, 18.729501),
>>>                     (-76.552734, 19.40443),
>>>                     (-74.61914, 19.134789),
>>>                     (-73.652343, 20.07657),
>>>                     (-73.157958, 20.210656)])
>>> f = Feature(geometry=ls)
>>> bezier_spline(f)

Parameters

line (geojson.feature.Feature) –

Return type

geojson.feature.Feature

turfpy.transformation.merge_dict(dicts)

Parameters

dicts (list) –

turfpy.transformation.union(features)

Given list of features or FeatureCollection return union of those.

Parameters

features (Union[List[geojson.feature.Feature], geojson.feature.FeatureCollection]) – A list of GeoJSON features or FeatureCollection.

Returns

A GeoJSON Feature or FeatureCollection.

Return type

Union[geojson.feature.Feature, geojson.feature.FeatureCollection]

Example:

>>> from turfpy.transformation import union
>>> from geojson import Feature, Polygon, FeatureCollection
>>> f1 = Feature(geometry=Polygon([[
...          [-82.574787, 35.594087],
...          [-82.574787, 35.615581],
...          [-82.545261, 35.615581],
...          [-82.545261, 35.594087],
...          [-82.574787, 35.594087]
...      ]]), properties={"fill": "#00f"})
>>> f2 = Feature(geometry=Polygon([[
...          [-82.560024, 35.585153],
...          [-82.560024, 35.602602],
...          [-82.52964, 35.602602],
...          [-82.52964, 35.585153],
...          [-82.560024, 35.585153]]]), properties={"fill": "#00f"})
>>> union(FeatureCollection([f1, f2], properties={"combine": "yes"}))

turfpy.transformation._alpha_shape(points, alpha)

Compute the alpha shape (concave hull) of a set of points.

Parameters

• points – Iterable container of points.

• alpha – alpha value to influence the gooeyness of the border. Smaller numbers don’t fall inward as much as larger numbers. Too large, and you lose everything!

turfpy.transformation.get_points(features)

turfpy.transformation.get_ext_points(geom, points)

turfpy.transformation.concave(features, alpha=2)

Generate concave hull for the given feature or Feature Collection.

Parameters

• features (Union[geojson.feature.Feature, geojson.feature.FeatureCollection]) – It can be a feature or Feature Collection

• alpha – Alpha determines the shape of concave hull, greater values will make shape more tighten

Returns

Feature of concave hull polygon

Example:

>>> from turfpy.transformation import concave
>>> from geojson import FeatureCollection, Feature, Point
>>> f1 = Feature(geometry=Point((-63.601226, 44.642643)))
>>> f2 = Feature(geometry=Point((-63.591442, 44.651436)))
>>> f3 = Feature(geometry=Point((-63.580799, 44.648749)))
>>> f4 = Feature(geometry=Point((-63.573589, 44.641788)))
>>> f5 = Feature(geometry=Point((-63.587665, 44.64533)))
>>> f6 = Feature(geometry=Point((-63.595218, 44.64765)))
>>> fc = [f1, f2, f3, f4, f5, f6]
>>> concave(FeatureCollection(fc), alpha=100)

turfpy.transformation.convex(features)

Generate convex hull for the given feature or Feature Collection

Parameters

features (Union[geojson.feature.Feature, geojson.feature.FeatureCollection]) – It can be a feature or Feature Collection

Returns

Feature of convex hull polygon

Example:

>>> from turfpy.transformation import convex
>>> from geojson import FeatureCollection, Feature, Point
>>> f1 = Feature(geometry=Point((10.195312, 43.755225)))
>>> f2 = Feature(geometry=Point((10.404052, 43.8424511)))
>>> f3 = Feature(geometry=Point((10.579833, 43.659924)))
>>> f4 = Feature(geometry=Point((10.360107, 43.516688)))
>>> f5 = Feature(geometry=Point((10.14038, 43.588348)))
>>> f6 = Feature(geometry=Point((10.195312, 43.755225)))
>>> fc = [f1, f2, f3, f4, f5, f6]
>>> convex(FeatureCollection(fc))

turfpy.transformation.dissolve(features, property_name=None)

Take FeatureCollection or list of features to dissolve based on property_name provided. :param features: A list of GeoJSON features or FeatureCollection. :param property_name: Name of property based on which to dissolve. :return: A GeoJSON Feature or FeatureCollection.

Example:

>>> from geojson import Polygon, Feature, FeatureCollection
>>> from turfpy.transformation import dissolve
>>> f1 = Feature(geometry=Polygon([[
>>>     [0, 0],
>>>     [0, 1],
>>>     [1, 1],
>>>     [1, 0],
>>>     [0, 0]]]), properties={"combine": "yes", "fill": "#00f"})
>>> f2 = Feature(geometry=Polygon([[
>>>     [0, -1],
>>>     [0, 0],
>>>     [1, 0],
>>>     [1, -1],
>>>     [0,-1]]]), properties={"combine": "yes"})
>>> f3 = Feature(geometry=Polygon([[
>>>     [1,-1],
>>>     [1, 0],
>>>     [2, 0],
>>>     [2, -1],
>>>     [1, -1]]]), properties={"combine": "no"})
>>> dissolve(FeatureCollection([f1, f2, f3]), property_name='combine')

Parameters

• features (Union[List[geojson.feature.Feature], geojson.feature.FeatureCollection]) –

• property_name (Optional[str]) –

Return type

geojson.feature.FeatureCollection

turfpy.transformation.difference(feature_1, feature_2)

Find the difference between given two features. :param feature_1: A GeoJSON feature :param feature_2: A GeoJSON feature :return: A GeoJSON feature

Example:

>>> from geojson import Polygon, Feature
>>> from turfpy.transformation import difference
>>> f1 = Feature(geometry=Polygon([[
>>>     [128, -26],
>>>     [141, -26],
>>>     [141, -21],
>>>     [128, -21],
>>>     [128, -26]]]), properties={"combine": "yes", "fill": "#00f"})
>>> f2 = Feature(geometry=Polygon([[
>>>     [126, -28],
>>>     [140, -28],
>>>     [140, -20],
>>>     [126, -20],
>>>     [126, -28]]]), properties={"combine": "yes"})
>>> difference(f1, f2)

Parameters

• feature_1 (geojson.feature.Feature) –

• feature_2 (geojson.feature.Feature) –

Return type

geojson.feature.Feature

turfpy.transformation.transform_rotate(feature, angle, pivot=None, mutate=False)

Rotates any geojson Feature or Geometry of a specified angle, around its centroid or a given pivot point; all rotations follow the right-hand rule.

Parameters

• feature (Union[List[geojson.feature.Feature], geojson.feature.FeatureCollection]) – Geojson to be rotated.

• angle (float) – angle of rotation (along the vertical axis), from North in decimal degrees, negative clockwise

• pivot (Optional[list]) – point around which the rotation will be performed

• mutate (bool) – allows GeoJSON input to be mutated (significant performance increase if True)

Returns

the rotated GeoJSON

Example :-

>>> from turfpy.transformation import transform_rotate
>>> from geojson import Polygon, Feature
>>> f = Feature(geometry=Polygon([[[0,29],[3.5,29],[2.5,32],[0,29]]]))
>>> pivot = [0, 25]
>>> transform_rotate(f, 10, pivot)

turfpy.transformation.transform_translate(feature, distance, direction, units='km', z_translation=0, mutate=False)

Moves any geojson Feature or Geometry of a specified distance along a Rhumb Line on the provided direction angle.

Parameters

• feature (Union[List[geojson.feature.Feature], geojson.feature.FeatureCollection]) – Geojson data that is to be translated

• distance (float) – length of the motion; negative values determine motion in opposite direction

• direction (float) – of the motion; angle from North in decimal degrees, positive clockwise

• units (str) – units for the distance and z_translation

• z_translation (float) – length of the vertical motion, same unit of distance

• mutate (bool) – allows GeoJSON input to be mutated (significant performance increase if true)

Returns

the translated GeoJSON

Example :-

>>> from turfpy.transformation import transform_translate
>>> from geojson import Polygon, Feature
>>> f = Feature(geometry=Polygon([[[0,29],[3.5,29],[2.5,32],[0,29]]]))
>>> transform_translate(f, 100, 35, mutate=True)

turfpy.transformation.transform_scale(features, factor, origin='centroid', mutate=False)

Scale a GeoJSON from a given point by a factor of scaling (ex: factor=2 would make the GeoJSON 200% larger). If a FeatureCollection is provided, the origin point will be calculated based on each individual Feature.

Parameters

• features – GeoJSON to be scaled

• factor (float) – of scaling, positive or negative values greater than 0

• origin (Union[str, list]) – Point from which the scaling will occur (string options: sw/se/nw/ne/center/centroid)

• mutate (bool) – allows GeoJSON input to be mutated (significant performance increase if true)

Returns

Scaled Geojson

Example :-

>>> from turfpy.transformation import transform_scale
>>> from geojson import Polygon, Feature
>>> f = Feature(geometry=Polygon([[[0,29],[3.5,29],[2.5,32],[0,29]]]))
>>> transform_scale(f, 3, origin=[0, 29])

turfpy.transformation.scale(feature, factor, origin)

turfpy.transformation.define_origin(geojson, origin)

turfpy.transformation.tesselate(poly)

Tesselates a Feature into a FeatureCollection of triangles using earcut.

Parameters

poly (geojson.feature.Feature) – A GeoJSON feature class:geojson.Polygon.

Returns

A GeoJSON FeatureCollection of triangular polygons.

Return type

geojson.feature.FeatureCollection

Example:

>>> from geojson import Feature
>>> from turfpy.transformation import tesselate
>>> polygon = Feature(geometry={"coordinates": [[[11, 0], [22, 4], [31, 0], [31, 11],
... [21, 15], [11, 11], [11, 0]]], "type": "Polygon"})
>>> tesselate(polygon)

turfpy.transformation.__process_polygon(coordinates)

turfpy.transformation.__flatten_coords(data)

turfpy.transformation.line_offset(geojson, distance, unit='km')

Takes a linestring or multilinestring and returns a line at offset by the specified distance.

Parameters

• geojson (geojson.feature.Feature) – input GeoJSON

• distance (float) – distance to offset the line (can be of negative value)

• unit (str) – Units in which distance to be calculated, values can be ‘deg’, ‘rad’, ‘mi’, ‘km’, default is ‘km’

Returns

Line feature offset from the input line

Return type

geojson.feature.Feature

Example:

>>> from geojson import MultiLineString, Feature
>>> from turfpy.transformation import line_offset
>>> ls = Feature(geometry=MultiLineString([
... [(3.75, 9.25), (-130.95, 1.52)],
... [(23.15, -34.25), (-1.35, -4.65), (3.45, 77.95)]
... ]))
>>> line_offset(ls, 2, unit='mi')

turfpy.transformation.line_offset_feature(line, distance, units)

turfpy.transformation._process_segment(point1, point2, offset)

turfpy.transformation._intersection(a, b)

turfpy.transformation._is_parallel(a, b)

turfpy.transformation._ab(segment)

turfpy.transformation._cross_product(v1, v2)

turfpy.transformation._intersect_segments(a, b)

turfpy.transformation._add(v1, v2)

turfpy.transformation._sub(v1, v2)

turfpy.transformation._scalar_mult(s, v)

turfpy.transformation.voronoi(points, bbox=None)

Takes a FeatureCollection of points, and a bounding box, and returns a FeatureCollection of Voronoi polygons.

Parameters

• points (Union[geojson.feature.FeatureCollection, List]) – To find the Voronoi polygons around. Points should be either FeatureCollection of points or list of points.

• bbox (Optional[list]) – A bounding box to clip.

Returns

A GeoJSON Feature.

Return type

geojson.feature.Feature

Example:

>>> from turfpy.transformation import voronoi
>>> points = [
... [-66.9703, 40.3183],
... [-63.7763, 40.4500],
... [-65.4196, 42.13985310302137],
... [-69.5813, 43.95405461286195],
... [-65.66337553550034, 55.97088945355232],
... [-60.280418548905, 56.240669185466146],
... [-68.5129561347689, 50.12984589640148],
... [-64.2393519226657, 59.66235385923687],
... ]
>>> bbox = [-70, 40, -60, 60]
>>> voronoi(points, bbox)