defmodule Topo do
  alias Topo.Intersects
  alias Topo.Contains
  alias Topo.Cleaner

  @moduledoc ~S"""
  A Geometry library for Elixir that calculates relationships between two
  geometries.  Geometries can be of any of the following types:

  * Point
  * LineString
  * Polygon
  * MultiPoint
  * MultiLineString
  * MultiPolygon

  Each of these functions can be passed any two Geometries in either a Map with a
  `:type` and `:coordinates` keys or as a struct generated via the Geo library
  (https://github.com/bryanjos/geo). Coordinates are represented as atoms `{x, y}`
  and multiple coordinates as Lists.

  ```elixir
  a = %{type: "Polygon", coordinates: [[{2, 2}, {20, 2}, {11, 11}, {2, 2}]]}
  b = %Geo.Polygon{coordinates: [[{2, 2}, {20, 2}, {11, 11}, {2, 2}]]}

  Topo.equals? a, b # => true
  ```

  Instead of a Point geometry, just a single coordinate can be used.

  ```elixir
  a = %{type: "Polygon", coordinates: [[{2, 2}, {20, 2}, {11, 11}, {2, 2}]]}

  Topo.intersects? a, {4, 6} # => true
  ```

  The `Topo` library's functions will automatically attempt to "clean" geometries
  passed to them:

  * Linear Rings (including Polygons) will be reordered to a counter-clockwise
  direction.
  * Polygon's Linear Rings will automatically be closed if the first point is not
  repeated as the last point.
  * Points that are equal or collinear with surrounding points are removed from
  LineStrings or Polygons.
  """

  @type geometry ::
          {number, number}
          | %{type: String.t(), coordinates: list}
          | %Geo.Point{}
          | %Geo.MultiPoint{}
          | %Geo.LineString{}
          | %Geo.MultiLineString{}
          | %Geo.Polygon{}
          | %Geo.MultiPolygon{}

  @doc ~S"""
  Returns `true` if geometries **A** and **B** share at least one point in
  common.

  ## Examples
      iex> Topo.intersects?(
      ...>   %{type: "Polygon", coordinates: [[{2, 2}, {20, 2}, {11, 11}, {2, 2}]]},
      ...>   %{type: "LineString", coordinates: [{11, 10}, {4, 2.5}, {16, 2.5}, {11, 10}]}
      ...> )
      true

      iex> Topo.intersects?(
      ...>   %{type: "Polygon", coordinates: [
      ...>     [{60, 120}, {60, 40}, {160, 40}, {160, 120}, {60, 120}],
      ...>     [{140, 100}, {80, 100}, {80, 60}, {140, 60}, {140, 100}]]},
      ...>   %{type: "MultiPoint", coordinates: [{70, 35}, {100, 80}]}
      ...> )
      false
  """
  @spec intersects?(geometry, geometry) :: boolean
  def intersects?(a, b), do: Intersects.intersects?(Cleaner.clean(a), Cleaner.clean(b))

  @doc ~S"""
  Returns `true` if geometries **A** and **B** do not have any points in
  common.

  ## Examples
      iex> Topo.disjoint?({1, -3}, %{type: "MultiPoint", coordinates: [{70, 35}, {100, 80}]})
      true

      iex> Topo.disjoint?(
      ...>   %{type: "Polygon", coordinates: [
      ...>     [{60, 120}, {60, 40}, {160, 40}, {160, 120}, {60, 120}],
      ...>     [{140, 100}, {80, 100}, {80, 60}, {140, 60}, {140, 100}]]},
      ...>   %Geo.MultiPoint{coordinates: [{70, 35}, {100, 80}]}
      ...> )
      true
  """
  @spec disjoint?(geometry, geometry) :: boolean
  def disjoint?(a, b), do: !Intersects.intersects?(Cleaner.clean(a), Cleaner.clean(b))

  @doc ~S"""
  Returns `true` if all points of geometry **B** lie within **A**.

  There are a few non-obvious special cases that are worth mentioning:

    - A Polygon does not contain its own boundary.  Specifically a LineString that
    is the exact same as a Polygon's exterior Linear ring is not contained within a
    that Polygon.

    ```elixir
    a = %Geo.Polygon{coordinates: [[{2, 2}, {20, 2}, {11, 11}, {2, 2}]]}
    b = %Geo.LineString{coordinates: [{2, 2}, {20, 2}, {11, 11}, {2, 2}]}

    Topo.contains? a, b # => false
    Topo.intersects? a, b  # => true
    ```

    - A LineString does not contain it's own first and last point (unless those
    points are the same, as in a LinearRing)

    ```elixir
    a = %Geo.LineString{coordinates: [{1, 3}, {2, -1}, {0, -1}]}
    b = %Geo.LineString{coordinates: [{1, 3}, {2, -1}, {0, -1}, {1, 3}]}

    Topo.contains? a, {1, 3} # => false
    Topo.intersects? a, {1, 3} # => true
    Topo.contains? b, {1, 3} # => true
    ```

  ## Examples
      iex> Topo.contains?(
      ...>   %{type: "Polygon", coordinates: [[{20, 20}, {20, 180}, {220, 180}, {220, 20}, {20, 20}]]},
      ...>   %{type: "Polygon", coordinates: [[{160, 60}, {20, 20}, {100, 140}, {160, 60}]]}
      ...> )
      true

      iex> Topo.contains?(
      ...>   %{type: "Polygon", coordinates: [[{160, 60}, {20, 20}, {100, 140}, {160, 60}]]},
      ...>   %{type: "Polygon", coordinates: [[{20, 20}, {20, 180}, {220, 180}, {220, 20}, {20, 20}]]}
      ...> )
      false
  """
  @spec contains?(geometry, geometry) :: boolean
  def contains?(a, b), do: Contains.contains?(Cleaner.clean(a), Cleaner.clean(b))

  @doc ~S"""
  This is the direct converse of `contains?`.  All points of
  geometry **A** lie within geometry **B**.

  ## Examples
      iex> Topo.within?(
      ...>   %{type: "Polygon", coordinates: [[{20, 20}, {20, 180}, {220, 180}, {220, 20}, {20, 20}]]},
      ...>   %{type: "Polygon", coordinates: [[{160, 60}, {20, 20}, {100, 140}, {160, 60}]]}
      ...> )
      false

      iex> Topo.within?(
      ...>   %{type: "Polygon", coordinates: [[{160, 60}, {20, 20}, {100, 140}, {160, 60}]]},
      ...>   %{type: "Polygon", coordinates: [[{20, 20}, {20, 180}, {220, 180}, {220, 20}, {20, 20}]]}
      ...> )
      true
  """
  @spec within?(geometry, geometry) :: boolean
  def within?(a, b), do: Contains.contains?(Cleaner.clean(b), Cleaner.clean(a))

  @doc ~S"""
  Geometries **A** and **B** are equivalent and cover the exact
  same set of points.  By definition, **A** and **B** are equal if **A** contains
  **B** and **B** contains **A**.  Equality does not necessarily mean that the
  geometries are of the same type.  A Point **A** is equal to a MultiPoint that
  contains only the same Point **A**.

  ## Examples
      iex> Topo.equals?(
      ...>   %{type: "Point", coordinates: {2, -3}},
      ...>   %{type: "MultiPoint", coordinates: [{2, -3}]}
      ...> )
      true

      iex> Topo.equals?(
      ...>   %{type: "Polygon", coordinates: [[{160, 60}, {20, 20}, {100, 140}, {160, 60}]]},
      ...>   %{type: "Polygon", coordinates: [[{20, 20}, {20, 180}, {220, 180}, {220, 20}, {20, 20}]]}
      ...> )
      false
  """
  @spec equals?(geometry, geometry) :: boolean
  def equals?(a, b), do: do_equals?(Cleaner.clean(a), Cleaner.clean(b))

  defp do_equals?(a, b), do: Contains.contains?(a, b) && Contains.contains?(b, a)
end