feat(decode): add keyword preferred_size (#18)

Author: johnnychen94

README.md

@@ -83,6 +83,15 @@ filename = testimage("earth", download_only=true)
 @btime jpeg_decode(Gray, filename; scale_ratio=0.25); # 63.119 ms (6 allocations: 1.08 MiB)
 ```
 
+An exclusive alternative to `scale_ratio` is `preferred_size`:
+
+```julia
+# minimal `scale_ratio` that output size is greater than or equal to (512, 512)
+jpeg_decode(filename; preferred_size=(512, 512)) # size: (751, 750)
+# minimal `scale_ratio` that output size is less than or equal to (512, 512)
+jpeg_decode(filename; preferred_size=(<=, (512, 512))) # size: (376, 375)
+```
+
 ## Acknowledgements
 
 The purpose of this project is to replace [ImageMagick.jl] with [ImageIO]. Steven G. Johnson first

docs/src/index.md

@@ -80,3 +80,12 @@ filename = testimage("earth", download_only=true)
 # process only a few pixels for luminance component
 @btime jpeg_decode(Gray, filename; scale_ratio=0.25); # 63.119 ms (6 allocations: 1.08 MiB)
 ```
+
+An exclusive alternative to `scale_ratio` is `preferred_size`:
+
+```julia
+# minimal `scale_ratio` that output size is greater than or equal to (512, 512)
+jpeg_decode(filename; preferred_size=(512, 512)) # size: (751, 750)
+# minimal `scale_ratio` that output size is less than or equal to (512, 512)
+jpeg_decode(filename; preferred_size=(<=, (512, 512))) # size: (376, 375)
+```

src/decode.jl

@@ -12,7 +12,14 @@ Decode the JPEG image as colorant matrix. The source data can be either a filena
   before encoding. The default value is `false`.
 - `scale_ratio::Real`: scale the image by ratio `scale_ratio` in `M/8` with `M ∈ 1:16`. The
   default value is `1`. For values are not in the range, they will be mapped to the nearest
-  value, e.g., `0.3 => 2/8` and `0.35 => 3/8`.
+  value, e.g., `0.3 => 2/8` and `0.35 => 3/8`. `scale_ratio` and `preferred_size` may not be
+  used together.
+- `preferred_size::Tuple`: infer the minimal `scale_ratio` that `all(size(out) .>=
+  preferred_size))` holds. It can optionally be `(op, preferred_size)` format, with compare
+  operation `op` be one of `>`, `>=`, `<` or `<=`. If `op in (>=, >)` then it gets the
+  minimal `scale_ratio`, otherwise it gets the maximum `scale_ratio` for `op in (<=, <)`.
+  `scale_ratio` and `preferred_size` may not be used together. The `preferred_size`
+  dimensions are not affected by keyword `transpose`.
 
 # Examples
 
@@ -52,7 +59,8 @@ function jpeg_decode(
         ::Type{CT},
         data::Vector{UInt8};
         transpose=false,
-        scale_ratio=1) where CT<:Colorant
+        scale_ratio::Union{Nothing,Real}=nothing,
+        preferred_size::Union{Nothing,Tuple}=nothing) where CT<:Colorant
     _jpeg_check_bytes(data)
     out_CT, jpeg_cls = _jpeg_out_color_space(CT)
 
