Public interface

load(filepath; mode, kwargs...)

Loads a TIFF image. Optional flags verbose, lazyio, and mmap are set to true, false, and false by default, respectively. Setting verbose to false will hide the loading bar, while setting either lazyio or mmap to true defer loading until the data are needed (by either of two mechanisms).

Parallelism is enabled by default, but can be disabled by setting JULIA_IMAGES_PARALLEL=false in your environment

Loading images with a large number of channels may result in a noticeable delay on the first load (up to several minutes for hundreds or thousands of channels)

See Lazy TIFFs for more details about memory-mapping and lazy I/O.

save(io, data)

Write data to io, if data is a DenseTaggedImage then any custom tags are also written to the file, otherwise a minimal set of tags are added to make the data readable by other TIFF engines.

color(img::AbstractTIFF{ <: WidePixel}; alpha)

Extract the color channels from multispectral image img

The optional alpha parameter allows an arbitrary channel to be used as the alpha channel

julia> img = DenseTaggedImage(WidePixel.([rand(RGB{Float32}) for x in 1:256, y in 1:256], [(rand(Float32),) for x in 1:256, y in 1:256]));

julia> eltype(img)
WidePixel{RGB{Float32}, Tuple{Float32}}

julia> nchannels(img)
4

julia> eltype(color(img; alpha=4)) # use the fourth channel as an alpha channel
RGBA{Float32}

color(img::AbstractTIFF)

This is an identity relation that just returns img

color(x::WidePixel; alpha)

Return the value of the color field of x

The optional alpha parameter allows an arbitrary channel to be used as the alpha channel

color(x::Colorant)

This is an identity relation that just returns x

nchannels(img::AbstractTIFF)

Return the number of channels in each pixel

For example, an image with RGB pixels has 3 channels

channel(img, i)

Get the i'th channel of data from img

For example, channel(img, 2) would yield the green channel of an RGB image, or the (unlabeled) second channel of a multispectral image

struct DenseTaggedImage{T, N, O<:Unsigned, AA<:AbstractArray} <: TiffImages.AbstractDenseTIFF{T, N}

The most common TIFF structure that associates an Image File Directory, aka TiffImages.IFD, with each XY image slice.

julia> img = TiffImages.DenseTaggedImage(Gray.(zeros(UInt8, 10, 10)));

julia> size(img)
(10, 10)

julia> ifds(img)
IFD, with tags: 
	Tag(IMAGEWIDTH, 10)
	Tag(IMAGELENGTH, 10)
	Tag(BITSPERSAMPLE, 8)
	Tag(PHOTOMETRIC, 1)
	Tag(SAMPLESPERPIXEL, 1)
	Tag(SAMPLEFORMAT, 1)

julia> ifds(img)[TiffImages.XRESOLUTION] = 0x00000014//0x00000064 # write custom data
0x00000001//0x00000005

julia> TiffImages.save(mktemp()[2], img); # write to temp file

See also TiffImages.load and TiffImages.save

mutable struct LazyBufferedTIFF{T<:Union{Colorant, TiffImages.WidePixel}, O<:Unsigned, AA<:AbstractArray} <: TiffImages.AbstractDenseTIFF{T<:Union{Colorant, TiffImages.WidePixel}, 3}

A type to represent lazily-loaded TIFF data, returned by TiffImages.load(filepath; lazyio=true). Useful for opening and operating on images too large to store in memory, and for incrementally writing new TIFF files.

This works by buffering individual slices. This allows broad format support, including compressed TIFFs, but with mixed performance depending on your specific access (indexing) patterns. See discussion in the package documentation, and MmappedTIFF for an alternative with different strengths and weaknesses.

julia> using TiffImages, ColorTypes

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

julia> close(img) # when you're done, close the stream

• file: Pointer to keep track of the backing file

• ifds: The associated tags for each slice in this array

• dims

• working_cache: An internal cache to fill reading from disk

• cache: An internal cache to fill with fully transformed data

• cache_index: The index of the currently loaded slice

• last_ifd_offset: Position of last loaded IFD, updated whenever a slice is appended

• readonly: A flag tracking whether this file is editable

struct MmappedTIFF{T<:Union{Colorant, TiffImages.WidePixel}, N, O<:Unsigned, A<:AbstractArray{T<:Union{Colorant, TiffImages.WidePixel}, 2}} <: TiffImages.AbstractTIFF{T<:Union{Colorant, TiffImages.WidePixel}, N}

A type to represent memory-mapped TIFF data, returned by TiffImages.load(filepath; mmap=true). Useful for opening and operating on images too large to store in memory.

This works by exploiting the operating system's memory-mapping capabilities. This is not compatible with certain TIFF options, including compression, but when applicable it gives good performance for most access (indexing) patterns. See discussion in the package documentation, and LazyBufferedTIFF for an alternative with different strengths and weaknesses.

julia> using TiffImages

julia> img = TiffImages.load(filepath; mmap=true);

julia> print(summary(img))
200×541 TiffImages.MmappedTIFF{RGBA{N0f8}, 2}

Fields:

• chunks: 2d slices in the file

• ifds: The associated tags for each slice in this array

• sz2: The 2d slice size