docs(border-arrays): document filtering helper functions

Adds documentation for `kern_padding`, `outer_axes`, and `padtoaxes`
functions, which are helper functions for sampling extended arrays for
filtering purposes.

Also fixes the missing cross-refs and fixes the `rand` doctest.

Author: kunzaatko

docs/src/pages/arrays/border-arrays.md

@@ -80,8 +80,31 @@ end
 f
 ```
 
-If the border type does not support the extent of the padding that is given in the constructor, the [`TransferFunctions.InvalidBorderExtent`](@ref) is thrown.
+If the border type does not support the extent of the padding that is given in the constructor, the
+[`TransferFunctions.InvalidBorderExtent`](@ref) is thrown.
 
 ```@docs
 TransferFunctions.InvalidBorderExtent
 ```
+
+# Functions 
+Border arrays are useful for extending the domain of an array for [filtering](@ref filtering-manual).
+
+This motivates some helper functions for sampling an extended array at given indices.
+
+To determine the padding necessary for a given kernel in filtering, you can use `kern_padding`
+
+```@docs
+TransferFunctions.kern_padding
+```
+
+For determining the indices that are necessary in the parent to facilitate a filtering, you can use `outer_axes`
+```@docs
+TransferFunctions.outer_axes
+```
+
+For extending the domain of an array to some given indices with a border strategy, you can use `padtoaxes`. This may
+also be useful if you do not want to have all the indices of the parent in the output of a filtering.
+```@docs
+padtoaxes
+```

docs/src/pages/devdocs/array-types.md

@@ -5,13 +5,9 @@ CollapsedDocStrings = true
 
 # Filtering Arrays and Circulant Tensors
 
-- [`TransferFunctions.kern_padding`](@ref) is used to determine the padding necessary to perform the full domain
+- [`TransferFunctions.kern_padding`](@ref) is useful for determining the padding necessary to perform the full domain
   filtering of an array.
 
-```@docs
-TransferFunctions.kern_padding
-```
-
 - [`TransferFunctions.ind2sub`](@ref) is used in the [`FilteringMatrix`](@ref) to determine the "`kernel`" and
   "`parent`" indices from the index to the `FilteringMatrix`.
 

docs/src/pages/filtering/array-discrete-filtering.md

@@ -10,7 +10,7 @@ using OffsetArrays: no_offset_view
 A = testimage("mandril_color")
 ```
 
-# Filtering
+# [Filtering](@id filtering-manual)
 
 `TransferFucntions` provides some functions for discrete filtering. Both convolution and correlation have a dedicated
 function. This function accepts an image `A`, kernel `K` and an optional [border](@ref "Border Types") and an output

src/types/border-arrays.jl

@@ -274,7 +274,7 @@ end
     border_array(A, border, padding)
 Construct a [`BorderArray`](@ref) of `A` with the border `border` and padding `padding`.
 
-See also [`padtoaxes`](@ref TransferFunctions.padtoaxes)
+See also [`padtoaxes`](@ref)
 ```jldoctest
 julia> border_array(reshape(1:9, (3,3)), :circular, 2)
 7×7 border_array(reshape(::UnitRange{Int64}, 3, 3), :Circular) with eltype Int64 with indices -1:5×-1:5:
@@ -298,30 +298,59 @@ For any indices where the `target` is contained in the parent `A`, a view is tak
 
 See also [`border_array`](@ref).
 ```jldoctest
