Summary

Types

An n-dimensional point.

Byte order.

A list of n-dimensional coordinates.

A list of n-dimensional coordinates where the first and last point are equal, creating a ring.

The Spatial Reference System Identifier to identify projected, unprojected, and local spatial coordinate system definitions.

t()

The supported geometries.

Well-Known Binary (WKB) is the binary representation of WKT.

Well-Known Text (WKT) is a text markup language for representing vector geometry objects.

Functions

Returns true if a geometry is empty.

Returns an :ok tuple with the geometry from the given EWKB binary.

The same as from_ewkb/1, but raises a Geometry.DecodeError exception if it fails.

Returns an :ok tuple with the geometry from the given EWKT string.

The same as from_ewkt/1, but raises a Geometry.DecodeError exception if it fails.

Returns an :ok tuple with the geometry from the given GeoJSON term.

The same as from_geo_json/1, but raises a Geometry.DecodeError exception if it fails.

Returns an :ok tuple with the geometry from the given WKB binary.

The same as from_wkb/1, but raises a Geometry.DecodeError exception if it fails.

Returns an :ok tuple with the geometry from the given WKT string.

The same as from_wkt/1, but raises a Geometry.DecodeError exception if it fails.

Returns the EWKB representation of a geometry.

Returns the EWKT representation of the given geometry.

Returns the GeoJSON term representation of a geometry.

Returns the WKB representation of a geometry.

Returns the WKT representation of the given geometry.

Types

coordinates()

@type coordinates() :: [number(), ...]

An n-dimensional point.

endian()

@type endian() :: :ndr | :xdr

Byte order.

  • :ndr: Little endian byte order encoding
  • :xdr: Big endian byte order encoding

geo_json_term()

@type geo_json_term() :: map()

A GeoJson term.

path()

@type path() :: [coordinates()]

A list of n-dimensional coordinates.

ring()

@type ring() :: [coordinates()]

A list of n-dimensional coordinates where the first and last point are equal, creating a ring.

srid()

@type srid() :: non_neg_integer()

The Spatial Reference System Identifier to identify projected, unprojected, and local spatial coordinate system definitions.

t()

The supported geometries.

wkb()

@type wkb() :: binary()

Well-Known Binary (WKB) is the binary representation of WKT.

wkt()

@type wkt() :: String.t()

Well-Known Text (WKT) is a text markup language for representing vector geometry objects.

Functions

empty?(geometry)

@spec empty?(t()) :: boolean()

Returns true if a geometry is empty.

Examples

iex> Geometry.empty?(Point.new(1, 2))
false
iex> Geometry.empty?(Point.new())
true
iex> Geometry.empty?(LineString.new([]))
true

from_ewkb(wkb)

@spec from_ewkb(wkb()) :: {:ok, t()} | {:error, Geometry.DecodeError.t()}

Returns an :ok tuple with the geometry from the given EWKB binary.

Otherwise returns an :error tuple.

If the given binary not an extended wkb/0 a nil for the SRID is returned.

Examples

iex> "0020000001000012673FF00000000000004000000000000000"
...> |> Base.decode16!()
...> |> Geometry.from_ewkb()
{:ok, %Point{coordinates: [1.0, 2.0], srid: 4711}}

iex> "0101000080000000000000F03F00000000000000400000000000000840"
...> |> Base.decode16!()
...> |> Geometry.from_ewkb()
{:ok, %PointZ{coordinates: [1.0, 2.0, 3.0], srid: 0}}

from_ewkb!(wkb)

@spec from_ewkb!(wkb()) :: t()

The same as from_ewkb/1, but raises a Geometry.DecodeError exception if it fails.

from_ewkt(wkt)

@spec from_ewkt(wkt()) :: {:ok, t()} | {:error, Geometry.DecodeError.t()}

Returns an :ok tuple with the geometry from the given EWKT string.

Otherwise returns an :error tuple.

If the given string not an extended wkt/0 a nil for the SRID is returned.

Examples

