Geo.Turf.Classification (geo_turf v0.6.0)

Copy Markdown View Source

A collection of classification and boolean spatial functions.

Summary

Types

line_location()

Functions

nearest_point(target, points, opts \\ [])

Takes a reference Point and a list of Points and returns the point closest to the reference. Distance is calculated geodesically (Haversine).

nearest_point_on_line(point, line, opts \\ [])

Snaps a Point to the nearest point on a LineString or MultiLineString.

point_in_polygon?(point, polygon, opts \\ [])

Takes a Point and a Polygon (or MultiPolygon) and determines whether the Point lies inside the shape. Points on the boundary are considered inside unless :ignore_boundary is set to true. Empty polygons return false.

point_on_line?(point, line, opts \\ [])

Tests whether a Point lies on a LineString or MultiLineString.

points_within_polygon(points, polygon)

Filters a list of Points to those falling inside the given Polygon or MultiPolygon.

Types

line_location()

@type line_location() :: %{
  distance: float(),
  location: float(),
  segment_index: non_neg_integer(),
  line_index: non_neg_integer()
}

Functions

nearest_point(target, points, opts \\ [])

@spec nearest_point(Geo.Point.t(), [Geo.Point.t()], keyword()) :: Geo.Point.t() | nil

Takes a reference Point and a list of Points and returns the point closest to the reference. Distance is calculated geodesically (Haversine).

Returns nil if the list is empty.

Options

Examples

iex> target = %Geo.Point{coordinates: {28.965797, 41.010086}}
...> points = [
...>   %Geo.Point{coordinates: {28.973865, 41.011122}},
...>   %Geo.Point{coordinates: {28.948459, 41.024204}},
...>   %Geo.Point{coordinates: {28.938674, 41.013324}}
...> ]
...> Geo.Turf.Classification.nearest_point(target, points)
%Geo.Point{coordinates: {28.973865, 41.011122}}

iex> Geo.Turf.Classification.nearest_point(%Geo.Point{coordinates: {0, 0}}, [])
nil

nearest_point_on_line(point, line, opts \\ [])

@spec nearest_point_on_line(
  Geo.Point.t(),
  Geo.LineString.t() | Geo.MultiLineString.t(),
  keyword()
) :: {:ok, Geo.Point.t(), line_location()} | :error

Snaps a Point to the nearest point on a LineString or MultiLineString.

Returns {:ok, point, metadata}. point has WGS84 SRID 4326; metadata contains the raw point-to-line :distance, the raw along-line :location, and zero-based :segment_index and :line_index. A LineString has line_index 0; for a MultiLineString it identifies the member containing the snapped segment. :distance and :location use :units, which defaults to :kilometers.

Returns :error when the line contains no coordinates.

point_in_polygon?(point, polygon, opts \\ [])

@spec point_in_polygon?(
  Geo.Point.t(),
  Geo.Polygon.t() | Geo.MultiPolygon.t(),
  keyword()
) :: boolean()

Takes a Point and a Polygon (or MultiPolygon) and determines whether the Point lies inside the shape. Points on the boundary are considered inside unless :ignore_boundary is set to true. Empty polygons return false.

Options

  • :ignore_boundary - when true, points on the polygon boundary return false. Defaults to false.

Examples

iex> poly = %Geo.Polygon{coordinates: [[{0, 0}, {0, 4}, {4, 4}, {4, 0}, {0, 0}]]}
...> Geo.Turf.Classification.point_in_polygon?(%Geo.Point{coordinates: {2, 2}}, poly)
true

iex> poly = %Geo.Polygon{coordinates: [[{0, 0}, {0, 4}, {4, 4}, {4, 0}, {0, 0}]]}
...> Geo.Turf.Classification.point_in_polygon?(%Geo.Point{coordinates: {5, 5}}, poly)
false

point_on_line?(point, line, opts \\ [])

@spec point_on_line?(
  Geo.Point.t(),
  Geo.LineString.t() | Geo.MultiLineString.t(),
  keyword()
) :: boolean()

Tests whether a Point lies on a LineString or MultiLineString.

Endpoints are included. :tolerance is an inclusive maximum geodesic distance from the line in the requested :units; it defaults to zero. :units defaults to :kilometers. Empty lines return false.

Examples

iex> line = %Geo.LineString{coordinates: [{0, 0}, {2, 0}]}
...> Geo.Turf.Classification.point_on_line?(
...>   %Geo.Point{coordinates: {1, 0}},
...>   line
...> )
true

points_within_polygon(points, polygon)

@spec points_within_polygon(
  [Geo.Point.t()],
  Geo.Polygon.t() | Geo.MultiPolygon.t()
) :: [Geo.Point.t()]

Filters a list of Points to those falling inside the given Polygon or MultiPolygon.

Examples

iex> poly = %Geo.Polygon{coordinates: [[{0, 0}, {0, 4}, {4, 4}, {4, 0}, {0, 0}]]}
...> points = [%Geo.Point{coordinates: {2, 2}}, %Geo.Point{coordinates: {5, 5}}]
...> Geo.Turf.Classification.points_within_polygon(points, poly)
[%Geo.Point{coordinates: {2, 2}}]