Suppress canonicalization for lazy IO (#51)

Also supports the upcoming TiffImages 0.6.

Project.toml

@@ -27,7 +27,7 @@ OpenEXR = "0.3"
 PNGFiles = "0.3"
 QOI = "1"
 Sixel = "0.1.2"
-TiffImages = "0.3, 0.4, 0.5"
+TiffImages = "0.3, 0.4, 0.5, 0.6"
 julia = "1.6"
 
 [extras]

README.md

@@ -37,6 +37,13 @@ save("test.tiff", rand(RGB, 100, 100))
 load("test.tiff")
 ```
 
+## Canonicalization
+
+Some image loaders may return custom AbstractArray types. By default, this package "canonicalizes" the returned type to be either `Array` or [`IndirectArray`](https://github.com/JuliaArrays/IndirectArrays.jl).
+An exception is for calls like `load(filename; mmap=true)` where the image data will be "lazily" loaded using [memory-mapped IO](https://en.wikipedia.org/wiki/Memory-mapped_I/O), in which case the default is to allow the lower-level I/O package to return whatever AbstractArray type it chooses.
+
+You can manually control canonicalization with `load(filename; canonicalize=tf)` where `tf` is `true` or `false`.
+
 ## Compatibility
 
 If you're using old Julia versions (`VERSION < v"1.3"`), a dummy ImageIO version v0.0.1 with no real function will be installed.

src/ImageIO.jl

@@ -48,6 +48,12 @@ function enforce_canonical_type(f, data)
     end
 end
 
+# For lazy loads by either of
+#   load(io; mmap=true)
+#   load(io; lazyio=true)
+# do not canonicalize by default. A package that supports both is TiffImages v0.6+.
+uses_lazy(kwargs) = get(kwargs, :mmap, false) || get(kwargs, :lazyio, false)
+
 ## PNGs
 
 
@@ -100,13 +106,15 @@ end
 
 ## TIFFs
 
-function load(f::File{DataFormat{:TIFF}}; kwargs...)
+function load(f::File{DataFormat{:TIFF}}; canonicalize::Union{Bool,Nothing}=nothing, kwargs...)
+    canonicalize = something(canonicalize, !uses_lazy(kwargs))
     data = TiffImages.load(f.filename; kwargs...)
-    return enforce_canonical_type(f, data)
+    return canonicalize ? enforce_canonical_type(f, data) : data
 end
-function load(s::Stream{DataFormat{:TIFF}}; kwargs...)
+function load(s::Stream{DataFormat{:TIFF}}; canonicalize::Union{Bool,Nothing}=nothing, kwargs...)
+    canonicalize = something(canonicalize, !uses_lazy(kwargs))
     data = TiffImages.load(stream(s); kwargs...)
-    return enforce_canonical_type(s, data)
+    return canonicalize ? enforce_canonical_type(s, data) : data
 end
 
 function save(f::File{DataFormat{:TIFF}}, image::S) where {T, S<:Union{AbstractMatrix, AbstractArray{T,3}}}

test/runtests.jl

@@ -135,6 +135,16 @@ Threads.nthreads() <= 1 && @info "Threads.nthreads() = $(Threads.nthreads()), mu
                 img_saveload = open(io->ImageIO.load(Stream{format"TIFF"}(io)), joinpath(tmpdir, "test_io.tiff"))
                 @test img == img_saveload
                 @test typeof(img_saveload) == ImageIO.canonical_type(f, img_saveload)
+
+                # mmapped images should not canonicalize by default, and can be controlled manually
+                img_saveload = ImageIO.load(f; mmap=true)
+                @test typeof(img_saveload) != ImageIO.canonical_type(f, img_saveload)
+                img_saveload = ImageIO.load(f; canonicalize=false)
+                @test typeof(img_saveload) != ImageIO.canonical_type(f, img_saveload)
+                img_saveload = open(io->ImageIO.load(Stream{format"TIFF"}(io); mmap=true), joinpath(tmpdir, "test_io.tiff"))
+                @test typeof(img_saveload) != ImageIO.canonical_type(f, img_saveload)
+                img_saveload = open(io->ImageIO.load(Stream{format"TIFF"}(io); canonicalize=false), joinpath(tmpdir, "test_io.tiff"))
+                @test typeof(img_saveload) != ImageIO.canonical_type(f, img_saveload)
             end
         end
     end