iex> Geometry.from_ewkt("SRID=42;Point (1.1 2.2)")
{:ok, %Point{coordinates: [1.1, 2.2], srid: 42}}

iex> Geometry.from_ewkt("Point ZM (1 2 3 4)")
{:ok, %PointZM{coordinates: [1, 2, 3, 4], srid: 0}}

iex> Geometry.from_ewkt("Point XY (1 2 3 4)")
{:error, "expected Point data", "XY (1 2 3 4)", {1, 0}, 6}
{
  :error,
  %Geometry.DecodeError{
    from: :wkt,
    line: {1, 0},
    message: "expected Point data",
    offset: 6,
    rest: "XY (1 2 3 4)"
  }
}

from_ewkt!(wkt)

@spec from_ewkt!(wkt()) :: t()

The same as from_ewkt/1, but raises a Geometry.DecodeError exception if it fails.

from_geo_json(json, dim \\ :xy)

@spec from_geo_json(geo_json_term(), :xy | :xyz | :xym | :xyzm) ::
  {:ok, t() | Geometry.Feature.t() | Geometry.FeatureCollection.t()}
  | {:error, Geometry.DecodeError.t()}

Returns an :ok tuple with the geometry from the given GeoJSON term.

Otherwise returns an :error tuple.

The optional second argument specifies which type is expected. The possible values are :xy, :xym, xyz, and :xyzm. Defaults to :xy.

Examples

iex> ~s({"type": "Point", "coordinates": [1, 2]})
iex> |> Jason.decode!()
iex> |> Geometry.from_geo_json()
{:ok, %Point{coordinates: [1, 2], srid: 4326}}

iex> ~s({"type": "Point", "coordinates": [1, 2, 3, 4]})
iex> |> Jason.decode!()
iex> |> Geometry.from_geo_json(:xyzm)
{:ok, %PointZM{coordinates: [1, 2, 3, 4], srid: 4326}}

iex> ~s({"type": "Dot", "coordinates": [1, 2]})
iex> |> Jason.decode!()
iex> |> Geometry.from_geo_json()
{
  :error,
  %Geometry.DecodeError{
    from: :geo_json,
    reason: [unknown_type: "Dot"]
  }
}

from_geo_json!(json, dim \\ :xy)

@spec from_geo_json!(geo_json_term(), type :: :xy | :xyz | :xym | :xyzm) ::
  t() | Geometry.Feature.t() | Geometry.FeatureCollection.t()

The same as from_geo_json/1, but raises a Geometry.DecodeError exception if it fails.

from_wkb(wkb)

@spec from_wkb(wkb()) :: {:ok, t()} | {:error, Geometry.DecodeError.t()}

Returns an :ok tuple with the geometry from the given WKB binary.

Otherwise returns an :error tuple.

If the given binary is an extended wkb/0 the SRID is ignored.

Examples

iex> "0020000001000012673FF00000000000004000000000000000"
...> |> Base.decode16!()
...> |> Geometry.from_wkb()
{:ok, %Point{coordinates: [1.0, 2.0], srid: 4711}}

iex> "0101000080000000000000F03F00000000000000400000000000000840"
...> |> Base.decode16!()
...> |> Geometry.from_wkb()
{:ok, %PointZ{coordinates: [1.0, 2.0, 3.0]}}

iex> "FF"
...> |> Base.decode16!()
...> |> Geometry.from_wkb()
{
  :error,
  %Geometry.DecodeError{
    from: :wkb,
    offset: 0,
    reason: [expected_endian: :flag],
    rest: <<255>>
  }
}

from_wkb!(wkb)

@spec from_wkb!(wkb()) :: t()

The same as from_wkb/1, but raises a Geometry.DecodeError exception if it fails.

from_wkt(wkt)

@spec from_wkt(wkt()) :: {:ok, t()} | {:error, Geometry.DecodeError.t()}

Returns an :ok tuple with the geometry from the given WKT string.

Otherwise returns an :error tuple.

If the given string is an extended wkt/0 the SRID is ignored.

Examples