@@ -66,7 +74,14 @@ function jpeg_decode(
         LibJpeg.jpeg_read_header(cinfo_ref, true)
 
         # set decompression parameters, if given
-        r = _cal_scale_ratio(scale_ratio)
+        if !isnothing(preferred_size) && !transpose
+            if preferred_size[1] isa Function
+                preferred_size = (preferred_size[1], reverse(preferred_size[2]))
+            else
+                preferred_size = reverse(preferred_size)
+            end
+        end
+        r = _cal_scale_ratio(scale_ratio, preferred_size, cinfo)
         cinfo.scale_num, cinfo.scale_denom = r.num, r.den
         cinfo.out_color_space = jpeg_cls
 
@@ -127,7 +142,37 @@ _jpeg_decode!(out::Matrix{<:Colorant}, cinfo::LibJpeg.jpeg_decompress_struct) =
 
 # libjpeg-turbo only supports ratio M/8 with M from 1 to 16
 const _allowed_scale_ratios = ntuple(i->i//8, 16)
-_cal_scale_ratio(r::Real) = _allowed_scale_ratios[findmin(x->abs(x-r), _allowed_scale_ratios)[2]]
+function _cal_scale_ratio(::Real, ::Tuple, cinfo)
+    throw(ArgumentError("Keywords `aspect_ratio` and `preferred_size` are exclusive to each other: you should only specify one of them."))
+end
+_cal_scale_ratio(::Nothing, ::Nothing, cinfo) = 1//1
+_cal_scale_ratio(r::Real, ::Nothing, cinfo) = _allowed_scale_ratios[findmin(x->abs(x-r), _allowed_scale_ratios)[2]]
+function _cal_scale_ratio(::Nothing, preferred_size::Tuple, cinfo)
+    cinfo.scale_num, cinfo.scale_denom = 1, 1
+    LibJpeg.jpeg_calc_output_dimensions(Ref(cinfo))
+    out_size = (Int(cinfo.output_width), Int(cinfo.output_height))
+    op, preferred_size = if preferred_size[1] isa Function
+        op = preferred_size[1]
+        op in (>, >=, <, <=) || throw(ArgumentError("the compare operation must be one of `>`, `>=`, `<` and `<=`."))
+        op, preferred_size[2]
+    else
+        >=, preferred_size
+    end
+    if op in (>, >=)
+        idx = findfirst(x->all(op.(x .* out_size, preferred_size)), _allowed_scale_ratios)
+        if isnothing(idx)
+            @warn "Failed to infer appropriate scale ratio, use `scale_ratio=2` instead." actual_size=out_size preferred_size
+            idx = length(_allowed_scale_ratios)
+        end
+    elseif op in (<, <=)
+        idx = findlast(x->all(op.(x .* out_size, preferred_size)), _allowed_scale_ratios)
+        if isnothing(idx)
+            @warn "Failed to infer appropriate scale ratio, use `scale_ratio=1/8` instead." actual_size=out_size preferred_size
+            idx = 1
+        end
+    end
+    return _allowed_scale_ratios[idx]
+end
 
 function _default_out_color_space(filename::AbstractString)
     _jpeg_check_bytes(filename)

test/Project.toml

@@ -5,5 +5,6 @@ FileIO = "5789e2e9-d7fb-5bc7-8068-2c6fae9b9549"
 ImageCore = "a09fc81d-aa75-5fe9-8630-4744c3626534"
 ImageIO = "82e4d734-157c-48bb-816b-45c225c6df19"
 ImageQualityIndexes = "2996bd0c-7a13-11e9-2da2-2f5ce47296a9"
+Suppressor = "fd094767-a336-5f1f-9728-57cf17d0bbfb"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 TestImages = "5e47fb64-e119-507b-a336-dd2b206d9990"

test/runtests.jl

@@ -6,6 +6,7 @@ using Documenter
 using TestImages
 using ImageQualityIndexes
 using ImageCore
+using Suppressor
 
 # ensure TestImages artifacts are downloaded before running documenter test
 testimage("cameraman")

test/tst_decode.jl

@@ -51,6 +51,38 @@
         @test size(data) == (128, 192) != 0.3 .* size(img_rgb)
     end
 
+    @testset "preferred_size" begin
+        # lighthouse: (512, 768)
+        actual_size = size(img_rgb)
+        data = jpeg_decode(img_rgb_bytes; scale_ratio=0.25)
+        data_new = jpeg_decode(img_rgb_bytes; preferred_size=size(data))
+        @test size(data_new) == size(data)
+
+        data_new = jpeg_decode(img_rgb_bytes; preferred_size=(>=, size(data)))
+        @test size(data_new) == size(data)
+
+        data_new = jpeg_decode(img_rgb_bytes; preferred_size=(>, size(data)))
+        @test size(data_new) == 3/8 .* actual_size
+
+        data_new = jpeg_decode(img_rgb_bytes; preferred_size=(<=, size(data)))
+        @test size(data_new) == size(data)
+
+        data_new = jpeg_decode(img_rgb_bytes; preferred_size=(<, size(data)))
+        @test size(data_new) == 1/8 .* actual_size
+
+        data_new = @suppress_err jpeg_decode(img_rgb_bytes; preferred_size=3 .* actual_size)
+        @test size(data_new) == 2 .* actual_size
+        msg = @capture_err jpeg_decode(img_rgb_bytes; preferred_size=3 .* actual_size)
+        @test occursin("Warning: Failed to infer appropriate scale ratio, use `scale_ratio=2` instead.", msg)
+
+        data_new = @suppress_err jpeg_decode(img_rgb_bytes; preferred_size=(<=, 1/16 .* actual_size))
+        @test size(data_new) == 1/8 .* actual_size
+        msg = @capture_err jpeg_decode(img_rgb_bytes; preferred_size=(<=, 1/16 .* actual_size))
+        @test occursin("Warning: Failed to infer appropriate scale ratio, use `scale_ratio=1/8` instead.", msg)
+
+        @test_throws ArgumentError jpeg_decode(img_rgb_bytes; preferred_size=size(data), scale_ratio=1)
+    end
+
     @testset "transpose" begin
         data = jpeg_decode(jpeg_encode(img_rgb; transpose=true); transpose=true)
         @test assess_psnr(data, img_rgb) > 33.95