deprecate the dims::Vector{Int} method of restrict (#5)

* deprecate vector dims input

* update `restrict` docs

* Also rename the input `region` to `dims`

* format Project.toml

Author: johnnychen94

Project.toml

@@ -10,8 +10,8 @@ ImageCore = "0.8, 0.9"
 julia = "1"
 
 [extras]
-OffsetArrays = "6fe1bfb0-de20-5000-8ca7-80f57d26f881"
 ImageMagick = "6218d12a-5da1-5696-b52f-db25d2ecc6d1"
+OffsetArrays = "6fe1bfb0-de20-5000-8ca7-80f57d26f881"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 TestImages = "5e47fb64-e119-507b-a336-dd2b206d9990"
 

src/ImageUtils.jl

@@ -8,6 +8,7 @@ using ImageCore.OffsetArrays
 
 include("restrict.jl")
 include("compat.jl")
+include("deprecated.jl")
 
 if VERSION >= v"1.4.2" # work around https://github.com/JuliaLang/julia/issues/34121
     include("precompile.jl")

src/deprecated.jl

@@ -0,0 +1,5 @@
+# BEGIN 0.1 deprecation
+
+@deprecate restrict(A::AbstractArray, region::Vector{Int}) restrict(A, (region...,))
+
+# END 0.1 deprecation

src/restrict.jl

@@ -1,8 +1,55 @@
 """
-    restrict(img[, region]) -> imgr
+    restrict(img[, dims]) -> imgr
 
 Reduce the size of `img` by approximately two-fold along the dimensions listed in
-`region`, or all spatial coordinates if `region` is not specified.
+`dims`, or all spatial coordinates if `dims` is not specified.
+
+# Output
+
+The type of output array `imgr` depends on the input type:
+
+- If `img` is not an `OffsetArray`, then output array `imgr` will be a typical `Array` type.
+- If `img` is an `OffsetArray`, then output array `imgr` will also be an `OffsetArray`.
+
+The size of `imgr` is approximately `1/2` of the original size. More specifically:
+
+- if `Nₖ = size(img, k)` is odd, then `size(imgr, k) == (Nₖ+1) ÷ 2`.
+- if `Nₖ = size(img, k)` is even, then `size(imgr, k) == (Nₖ÷2) + 1`.
+
+# Examples
+
+The optional argument `dims` can be a `Tuple` or `Integer`:
+
+```julia
+A = rand(5, 5) # size: (5, 5)
+
+restrict(A) # size: (3, 3)
+
+restrict(A, 1) # size: (3, 5)
+restrict(A, 2) # size: (5, 3)
+
+restrict(A, (1, )) # size: (3, 5)
+restrict(A, (1, 2)) # size: (3, 3)
+```
+
+Unless the input array is 1-based, the origin will be halfed:
+
+```julia
+julia> using ImageUtils, OffsetArrays
+
+julia> Ao = OffsetArray(rand(5, 4), 5, 6);
+
+julia> Ar = restrict(Ao);
+
+julia> axes(Ao)
+(OffsetArrays.IdOffsetRange(values=6:10, indices=6:10), OffsetArrays.IdOffsetRange(values=7:10, indices=7:10))
+
+julia> axes(Ar)
+(OffsetArrays.IdOffsetRange(values=3:5, indices=3:5), OffsetArrays.IdOffsetRange(values=4:6, indices=4:6))
+```
+
+# Extended help
+
 The term `restrict` is taken from the coarsening operation of algebraic multigrid
 methods; it is the adjoint of "prolongation" (which is essentially interpolation).
 `restrict` anti-aliases the image as it goes, so is better than a naive summation
@@ -69,10 +116,9 @@ In some applications (e.g., image registration), you may find it useful to trim
 """
 restrict(img::AbstractArray, ::Tuple{}) = img
 
-restrict(A::AbstractArray, region::Vector{Int}) = restrict(A, (region...,))
 restrict(A::AbstractArray) = restrict(A, coords_spatial(A))
-function restrict(A::AbstractArray, region::Dims)
-    restrict(restrict(A, region[1]), Base.tail(region))
+function restrict(A::AbstractArray, dims::Dims)
+    restrict(restrict(A, dims[1]), Base.tail(dims))
 end
 
 function restrict(A::AbstractArray{T,N}, dim::Integer) where {T,N}

test/deprecated.jl

@@ -0,0 +1,6 @@
+@testset "deprecation" begin
+    @testset "restrict" begin
+        A = rand(N0f8, 4, 5, 3)
+        @test restrict(A, [1, 2]) == restrict(A, (1, 2))
+    end
+end

test/runtests.jl

@@ -3,4 +3,7 @@ using Test, TestImages
 
 @testset "ImageUtils.jl" begin
     include("restrict.jl")
+
+    @info "deprecations are expected"
+    include("deprecated.jl")
 end