distance

defmodule Distance do
  @moduledoc ~S"""

  Basic distance calculations for cartesian coordinates for calculting

  distances on a single plane.  If you are looking to calculating distance

  on the surface of Earth, check out the `Distance.GreatCircle` module.



  ## Examples

      iex> Distance.distance({2.5, 2.5}, {4, 0.8})

      2.2671568097509267

      iex> Distance.segment_distance({2.5, 2.5}, {4, 0.8}, {-2, 3})

      1.0797077632696

      iex> Distance.distance([{2.5, 2.5}, {4, 0.8}, {-2, 3}, {1, -1}])

      13.657774933219109

  """

  @doc """

  Returns the geometric distance between two points.  Accepts 2- or

  3-dimensional points.



  ## Examples

      iex> Distance.distance({1, -2}, {-2, 2})

      5.0

      iex> Distance.distance({1, -2, 2}, {-2, 2, 1})

      5.0990195135927845

  """
  def distance(p1, p2), do: :math.sqrt(distance_squared(p1, p2))

  @doc """

  Returns the geometric distance from a point `p` and the line segment

  between two points `p1` and `p2`.  Note that this is a line segment, not

  an infinite line, so points not between `p1` and `p2` will return the

  distance to the nearest of the two endpoints.



  ## Examples

      iex> Distance.segment_distance({3, 2}, {-2, 1}, {5, 3})

      0.4120816918460673 # distance between the point {3, 2} and the closest point along line segment ({-2, 1}, {5, 3})

      iex> Distance.segment_distance({1, -2}, {-2, 2}, {-10, 102})

      5.0

      iex> Distance.segment_distance({1, -2}, {-2, 2}, {1, -2})

      0.0

  """
  def segment_distance(p, p1, p2), do: :math.sqrt(segment_distance_squared(p, p1, p2))

  @doc """

  Returns the square of the distance between two points.  This is used by the

  `Distance.distance` function above, but having access to the value before

  the expensice sqaure root operation is useful for time-sensitive applications

  that only need values for comparison.



  ## Examples

      iex> Distance.distance_squared({1, -2}, {-2, 2})

      25

      iex> Distance.distance_squared({1, -2, 2}, {-2, 2, 1})

      26

  """
  def distance_squared({x1, y1}, {x2, y2}) do
    dx = x1 - x2
    dy = y1 - y2

    dx * dx + dy * dy
  end

  def distance_squared({x1, y1, z1}, {x2, y2, z2}) do
    dx = x1 - x2
    dy = y1 - y2
    dz = z1 - z2

    dx * dx + dy * dy + dz * dz
  end

  @doc """

  Similar to `Distance.distance_squared`, this provides much faster comparable

  version of `Distance.segment_distance`.



  ## Examples

      iex> Distance.segment_distance_squared({3, 2}, {-2, 1}, {5, 3})

      0.16981132075471717

      iex> Distance.segment_distance_squared({1, -2}, {-2, 2}, {-10, 102})

      25

  """
  def segment_distance_squared({x, y}, {x1, y1}, {x2, y2}) when x1 == x2 and y1 == y2, do: distance_squared({x, y}, {x1, y1})
  def segment_distance_squared({x, y}, {x1, y1}, {x2, y2}) do
    dx = x2 - x1
    dy = y2 - y1

    t = ((x - x1) * dx + (y - y1) * dy) / (dx * dx + dy * dy)

    cond do
       (t > 1) -> distance_squared({x, y}, {x2, y2})
       (t > 0) -> distance_squared({x, y}, {x1 + dx * t, y1 + dy * t})
       true -> distance_squared({x, y}, {x1, y1})
    end
  end

  @doc """

  Returns the geometric distance of the linestring defined by the List of

  points.  Accepts 2- or 3-dimensional points.



  ## Examples

      iex> Distance.distance([{2.5, 2.5}, {4, 0.8}, {2.5, 3.1}, {2.5, 3.1}])

      5.013062853300123

      iex> Distance.distance([{1, -2, 1}, {-2, 2, -1}, {-2, 1, 0}, {2, -3, 1}])

      12.543941016045627

  """
  def distance([]), do: 0
  def distance([_]), do: 0
  def distance([p1, p2]), do: distance(p1, p2)
  def distance([p1, p2 | tail]) do
    distance(p1, p2) + distance([ p2 | tail])
  end
end