API

Internal function.

Extended help

_get_dataapi_metadata(geom, key, default)

Get metadata associated with key key from some object, geom, that has DataAPI.jl metadata support.

If the object does not have metadata support, or the key does not exist, return default.

area(geom) -> Number

Return the area of geom in its 2d coordinate system. Note that this is only valid for AbstractSurfaceTraits.

asbinary(geom) -> WKB

Convert geom into Well Known Binary (WKB) representation, such as 000000000140000000000000004010000000000000.

astext(geom) -> WKT

Convert geom into Well Known Text (WKT) representation, such as POINT (30 10).

bbox(geom) -> T <: Extents.Extent

Alias for extent, for compatibility with GeoJSON and the Python geointerface. Ensures backwards compatibility with GeoInterface version 0.

boundary(geom) -> Curve

Return the boundary of geom. Note that this is only valid for AbstractSurfaceTraits.

boundingpolygons(geom, i) -> AbstractMultiPolygon

Returns the collection of polygons in this surface that bounds the ith patch in the given geom.

buffer(geom, distance) -> AbstractGeometry

Returns a geometric object that represents a buffer of the given geom with distance.

centroid(geom) -> Point

The mathematical centroid for this Surface as a Point. The result is not guaranteed to be on this Surface. Note that this is only valid for AbstractSurfaceTraits.

contains(a, b) -> Bool

Returns whether a contains b. The order of arguments is important. Equivalent to within with reversed arguments.

convert(type::CustomGeom, geom)
convert(module::Module, geom)

Create a CustomGeom from any geom that implements the GeoInterface.

Can also convert to a Module, which finds the corresponding geom type for the trait using the modules geointerface_traittype method.

convert(T::Type) or convert(m::Module) return curried versions of that function, just like ==.

Extended help

For developers, the base implementation is GeoInterface.convert(::YourGeomType, ::AbstractTrait, some_other_geom). This is the method signature that must be implemented for a custom geometry type.

Users may also call this method directly, if they know the exact output - this can sometimes save the Julia compiler some work and cause more optimal code to be generated.

For convenience and type stability there is a convert(::Module, ::AbstractTrait, geom) method that is particularly useful when the trait of a geometry needs to be propagated deep within the stack.

This helps to prevent the compiler from losing the trait information, especially useful when dealing with sumtype-like implementations or opaque pointers from C libraries.

convexhull(geom) -> AbstractCurve

Returns a geometric object that represents the convex hull of the given geom.

coordinates(geom) -> Vector

Return (an iterator of) point coordinates. Ensures backwards compatibility with GeoInterface version 0.

coordnames(geom) -> Tuple{Symbol}

Return the names of coordinate dimensions (such for (:X,:Y,:Z)) for the geometry.

coordtype(geom) -> Type

Return the type of the coordinates in the geom.

Usually <: AbstractFloat but can be any Number.

crosses(a, b) -> Bool

Returns whether a and b cross.

crs(geom) -> T <: GeoFormatTypes.CoordinateReferenceSystemFormat

Retrieve Coordinate Reference System for given geom. In SF this is defined as SRID.

crstrait(geom) -> AbstractCRSTrait

Retrieves the type of the Coordinate Reference System for the given geom. Defaults to retrieving from crs(geom) and to UnknownTrait if not implemented.

difference(a, b) -> AbstractGeometry

Returns a geometric object that represents the Point set difference of a with b

disjoint(a, b) -> Bool

Returns whether a and b are disjoint. Inverse of intersects.

distance(a, b) -> Number

Returns the shortest distance between a with b.

endpoint(geom) -> Point

Return the last point in the geom. Note that this is only valid for AbstractCurveTraits.

equals(a, b) -> Bool

Returns whether a and b are equal. Equivalent to (within && contains).

extent(obj; fallback=true) -> T <: Extents.Extent

Retrieve the extent (bounding box) for given geom or feature. In SF this is defined as envelope.

Extents.extent(obj) will be called if extent(trait(obj), obj), is not defined so it may be preferable to define Extents.extent directly.

When fallback is true, and the obj does not have an extent, an extent is calculated from the coordinates of all geometries in obj.

