Merge pull request #465 from nikopj/pad-symmetric

symmetric and circular padding

Author: ToucheSir

docs/src/reference.md

@@ -57,8 +57,10 @@ lpnormpool
 
 ```@docs
 pad_reflect
-pad_constant
+pad_symmetric
+pad_circular
 pad_repeat
+pad_constant
 pad_zeros
 ```
 

src/NNlib.jl

@@ -75,7 +75,7 @@ export maxpool, maxpool!, meanpool, meanpool!, lpnormpool, lpnormpool!,
     ∇maxpool, ∇maxpool!, ∇meanpool, ∇meanpool!, ∇lpnormpool, ∇lpnormpool!
 
 include("padding.jl")
-export pad_constant, pad_repeat, pad_reflect, pad_zeros
+export pad_constant, pad_repeat, pad_reflect, pad_zeros, pad_symmetric, pad_circular
 
 include("upsample.jl")
 export upsample_nearest, ∇upsample_nearest,

src/padding.jl

@@ -23,7 +23,7 @@ If `dims` is not given, it defaults to all dimensions.
 For integer `pad` input, it is applied on both sides
 on every dimension in `dims`.
 
-See also [`pad_zeros`](@ref), [`pad_reflect`](@ref) and [`pad_repeat`](@ref).
+See also [`pad_zeros`](@ref), [`pad_repeat`](@ref), [`pad_reflect`](@ref), [`pad_symmetric`](@ref), and [`pad_circular`](@ref).
 
 ```jldoctest
 julia> r = reshape(1:4, 2, 2)
@@ -169,12 +169,12 @@ of some length `2n` that specifies the left and right padding size
 for each of the dimensions in `dims`. If `dims` is not given, 
 it defaults to the first `n` dimensions.
 
-For integer `pad` input instead, it is applied on both sides
+If `pad` is an integer, it is applied on both sides
 on every dimension in `dims`. In this case, `dims` 
 defaults to the first `ndims(x)-2` dimensions 
 (i.e. excludes the channel and batch dimension). 
 
-See also [`pad_reflect`](@ref) and [`pad_constant`](@ref).
+See also [`pad_reflect`](@ref), [`pad_symmetric`](@ref), [`pad_circular`](@ref), and [`pad_constant`](@ref).
 
 ```jldoctest
 julia> r = reshape(1:9, 3, 3)
@@ -230,12 +230,12 @@ of some length `2n` that specifies the left and right padding size
 for each of the dimensions in `dims`. If `dims` is not given, 
 it defaults to the first `n` dimensions.
 
-For integer `pad` input instead, it is applied on both sides
+If `pad` is an integer, it is applied on both sides
 on every dimension in `dims`. In this case, `dims` 
 defaults to the first `ndims(x)-2` dimensions 
-(i.e. excludes the channel and batch dimension).
+(i.e. excludes the channel and batch dimension). 
 
