feat: initial jpeg_encode implementation

Following example.txt and libjpeg.txt in libjpeg-turbo, this commit
implements a `jpeg_encode` function with two APIs:

- `jpeg_encode(io_or_filename, img; kwargs...) -> Int`
- `jpeg_encode(img; kwargs...) -> Vector{UInt8}`

Author: johnnychen94

Project.toml

@@ -5,9 +5,11 @@ version = "0.1.0"
 
 [deps]
 CEnum = "fa961155-64e5-5f13-b03f-caf6b980ea82"
+ImageCore = "a09fc81d-aa75-5fe9-8630-4744c3626534"
 JpegTurbo_jll = "aacddb02-875f-59d6-b918-886e6ef4fbf8"
 
 [compat]
 CEnum = "0.3, 0.4"
+ImageCore = "0.8, 0.9"
 JpegTurbo_jll = "~2.1"
 julia = "1.6"

docs/src/reference.md

@@ -4,6 +4,10 @@ CurrentModule = JpegTurbo
 
 # Function references
 
+```@docs
+jpeg_encode
+```
+
 ## Utilities
 
 ```@docs

src/JpegTurbo.jl

@@ -1,7 +1,14 @@
 module JpegTurbo
 
+using ImageCore
+
 include("../lib/LibJpeg.jl")
 using .LibJpeg
 include("libjpeg_utils.jl")
 
+include("common.jl")
+include("encode.jl")
+
+export jpeg_encode
+
 end

src/common.jl

@@ -0,0 +1,12 @@
+jpeg_components(::AbstractArray{T}) where T = jpeg_components(T)
+jpeg_components(::Type{CT}) where CT<:Colorant = length(CT)
+jpeg_components(::Type{T}) where T<:Number = 1
+
+jpeg_color_space(::AbstractArray{T}) where T = jpeg_color_space(T)
+jpeg_color_space(::Type{CT}) where CT<:Gray = LibJpeg.JCS_GRAYSCALE
+jpeg_color_space(::Type{CT}) where CT<:RGB = LibJpeg.JCS_RGB
+jpeg_color_space(::Type{CT}) where CT<:BGR = LibJpeg.JCS_EXT_BGR
+jpeg_color_space(::Type{CT}) where CT<:RGBA = LibJpeg.JCS_EXT_RGBA
+jpeg_color_space(::Type{CT}) where CT<:BGRA = LibJpeg.JCS_EXT_BGRA
+jpeg_color_space(::Type{CT}) where CT<:ABGR = LibJpeg.JCS_EXT_ABGR
+jpeg_color_space(::Type{CT}) where CT<:ARGB = LibJpeg.JCS_EXT_ARGB

src/encode.jl

@@ -0,0 +1,124 @@
+"""
+    jpeg_encode(filename::AbstractString, img; kwargs...) -> Int
+    jpeg_encode(io::IO, img; kwargs...) -> Int
+    jpeg_encode(img; kwargs...) -> Vector{UInt8}
+
+Encode 2D image `img` as JPEG byte sequences and write to given I/O stream or file. The
+return value is number of bytes. If output is not specified, the encoded result is stored
+in memory as return value.
+
+# Parameters
+
+- `transpose::Bool`: whether we need to permute the image's width and height dimension
+  before encoding. The default value is `false`.
+- `quality::Int`: Constructs JPEG quantization tables appropriate for the indicated
+  quality setting. The quality value is expressed on the 0..100 scale recommended by IJG.
+
+!!! info "Custom compression parameters"
+    JPEG has a large number of compression parameters that determine how the image is
+    encoded. Most applications don't need or want to know about all these parameters. For
+    more detailed information and explaination, please refer to the "Compression parameter
+    selection" in [1]. Unsupported custom parameters might cause Julia segmentation fault.
+
+# Examples
+
+```jldoctest
+julia> using JpegTurbo, TestImages
+
+julia> img = testimage("cameraman");
+
+julia> jpeg_encode("out.jpg", img) # write to file
+28210
+
+julia> buf = jpeg_encode(img); length(buf) # directly write to memory
+28210
+```
+
+# References
+
+- [1] [libjpeg API Documentation (libjpeg.txt)](https://raw.githubusercontent.com/libjpeg-turbo/libjpeg-turbo/main/libjpeg.txt)
+"""
+function jpeg_encode(img::AbstractMatrix; transpose=false, kwargs...)
+    # quantilized into 8bit sequences first
+    AT = Array{n0f8(eltype(img)), ndims(img)}
+    # jpegturbo is a C library and assumes row-major memory order, thus `collect` the data into
+    # contiguous memeory layout already makes a transpose.
+    img = transpose ? convert(AT, img) : convert(AT, PermutedDimsArray(img, (2, 1)))
+
+    return _encode(img; kwargs...)
+end
+
+function jpeg_encode(filename::AbstractString, img; kwargs...)
+    open(filename, "w") do io
+        jpeg_encode(io, img; kwargs...)
+    end
+end
+# TODO(johnnychen94): further improve the performance via asynchronously IO and buffer reuse.
+jpeg_encode(io::IO, img; kwargs...) = write(io, jpeg_encode(img; kwargs...))
+
+
+function _encode(
+    img::Matrix{<:Colorant};
+    colorspace::Union{Nothing,Type} = nothing,
+    quality::Union{Nothing,Int} = nothing,
+    arith_code::Union{Nothing,Bool} = nothing,
+    optimize_coding::Union{Nothing,Bool} = nothing,
+    smoothing_factor::Union{Nothing,Int} = nothing,
+    write_JFIF_header::Union{Nothing,Bool} = nothing,
+    JFIF_version::Union{Nothing,VersionNumber} = nothing,
+    density_unit::Union{Nothing,Int} = nothing,
+    X_density::Union{Nothing,Int} = nothing,
+    Y_density::Union{Nothing,Int} = nothing,
+    write_Adobe_marker::Union{Nothing,Bool} = nothing
+)
+    cinfo = LibJpeg.jpeg_compress_struct()
+    cinfo_ref = Ref(cinfo)
+    jerr = Ref{LibJpeg.jpeg_error_mgr}()
+    cinfo.err = LibJpeg.jpeg_std_error(jerr)
+    LibJpeg.jpeg_create_compress(cinfo_ref)
+
+    # set input image information
+    cinfo.image_width = size(img, 1)
+    cinfo.image_height = size(img, 2)
+    cinfo.input_components = jpeg_components(img)
+    cinfo.in_color_space = jpeg_color_space(img)
+
+    # set compression keywords
+    # it's recommended to call `jpeg_set_defaults` first before setting custom parameters
+    # as it's more likely to provide a working parameters and is more likely to be working
+    # correctly in the future.
+    LibJpeg.jpeg_set_defaults(cinfo_ref)
+    isnothing(colorspace) || LibJpeg.jpeg_set_colorspace(cinfo_ref, jpeg_color_space(colorspace))
+    isnothing(quality) || LibJpeg.jpeg_set_quality(cinfo_ref, quality, true)
+    isnothing(arith_code) || (cinfo.arith_code = arith_code)
+    isnothing(optimize_coding) || (cinfo.optimize_coding = optimize_coding)
+    isnothing(smoothing_factor) || (cinfo.smoothing_factor = smoothing_factor)
+    isnothing(write_JFIF_header) || (cinfo.write_JFIF_header = write_JFIF_header)
+    if !isnothing(JFIF_version)
+        cinfo.JFIF_major_version = UInt8(JFIF_version.major)
+        cinfo.JFIF_minor_version = UInt8(JFIF_version.minor)
+    end
+    isnothing(density_unit) || (cinfo.density_unit = density_unit)
+    isnothing(X_density) || (cinfo.X_density = X_density)
+    isnothing(Y_density) || (cinfo.Y_density = Y_density)
+    isnothing(write_Adobe_marker) || (cinfo.write_Adobe_marker = write_Adobe_marker)
+
+    # set destination
+    # TODO(johnnychen94): allow pre-allocated buffer
+    bufsize = Ref{Culong}(0)
+    buf_ptr = Ref{Ptr{UInt8}}(C_NULL)
+    LibJpeg.jpeg_mem_dest(cinfo_ref, buf_ptr, bufsize)
+
+    # compression stage
+    LibJpeg.jpeg_start_compress(cinfo_ref, true)
+    row_stride = size(img, 1) * jpeg_components(img)
+    row_pointer = Ref{Ptr{UInt8}}(0)
+    while (cinfo.next_scanline < cinfo.image_height)
+        row_pointer[] = pointer(img) + cinfo.next_scanline * row_stride
+        LibJpeg.jpeg_write_scanlines(cinfo_ref, row_pointer, 1);
+    end
+    LibJpeg.jpeg_finish_compress(cinfo_ref)
+    LibJpeg.jpeg_destroy_compress(cinfo_ref)
+
+    return unsafe_wrap(Array, buf_ptr[], bufsize[]; own=true)
+end

test/Project.toml

@@ -1,2 +1,9 @@
 [deps]
+Aqua = "4c88cf16-eb10-579e-8560-4a9242c79595"
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+ImageCore = "a09fc81d-aa75-5fe9-8630-4744c3626534"
+ImageIO = "82e4d734-157c-48bb-816b-45c225c6df19"
+ImageMagick = "6218d12a-5da1-5696-b52f-db25d2ecc6d1"
+ImageQualityIndexes = "2996bd0c-7a13-11e9-2da2-2f5ce47296a9"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
+TestImages = "5e47fb64-e119-507b-a336-dd2b206d9990"

test/runtests.jl

@@ -1,8 +1,34 @@
 using JpegTurbo
 using JpegTurbo.LibJpeg
 using Test
+using Aqua
+using Documenter
+using TestImages
+using ImageQualityIndexes
+using ImageMagick
+using ImageCore
+
+tmpdir = tempdir()
+function decode_encode(img; kwargs...)
+    tmpfile = joinpath(tmpdir, "tmp.jpg")
+    buf = @inferred jpeg_encode(img; kwargs...)
+    write(tmpfile, buf)
+    # TODO(johnnychen94): load back with `JpegTurbo.decode`
+    return ImageMagick.load(tmpfile)
+end
 
 @testset "JpegTurbo.jl" begin
+    @testset "Project meta quality checks" begin
+        Aqua.test_all(JpegTurbo;
+            ambiguities=false,
+            project_extras=true,
+            deps_compat=true,
+            stale_deps=true,
+            project_toml_formatting=true
+        )
+        doctest(JpegTurbo, manual = false)
+    end
+
     @testset "config" begin
         @test_nowarn JpegTurbo.versioninfo()
 
@@ -14,5 +40,11 @@ using Test
         @test LibJpeg.BITS_IN_JSAMPLE == 8
         @test LibJpeg.MAXJSAMPLE == 255
         @test LibJpeg.CENTERJSAMPLE == 128
+
+        # ensure colorspace extensions are supported
+        @test LibJpeg.JCS_EXTENSIONS == 1
+        @test LibJpeg.JCS_ALPHA_EXTENSIONS == 1
     end
+
+    include("tst_encode.jl")
 end

test/tst_encode.jl

@@ -0,0 +1,32 @@
+@testset "jpeg_encode" begin
+
+img_rgb = testimage("lighthouse")
+
+@testset "basic" begin
+    for CT in [Gray, RGB, #=YCbCr,=# #=RGBX,=# BGR, #=XRGB,=# RGBA, BGRA, ABGR, ARGB]
+        img = CT.(img_rgb)
+        data = decode_encode(img)
+        @test data ≈ decode_encode(float32.(img))
+
+        # ensure default keyword values are not changed by accident
+        @test data == decode_encode(img, transpose=false)
+        @test decode_encode(img, transpose=true) == decode_encode(img', transpose=false)
+    end
+end
+
+# keyword checks
+@testset "quality" begin
+    img = testimage("cameraman")
+    psnr_refs = Dict(
+        1   => 24.5647,
+        10  => 31.3434,
+        50  => 38.8765,
+        100 => 59.3770,
+    )
+    for (q, r) in psnr_refs
+        v = assess_psnr(img, decode_encode(img, quality=q))
+        @test v >= r
+    end
+end
+
+end # @testset "jpeg_encode"