Merge branch 'main' into as/clipping_crs

Author: asinghvi17

.github/workflows/CI.yml

@@ -34,12 +34,11 @@ jobs:
             arch: arm64
     steps:
       - uses: actions/checkout@v2
-      - uses: julia-actions/cache@v1
-      - uses: julia-actions/setup-julia@v1
+      - uses: julia-actions/cache@v2
+      - uses: julia-actions/setup-julia@v2
         with:
           version: ${{ matrix.version }}
           arch: ${{ matrix.arch }}
-      - uses: julia-actions/cache@v1
       - name: Dev GeometryOpsCore and add other packages
         run: julia --project=. -e 'using Pkg; Pkg.develop(; path = joinpath(".", "GeometryOpsCore"));'
       - uses: julia-actions/julia-buildpkg@v1
@@ -62,8 +61,8 @@ jobs:
       actions: write
     steps:
       - uses: actions/checkout@v2
-      - uses: julia-actions/cache@v1
-      - uses: julia-actions/setup-julia@v1
+      - uses: julia-actions/cache@v2
+      - uses: julia-actions/setup-julia@v2
         with:
           version: '1'
       - name: Build and add versions
@@ -82,9 +81,9 @@ jobs:
       statuses: write
       actions: write
     steps:
-      - uses: actions/checkout@v2
-      - uses: julia-actions/cache@v1
-      - uses: julia-actions/setup-julia@v1
+      - uses: actions/checkout@v4
+      - uses: julia-actions/cache@v2
+      - uses: julia-actions/setup-julia@v2
         with:
           version: '1'
       - name: Build and add versions

GeometryOpsCore/Project.toml

@@ -1,7 +1,7 @@
 name = "GeometryOpsCore"
 uuid = "05efe853-fabf-41c8-927e-7063c8b9f013"
 authors = ["Anshul Singhvi <[email protected]>", "Rafael Schouten <[email protected]>", "Skylar Gering <[email protected]>", "and contributors"]
-version = "0.1.5"
+version = "0.1.7"
 
 [deps]
 DataAPI = "9a962f9c-6df0-11e9-0e5d-c546b8b5ee8a"

GeometryOpsCore/src/apply.jl

@@ -175,9 +175,11 @@ with the same schema, but with the new geometry column.
 This new table may be of the same type as the old one iff `Tables.materializer` is defined for 
 that table.  If not, then a `NamedTuple` is returned.
 =#
-function _apply_table(f::F, target, iterable::IterableType; geometrycolumn = nothing, preserve_default_metadata = false, threaded, kw...) where {F, IterableType}
-    _get_col_pair(colname) = colname => Tables.getcolumn(iterable, colname)
-    # We extract the geometry column and run `apply` on it.
+function _apply_table(f::F, target, iterable::IterableType; geometrycolumn = nothing, preserve_default_metadata = false, threaded, kw...) where {F, IterableType}    # We extract the geometry column and run `apply` on it.
+    # First, we need the table schema:
+    input_schema = Tables.schema(iterable)
+    input_colnames = input_schema.names
+    # then, we find the geometry column(s)
     geometry_columns = if isnothing(geometrycolumn)
         GI.geometrycolumns(iterable)
     elseif geometrycolumn isa NTuple{N, <: Symbol} where N
