Note: this unregistered package served as a draft to redesign Julia's GeoInterface. Follow https://github.com/JuliaGeo/GeoInterface.jl for all current developments.

GeoInterfaceRFC

An interface for geospatial vector data in Julia

This Package describe a set of traits based on the Simple Features standard (SF) for geospatial vector data, including the SQL/MM extension with support for circular geometry.

Packages which support the GeoInterfaceRFC.jl interface can be found in INTEGRATIONS.md.

Changes with respect to SF

While we try to adhere to SF, there are changes and extensions to make it more Julian.

Function names

All function names are without the ST_ prefix and are lowercased. In some cases the names have changed as well, to be inline with common Julia functions. NumX becomes nx and Xn becomes getX:

GeometryType -> geomtype
NumGeometries -> ngeom
GeometryN -> getgeom
NumPatches -> npatch
# etc

We also simplified the dimension functions. From the three original (dimension, coordinateDimension, spatialDimension) there's now only the coordinate dimension, so not to overlap with the Julia ndims.

coordinateDimension -> ncoords

We've generalized the some functions:

SRID -> crs
envelope -> extent

And added a helper method to clarify the naming of coordinates.

coordnames = (:X, :Y, :Z, :M)

Coverage

Not all SF functions are implemented, either as a possibly slower fallback or empty descriptor or not at all. The following SF functions are not (yet) available.

dimension
spatialDimension
asText
asBinary
is3D
isMeasured
boundary

locateAlong
locateBetween

distance
buffer
convexHull

While the following functions have no implementation:

equals
disjoint
touches
within
overlaps
crosses
intersects
contains
relate

intersection
union
difference
symdifference

Implementation

GeoInterface provides a traits interface, not unlike Tables.jl, by

(a) a set of functions:

geomtype(geom)
ncoord(geom)
ngeom(geom)
getgeom(geom::geomtype, i)
...

(b) a set of types for dispatching on said functions. The types tells GeoInterface how to interpret the input object inside a GeoInterface function.

abstract Geometry
Point <: AbstractPoint <: AbstractGeometry
MultiPoint <: AbstractMultiPointGeometry <:AbstractGeometryCollection <: AbstractGeometry
...

For developers looking to implement the interface

GeoInterface requires five functions to be defined for a given geom:

GeoInterface.geomtype(geom::geomtype)::DataType = GeoInterface.X()
GeoInterface.ncoord(geomtype(geom), geom::geomtype)::Integer
GeoInterface.getcoord(geomtype(geom), geom::geomtype, i)::Real  # only for Points
GeoInterface.ngeom(geomtype(geom), geom::geomtype)::Integer
GeoInterface.getgeom(geomtype(geom), geom::geomtype, i)  # geomtype -> GeoInterface.Y

Where the getgeom could be an iterator (without the i) as well. It will return a new geom with the correct geomtype. The ngeom and getgeom are aliases for their geom specific counterparts, such as npoints and getpoint for LineStrings.

There are also optional generic methods that could help or speed up operations:

GeoInterface.crs(geom)::Union{Missing, GeoFormatTypes.CoordinateReferenceSystemFormat}
GeoInterface.extent(geom)  # geomtype -> GeoInterface.Rectangle

And lastly, there are many other optional functions for each specific geometry. GeoInterface provides fallback implementations based on the generic functions above, but these are not optimized. These are detailed in the next chapter.

Examples

A geom::geomtype with "Point"-like traits implements

GeoInterface.geomtype(geom::geomtype)::DataType = GeoInterface.Point()
GeoInterface.ncoord(::GeoInterface.Point, geom::geomtype)::Integer
GeoInterface.getcoord(::GeoInterface.Point, geom::geomtype, i)::Real

# Defaults
GeoInterface.ngeom(::GeoInterface.Point, geom)::Integer = 0
GeoInterface.getgeom(::GeoInterface.Point, geom::geomtype, i) = nothing

A geom::geomtype with "LineString"-like traits implements the following methods:

GeoInterface.geomtype(geom::geomtype)::DataType = GeoInterface.LineString()
GeoInterface.ncoord(::GeoInterface.LineString, geom::geomtype)::Integer

# These alias for npoint and getpoint
GeoInterface.ngeom(::GeoInterface.LineString, geom::geomtype)::Integer
GeoInterface.getgeom(::GeoInterface.LineString, geom::geomtype, i) # of geomtype Point

# Optional
GeoInterface.isclosed(::GeoInterface.LineString, geom::geomtype)::Bool
GeoInterface.issimple(::GeoInterface.LineString, geom::geomtype)::Bool
GeoInterface.length(::GeoInterface.LineString, geom::geomtype)::Real

A geom::geomtype with "Polygon"-like traits can implement the following methods:

