Geometry (Geometry v1.1.0)
View SourceA set of geometry types for WKT/ WKB and GeoJson.
Geometry
provide the decoding and encoding for geometires of type WKT/EWKT,
WKB/EWKB and GeoJon.
The following gemetries are supported:
- Point
- LineString
- Polygon
- MultiPoint
- MultiLineString
- MultiPolyogon
- GeometryCollection
For GeoJson also Geometry.Feature
and Geometry.FeatureCollection
are
supported.
Summary
Types
An n-dimensional point.
Byte order.
A GeoJson term.
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.
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
@type coordinates() :: [number(), ...]
An n-dimensional point.
@type endian() :: :ndr | :xdr
Byte order.
:ndr
: Little endian byte order encoding:xdr
: Big endian byte order encoding
@type geo_json_term() :: map()
A GeoJson term.
@type path() :: [coordinates()]
A list of n-dimensional coordinates.
@type ring() :: [coordinates()]
A list of n-dimensional coordinates where the first and last point are equal, creating a ring.
@type srid() :: non_neg_integer()
The Spatial Reference System Identifier to identify projected, unprojected, and local spatial coordinate system definitions.
@type t() :: Geometry.GeometryCollection.t() | Geometry.GeometryCollectionM.t() | Geometry.GeometryCollectionZ.t() | Geometry.GeometryCollectionZM.t() | Geometry.LineString.t() | Geometry.LineStringM.t() | Geometry.LineStringZ.t() | Geometry.LineStringZM.t() | Geometry.MultiLineString.t() | Geometry.MultiLineStringM.t() | Geometry.MultiLineStringZ.t() | Geometry.MultiLineStringZM.t() | Geometry.MultiPoint.t() | Geometry.MultiPointM.t() | Geometry.MultiPointZ.t() | Geometry.MultiPointZM.t() | Geometry.MultiPolygon.t() | Geometry.MultiPolygonM.t() | Geometry.MultiPolygonZ.t() | Geometry.MultiPolygonZM.t() | Geometry.Polygon.t() | Geometry.PolygonM.t() | Geometry.PolygonZ.t() | Geometry.PolygonZM.t() | Geometry.Point.t() | Geometry.PointM.t() | Geometry.PointZ.t() | Geometry.PointZM.t()
The supported geometries.
@type wkb() :: binary()
Well-Known Binary (WKB) is the binary representation of WKT.
@type wkt() :: String.t()
Well-Known Text (WKT) is a text markup language for representing vector geometry objects.
Functions
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
@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}}
The same as from_ewkb/1
, but raises a Geometry.DecodeError
exception if it fails.
@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)"
}
}
The same as from_ewkt/1
, but raises a Geometry.DecodeError
exception if it fails.
@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"]
}
}
@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.
@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>>
}
}
The same as from_wkb/1
, but raises a Geometry.DecodeError
exception if it fails.
@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)"}
}
The same as from_wkt/1
, but raises a Geometry.DecodeError
exception if it fails.
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"
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)"
@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]]}
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"
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)"