Added iterators. Added feature interface. Updated documentation based on review.

Author: evetion

docs/src/background/sf.md

@@ -1,6 +1,6 @@
 # Simple Features
-Simple Features (SF) are OGC standards describing two dimensional geographic features, such as Points and Polygons and the relations between them.
-The standards describe a hierarchy of types (Part 1), an interface with SQL (Part II) and an SQL/MM extension with support for circular geometry.
+Simple Features ([SF](https://en.wikipedia.org/wiki/Simple_Features)) are OGC standards describing two dimensional geographic features, such as Points and Polygons and the relations between them.
+The standards describe a hierarchy of types (Part 1), a functional interface with SQL (Part II) and an SQL/MM extension with support for circular geometry types, such as `Circularstring`.
 
 ## Type hierarchy
 All types used here come from the SF. We added `Trait` to all geometry types here to distinguish them from actual geometry structs.
@@ -12,7 +12,7 @@ All types used here come from the SF. We added `Trait` to all geometry types her
 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`:
+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 `geomN` becomes `getgeom`:
 ```julia
 GeometryType -> geomtype
 NumGeometries -> ngeom
@@ -24,15 +24,18 @@ NumPatches -> npatch
 We generalized [`ngeom`](@ref) and [`getgeom`](@ref) to apply to 
 all geometries, not just a [`AbstractGeometryCollectionTrait`](@ref)s.
 
-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`.
+We also simplified the dimension functions. From the three original (`dimension`, `coordinateDimension`, `spatialDimension`) there's now only the coordinate dimension, by using `ncoords`, which represent coordinate dimensions like `X`, `Y`, `Z` and `M`. Topological dimensions (a point is 0-dimensional), and the functions related to it, are not used in this interface to prevent confusion. Similarly, we do not overload the Julia `ndims`, to prevent confusion and possible conflict with custom vector based geometries.
+
 ```julia
 coordinateDimension -> ncoords  # x, y, z, m
+dimension -> unused
+spatialDimension -> unused
 ```
 
-We've generalized the some functions:
+We've generalized the naming of some functions:
 ```julia
 SRID -> crs
-envelope -> extent
+envelope -> extent  # also aliased to bbox
 ```
 
 And added a helper method to clarify the naming of coordinates.
@@ -44,10 +47,9 @@ coordnames = (:X, :Y, :Z, :M)
 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.
 
 ```julia
-dimension
+dimension  # topological dimensions
 spatialDimension
-asText
-asBinary
+
 
 locateAlong
 locateBetween

docs/src/guides/defaults.md

@@ -5,16 +5,18 @@ Of note here are the `ngeom` and `getgeom` for each geometry type, which transla
 |                            | ngeom       | getgeom       |
 |----------------------------|-------------|---------------|
 | [`AbstractPointTrait`](@ref)              | -           | -             |
-| [`AbstractCurveTrait`](@ref), [`MultiPointTrait`](@ref)  | [`npoint`](@ref)      | [`getpoint`](@ref)      |
-| [`AbstractPolygonTrait`](@ref)            | [`nring`](@ref)       | [`getring`](@ref)       |
-| [`AbstractMultiLineStringTrait`](@ref)    | [`nlinestring`](@ref) | [`getlinestring`](@ref) |
-| [`AbstractMultiPolygonTrait`](@ref)       | [`npolygon`](@ref)    | [`getpolygon`](@ref)    |
-| [`AbstractPolyhedralSurfaceTrait`](@ref)  | [`npatch`](@ref)      | [`getpatch`](@ref)      |
-| [`AbstractGeometryCollectionTrait`](@ref) | [`ngeom`](@ref)       | [`getgeom`](@ref)       |
+| [`AbstractCurveTrait`](@ref), [`MultiPointTrait`](@ref)  | [`npoint(geom)`](@ref)      | [`getpoint(geom)`](@ref)      |
+| [`AbstractPolygonTrait`](@ref)            | [`nring(geom)`](@ref)       | [`getring(geom)`](@ref)       |
+| [`AbstractMultiLineStringTrait`](@ref)    | [`nlinestring(geom)`](@ref) | [`getlinestring(geom)`](@ref) |
+| [`AbstractMultiPolygonTrait`](@ref)       | [`npolygon(geom)`](@ref)    | [`getpolygon(geom)`](@ref)    |
+| [`AbstractPolyhedralSurfaceTrait`](@ref)  | [`npatch(geom)`](@ref)      | [`getpatch(geom)`](@ref)      |
+| [`AbstractGeometryCollectionTrait`](@ref) | [`ngeom(geom)`](@ref)       | [`getgeom(geom)`](@ref)       |
 
 ## Polygons
 Of note are `PolygonTrait`s, which can have holes, for which we automatically add the following
-functions based on the `ngeom` implemented by package authors.
+functions based on the `ngeom` implemented by package authors. In some cases, the assumptions here
+are not correct (most notably Shapefile), where the second ring is not necessarily a hole, but could
+be another exterior.
 
 ```julia
 getexterior(p::AbstractPolygonTrait, geom) = getring(p, geom, 1)

docs/src/guides/developer.md

@@ -15,7 +15,7 @@ GeoInterface.getcoord(geomtype(geom), geom::customgeom, i)::Real  # only for Poi
 GeoInterface.ngeom(geomtype(geom), geom::customgeom)::Integer
 GeoInterface.getgeom(geomtype(geom), geom::customgeom, 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.
+Where the `getgeom` and `getcoord` 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.
 
 You read more about the `geomtype` in the [Type hierarchy](@ref).
 
@@ -29,6 +29,13 @@ GeoInterface.extent(geomtype(geom), geom::customgeom)::Extents.Extent
 
 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 [Fallbacks](@ref).
 
+## Required for Feature
+```julia
+GeoInterface.isfeature(feat::customfeat)::Bool = true
+GeoInterface.properties(feat::customfeat)
+GeoInterface.geometry(feat::customfeat)
+```
+
 ## GeoSpatial Operations
 ```julia
 distance(geomtype(a), geomtype(b), a, b)

docs/src/tutorials/usage.md

@@ -1,14 +1,15 @@
 # Traits interface
-GeoInterface provides a traits interface, not unlike Tables.jl, by a set of functions and types.
+GeoInterface provides a traits interface, not unlike Tables.jl, by a set of functions and types for geospatial data.
 
 ## Functions
 (a) a set of functions: 
 ```julia
 isgeometry(geom)
 geomtype(geom)
 ncoord(geom)
+getcoord(geom, i)
 ngeom(geom)
-getgeom(geom::geomtype, i)
+getgeom(geom, i)
 ...
 ```
 
@@ -32,7 +33,7 @@ to work with their custom geometries, you can just call the above generic functi
 julia> using ArchGDAL
 julia> geom = createpolygon(...)::ArchGDAL.IGeometry  # no idea about the interface
 
-# With GeoInterface
+# Inspect with GeoInterface methods
 julia> isgeometry(geom)
 True
 julia> geomtype(geom)

src/defaults.jl

@@ -20,33 +20,42 @@ isempty(T, geom) = false
 
 ## Points
 ngeom(::AbstractPointTrait, geom)::Integer = 0
+getgeom(::AbstractPointTrait, geom) = nothing
 getgeom(::AbstractPointTrait, geom, i) = nothing
 
 ## LineStrings
 npoint(c::AbstractCurveTrait, geom) = ngeom(c, geom)
+getpoint(c::AbstractCurveTrait, geom) = getgeom(c, geom)
 getpoint(c::AbstractCurveTrait, geom, i) = getgeom(c, geom, i)
 startpoint(c::AbstractCurveTrait, geom) = getpoint(c, geom, 1)
 endpoint(c::AbstractCurveTrait, geom) = getpoint(c, geom, length(geom))
 
 ## Polygons
 nring(p::AbstractPolygonTrait, geom) = ngeom(p, geom)
+getring(p::AbstractPolygonTrait, geom) = getgeom(p, geom)
 getring(p::AbstractPolygonTrait, geom, i) = getgeom(p, geom, i)
 getexterior(p::AbstractPolygonTrait, geom) = getring(p, geom, 1)
 nhole(p::AbstractPolygonTrait, geom) = nring(p, geom) - 1
 gethole(p::AbstractPolygonTrait, geom, i) = getring(p, geom, i + 1)
 
 ## MultiLineString
 nlinestring(p::AbstractMultiLineStringTrait, geom) = ngeom(p, geom)
+getlinestring(p::AbstractMultiLineStringTrait, geom) = getgeom(p, geom)
 getlinestring(p::AbstractMultiLineStringTrait, geom, i) = getgeom(p, geom, i)
 
 ## MultiPolygon
 npolygon(p::AbstractMultiPolygonTrait, geom) = ngeom(p, geom)
+getpolygon(p::AbstractMultiPolygonTrait, geom) = getgeom(p, geom)
 getpolygon(p::AbstractMultiPolygonTrait, geom, i) = getgeom(p, geom, i)
 
 ## Surface
 npatch(p::AbstractPolyHedralSurfaceTrait, geom)::Integer = ngeom(p, geom)
+getpatch(p::AbstractPolyHedralSurfaceTrait, geom) = getgeom(p, geom)
 getpatch(p::AbstractPolyHedralSurfaceTrait, geom, i::Integer) = getgeom(p, geom, i)
 
+## Default iterator
+getgeom(p::AbstractGeometryTrait, geom) = (getgeom(p, geom, i) for i in 1:ngeom(p, geom))
+getcoord(p::AbstractPointTrait, geom) = (getcoord(p, geom, i) for i in 1:ncoord(p, geom))
 
 ## Npoints
 npoint(::LineTrait, _) = 2
@@ -71,8 +80,17 @@ extent(::AbstractGeometryTrait, geom) = nothing
 
 # Backwards compatibility
 function coordinates(::AbstractPointTrait, geom)
-    collect(getcoord(geom, i) for i in 1:ncoord(geom))
+    collect(getcoord(geom))
 end
 function coordinates(::AbstractGeometryTrait, geom)
-    collect(coordinates(getgeom(geom, i)) for i in 1:ngeom(geom))
+    collect(coordinates(getgeom(geom)))
 end
+
+# Subtraits
+subtrait(::PointTrait) = nothing
+subtrait(::LineStringTrait) = PointTrait
+subtrait(::PolygonTrait) = LineStringTrait
+subtrait(::MultiPointTrait) = PointTrait
+subtrait(::MultiLineStringTrait) = LineStringTrait
+subtrait(::MultiPolygonTrait) = PolygonTrait
+subtrait(::GeometryCollectionTrait) = nothing

src/interface.jl

@@ -10,6 +10,35 @@ method.
 isgeometry(x::T) where {T} = isgeometry(T)
 isgeometry(::Type{T}) where {T} = false
 
+"""
+    GeoInterface.isfeature(x) => Bool
+
+Check if an object `x` is a feature and thus implicitely 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 the older GeoInterface.
+"""
+isfeature(x::T) where {T} = isfeature(T)
+isfeature(::Type{T}) where {T} = false
+
+"""
+    GeoInterface.geometry(feat) => geom
+
+Retrieve the geometry of `feat`. It is expected that `isgeometry(geom) === true`.
+Ensures backwards compatibility with the older GeoInterface.
+"""
+geometry(feat) = nothing
+
+"""
+    GeoInterface.properties(feat) => properties
+
+Retrieve the properties of `feat`. This can be any Iterable that behaves like an AbstractRow.
+Ensures backwards compatibility with the older GeoInterface.
+"""
+properties(feat) = nothing
+
 """
     GeoInterface.geomtype(geom) => T <: AbstractGeometry
 
@@ -54,6 +83,10 @@ Return the `i`th coordinate for a given `geom`.
 Note that this is only valid for individual [`AbstractPoint`]s.
 """
 getcoord(geom, i::Integer) = getcoord(geomtype(geom), geom, i)
+"""
+    getcoord(geom) -> Iterator
+"""
+getcoord(geom) = getcoord(geomtype(geom), geom)
 
 # Curve, LineString, MultiPoint
 """
@@ -71,6 +104,10 @@ Return the `i`th Point in given `geom`.
 Note that this is only valid for [`AbstractCurve`](@ref)s and [`AbstractMultiPoint`](@ref)s.
 """
 getpoint(geom, i::Integer) = getpoint(geomtype(geom), geom, i)
+"""
+    getpoint(geom) -> Iterator
+"""
+getpoint(geom) = getpoint(geomtype(geom), geom)
 
 # Curve
 """
@@ -164,6 +201,10 @@ nring(geom) = nring(geomtype(geom), geom)
 Return the `i`th ring for a given `geom`.
 Note that this is only valid for [`AbstractPolygon`](@ref)s.
 """
+getring(geom, i::Integer) = getring(geomtype(geom), geom, i)
+"""
+    getring(geom) -> Iterator
+"""
 getring(geom) = getring(geomtype(geom), geom)
 
 """
@@ -189,6 +230,10 @@ Returns the `i`th interior ring for this given `geom`.
 Note that this is only valid for [`AbstractPolygon`](@ref)s.
 """
 gethole(geom, i::Integer) = gethole(geomtype(geom), geom, i)
+"""
+    gethole(geom) -> Iterator
+"""
+gethole(geom) = gethole(geomtype(geom), geom)
 
 # PolyHedralSurface
 """
@@ -206,6 +251,10 @@ Returns the `i`th patch for the given `geom`.
 Note that this is only valid for [`AbstractPolyHedralSurface`](@ref)s.
 """
 getpatch(geom, i::Integer) = getpatch(geomtype(geom), geom, i)
+"""
+    getpatch(geom) -> Iterator
+"""
+getpatch(geom) = getpatch(geomtype(geom), geom)
 
 """
     boundingpolygons(geom, i) -> AbstractMultiPolygon
@@ -228,6 +277,10 @@ ngeom(geom) = ngeom(geomtype(geom), geom)
 Returns the `i`th geometry for the given `geom`.
 """
 getgeom(geom, i::Integer) = getgeom(geomtype(geom), geom, i)
+"""
+    getgeom(geom) -> Iterator
+"""
+getgeom(geom) = getgeom(geomtype(geom), geom)
 
 # MultiLineString
 """
@@ -245,6 +298,10 @@ Returns the `i`th linestring for the given `geom`.
 Note that this is only valid for [`AbstractMultiLineString`](@ref)s.
 """
 getlinestring(geom, i::Integer) = getlinestring(geomtype(geom), geom, i)
+"""
+    getlinestring(geom) -> Iterator
+"""
+getlinestring(geom) = getlinestring(geomtype(geom), geom)
 
 # MultiPolygon
 """
@@ -254,13 +311,18 @@ Returns the number of polygons for the given `geom`.
 Note that this is only valid for [`AbstractMultiPolygon`](@ref)s.
 """
 npolygon(geom) = npolygon(geomtype(geom), geom)
+
 """
     getpolygon(geom, i::Integer) -> AbstractCurve
 
 Returns the `i`th polygon for the given `geom`.
 Note that this is only valid for [`AbstractMultiPolygon`](@ref)s.
 """
 getpolygon(geom, i::Integer) = getpolygon(geomtype(geom), geom, i)
+"""
+    getpolygon(geom) -> Iterator
+"""
+getpolygon(geom) = getpolygon(geomtype(geom), geom)
 
 # Other methods
 """
@@ -284,6 +346,7 @@ extent(geom) = extent(geomtype(geom), geom)
 
 Alias for [`extent`](@ref), for compatibility with
 GeoJSON and the Python geointerface.
+Ensures backwards compatibility with the older GeoInterface.
 """
 bbox(geom) = extent(geom)
 
@@ -458,7 +521,7 @@ ismeasured(geom) = ismeasured(geomtype(geom), geom)
     coordinates(geom) -> Vector
 
 Return (an iterator of) point coordinates.
-Ensure backwards compatibility with the older GeoInterface
+Ensures backwards compatibility with the older GeoInterface.
 """
 coordinates(geom) = coordinates(geomtype(geom), geom)