GeoInterface.geomtype(geom::geomtype)::DataType = GeoInterface.Polygon()
GeoInterface.ncoord(::GeoInterface.Polygon, geom::geomtype)::Integer

# These alias for nring and getring
GeoInterface.ngeom(::GeoInterface.Polygon, geom::geomtype)::Integer
GeoInterface.getgeom(::GeoInterface.Polygon, geom::geomtype, i)::"LineString"

# Optional
GeoInterface.area(::GeoInterface.Polygon, geom::geomtype)::Real
GeoInterface.centroid(::GeoInterface.Polygon, geom::geomtype)::"Point"
GeoInterface.pointonsurface(::GeoInterface.Polygon, geom::geomtype)::"Point"
GeoInterface.boundary(::GeoInterface.Polygon, geom::geomtype)::"LineString"

A geom::geomtype with "GeometryCollection"-like traits has to implement the following methods:

GeoInterface.geomtype(geom::geomtype) = GeoInterface.GeometryCollection()
GeoInterface.ncoord(::GeoInterface.GeometryCollection, geom::geomtype)::Integer
GeoInterface.ngeom(::GeoInterface.GeometryCollection, geom::geomtype)::Integer
GeoInterface.getgeom(::GeoInterface.GeometryCollection,geom::geomtypem, i)::"Geometry"

A geom::geomtype with "MultiPoint"-like traits has to implement the following methods:

GeoInterface.geomtype(geom::geomtype) = GeoInterface.MultiPoint()
GeoInterface.ncoord(::GeoInterface.MultiPoint, geom::geomtype)::Integer

# These alias for npoint and getpoint
GeoInterface.ngeom(::GeoInterface.MultiPoint, geom::geomtype)::Integer
GeoInterface.getgeom(::GeoInterface.MultiPoint, geom::geomtype, i)::"Point"

A geom::geomtype with "MultiLineString"-like traits has to implement the following methods:

GeoInterface.geomtype(geom::geomtype) = GeoInterface.MultiLineString()
GeoInterface.ncoord(::GeoInterface.MultiLineString, geom::geomtype)::Integer

# These alias for nlinestring and getlinestring
GeoInterface.ngeom(::GeoInterface.MultiLineString, geom::geomtype)::Integer
GeoInterface.getgeom(::GeoInterface.MultiLineString,geom::geomtypem, i)::"LineString"

A geom::geomtype with "MultiPolygon"-like traits has to implement the following methods:

GeoInterface.geomtype(geom::geomtype) = GeoInterface.MultiPolygon()
GeoInterface.ncoord(::GeoInterface.MultiPolygon, geom::geomtype)::Integer

# These alias for npolygon and getpolygon
GeoInterface.ngeom(::GeoInterface.MultiPolygon, geom::geomtype)::Integer
GeoInterface.getgeom(::GeoInterface.MultiPolygon, geom::geomtype, i)::"Polygon"

Testing the interface

GeoInterface provides a Testsuite for a geom type to check whether all functions that have been implemented also work as expected.

GeoInterface.test_interface_for_geom(geom)

Review

Still writing things down, this post will be edited/extended!

This is gonna be a long post, not sure about the right format.

Thanks for taking the time to put together an proposal! SF is essential, although like most OGC standards, falls into the rabbit hole of prescriptive standards on top of a descriptive one. The latter is way more developer friendly and is what were doing here now. Therefore I would like to extend and dare I say improve the SF in this package, much like PostGIS has done, for usability. A nice implementation is also over at R.

Functions

I would like to add at least all the functions defined on the abstract geometry type, per SF, although we can play with the names.

dimension() : Integer
coordinateDimension() : Integer
spatialDimension() : Integer
geometry Type() : String
SRID() : Integer
envelope() : Geometry
asText() : String
asBinary () : Binary
isEmpty () : Boolean
isSimple() : Boolean
is3D() : Boolean
isMeasured() : Boolean
boundary () : Geometry

Not all of them need to be implemented, but fixing the spatial reference and an easy implementation for the bounding box seem essential to me. Speaking of functions that could use some actual algorithm, where will those be? The whole suite of DE-9IM functions? Pure Julia, or GEOS? Can you choose a backing engine (like a CPU/GPU switch?). Do we provide an area function (defined in SF for Polygons) or length. Where do these implementations belong?

Types

As seen above, there are a lot more types than we now have defined. There are also intermediate types (Curve) or subtypes (Triangle). On top of this, the ISO SQL MM standard extends this, partly implemented and extended by PostGIS.

IO

Parsing WKT/WKB could be in another package that also implements this Interface? Same goes for GeoJSON and many other formats. We probably don't need a function for this.

juliageo / geointerfacerfc.jl Goto Github PK