GeoInterface.geometry(feat) => geom

Retrieve the geometry of feat. It is expected that isgeometry(geom) === true. Ensures backwards compatibility with GeoInterface version 0.

GeoInterface.geometrycolumns(featurecollection) => (:geometry,)

Retrieve the geometrycolumn(s) of featurecollection; the fields (or columns in a table) which contain geometries that support GeoInterface.

This is always a Tuple of Symbols.

GeoInterface.geomtrait(geom) => T <: AbstractGeometry

Returns the geometry type, such as PolygonTrait or PointTrait.

getcoord(geom, i) -> Number

Return the ith coordinate for a given geom. A coordinate isa Real. Note that this is only valid for individual AbstractPointTraits.

getcoord(geom) -> iterator

getexterior(geom) -> Curve

Returns the exterior ring of a Polygon as a AbstractCurve. Note that this is only valid for AbstractPolygonTraits.

GeoInterface.getfeature(collection) => [feature, ...]

Retrieve the features of collection as some iterable of features. It is expected that isfeature(feature) === true.

getgeom(geom, i::Integer) -> AbstractGeometry

Returns the ith geometry for the given geom.

getgeom(geom) -> iterator

Returns an iterator over all geometry components in geom.

gethole(geom, i::Integer) -> Curve

Returns the ith interior ring for this given geom. Note that this is only valid for AbstractPolygonTraits.

gethole(geom) -> iterator

Returns an iterator over all holes in geom. Note that this is only valid for AbstractPolygonTraits.

getlinestring(geom, i::Integer) -> AbstractCurve

Returns the ith linestring for the given geom. Note that this is only valid for AbstractMultiLineStringTraits.

getlinestring(geom) -> iterator

Returns an iterator over all linestrings in a geometry. Note that this is only valid for AbstractMultiLineStringTraits.

getpatch(geom, i::Integer) -> AbstractPolygon

Returns the ith patch for the given geom. Note that this is only valid for AbstractPolyhedralSurfaceTraits.

getpatch(geom) -> iterator

Returns an iterator over all patches in geom. Note that this is only valid for AbstractPolyhedralSurfaceTraits.

getpoint(geom, i::Integer) -> Point

Return the ith Point in given geom. Note that this is only valid for AbstractCurveTraits and AbstractMultiPointTraits.

getpoint(geom) -> iterator

Returns an iterator over all points in geom.

getpolygon(geom, i::Integer) -> AbstractCurve

Returns the ith polygon for the given geom. Note that this is only valid for AbstractMultiPolygonTraits.

getpolygon(geom) -> iterator

Returns an iterator over all polygons in a geometry. Note that this is only valid for AbstractMultiPolygonTraits.

getring(geom, i::Integer) -> AbstractCurve

A specific ring i in a polygon or multipolygon (exterior and holes). Note that this is only valid for AbstractPolygonTraits and AbstractMultiPolygonTraits.

getring(geom) -> iterator

Returns an iterator over all rings in geom. Note that this is only valid for AbstractPolygonTraits and AbstractMultiPolygonTraits in single-argument form.

intersection(a, b) -> AbstractGeometry

Returns a geometric object that represents the Point set intersection of a with b

intersects(a, b) -> Bool

Returns whether a and b intersect. Inverse of disjoint.

is3d(geom) -> Bool

Return whether the given geom has a :Z coordinate.

isclosed(geom) -> Bool

Return whether the geom is closed, i.e. whether the startpoint is the same as the endpoint. Note that this is only valid for AbstractCurveTraits.

isempty(geom) -> Bool

Return true when the geometry is empty.

GeoInterface.isfeature(x) => Bool

Check if an object x is a feature and thus implicitly supports some GeoInterface methods. A feature is a combination of a geometry and properties, not unlike a row in a table. It is recommended that for users implementing MyType, they define only isfeature(::Type{MyType}). isfeature(::MyType) will then automatically delegate to this method.

Ensures backwards compatibility with GeoInterface version 0.

GeoInterface.isfeaturecollection(x) => Bool

Check if an object x is a collection of features and thus implicitly supports some GeoInterface methods. A feature collection is a collection of features, and may also contain metatdata for the whole collection, like an Extent.