iex> Geometry.from_wkt("SRID=42;Point (1.1 2.2)")
{:ok, %Point{coordinates: [1.1, 2.2], srid: 42}}

iex> Geometry.from_wkt("Point ZM (1 2 3 4)")
{:ok, %PointZM{coordinates: [1, 2, 3, 4], srid: 0}}

iex> Geometry.from_wkt("Point XY (1 2 3 4)")
{:error,  %Geometry.DecodeError{
  from: :wkt,
  line: {1, 0},
  message: "expected Point data",
  offset: 6,
  rest: "XY (1 2 3 4)"}
}

from_wkt!(wkt)

@spec from_wkt!(wkt()) :: t()

The same as from_wkt/1, but raises a Geometry.DecodeError exception if it fails.

to_ewkb(geometry, endian \\ :ndr)

@spec to_ewkb(t(), endian()) :: wkb()

Returns the EWKB representation of a geometry.

If the srid of the geometry is 0, a WKB is returned.

The optional :endian argument indicates whether :xdr big endian or :ndr little endian is returned. The default is :ndr.

Examples

iex> PointZ.new(1, 2, 3, 3825)
...> |> Geometry.to_ewkb()
...> |> Base.encode16()
"01010000A0F10E0000000000000000F03F00000000000000400000000000000840"

iex> PointZ.new(1, 2, 3, 0)
...> |> Geometry.to_ewkb()
...> |> Base.encode16()
"0101000080000000000000F03F00000000000000400000000000000840"

iex> Point.new(1, 2, 3825)
...> |> Geometry.to_ewkb(:xdr)
...> |> Base.encode16()
"002000000100000EF13FF00000000000004000000000000000"

to_ewkt(geometry)

@spec to_ewkt(t()) :: wkt()

Returns the EWKT representation of the given geometry.

If the srid of the geometry is 0, a WKT is returned.

Examples

iex> Geometry.to_ewkt(PointZ.new(1.1, 2.2, 3.3, 4211))
"SRID=4211;POINT Z (1.1 2.2 3.3)"

iex> Geometry.to_ewkt(LineString.new([Point.new(1, 2), Point.new(3, 4)], 3825))
"SRID=3825;LINESTRING (1 2, 3 4)"

iex> Geometry.to_ewkt(Point.new(1, 2))
"POINT (1 2)"

to_geo_json(geometry)

@spec to_geo_json(t()) :: geo_json_term()

Returns the GeoJSON term representation of a geometry.

Examples

iex> Geometry.to_geo_json(PointZ.new(1.2, 3.4, 5.6))
%{"type" => "Point", "coordinates" => [1.2, 3.4, 5.6]}

iex> Geometry.to_geo_json(LineString.new([Point.new(1, 2), Point.new(3, 4)]))
%{"type" => "LineString", "coordinates" => [[1, 2], [3, 4]]}

to_wkb(geometry, endian \\ :ndr)

@spec to_wkb(t(), endian()) :: wkb()

Returns the WKB representation of a geometry.

The optional :endian argument indicates whether :xdr big endian or :ndr little endian is returned. The default is :ndr.

Examples

iex> PointZ.new(1, 2, 3)
...> |> Geometry.to_wkb()
...> |> Base.encode16()
"0101000080000000000000F03F00000000000000400000000000000840"

iex> PointZ.new(1, 2, 3)
...> |> Geometry.to_wkb(:xdr)
...> |> Base.encode16()
"00800000013FF000000000000040000000000000004008000000000000"

to_wkt(geometry)

@spec to_wkt(t()) :: wkt()

Returns the WKT representation of the given geometry.

Examples

iex> Geometry.to_wkt(PointZ.new(1.1, 2.2, 3.3))
"POINT Z (1.1 2.2 3.3)"

iex> Geometry.to_wkt(LineString.new([Point.new(1, 2), Point.new(3, 4)]))
"LINESTRING (1 2, 3 4)"

iex> Geometry.to_wkt(Point.new(1, 2))
"POINT (1 2)"