-See also [`pad_repeat`](@ref) and [`pad_constant`](@ref).
+See also [`pad_repeat`](@ref), [`pad_symmetric`](@ref), [`pad_circular`](@ref), and [`pad_constant`](@ref).
 
 ```jldoctest
 julia> r = reshape(1:9, 3, 3)
@@ -277,8 +277,127 @@ function pad_reflect(x::AbstractArray{F,N}, pad::NTuple{2,Int};
   return cat(xl, x, xr, dims = dims)
 end
 
+"""
+    pad_symmetric(x, pad::Tuple; [dims])
+    pad_symmetric(x, pad::Int; [dims])
+
+Pad the array `x` reflecting its values symmetrically across the border, i.e. the border values of `x` are present in the padding values, in contrast to [`pad_reflect`](@ref).
+
+`pad` can a tuple of integers `(l1, r1, ..., ln, rn)`
+of some length `2n` that specifies the left and right padding size
+for each of the dimensions in `dims`. If `dims` is not given, 
+it defaults to the first `n` dimensions.
+
+If `pad` is an integer, it is applied on both sides
+on every dimension in `dims`. In this case, `dims` 
+defaults to the first `ndims(x)-2` dimensions 
+(i.e. excludes the channel and batch dimension). 
+
+See also [`pad_repeat`](@ref), [`pad_reflect`](@ref), [`pad_circular`](@ref), and [`pad_constant`](@ref).
+
+```jldoctest
+julia> r = reshape(1:9, 3, 3)
+3×3 reshape(::UnitRange{Int64}, 3, 3) with eltype Int64:
+ 1  4  7
+ 2  5  8
+ 3  6  9
+
+julia> pad_symmetric(r, (1,2,1,2))
+6×6 Matrix{Int64}:
+ 1  1  4  7  7  4
+ 1  1  4  7  7  4
+ 2  2  5  8  8  5
+ 3  3  6  9  9  6
+ 3  3  6  9  9  6
+ 2  2  5  8  8  5
+```
+"""
+function pad_symmetric(x::AbstractArray, pad::NTuple{M,Int}; 
+                     dims=1:M÷2) where M
+  length(dims) == M ÷ 2 ||
+    throw(ArgumentError("The number of dims should be equal to the number of padding dimensions"))
+  for (i, d) in enumerate(dims)
+    x = pad_symmetric(x, (pad[2i-1], pad[2i]); dims = d)
+  end  
+  return x
+end
+
+function pad_symmetric(x::AbstractArray{F,N}, pad::NTuple{2,Int}; 
+                     dims::Int = 1) where {F,N}
+  lpad, rpad = pad
+  
+  n = size(x, dims)
+  xl = selectdim(x, dims, lpad:-1:1)
+  xr = selectdim(x, dims, n:-1:n-rpad+1)
+  return cat(xl, x, xr, dims = dims)
+end
+
+"""
+    pad_circular(x, pad::Tuple; [dims])
+    pad_circular(x, pad::Int; [dims])
+
+Pad the array `x` "circularly" across the border by wrapping around values from the opposite side of `x`. 
+
+`pad` can a tuple of integers `(l1, r1, ..., ln, rn)`
+of some length `2n` that specifies the left and right padding size
+for each of the dimensions in `dims`. If `dims` is not given, 
+it defaults to the first `n` dimensions.
+
+If `pad` is an integer, it is applied on both sides
+on every dimension in `dims`. In this case, `dims` 
+defaults to the first `ndims(x)-2` dimensions 
+(i.e. excludes the channel and batch dimension). 
+
+The pad length on either side in any dimension must not exceed the
+size of `x` in that dimension, i.e. `pad_circular` is not able to create abitrary sized tilings of `x`.
+
+See also [`pad_repeat`](@ref), [`pad_reflect`](@ref), [`pad_symmetric`](@ref), and [`pad_constant`](@ref).
+
+```jldoctest
+julia> r = reshape(1:9, 3, 3)
+3×3 reshape(::UnitRange{Int64}, 3, 3) with eltype Int64:
+ 1  4  7
+ 2  5  8
+ 3  6  9
+
+julia> pad_circular(r, (1,2,1,2))
+6×6 Matrix{Int64}:
+ 9  3  6  9  3  6
+ 7  1  4  7  1  4
+ 8  2  5  8  2  5
+ 9  3  6  9  3  6
+ 7  1  4  7  1  4
+ 8  2  5  8  2  5
+```
+"""
+function pad_circular(x::AbstractArray, pad::NTuple{M,Int}; 
+                     dims=1:M÷2) where M
+  length(dims) == M ÷ 2 ||
+    throw(ArgumentError("The number of dims should be equal to the number of padding dimensions"))
+
+  for (i, d) in enumerate(dims)
+    x = pad_circular(x, (pad[2i-1], pad[2i]); dims = d)
+  end  
+  return x
+end
+
+function pad_circular(x::AbstractArray{F,N}, pad::NTuple{2,Int}; 
+                     dims::Int = 1) where {F,N}
+  lpad, rpad = pad
+  n = size(x, dims)
+
+  xl = selectdim(x, dims, n-lpad+1:n)
+  xr = selectdim(x, dims, 1:rpad)
+  return cat(xl, x, xr, dims = dims)
+end
+
 # convenience methods for symmetric and homogeneous padding
 pad_repeat(x::AbstractArray{F,N}, pad::Int; dims=1:N-2) where {F,N} =
   pad_repeat(x, ntuple(_ -> pad, 2length(dims)); dims = dims)
 pad_reflect(x::AbstractArray{F,N}, pad::Int; dims=1:N-2) where {F,N} =
   pad_reflect(x, ntuple(_ -> pad, 2length(dims)); dims = dims)
+pad_symmetric(x::AbstractArray{F,N}, pad::Int; dims=1:N-2) where {F,N} =
+  pad_symmetric(x, ntuple(_ -> pad, 2length(dims)); dims = dims)
+pad_circular(x::AbstractArray{F,N}, pad::Int; dims=1:N-2) where {F,N} =
+  pad_circular(x, ntuple(_ -> pad, 2length(dims)); dims = dims)
+