-julia> TF.padtoaxes(OAs.OffsetArray(rand(100,100), -30:69, -20:79), :fill, (-35:-25, -30:-15))
-11×16 border_array(view(OffsetArray(::Matrix{Float64}, -30:69, -20:79), Base.IdentityUnitRange(-30:-25), Base.IdentityUnitRange(-20:-15)), fill(0.0)) with eltype Float64 with indices -35:-25×-30:-15:
- 0.0  0.0  0.0  0.0  0.0  0.0  0.0  0.0  0.0  0.0  …  0.0       0.0       0.0       0.0
- 0.0  0.0  0.0  0.0  0.0  0.0  0.0  0.0  0.0  0.0     0.0       0.0       0.0       0.0
- 0.0  0.0  0.0  0.0  0.0  0.0  0.0  0.0  0.0  0.0     0.0       0.0       0.0       0.0
- 0.0  0.0  0.0  0.0  0.0  0.0  0.0  0.0  0.0  0.0     0.0       0.0       0.0       0.0
- 0.0  0.0  0.0  0.0  0.0  0.0  0.0  0.0  0.0  0.0     0.0       0.0       0.0       0.0
- 0.0  0.0  0.0  0.0  0.0  0.0  0.0  0.0  0.0  0.0  …  0.452376  0.20255   0.921373  0.654289
- 0.0  0.0  0.0  0.0  0.0  0.0  0.0  0.0  0.0  0.0     0.727716  0.355869  0.156582  0.437704
- 0.0  0.0  0.0  0.0  0.0  0.0  0.0  0.0  0.0  0.0     0.52427   0.591113  0.223759  0.943134
- 0.0  0.0  0.0  0.0  0.0  0.0  0.0  0.0  0.0  0.0     0.709755  0.46971   0.550499  0.150776
- 0.0  0.0  0.0  0.0  0.0  0.0  0.0  0.0  0.0  0.0     0.575396  0.854017  0.170872  0.825171
- 0.0  0.0  0.0  0.0  0.0  0.0  0.0  0.0  0.0  0.0  …  0.962307  0.898315  0.922924  0.925127
+julia> padtoaxes(OAs.OffsetArray(reshape(1:100^2, 100, 100), -30:69, -20:79), :fill, (-35:-25, -30:-15))
+11×16 border_array(view(OffsetArray(reshape(::UnitRange{Int64}, 100, 100), -30:69, -20:79), Base.IdentityUnitRange(-30:-25), Base.IdentityUnitRange(-20:-15)), fill(0)) with eltype Int64 with indices -35:-25×-30:-15:
+ 0  0  0  0  0  0  0  0  0  0  0    0    0    0    0    0
+ 0  0  0  0  0  0  0  0  0  0  0    0    0    0    0    0
+ 0  0  0  0  0  0  0  0  0  0  0    0    0    0    0    0
+ 0  0  0  0  0  0  0  0  0  0  0    0    0    0    0    0
+ 0  0  0  0  0  0  0  0  0  0  0    0    0    0    0    0
+ 0  0  0  0  0  0  0  0  0  0  1  101  201  301  401  501
+ 0  0  0  0  0  0  0  0  0  0  2  102  202  302  402  502
+ 0  0  0  0  0  0  0  0  0  0  3  103  203  303  403  503
+ 0  0  0  0  0  0  0  0  0  0  4  104  204  304  404  504
+ 0  0  0  0  0  0  0  0  0  0  5  105  205  305  405  505
+ 0  0  0  0  0  0  0  0  0  0  6  106  206  306  406  506
 ```
+
+!!! warning "`:circular` border"
+    By default, this constructs a border array from the view into the parent array. If you use some border strategy that
+    uses indices and/or values of the other edge, you may want to have the border array constructed from the full array
+    instead and take the view into it. This can be done by setting the `outerpadding` keyword argument to `true`.
+
+
+```jldoctest
+julia> padtoaxes(reshape(1:121, 11, 11), :circular, (-1:2, -1:2))
+4×4 border_array(view(reshape(::UnitRange{Int64}, 11, 11), Base.IdentityUnitRange(1:2), Base.IdentityUnitRange(1:2)), :Circular) with eltype Int64 with indices -1:2×-1:2:
+ 1  12  1  12
+ 2  13  2  13
+ 1  12  1  12
+ 2  13  2  13
+
+julia> padtoaxes(reshape(1:121, 11, 11), :circular, (-1:2, -1:2); outerpadding=true)
+4×4 view(border_array(reshape(::UnitRange{Int64}, 11, 11), :Circular), Base.IdentityUnitRange(-1:2), Base.IdentityUnitRange(-1:2)) with eltype Int64 with indices -1:2×-1:2:
+ 109  120  10  21
+ 110  121  11  22
+ 100  111   1  12
+ 101  112   2  13
+```
+
+!!! tip "Border extent"
+    `outerpadding` may also lead to a greater extent of the border supplied since for example the `:circular` border is
+      only defined when the wrapped index is in the range of the parent view which is smaller that the parent array.
 """
-function padtoaxes(parent, border, target)
+function padtoaxes(parent, border, target; outerpadding=false)
     padding = map(target, axes(parent)) do t, ax
         (abs(max(0, first(ax)- first(t))), abs(max(0, last(t) - last(ax))))
     end
-    viewaxes = map(target, axes(parent)) do t, ax
-        (max(first(ax), first(t))):(min(last(ax), last(t)))
+    if !outerpadding
+      viewaxes = map(target, axes(parent)) do t, ax
+          (max(first(ax), first(t))):(min(last(ax), last(t)))
+      end
+      return border_array(offset_view(parent, viewaxes...), border, padding)
+    else 
+      return offset_view(border_array(parent, border, padding), target...)
     end
-    A = offset_view(parent, viewaxes...)
-    return border_array(A, border, padding)
 end
 
 function Base.showarg(io::IO, A::BorderArray, toplevel)

src/utils.jl

@@ -284,6 +284,13 @@ julia> TF.OriginAt(3, 3)(reshape(1:16, (4,4)))
     kern_padding(kern)
 Determine the padding necessary to keep the input array fully contained in the interior of the output when filtered with
 `kern`.
+
+```jldoctest
+julia> K = OAs.OffsetArray(ones(11,8) ./ (11*8), -5:5, -3:4);
+
+julia> TF.kern_padding(K)
+((5, 5), (3, 4))
+```
 """
 function kern_padding(K::Indices)
     if !all(I -> 0 ∈ I, K)
@@ -298,6 +305,8 @@ kern_padding(K::AbstractArray) = kern_padding(axes(K))
     inner_axes(A, K)
 Determine the inner axes of the array with edges `edges` or when filtered with kernel `K`.
 
+See also [`outer_axes`](@ref).
+
 ```jldoctest
 julia> TF.inner_axes(ones(100,100), ((2,4), (1,10)))
 (3:96, 2:90)
@@ -319,6 +328,7 @@ For instance this is useful when one wants to select the indices necessary to ta
 the filtered array with some kernel `K` at indices of `A` without the need for calculating for all of the indices of the
 initial array.
 
+See also [`inner_axes`](@ref).
 ```jldoctest
 julia> TF.outer_axes(ones(100,100), ((2,4), (1,10)))
 (-1:104, 0:110)