Add comments to naturalindexing and clean up

e.g. remove redundant getpoint definitions, etc

Author: asinghvi17

src/utils/NaturalIndexing.jl

@@ -4,6 +4,9 @@ import GeoInterface as GI
 import Extents
 
 using ..SpatialTreeInterface
+
+import ..GeometryOps as GO # TODO: only needed for NaturallyIndexedRing, remove when that is removed.
+
 export NaturalTree, NaturallyIndexedRing, prepare_naturally
 
 """
@@ -35,33 +38,37 @@ struct NaturalIndex{E <: Extents.Extent}
     levels::Vector{NaturalLevel{E}}
 end
 
-GI.extent(idx::NaturalIndex) = idx.extent
 Extents.extent(idx::NaturalIndex) = idx.extent
 
 function Base.show(io::IO, ::MIME"text/plain", idx::NaturalIndex)
     println(io, "NaturalIndex with $(length(idx.levels)) levels and $(idx.nodecapacity) children per node")
     println(io, "extent: $(idx.extent)")
 end
-
 function Base.show(io::IO, idx::NaturalIndex)
     println(io, "NaturalIndex($(length(idx.levels)) levels, $(idx.extent))")
 end
 
 function NaturalIndex(geoms; nodecapacity = 32)
+    # Get the extent type initially (coord order, coord type, etc.)
+    # so that the construction is type stable.
     e1 = GI.extent(first(geoms))
     E = typeof(e1)
     return NaturalIndex{E}(geoms; nodecapacity = nodecapacity)
 end
-
-function NaturalIndex{E}(geoms; nodecapacity = 32) where E <: Extents.Extent
-    last_level_extents = GI.extent.(geoms)
+function NaturalIndex(last_level_extents::Vector{E}; nodecapacity = 32) where E <: Extents.Extent
+    # If we are passed a vector of extents - inflate immediately!
     return NaturalIndex{E}(last_level_extents; nodecapacity = nodecapacity)
 end
 
-function NaturalIndex(last_level_extents::Vector{E}; nodecapacity = 32) where E <: Extents.Extent
+function NaturalIndex{E}(geoms; nodecapacity = 32) where E <: Extents.Extent
+    # If passed a vector of geometries, and we know the type of the extent,
+    # then simply retrieve the extents so they can serve as the "last-level" 
+    # extents.
+    # Finally, call the lowest level method that performs inflation.
+    last_level_extents = GI.extent.(geoms)
     return NaturalIndex{E}(last_level_extents; nodecapacity = nodecapacity)
 end
-
+# This is the main constructor that performs inflation.
 function NaturalIndex{E}(last_level_extents::Vector{E}; nodecapacity = 32) where E <: Extents.Extent
     ngeoms = length(last_level_extents)
     last_level = NaturalLevel(last_level_extents)
@@ -70,11 +77,11 @@ function NaturalIndex{E}(last_level_extents::Vector{E}; nodecapacity = 32) where
 
     levels = Vector{NaturalLevel{E}}(undef, nlevels)
     levels[end] = last_level
-
+    # Iterate backwards, from bottom to top level,
+    # and build up the level extent vectors.
     for level_index in (nlevels-1):(-1):1
-        prev_level = levels[level_index+1] # this is always instantiated
+        prev_level = levels[level_index+1] # this is always instantiated, since we are iterating backwards
         nrects = _number_of_keys(nodecapacity, nlevels - (level_index), ngeoms)
-        # @show level_index nrects
         extents = [
             begin
                 start = (rect_index - 1) * nodecapacity + 1
@@ -185,6 +192,15 @@ SpatialTreeInterface.getchild(node::NaturalIndex, i) = SpatialTreeInterface.getc
 
 SpatialTreeInterface.child_indices_extents(node::NaturalIndex) = (i_ext for i_ext in enumerate(node.levels[1].extents))
 
+"""
+    NaturallyIndexedRing(points; nodecapacity = 32)
+
+A linear ring that contains a natural index.
+
+!!! warning
+    This will be removed in favour of prepared geometry - the idea here
+    is just to test what interface works best to store things in.
+"""
 struct NaturallyIndexedRing
     points::Vector{Tuple{Float64, Float64}}
     index::NaturalIndex{Extents.Extent{(:X, :Y), NTuple{2, NTuple{2, Float64}}}}
@@ -194,7 +210,6 @@ function NaturallyIndexedRing(points::Vector{Tuple{Float64, Float64}}; nodecapac
     index = NaturalIndex(GO.edge_extents(GI.LinearRing(points)); nodecapacity)
     return NaturallyIndexedRing(points, index)
 end
-
 NaturallyIndexedRing(ring::NaturallyIndexedRing) = ring
 
 function GI.convert(::Type{NaturallyIndexedRing}, ::GI.LinearRingTrait, geom)
@@ -203,24 +218,19 @@ function GI.convert(::Type{NaturallyIndexedRing}, ::GI.LinearRingTrait, geom)
 end
 
 Base.show(io::IO, ::MIME"text/plain", ring::NaturallyIndexedRing) = Base.show(io, ring)
-
 Base.show(io::IO, ring::NaturallyIndexedRing) = print(io, "NaturallyIndexedRing($(length(ring.points)) points) with index $(sprint(show, ring.index))")
 
 GI.ncoord(::GI.LinearRingTrait, ring::NaturallyIndexedRing) = 2
 GI.is3d(::GI.LinearRingTrait, ring::NaturallyIndexedRing) = false
 GI.ismeasured(::GI.LinearRingTrait, ring::NaturallyIndexedRing) = false
 
-GI.npoint(::GI.LinearRingTrait, ring::NaturallyIndexedRing) = length(ring.points)
-GI.getpoint(::GI.LinearRingTrait, ring::NaturallyIndexedRing) = ring.points[i]
-GI.getpoint(::GI.LinearRingTrait, ring::NaturallyIndexedRing, i::Int) = ring.points[i]
-
 GI.ngeom(::GI.LinearRingTrait, ring::NaturallyIndexedRing) = length(ring.points)
 GI.getgeom(::GI.LinearRingTrait, ring::NaturallyIndexedRing) = ring.points
 GI.getgeom(::GI.LinearRingTrait, ring::NaturallyIndexedRing, i::Int) = ring.points[i]
 
 Extents.extent(ring::NaturallyIndexedRing) = ring.index.extent
 
-GI.isgeometry(::NaturallyIndexedRing) = true
+GI.isgeometry(::Type{<: NaturallyIndexedRing}) = true
 GI.geomtrait(::NaturallyIndexedRing) = GI.LinearRingTrait()
 
 function prepare_naturally(geom)