It is recommended that for users implementing MyType, they define only isfeaturecollection(::Type{MyType}). isfeaturecollection(::MyType) will then automatically delegate to this method.

GeoInterface.isgeometry(x) => Bool

Check if an object x is a geometry and thus implicitly supports GeoInterface methods. It is recommended that for users implementing MyType, they define only isgeometry(::Type{MyType}). isgeometry(::MyType) will then automatically delegate to this method.

ismeasured(geom) -> Bool

Return whether the given geom has a :M coordinate.

GeoInterface.israster(x) => Bool

Check if an object x is a raster and thus implicitly supports some GeoInterface methods. A raster requires the crs and extent methods to be defined.

It is recommended that for users implementing MyType, they define only israster(::Type{MyType}). israster(::MyType) will then automatically delegate to this method.

isring(geom) -> Bool

Return whether the geom is a ring, i.e. whether the geom isclosed and issimple. Note that this is only valid for AbstractCurveTraits.

issimple(geom) -> Bool

Return true when the geometry is simple, i.e. doesn't cross or touch itself.

length(geom) -> Number

Return the length of geom in its 2d coordinate system. Note that this is only valid for AbstractCurveTraits.

m(geom) -> Number

Return the :M (measured) coordinate of the given geom. Note that this is only valid for AbstractPointTraits.

For length 4 Tuple and Vector points, the fourth value is returned.

Length 3 Tuple and Vector points can not represent measured points, and will throw an ArgumentError.

ncoord(geom) -> Integer

Return the number of coordinate dimensions (such as 3 for X,Y,Z) for the geometry. Note that SF distinguishes between dimensions, spatial dimensions and topological dimensions, which we do not.

GeoInterface.nfeature(collection)

Retrieve the number of features in a feature collection.

ngeom(geom) -> Integer

Returns the number of geometries for the given geom.

nhole(geom) -> Integer

Returns the number of holes for this given geom. Note that this is only valid for AbstractPolygonTraits.

nlinestring(geom) -> Integer

Returns the number of curves for the given geom. Note that this is only valid for AbstractMultiLineStringTraits.

npatch(geom)

Returns the number of patches for the given geom. Note that this is only valid for AbstractPolyhedralSurfaceTraits.

npoint(geom) -> Int

Return the number of points in given geom. Note that this is only valid for AbstractCurveTraits and AbstractMultiPointTraits.

npolygon(geom) -> Integer

Returns the number of polygons for the given geom. Note that this is only valid for AbstractMultiPolygonTraits.

nring(geom) -> Integer

Return the number of rings in given geom. Note that this is only valid for AbstractPolygonTraits and AbstractMultiPolygonTraits

overlaps(a, b) -> Bool

Returns whether a and b overlap. Also called covers in DE-9IM.

pointonsurface(geom) -> Point

A Point guaranteed to be on this geometry (as opposed to centroid). Note that this is only valid for AbstractSurfaceTraits.

GeoInterface.properties(feat) => properties

Retrieve the properties of feat. This can be any Iterable that behaves like an AbstractRow. Ensures backwards compatibility with GeoInterface version 0.

relate(a, b, relationmatrix::String) -> Bool

Returns whether a and b relate, based on the provided relation matrix.

startpoint(geom) -> Point

Return the first point in the geom. Note that this is only valid for AbstractCurveTraits.

subtrait(t::AbstractGeometryTrait)

Gets the expected, possible abstract, (sub)trait for subgeometries (retrieved with getgeom) of trait t. This follows the Type hierarchy of Simple Features.

Examples

julia> GeoInterface.subtrait(LineStringTrait())
AbstractPointTrait
julia> GeoInterface.subtrait(PolygonTrait())  # Any of LineStringTrait, LineTrait, LinearRingTrait
AbstractLineStringTrait

# `nothing` is returned when there's no subtrait or when it's not known beforehand
julia> isnothing(GeoInterface.subtrait(PointTrait()))
true
julia> isnothing(GeoInterface.subtrait(GeometryCollectionTrait()))
true

symdifference(a, b) -> AbstractGeometry

Returns a geometric object that represents the Point set symmetric difference of a with b.

