Box{N}, Window{N}, and Kernel{N} aliases

emmt · emmt · commit 5aea2bf66d3c · 2025-02-27T17:19:36.000+01:00
diff --git a/NEWS.md b/NEWS.md
@@ -27,10 +27,21 @@
 * The algorithm to infer the result type is now based on Julia's arithmetic rules and can
   cope with arguments that have units.
 
-* To represent hyper-rectangular neighborhoods, instances of non-exported
-  `LocalFilters.Box` have been replaced by fast uniform arrays with offset axes from the
-  [`StructuredArrays`](https://github.com/emmt/StructuredArrays.jl) package.
-  `LocalFilters.Box{N,I}` is now an alias to `FastUniformArray{Boll,N,true,I}`.
+* Non-exported *public* aliases `LocalFilters.Kernel{N}` and `LocalFilters.Window{N}`for
+  union of types suitable to define `N`-dimensional kernels or windows in `LocalFilters`.
+  A **kernel** is an array of weights implementing a local filter or an array of Booleans
+  representing a local neighborhood. A **window** is an array of Booleans representing a
+  local neighborhood. As an optimization, a **box** is an hyper-rectangular neighborhood
+  with axes aligned with the Cartesian axes. Thus, a window whose values are all true is
+  also a box and a kernel with Boolean values is also a window. The function
+  `kernel(Dims{N},B)` yields an `N`-dimensional array for any `B::LocalFilters.Kernel{N}`,
+  with Boolean values for any `B::LocalFilters.Window{N}`.
+
+* Non-exported *public* type `LocalFilters.Box{N}` is now an alias to an efficient type to
+  represent `N`-dimensional **boxes**, that is uniformly true windows or hyper-rectangular
+  neighborhoods. Currently, instances of this type are fast uniformly true arrays with
+  offset axes from the [`StructuredArrays`](https://github.com/emmt/StructuredArrays.jl)
+  package and `LocalFilters.Box{N}` is just `FastUniformArray{Bool,N,true}`.
 
 * In local filtering operations, small integers arguments are automatically promoted to a
   wider integer type to avoid overflows. This is similar to what is done by base reduction
diff --git a/docs/src/reference.md b/docs/src/reference.md
@@ -63,15 +63,18 @@ FORWARD_FILTER
 REVERSE_FILTER
 ```
 
-## Neighborhoods and kernels
+## Neighborhoods, boxes, kernels, and windows
 
 ```@docs
 kernel
-reverse_kernel
+LocalFilters.Kernel
+LocalFilters.Window
 strel
 LocalFilters.ball
 LocalFilters.box
+LocalFilters.Box
 LocalFilters.centered
+reverse_kernel
 ```
 
 ## Utilities
diff --git a/src/generic.jl b/src/generic.jl
@@ -83,20 +83,14 @@ As another example, implementing a convolution by `B` writes:
 """ localfilter!
 
 # This version builds a kernel.
-function localfilter!(dst::AbstractArray{<:Any,N},
-                      A::AbstractArray{<:Any,N},
-                      B::Window{N},
-                      initial,
-                      update::Function,
+function localfilter!(dst::AbstractArray{<:Any,N}, A::AbstractArray{<:Any,N},
+                      B::Kernel{N}, initial, update::Function,
                       final::Function = identity; kwds...) where {N}
     return localfilter!(dst, A, kernel(Dims{N}, B), initial, update, final; kwds...)
 end
 
-@inline function localfilter!(dst::AbstractArray{<:Any,N},
-                              A::AbstractArray{<:Any,N},
-                              B::AbstractArray{<:Any,N},
-                              initial,
-                              update::Function,
+@inline function localfilter!(dst::AbstractArray{<:Any,N}, A::AbstractArray{<:Any,N},
+                              B::AbstractArray{<:Any,N}, initial, update::Function,
                               final::Function = identity;
                               order::FilterOrdering = FORWARD_FILTER) where {N}
     !(initial isa Function) || axes(dst) == axes(A) || throw(DimensionMismatch(
@@ -141,18 +135,14 @@ automatically yield either `B[j-i]` or `B[i-j]` depending on whether `order` is
 `FORWARD_FILTER` or `REVERSE_FILTER`.
 
 """
-function localfilter!(dst::AbstractArray{<:Any,N},
-                      A::AbstractArray{<:Any,N},
-                      B::Window{N},
-                      filter!::Function; kwds...) where {N}
+function localfilter!(dst::AbstractArray{<:Any,N}, A::AbstractArray{<:Any,N},
+                      B::Kernel{N}, filter!::Function; kwds...) where {N}
     # Build kernel.
     return localfilter!(dst, A, kernel(Dims{N}, B), filter!; kwds...)
 end
 
-function localfilter!(dst::AbstractArray{<:Any,N},
-                      A::AbstractArray{<:Any,N},
-                      B::AbstractArray{<:Any,N},
-                      filter!::Function;
+function localfilter!(dst::AbstractArray{<:Any,N}, A::AbstractArray{<:Any,N},
+                      B::AbstractArray{<:Any,N}, filter!::Function;
                       order::FilterOrdering = FORWARD_FILTER) where {N}
     indices = Indices(dst, A, B)
     @inbounds for i in indices(dst)
diff --git a/src/linear.jl b/src/linear.jl
@@ -30,7 +30,7 @@ Keyword `order` specifies the filter direction, `FORWARD_FILTER` by default.
 See also [`localmean!`](@ref) and [`localfilter!`](@ref).
 
 """
-localmean(A::AbstractArray{<:Any,N}, B::Window{N} = 3; kwds...) where {N} =
+localmean(A::AbstractArray{<:Any,N}, B::Kernel{N} = 3; kwds...) where {N} =
     localmean(A, kernel(Dims{N}, B); kwds...)
 
 function localmean(A::AbstractArray{<:Any,N}, B::AbstractArray{<:Any,N}; kwds...) where {N}
@@ -53,7 +53,7 @@ See also [`localmean`](@ref) and [`localfilter!`](@ref).
 
 """
 function localmean!(dst::AbstractArray{<:Any,N}, A::AbstractArray{<:Any,N},
-                    B::Window{N} = 3; kwds...) where {N}
+                    B::Kernel{N} = 3; kwds...) where {N}
     return localmean!(dst, A, kernel(Dims{N}, B); kwds...)
 end
 
diff --git a/src/morphology.jl b/src/morphology.jl
@@ -104,7 +104,7 @@ for (f, op) in ((:erode, :min), (:dilate, :max))
 
         # Build structuring element.
         function $f!(dst::AbstractArray{<:Any,N}, A::AbstractArray{<:Any,N},
-                     B::Window{N} = 3; kwds...) where {N}
+                     B::Kernel{N} = 3; kwds...) where {N}
             return $f!(dst, A, kernel(Dims{N}, B); kwds...)
         end
 
@@ -122,7 +122,7 @@ for (f, op) in ((:erode, :min), (:dilate, :max))
         end
 
         # Fast separable filter (in-place).
-        function $f!(A::AbstractArray{<:Any,N}, B::Window{N} = 3; kwds...) where {N}
+        function $f!(A::AbstractArray{<:Any,N}, B::Kernel{N} = 3; kwds...) where {N}
             _B = kernel(Dims{N}, B)
             is_morpho_math_box(_B) || throw(ArgumentError(
                 "for in-place operation kernel must be a simple box"))
@@ -239,7 +239,7 @@ See [`localextrema`](@ref) for an out-of-place version for more information.
 function localextrema!(Amin::AbstractArray{<:Any,N},
                        Amax::AbstractArray{<:Any,N},
                        A::AbstractArray{<:Any,N},
-                       B::Window{N} = 3; kwds...) where {N}
+                       B::Kernel{N} = 3; kwds...) where {N}
     return localextrema!(Amin, Amax, A, kernel(Dims{N}, B); kwds...)
 end
 
@@ -365,7 +365,7 @@ for f in (:closing, :opening)
 
         # Provide default structuring element and build kernel.
         function $f!(dst::AbstractArray{<:Any,N}, wrk::AbstractArray{<:Any,N},
-                     A::AbstractArray{<:Any,N}, B::Window{N} = 3; kwds...) where {N}
+                     A::AbstractArray{<:Any,N}, B::Kernel{N} = 3; kwds...) where {N}
             return $f!(dst, wrk, A, kernel(Dims{N}, B); kwds...)
         end
     end
diff --git a/src/types.jl b/src/types.jl
@@ -27,42 +27,51 @@ const ArrayAxes{N} = NTuple{N,AbstractUnitRange{<:Integer}}
 struct Indices{S<:IndexStyle} <: Function end
 
 """
-    LocalFilters.Window{N}
+    const LocalFilters.Box{N} = FastUniformArray{Bool,N,true}
+
+is an alias to the type of uniformly `true` `N`-dimensional arrays. Instances of this kind
+are used to represent hyper-rectangular sliding windows in `LocalFilters`.
+
+Method [`LocalFilters.box`](@ref) can be used to build an object of this type.
 
-is the union of types for an argument `B` to be suitable to define a simple
-`N`-dimensional hyper-rectangular sliding window and that can be converted into a
-`Box{N}`, that is a `N`-dimensional uniformly true kernel array by [`kernel(Dims{N},
-B)`](@ref LocalFilters.kernel).
+"""
+const Box{N} = FastUniformArray{Bool,N,true}
+@public Box
 
+"""
+    LocalFilters.BoxLike{N}
 
- a kernel
-by the [`LocalFilters.kernel`](@ref) method.
+is the union of types of arguments suitable to define a simple `N`-dimensional *box*, that
+is an hyper-rectangular sliding window. Any argument `B` of this type can be converted
+into a `Box{N}` instance which is a `N`-dimensional uniformly true array by
+[`kernel(Dims{N}, B)`](@ref LocalFilters.kernel).
 
 """
-const Window{N} = Union{Axis,NTuple{N,Axis},NTuple{2,CartesianIndex{N}},
-                        CartesianIndices{N}}
+const BoxLike{N} = Union{Axis,NTuple{N,Axis},NTuple{2,CartesianIndex{N}},
+                         CartesianIndices{N}}
 
 """
     LocalFilters.Kernel{N}
 
-is the union of types for an argument `B` to be suitable to define a `N`-dimensional
-kernel or filter that can be converted into a `N`-dimensional kernel array by
+is the union of types of arguments suitable to define a `N`-dimensional kernel or filter.
+Any argument `B` of this type can be converted into a `N`-dimensional kernel array by
 [`kernel(Dims{N}, B)`](@ref LocalFilters.kernel).
 
 """
-const Kernel{N} = Union{Window{N},AbstractArray{<:Any,N}}
+const Kernel{N} = Union{BoxLike{N},AbstractArray{<:Any,N}}
+@public Kernel
 
 """
-    const LocalFilters.Box{N} = FastUniformArray{Bool,N,true}
-
-is an alias to the type of `N`-dimensional arrays whose elements are all `true`. Instances
-of this kind are used to represent hyper-rectangular sliding windows in `LocalFilters`.
+    LocalFilters.Window{N}
 
-Method [`LocalFilters.box`](@ref) can be used to build an object of this type.
+is the union of types of arguments suitable to define a `N`-dimensional sliding *window*
+that is a `N`-dimensional array of Booleans indicating whether a position belongs to the
+window of not. Any argument `B` of this type can be converted into a `N`-dimensional
+array of Booleans by [`kernel(Dims{N}, B)`](@ref LocalFilters.kernel).
 
 """
-const Box{N} = FastUniformArray{Bool,N,true}
-@public Box
+const Window{N} = Union{BoxLike{N},AbstractArray{Bool,N}}
+@public Window
 
 """
     LocalFilters.FilterOrdering
