# `Geo.Turf.Measure`
[🔗](https://github.com/JonGretar/GeoTurf/blob/main/lib/geo/turf/measure.ex#L1)

A collection of measurement related tools

# `units`

```elixir
@type units() :: {:units, Geo.Turf.Math.length_unit()}
```

# `along`

```elixir
@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.
Note that this will aproximate location to the nearest coordinate point.

## Examples

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

# `along_midpoint`

```elixir
@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.Point{coordinates: {-23.629, 64.766}}

# `area`

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

Takes a feature or collection and returns their area in square meters.

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

# `bearing`

```elixir
@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

# `center`

```elixir
@spec center(Geo.geometry()) :: Geo.Point.t()
```

Find the center of a `Geo.geometry()` item and give us a `Geo.Point`

## Examples

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

# `centroid`

```elixir
@spec centroid(Geo.geometry()) :: Geo.Point.t()
```

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

## 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}}

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

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

# `close_to`

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

Verifies that two points are close to each other. 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

# `destination`

```elixir
@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](http://en.wikipedia.org/wiki/Haversine_formula) to account for global curvature.
See the `turf.destination` [documentation](http://turfjs.org/docs/#destination) 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, unit: :kilometers)
    %Geo.Point{coordinates: {-75.343, 39.08467963627546}}

# `distance`

Calculates the distance between two points in degrees, radians, miles, or kilometers.
This uses the [Haversine formula](http://en.wikipedia.org/wiki/Haversine_formula) to account for global curvature.

## Examples

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

# `length_of`

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

Takes a `t:Geo.geometry()` and measures its length in the specified units.

## Examples

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

---

*Consult [api-reference.md](api-reference.md) for complete listing*