Split types out into multiple files + add algo interface

Author: asinghvi17

GeometryOpsCore/src/GeometryOpsCore.jl

@@ -6,7 +6,7 @@ import GeoInterface
 import GeoInterface as GI
 import GeoInterface: Extents
 
-# Import all names from GeoInterface and Extents, so users can do `GO.extent` or `GO.trait`.
+# Import all exported names from GeoInterface and Extents, so users can do `GO.extent` or `GO.trait`.
 for name in names(GeoInterface)
     @eval using GeoInterface: $name
 end
@@ -19,7 +19,14 @@ using DataAPI
 import StableTasks
 
 include("keyword_docs.jl")
-include("types.jl")
+include("constants.jl")
+
+include("types/manifold.jl")
+include("types/algorithm.jl")
+include("types/operation.jl")
+include("types/exceptions.jl")
+include("types/booltypes.jl")
+include("types/traittarget.jl")
 
 include("apply.jl")
 include("applyreduce.jl")

GeometryOpsCore/src/types.jl

@@ -0,0 +1,67 @@
+#=
+# `Algorithm`s
+
+An `Algorithm` is a type that describes the algorithm used to perform some [`Operation`](@ref).
+
+An algorithm may be associated with one or many [`Manifold`](@ref)s.  It may either have the manifold as a field, or have it as a static parameter (e.g. `struct GEOS <: Manifold{Planar}`).
+
+
+Algorithms are:
+* Ways to perform an operation
+* For example: LHuilier, Bessel, Ericsson for spherical area
+* May be manifold agnostic (like simplification) or restrictive (like GEOS only works on planar, PROJ algorithm for arclength and area only works on geodesic)
+* May or may not carry manifolds around, but manifold should always be accessible from manifold(alg) - it's not necessary that fixed manifold args can skip carrying the manifold around, eg in the case of Proj{Geodesic}.
+
+=#
+
+export Algorithm, AutoAlgorithm, ManifoldIndependentAlgorithm, SingleManifoldAlgorithm, NoAlgorithm
+
+abstract type Algorithm{M <: Manifold} end
+
+struct AutoAlgorithm{T, M <: Manifold} <: Algorithm{M} 
+    manifold::M
+    x::T
+end
+
+AutoAlgorithm(m::Manifold; kwargs...) = AutoAlgorithm(m, kwargs)
+AutoAlgorithm(; kwargs...) = AutoAlgorithm(AutoManifold(), kwargs)
+
+
+abstract type ManifoldIndependentAlgorithm{M <: Manifold} <: Algorithm{M} end
+
+abstract type SingleManifoldAlgorithm{M <: Manifold} <: Algorithm{M} end
+
+struct NoAlgorithm{M <: Manifold} <: Algorithm{M} 
+    m::M
+end
+
+NoAlgorithm() = NoAlgorithm(Planar()) # TODO: add a NoManifold or AutoManifold type?
+# Maybe AutoManifold
+# and then we have DD.format like materialization  
+
+function (Alg::Type{<: SingleManifoldAlgorithm{M}})(m::M; kwargs...) where {M}
+    # successful - the algorithm is designed for this manifold
+    # in this case, just return `Alg(; kwargs...)`
+    return Alg(; kwargs...)
+end
+
+function (Alg::Type{<: ManifoldIndependentAlgorithm{M}})(m::Manifold; kwargs...) where {M}
+    # this catches the case where the algorithm doesn't match the manifold
+    # throw a WrongManifoldException and be done with it
+    throw(WrongManifoldException{typeof(m), M, Alg}())
+end
+
+# for example
+
+struct MyExternalArbitraryPackageAlgorithm <: SingleManifoldAlgorithm{Planar}
+    kw1::Int
+    kw2::String
+end # this already has the methods specified
+
+struct MyIndependentAlgorithm{M <: Manifold} <: ManifoldIndependentAlgorithm{M}
+    m::M
+    kw1::Int
+    kw2::String
+end
+
+MyIndependentAlgorithm(m::Manifold; kw1 = 1, kw2 = "hello") = MyIndependentAlgorithm(m, kw1, kw2)

GeometryOpsCore/src/types/algorithm.jl

@@ -0,0 +1,53 @@
+#=
+# `BoolsAsTypes`
+
+In `apply` and `applyreduce`, we pass `threading` and `calc_extent` as types, not simple boolean values.  
+
+This is to help compilation - with a type to hold on to, it's easier for 
+the compiler to separate threaded and non-threaded code paths.
+
+Note that if we didn't include the parent abstract type, this would have been really 
+type unstable, since the compiler couldn't tell what would be returned!
+
+We had to add the type annotation on the `booltype(::Bool)` method for this reason as well.
+
+
+!!! note Static.jl
+
+    Static.jl is a package that provides a way to store and manipulate static values.
+    But it creates a lot of invalidations since it breaks the assumption that operations
+    like `<`, `>` and `==` can only return booleans.  So we don't use it here.
+
+=#
+
+export BoolsAsTypes, True, False, booltype
+
+"""
+    abstract type BoolsAsTypes
+
+"""
+abstract type BoolsAsTypes end
+
+"""
+    struct True <: BoolsAsTypes
+
+A struct that means `true`.
+"""
+struct True <: BoolsAsTypes end
+
+"""
+    struct False <: BoolsAsTypes
+
+A struct that means `false`.
+"""
+struct False <: BoolsAsTypes end
+
+"""
+    booltype(x)
+
+Returns a [`BoolsAsTypes`](@ref) from `x`, whether it's a boolean or a BoolsAsTypes.
+"""
+function booltype end
+
+@inline booltype(x::Bool)::BoolsAsTypes = x ? True() : False()
+@inline booltype(x::BoolsAsTypes)::BoolsAsTypes = x

GeometryOpsCore/src/types/booltypes.jl

@@ -0,0 +1,45 @@
+#=
+# Errors and exceptions
+
+We create a few custom exception types in this file,
+that have nice show methods that we can use for certain errors.
+
+This makes it substantially easier to catch specific kinds of errors and show them.
+For example, we can catch `WrongManifoldException` and show a nice error message,
+and error hinters can be specialized to that as well.
+=#
+
+export WrongManifoldException
+
+"""
+    WrongManifoldException{InputManifold, DesiredManifold, Algorithm} <: Exception
+
+This error is thrown when an `Algorithm` is called with a manifold that it was not designed for.
+
+It's mainly called for [`SingleManifoldAlgorithm`](@ref) types.
+"""
+struct WrongManifoldException{InputManifold, DesiredManifold, Algorithm} <: Base.Exception
+    description::String
+end
+
+WrongManifoldException{I, D, A}() where {I, D, A} = WrongManifoldException{I, D, A}("")
+
+function Base.showerror(io::IO, e::WrongManifoldException{I,D,A}) where {I,D,A}
+    print(io, "Algorithm ")
+    printstyled(io, A; bold = true, color = :green) 
+    print(io, " is only compatible with manifold ")
+    printstyled(io, D; bold = true, color = :blue)
+    print(io, ",\n but it was called with manifold ")
+    printstyled(io, I; bold = true, color = :red)
+    print(io, ".")
+
+    println(io, """
+    \n
+    To fix this issue, you can specify the manifold explicitly, 
+    e.g. `$A($D(); kwargs...)`, when constructing the algorithm.
+    """)
+    if !isempty(e.description)
+        print(io, "\n\n")
+        print(io, e.description)
+    end
+end