testfeature(feature)

Test whether the required interface for your feature has been implemented correctly.

testfeaturecollection(featurecollection)

Test whether the required interface for your featurecollection has been implemented correctly.

testgeometry(geom)

Test whether the required interface for your geom has been implemented correctly.

testraster(raster)

Test whether the required interface for your raster has been implemented correctly.

touches(a, b) -> Bool

Returns whether a and b touch.

GeoInterface.trait(geom) => T <: AbstractGeometry

Returns the object type, such as FeatureTrait. For all isgeometry objects trait is the same as geomtrait(obj), e.g. PointTrait.

union(a, b) -> AbstractGeometry

Returns a geometric object that represents the Point set union of a with b

within(a, b) -> Bool

Returns whether a is within b. The order of arguments is important. Equivalent to contains with reversed arguments.

x(geom) -> Number

Return the :X coordinate of the given geom. Note that this is only valid for AbstractPointTraits.

For Tuple and Vector points, the first value is returned.

y(geom) -> Number

Return the :Y coordinate of the given geom. Note that this is only valid for AbstractPointTraits.

For Tuple and Vector points, the second value is returned.

z(geom) -> Number

Return the :Z coordinate of the given geom. Note that this is only valid for AbstractPointTraits.

For length 3 Tuple and Vector points, the third value is returned.

Supertype for all coordinate reference system traits

An AbstractCurvePolygonTrait type for all curved polygons.

An AbstractCurveTrait type for all curves.

An AbstractFeatureCollectionTrait for all feature collections

An AbstractFeatureTrait for all features

An AbstractGeographicTrait for all geographic coordinate reference systems

An AbstractGeometryCollectionTrait type for all geometrycollections.

An AbstractGeometryTrait type for all geometries.

An AbstractLineString type for all linestrings.

An AbstractMultiCurveTrait type for all multicurves.

An AbstractMultiLineStringTrait type for all multilinestrings.

An AbstractMultiPointTrait type for all multipoints.

An AbstractMultiPolygonTrait type for all multipolygons.

An AbstractMultiSurfaceTrait type for all multisurfaces.

An AbstractPointTrait for all points.

An AbstractPolygonTrait type for all polygons.

An AbstractPolyhedralSurfaceTrait type for all polyhedralsurfaces.

An AbstractProjectedTrait for all projected coordinate reference systems

An AbstractRasterTrait for all rasters

An AbstractSurfaceTrait type for all surfaces.

An AbstractTrait type for all geometries, features and feature collections.

A CircularStringTrait is a curve, with an odd number of points. A single segment consists of three points, where the first and last are the beginning and end, while the second is halfway the curve.

A CompoundCurveTrait is a curve that combines straight LineStringTraits and curved CircularStringTraits.

An AbstractCurvePolygonTrait that can contain either circular or straight curves as rings.

A FeatureCollectionTrait holds objects of FeatureTrait

A FeatureTrait holds geometries, properties and an extent

An GeographicTrait for all geographic coordinate reference systems

A GeometryCollection is a collection of Geometrys.

A PolygonTrait with six vertices.

A LineStringTrait is a collection of straight lines between its PointTraits.

A LineTrait is LineStringTrait with just two points.

A LinearRingTrait is a LineStringTrait with the same begin and endpoint.

A MultiCurveTrait is a collection of CircularStringTraits.

A MultiLineStringTrait is a collection of LineStringTraits.

A MultiPointTrait is a collection of PointTraits.

A MultiPolygonTrait is a collection of PolygonTraits.

A MultiSurfaceTrait is a collection of AbstractSurfaceTraits.

A PolygonTrait with five vertices.

A single point.

An AbstractSurfaceTrait with straight rings either as exterior or interior(s).

A PolyhedralSurfaceTrait is a connected surface consisting of PolygonTraits.

An ProjectedTrait for all projected coordinate reference systems

A PolygonTrait with four vertices.

A PolygonTrait that is rectangular and could be described by the minimum and maximum vertices.

A TINTrait is a PolyhedralSurfaceTrait consisting of TriangleTraits.

A PolygonTrait that is triangular.

An UnknownTrait for all unknown (assumed projected) coordinate reference systems