diff --git a/docs/src/lib/public.md b/docs/src/lib/public.md index 026d7d0e..b5b99f14 100644 --- a/docs/src/lib/public.md +++ b/docs/src/lib/public.md @@ -4,7 +4,6 @@ ```@docs TiffImages.load -memmap ``` ### Output Types diff --git a/examples/mmap_lazyio.jl b/examples/mmap_lazyio.jl index 9c289a4e..918d5bee 100644 --- a/examples/mmap_lazyio.jl +++ b/examples/mmap_lazyio.jl @@ -165,13 +165,14 @@ GC.gc() # ### Incremental writing # `TiffImages` also supports writing to a file via an append -# operation. As with most arrays, you need to provide an element type and a -# filepath, but we'll use the [`memmap`](@ref) function in place of `load` +# operation. We have a special type for this called +# [`LazyBufferedTIFF`](@ref), that we can create via the standard +# `empty` function using TiffImages #hide #-------------- using ImageCore # reexports Gray and N0f8 -img2 = memmap(Gray{N0f8}, "test.tif") +img2 = empty(LazyBufferedTIFF, Gray{N0f8}, "test.tif") # !!! note # For data-integrity reasons, `TiffImages` will not allow you to append to @@ -207,4 +208,4 @@ img2[:, :, 2] # helpful to set the `bigtiff` flag to true so that `TiffImages` can use 64-bit # offsets. You'll see that the addressable space sky rockets: -img3 = memmap(Gray{N0f16}, "test.btif"; bigtiff=true) +img3 = empty(LazyBufferedTIFF, Gray{N0f16}, "test.btif"; bigtiff=true) diff --git a/src/TiffImages.jl b/src/TiffImages.jl index 0abca0e0..15984c15 100644 --- a/src/TiffImages.jl +++ b/src/TiffImages.jl @@ -33,7 +33,7 @@ include(joinpath("types", "lazy.jl")) include(joinpath("types", "mmapped.jl")) include("load.jl") -export memmap +export memmap, LazyBufferedTIFF @deprecate TiffFile(::Type{O}) where O<:Unsigned TiffFile{O}() diff --git a/src/types/dense.jl b/src/types/dense.jl index b503ab48..585075ca 100644 --- a/src/types/dense.jl +++ b/src/types/dense.jl @@ -167,4 +167,4 @@ function save(filepath::String, data) nothing end -Base.push!(A::DenseTaggedImage{T, N, O, AA}, data) where {T, N, O, AA} = error("push! is only supported for memory mapped images. See `memmap`.") \ No newline at end of file +Base.push!(A::DenseTaggedImage{T, N, O, AA}, data) where {T, N, O, AA} = error("push! is only supported for memory mapped images. See `LazyBufferedTIFF`.") \ No newline at end of file diff --git a/src/types/lazy.jl b/src/types/lazy.jl index 27f0bfc6..aa13e1e8 100644 --- a/src/types/lazy.jl +++ b/src/types/lazy.jl @@ -13,7 +13,7 @@ with different strengths and weaknesses. ```jldoctest julia> using TiffImages, ColorTypes -julia> img = TiffImages.memmap(Gray{Float32}, joinpath(mktempdir(), "test.tif")) +julia> img = empty(LazyBufferedTIFF, Gray{Float32}, joinpath(mktempdir(), "test.tif")) 32-bit LazyBufferedTIFF{Gray{Float32}} 0×0×0 (writable) Current file size on disk: 8 bytes Addressable space remaining: 4.000 GiB @@ -67,7 +67,7 @@ function LazyBufferedTIFF(file::TiffFile{O}, ifds::Vector{IFD{O}}) where {O} end """ - memmap(T, filepath; bigtiff) + empty(LazyBufferedTIFF, T, filepath; bigtiff) Create a new memory-mapped file ready with element type `T` for appending future slices. The `bigtiff` flag, if true, allows 64-bit offsets for data larger than @@ -76,7 +76,7 @@ slices. The `bigtiff` flag, if true, allows 64-bit offsets for data larger than ```jldoctest; setup=:(rm("test.tif", force=true)) julia> using ColorTypes, FixedPointNumbers # for Gray{N0f8} type -julia> img = memmap(Gray{N0f8}, "test.tif"); # make memory-mapped image +julia> img = empty(LazyBufferedTIFF, Gray{N0f8}, "test.tif"); # make memory-mapped image julia> push!(img, rand(Gray{N0f8}, 100, 100)); @@ -86,13 +86,18 @@ julia> size(img) (100, 100, 2) ``` """ -function memmap(::Type{T}, filepath; bigtiff=false) where {T <: Colorant} +function Base.empty(::Type{LazyBufferedTIFF}, ::Type{T}, filepath; bigtiff=false) where {T <: Colorant} if isfile(filepath) error("This file already exists, please use `TiffImages.load` to open") end LazyBufferedTIFF(T, getstream(format"TIFF", open(filepath, "w+"), filepath); bigtiff = bigtiff) end +function memmap(t::Type{T}, filepath; bigtiff=false) where {T <: Colorant} + Base.depwarn("`memmap` is deprecated, please use empty(LazyBufferedTIFF, $t, $filepath; bigtiff = $bigtiff)", :memmap, force = true) + empty(LazyBufferedTIFF, t, filepath; bigtiff = bigtiff) +end + function LazyBufferedTIFF(::Type{T}, io::Stream; bigtiff = false) where {T} O = bigtiff ? UInt64 : UInt32 tf = TiffFile{O}(io) diff --git a/test/mmap_lazyio.jl b/test/mmap_lazyio.jl index 8dfcc863..e9284c68 100644 --- a/test/mmap_lazyio.jl +++ b/test/mmap_lazyio.jl @@ -71,7 +71,7 @@ end @testset "De novo construction" begin rm("test.tif", force = true) - img = memmap(Gray{N0f8}, "test.tif") + img = empty(LazyBufferedTIFF, Gray{N0f8}, "test.tif") # a newly initialized file should have every dimension equal to zero and # error if accessed @@ -86,7 +86,7 @@ end @testset "BigTIFF" begin rm("test.btif", force = true) - img = memmap(Gray{N0f8}, "test.btif"; bigtiff = true) + img = empty(LazyBufferedTIFF, Gray{N0f8}, "test.btif"; bigtiff = true) push!(img, rand(Gray{N0f8}, 100, 100)) @test size(img) == (100, 100, 1)