Add geometrycolumns as an interface method.

Author: evetion

docs/src/guides/developer.md

@@ -50,13 +50,27 @@ Base.convert(::Type{T}, ::LineStringTrait, geom::T) = geom  # fast fallthrough w
 Base.convert(::Type{T}, ::LineStringTrait, geom) = ...  # slow custom conversion based on ngeom and getgeom
 ```
 
-## Required for Feature
+## Required for Feature(Collection)s
+A Feature is a geometry with properties, and in modern parlance, a row in table.
+A FeatureCollection is thus a Vector of Features, often represented as a table.
+
+A Feature implements the following:
 ```julia
 GeoInterface.isfeature(feat::customfeat)::Bool = true
 GeoInterface.properties(feat::customfeat)
 GeoInterface.geometry(feat::customfeat)
 ```
 
+While a FeatureCollection implements the following:
+```julia
+GeoInterface.isfeaturecollection(::Type{customcollection}) = true
+GeoInterface.getfeature(trait(::customcollection), ::customcollection, i)
+GeoInterface.nfeature(trait(::customcollection), ::customcollection)
+GeoInterface.geometrycolumns(::customcollection) = (:geometry,)  # can be multiple!
+```
+
+The `geometrycolumns` enables other packages to know which field in a row, or column in a table, contains the geometry or geometries.
+
 ## GeoSpatial Operations
 ```julia
 distance(geomtrait(a), geomtrait(b), a, b)

src/GeoInterface.jl

@@ -43,7 +43,7 @@ export AbstractGeometryTrait,
     MultiPolygonTrait,
     AbstractFeatureTrait,
     FeatureTrait,
-    AbstractCollectionFeatureTrait,
+    AbstractFeatureCollectionTrait,
     FeatureCollectionTrait
 
 

src/interface.jl

@@ -38,6 +38,14 @@ automatically delegate to this method.
 isfeaturecollection(x::T) where {T} = isfeaturecollection(T)
 isfeaturecollection(::Type{T}) where {T} = false
 
+"""
+    GeoInterface.geometrycolumns(featurecollection) => (:geom,)
+
+Retrieve the geometrycolumn(s) of `featurecollection`; the fields (or columns in a table)
+which contain geometries that support GeoInterface.
+"""
+geometrycolumns(featurecollection) = (:geometry,)
+
 """
     GeoInterface.geometry(feat) => geom
 
@@ -60,15 +68,15 @@ properties(feat) = nothing
 Retrieve the features of `collection` as some iterable of features.
 It is expected that `isfeature(feature) === true`.
 """
-getfeature(collection) =  getfeature(trait(collection), collection)
+getfeature(collection) = getfeature(trait(collection), collection)
 getfeature(collection, i::Integer) = getfeature(trait(collection), collection, i)
 
 """
     GeoInterface.nfeature(collection)
 
 Retrieve the number of features in a feature collection.
 """
-nfeature(collection) = nfeature(trait(collection), collection) 
+nfeature(collection) = nfeature(trait(collection), collection)
 
 """
     GeoInterface.geomtrait(geom) => T <: AbstractGeometry
@@ -80,7 +88,7 @@ geomtrait(geom) = nothing
 """
     GeoInterface.trait(geom) => T <: AbstractGeometry
 
-Returns the object type, such as [`FeatureTrait`](@ref). 
+Returns the object type, such as [`FeatureTrait`](@ref).
 For all `isgeometry` objects `trait` is the same as `geomtrait(obj)`,
 e.g. [`PointTrait`](@ref).
 """

src/utils.jl

@@ -46,7 +46,7 @@ function testfeature(feature)
     props = properties(feature)
     if !isnothing(props)
         @assert first(propertynames(props)) isa Symbol "`propertynames` of $props does not return an iterable of `Symbol`"
-        map(n -> getproperty(props, n), propertynames(props))  
+        map(n -> getproperty(props, n), propertynames(props))
     end
     ext = extent(feature)
     @assert ext isa Union{Nothing,Extent}
@@ -70,5 +70,6 @@ function testfeaturecollection(fc)
         @warn "`nfeatures == 0` for feature collection, cannot test some properties"
     end
     @assert coordinates(fc) == coordinates.(getfeature(fc))
+    @assert geometrycolumns(fc) isa NTuple "feature collection $fc doesn't return a `NTuple` from `geometrycolumns`."
     return true
 end