@@ -187,31 +189,31 @@ function _apply_table(f::F, target, iterable::IterableType; geometrycolumn = not
     else
         throw(ArgumentError("geometrycolumn must be a Symbol or a tuple of Symbols, got a $(typeof(geometrycolumn))"))
     end
-    if !all(Base.Fix2(in, Tables.columnnames(iterable)), geometry_columns)
+    if !Base.issubset(geometry_columns, input_colnames)
         throw(ArgumentError(
             """
             `apply`: the `geometrycolumn` kwarg must be a subset of the column names of the table, 
             got $(geometry_columns)
             but the table has columns 
-            $(Tables.columnnames(iterable))
+            $(input_colnames)
             """
             ))
     end
+    # here we apply the function to the geometry column(s).
+    apply_kw = if isempty(used_reconstruct_table_kwargs(iterable))
+        kw
+    else
+        Base.structdiff(values(kw), NamedTuple{used_reconstruct_table_kwargs(iterable)})
+    end
     new_geometry_vecs = map(geometry_columns) do colname
-        _apply(f, target, Tables.getcolumn(iterable, colname); threaded, kw...)
+        _apply(f, target, Tables.getcolumn(iterable, colname); threaded, apply_kw...)
     end
-    # Then, we obtain the schema of the table,
-    old_schema = Tables.schema(iterable)
-    # filter the geometry column out,
-    new_names = filter(x -> !(x in geometry_columns), old_schema.names)
+    # Then, we filter the geometry column(s) out,
+    new_names = filter(x -> !(x in geometry_columns), input_colnames)
     # and try to rebuild the same table as the best type - either the original type of `iterable`,
     # or a named tuple which is the default fallback.
-    result = Tables.materializer(iterable)(
-        merge(
-            NamedTuple{geometry_columns, Base.Tuple{typeof.(new_geometry_vecs)...}}(new_geometry_vecs),
-            NamedTuple(Iterators.map(_get_col_pair, new_names))
-        )
-    )
+    # See the function directly below this one for the actual fallback implementation.
+    result = reconstruct_table(iterable, geometry_columns, new_geometry_vecs, new_names; kw...)
     # Finally, we ensure that metadata is propagated correctly.
     # This can only happen if the original table supports metadata reads,
     # and the result supports metadata writes.
@@ -246,6 +248,51 @@ function _apply_table(f::F, target, iterable::IterableType; geometrycolumn = not
     return result
 end
 
+
+"""
+    used_reconstruct_table_kwargs(input)
+
+Return a tuple of the kwargs that should be passed to `reconstruct_table` for the given input.
+
+This is "semi-public" API, and required for any input type that defines `reconstruct_table`.
+"""
+function used_reconstruct_table_kwargs(input) 
+    ()
+end
+
+"""
+    reconstruct_table(input, geometry_column_names, geometry_columns, other_column_names, args...; kwargs...)
+
+Reconstruct a table from the given input, geometry column names,
+geometry columns, and other column names.
+
+Any function that defines `reconstruct_table` must also define `used_reconstruct_table_kwargs`.
+
+The input must be a table.
+
+The function should return a best-effort attempt at a table of the same type as the input,
+with the new geometry column(s) and other columns.
+
+The fallback implementation invokes `Tables.materializer`.  But if you want to be efficient 
+and pass e.g. arbitrary kwargs to the materializer, or materialize in a different way, you 
+can do so by overloading this function for your desired input type.
+
+This is "semi-public" API and while it may add optional arguments, it will not add new required 
+positional arguments. All implementations must allow arbitrary kwargs to pass through and harvest 
+what they need.
+"""
+function reconstruct_table(input, geometry_column_names, geometry_columns, other_column_names, args...; kwargs...)
+    @assert Tables.istable(input)
+    _get_col_pair(colname) = colname => Tables.getcolumn(input, colname)
+
+    return Tables.materializer(input)(
+        merge(
+            NamedTuple{geometry_column_names, Base.Tuple{typeof.(geometry_columns)...}}(geometry_columns),
+            NamedTuple(Iterators.map(_get_col_pair, other_column_names))
+        )
+    )
+end
+
 # Rewrap all FeatureCollectionTrait feature collections as GI.FeatureCollection
 # Maybe use threads to call _apply on component features
 @inline function _apply(f::F, target, ::GI.FeatureCollectionTrait, fc;
@@ -323,12 +370,20 @@ end
 # So the `Target` is found. We apply `f` to geom and return it to previous
 # _apply calls to be wrapped with the outer geometries/feature/featurecollection/array.
 _apply(f::F, ::TraitTarget{Target}, ::Trait, geom; crs=GI.crs(geom), kw...) where {F,Target,Trait<:Target} = f(geom)
+function _apply(a::WithTrait{F}, ::TraitTarget{Target}, trait::Trait, geom; crs=GI.crs(geom), kw...) where {F,Target,Trait<:Target} 
+    a(trait, geom; Base.structdiff(values(kw), NamedTuple{(:threaded, :calc_extent)})...)
+end
 # Define some specific cases of this match to avoid method ambiguity
 for T in (
     GI.PointTrait, GI.LinearRing, GI.LineString,
     GI.MultiPoint, GI.FeatureTrait, GI.FeatureCollectionTrait
 )
-    @eval _apply(f::F, target::TraitTarget{<:$T}, trait::$T, x; kw...) where F = f(x)
+    @eval begin 
+        _apply(f::F, target::TraitTarget{<:$T}, trait::$T, x; kw...) where F = f(x)
+        function _apply(a::WithTrait{F}, target::TraitTarget{<:$T}, trait::$T, x; kw...) where F
+            a(trait, x; Base.structdiff(values(kw), NamedTuple{(:threaded, :calc_extent)})...)
+        end
+    end
 end
 
 

GeometryOpsCore/src/applyreduce.jl

@@ -51,7 +51,7 @@ Literate.jl source code is below.
 =#
 
 """
-    applyreduce(f, op, target::Union{TraitTarget, GI.AbstractTrait}, obj; threaded)
+    applyreduce(f, op, target::Union{TraitTarget, GI.AbstractTrait}, obj; threaded, init, kw...)
 
 Apply function `f` to all objects with the `target` trait,
 and reduce the result with an `op` like `+`. 
@@ -60,6 +60,8 @@ The order and grouping of application of `op` is not guaranteed.
 
 If `threaded==true` threads will be used over arrays and iterables, 
 feature collections and nested geometries.
+
+`init` functions the same way as it does in base Julia functions like `reduce`.
 """
 @inline function applyreduce(
     f::F, op::O, target, geom; threaded=false, init=nothing
@@ -129,6 +131,9 @@ end
 @inline function _applyreduce(f::F, op::O, ::TraitTarget{Target}, ::Trait, x; kw...) where {F,O,Target,Trait<:Target} 
     f(x)
 end
+@inline function _applyreduce(a::WithTrait{F}, op::O, ::TraitTarget{Target}, trait::Trait, x; kw...) where {F,O,Target,Trait<:Target} 
+    a(trait, x; Base.structdiff(values(kw), NamedTuple{(:threaded, :init)})...)
+end
 # Fail if we hit PointTrait
 # _applyreduce(f, op, target::TraitTarget{Target}, trait::PointTrait, geom; kw...) where Target = 
     # throw(ArgumentError("target $target not found"))
@@ -137,7 +142,12 @@ for T in (
     GI.PointTrait, GI.LinearRing, GI.LineString, 
     GI.MultiPoint, GI.FeatureTrait, GI.FeatureCollectionTrait
 )
-    @eval _applyreduce(f::F, op::O, ::TraitTarget{<:$T}, trait::$T, x; kw...) where {F, O} = f(x)
+    @eval begin
+        _applyreduce(f::F, op::O, ::TraitTarget{<:$T}, trait::$T, x; kw...) where {F, O} = f(x)
+        function _applyreduce(a::WithTrait{F}, op::O, ::TraitTarget{<:$T}, trait::$T, x; kw...) where {F, O}
+            a(trait, x; Base.structdiff(values(kw), NamedTuple{(:threaded, :init)})...)
+        end
+    end
 end
 
 ### `_mapreducetasks` - flexible, threaded mapreduce

GeometryOpsCore/src/types/applicators.jl

@@ -54,8 +54,26 @@ const WithXYZM = ApplyToPoint{true,true}
 
 (t::WithXY)(p) = t.f(GI.x(p), GI.y(p))
 (t::WithXYZ)(p) = t.f(GI.x(p), GI.y(p), GI.z(p))
-(t::WithXYZM)(p) = t.f(GI.x(p), GI.y(p), GI.m(p))
-(t::WithXYM)(p) = t.f(GI.x(p), GI.y(p), GI.z(p), GI.m(p))
+(t::WithXYZM)(p) = t.f(GI.x(p), GI.y(p), GI.z(p), GI.m(p))
+(t::WithXYM)(p) = t.f(GI.x(p), GI.y(p), GI.m(p))
+
+"""
+    WithTrait(f)
+
+WithTrait is a functor that applies a function to a trait and an object.
+
+Specifically, the calling convention is for `f` is changed
+from `f(geom)` to `f(trait, geom; kw...)`.
+
+This is useful to keep the trait materialized through the call stack,
+which can improve inferrability and performance.
+"""
+struct WithTrait{F} <: Applicator{F, Nothing}
+    f::F
+end
+
+(a::WithTrait)(trait::GI.AbstractTrait, obj; kw...) = a.f(trait, obj; kw...)
+rebuild(::WithTrait, f::F) where {F} = WithTrait{F}(f)
 
 # ***
 

GeometryOpsCore/src/types/exceptions.jl

@@ -8,8 +8,16 @@ This makes it substantially easier to catch specific kinds of errors and show th
 For example, we can catch `WrongManifoldException` and show a nice error message,
 and error hinters can be specialized to that as well.
 
+We also have a custom error type for missing keywords in an algorithm,
+which could eventually be extended to have typo detection, et cetera.
+
 ```@docs; canonical=false
-GeometryOpsCore.WrongManifoldException
+WrongManifoldException
+MissingKeywordInAlgorithmException
+```
+
+```@meta
+CollapsedDocStrings = true
 ```
 =#
 
@@ -46,4 +54,60 @@ function Base.showerror(io::IO, e::WrongManifoldException{I,D,A}) where {I,D,A}
         print(io, "\n\n")
         print(io, e.description)
     end
+end
+
+
+"""
+    MissingKeywordInAlgorithmException{Alg, F} <: Exception
+
+An error type which is thrown when a keyword argument is missing from an algorithm.
+
+The `alg` argument is the algorithm struct, and the `keyword` argument is the keyword
+that was missing.
+
+This error message is used in the [`enforce`](@ref GeometryOps.enforce) method.
+
+## Usage
+
+This is of course not how you would actually use this error type, but it is
+how you construct and throw it.
+
+```julia
+throw(MissingKeywordInAlgorithmException(GEOS(; tokl = 1.0), my_function, :tol))
+```
+
+Real world usage will often look like this:
+
+```julia
+function my_function(alg::CLibraryPlanarAlgorithm, args...)
+    mykwarg = enforce(alg, :mykwarg, my_function) # this will throw an error if :mykwarg is not present in alg
+end
+```
+"""
+struct MissingKeywordInAlgorithmException{Alg, F} <: Base.Exception
+    alg::Alg
+    f::F
+    keyword::Symbol
+end
+
+_name_of(x::Any) = nameof(typeof(x))
+_name_of(x::Function) = nameof(x)
+_name_of(x::Type) = nameof(x)
+_name_of(s::String) = s
+
+# This is just the generic dispatch, different algorithms can choose to dispatch
+# on their own types to provide more specific or interesting error messages.
+function Base.showerror(io::IO, e::MissingKeywordInAlgorithmException)
+    algorithm_name = _name_of(typeof(e.alg))
+    function_name = _name_of(e.f)
+    print(io, "The ")
+    printstyled(io, e.keyword; color = :red)
+    print(io, " parameter is required for the ")
+    printstyled(io, algorithm_name; bold = true)
+    println(io, " algorithm in `$(function_name)`,")
+    println(io, "but it was not provided.")
+    println(io)
+    println(io, "Provide it to the algorithm at construction time, like so:")
+    println(io, "`$(algorithm_name)(; $(e.keyword) = ...)`")
+    println(io, "and pass that as the algorithm to `$(function_name)`, usually the first argument.")
 end