@spec along(Geo.LineString.t(), number(), Geo.Turf.Math.length_unit()) ::
  Geo.Point.t() | :error

Takes a LineString and returns a Point at a specified distance along the line. Returns :error if the LineString has no coordinates.

Examples

iex> %Geo.LineString{coordinates: [{-23.621,64.769},{-23.629,64.766},{-23.638,64.766}]}
...>   |> Geo.Turf.Measure.along(2, :kilometers)
%Geo.Point{coordinates: {-23.638,64.766}, srid: 4326}

iex> Geo.Turf.Measure.along(%Geo.LineString{coordinates: []}, 1, :kilometers)
:error

@spec along_midpoint(Geo.LineString.t()) :: Geo.Point.t() | :error

Takes a LineString and returns a Point at the middle of the line.

Examples

iex> %Geo.LineString{coordinates: [{-23.621,64.769},{-23.629,64.766},{-23.638,64.766}]}
...>   |> Geo.Turf.Measure.along_midpoint()
...>   |> Geo.Turf.Math.approx(4)
%Geo.Point{coordinates: {-23.6284, 64.7662}, srid: 4326}

@spec area(Geo.geometry()) :: number()

Takes a geometry and returns its area in square meters. Geometries without area, including empty geometries, return 0.

Examples

iex> %Geo.Polygon{coordinates: [[{125, -15}, {113, -22}, {154, -27}, {144, -15}, {125, -15}]]}
...>   |> Geo.Turf.Measure.area()
3332484969239.2676

@spec bearing(Geo.Point.t(), Geo.Point.t()) :: float()

Takes two points and finds the geographic bearing between them, i.e. the angle measured in degrees from the north line (0 degrees)

Examples

iex> point1 = %Geo.Point{coordinates: {-75.343, 39.984}}
...> point2 = %Geo.Point{coordinates: {-75.534, 39.123}}
...> Geo.Turf.Measure.bearing(point1, point2)
...>  |> Geo.Turf.Math.rounded(2)
-170.23

@spec center(Geo.geometry()) :: Geo.Point.t() | :error

Finds the center of a Geo.geometry() bounding box and returns a Geo.Point. Returns :error when the geometry contains no coordinates.

Examples

iex> Geo.Turf.Measure.center(%Geo.Polygon{coordinates: [{0,0}, {0,10}, {10,10}, {10,0}]})
%Geo.Point{coordinates: {5, 5}, srid: 4326}

@spec centroid(Geo.geometry()) :: Geo.Point.t() | :error

Computes the centroid of a geometry as the mean position of all vertices. Closed polygon rings have their repeated closing vertex excluded, matching the behaviour of turf.centroid. Returns :error when the geometry contains no coordinates.

Examples

iex> Geo.Turf.Measure.centroid(%Geo.Polygon{coordinates: [[{-81, 41}, {-88, 36}, {-84, 31}, {-80, 33}, {-77, 39}, {-81, 41}]]})
%Geo.Point{coordinates: {-82.0, 36.0}, srid: 4326}

iex> Geo.Turf.Measure.centroid(%Geo.LineString{coordinates: [{0, 0}, {4, 0}, {4, 4}]})
%Geo.Point{coordinates: {2.6666666666666665, 1.3333333333333333}, srid: 4326}

iex> Geo.Turf.Measure.centroid(%Geo.Point{coordinates: {1.0, 2.0}})
%Geo.Point{coordinates: {1.0, 2.0}, srid: 4326}

@spec close_to(Geo.Point.t(), Geo.Point.t(), number(), Geo.Turf.Math.length_unit()) ::
  boolean()

Verifies that two points are within a maximum raw geodesic distance of each other. The maximum is inclusive and defaults to 100 meters.

Examples

iex> %Geo.Point{coordinates: {-22.653375, 64.844254}}
...> |> Geo.Turf.Measure.close_to(%Geo.Point{coordinates: {-22.654042, 64.843656}})
true

iex> %Geo.Point{coordinates: {-22.653375, 64.844254}}
...> |> Geo.Turf.Measure.close_to(%Geo.Point{coordinates: {-23.803020, 64.730435}}, 100, :kilometers)
true

@spec destination(
  origin :: Geo.Point.t(),
  distance :: number(),
  bearing :: number(),
  options :: [units()]
) :: Geo.Point.t()

Takes in an origin %Geo.Point{} and calculates the destination of a new %Geo.Point{} at a given distance and bearing away from the origin point.

This uses the Haversine formula to account for global curvature. See the turf.destination documentation for more information.

Parameters

• origin - the origin point
• distance - the distance from the origin point to the destination point
• bearing - the angle from the origin point to the destination point
• opts - a keyword list of options

Options

• :units - the unit of the distance, defaults to :kilometers

Examples

iex> %Geo.Point{coordinates: {-75.343, 39.984}}
...>   |> Geo.Turf.Measure.destination(100, 180, units: :kilometers)
%Geo.Point{coordinates: {-75.343, 39.08467963627546}, srid: 4326}

@spec distance(Geo.Point.t(), Geo.Point.t(), Geo.Turf.Math.length_unit()) :: float()

Calculates the distance between two points in degrees, radians, miles, or kilometers. This uses the Haversine formula to account for global curvature. Returns the raw floating-point result; use Geo.Turf.Math.rounded/2 when display rounding is needed.

Examples

iex> Geo.Turf.Measure.distance(
...>   %Geo.Point{coordinates: {-75.343, 39.984}},
...>   %Geo.Point{coordinates: {-75.534, 39.123}},
...>   :kilometers)
97.12922118967835

@spec final_bearing(Geo.Point.t(), Geo.Point.t()) :: float()

Takes two points and finds the final bearing between them, i.e. the bearing as it arrives at the destination point. Returns degrees in the range [-180, 180].

Examples

iex> point1 = %Geo.Point{coordinates: {-75.343, 39.984}}
...> point2 = %Geo.Point{coordinates: {-75.534, 39.123}}
...> Geo.Turf.Measure.final_bearing(point1, point2)
...>  |> Geo.Turf.Math.rounded(2)
-170.35

@spec length_of(Geo.geometry(), Geo.Turf.Math.length_unit()) :: number()

Takes a t:Geo.geometry() and measures its length in the specified units. length_of/2 is the canonical name because it avoids ambiguity with Kernel.length/1.

LineString paths and every independent MultiLineString member, polygon ring, MultiPolygon ring, and GeometryCollection child path contribute to the result. Separate paths are measured independently and are never joined. Point and MultiPoint geometries contribute no length. Empty geometries return 0.

Examples

iex> %Geo.LineString{coordinates: [{-23.621,64.769},{-23.629,64.766},{-23.638,64.766}]}
...>   |> Geo.Turf.Measure.length_of()
0.93