TIFFStack

Load TIFF files into matlab fast, with lazy loading

This class allows you to access a TIFF file as a matlab tensor, whileonly reading the data that you need from disk. A TIFFStack objectappears like a four-dimensional tensor, with dimensions for rows,columns, frames and channels (multiple samples per pixel). These objectscan be passed transparently into other functions that expect matlabtensors. If you need to process only a portion, or only one channel of aTIFF stack, then this class will save you allocating the enormousamounts of memory required to load the entire file. TIFFStack is alsomuch faster than using imread to read each frame of the TIFF fileseparately.

TIFFStack attempts to use libTiff, which is directly supportedin recent Matlab versions. This provides dramatic speed-ups, and is a good deal faster than using imread orthe Matlab Tiff class. If libTiff is not available, then Matlab-onlycode is used to read image data. permute, ipermute, transpose andctranspose are also transparently supported.

Download and install

Clone TIFFStack into a directory called@TIFFStack. The ampersand symbol (@) is important, since it indicatesto Matlab that TIFFStack is an object-oriented module. Add the parentdirectory — not the @TIFFStack directory — to the Matlab path.

Usage

tsStack = TIFFStack(strFilename <, bInvert>)

A TIFFStack object behaves like a read-only memory mapped TIFF file.The entire image stack is treated as a Matlab tensor. Each frame of thefile must have the same dimensions. Reading the image data is optimisedto the extent possible; the header information is only read once.

This class attempts to use the Matlab libTiff interface, if available.If not, it uses a modified version of tiffread [1, 2] to read data.Code is included (but disabled) to use the matlab imread function, butthis function returns invalid data for some TIFF formats.

Construction of a TIFFStack object

>> tsStack = TIFFStack('test.tiff'); % Construct a TIFF stack associated with a file

>> tsStack = TIFFStack('test.tiff', true); % Indicate that the image data should be inverted 
   tsStack = 
     TIFFStack handle 
     Properties: 
        bInvert: 1 
        strFilename: [1x9 char] 
        sImageInfo: [5x1 struct] 
        strDataClass: 'uint16'

Accessing data

>> tsStack(:, :, 3); % Retrieve the 3rd frame of the stack, all planes 
>> tsStack(:, :, 1, 3); % Retrieve the 3rd plane of the 1st frame 
>> size(tsStack) % Find the size of the stack (rows, cols, frames, planes per pixel)

ans = 
   128 128 5 1

>> tsStack(4); % Linear indexing is supported 
>> tsStack.bInvert = true; % Turn on data inversion

Stacks with interleaved frame, channel and slice dimensions

Some TIFF generation software stores multiple samples per pixel asinterleaved frames in a TIFF file. Other complex stacks may includemultiple different images per frame of time (e.g. multiple cameras ordifferent imaged locations per frame). TIFFStack allows these files to bede-interleaved, such that each conceptual data dimension has its ownreferencing dimension within Matlab.

This functionality uses the optional vnInterleavedFrameDims argument.This is a vector of dimensions that were interleaved into the singleframe dimension in the stack.

For example, a stack contains 2 channels of data per pixel, and 3 imagedlocations per frame, all interleaved into the TIFF frame dimension. Thestack contains 10 conceptual frames, and each frame contains 5x5 pixels.

The stack is therefore conceptually of dimensions [5 5 2 3 10 1], butappears on disk with dimensions [5 5 60 1]. (The final dimensioncorresponds to the samples-per-pixel dimension of the TIFF file).

>> tsStack = TIFFStack('file.tif', [], [2 3 10]);
>> size(tsStack)

ans =
     5    5    2    3   10

Permutation and indexing now works seamlessly on this stack, with eachconceptual dimension de-interleaved.

If desired, the final number of frames can be left offvnInterleavedFrameDims; for example

>> tsStack = TIFFStack('file.tif', [], [2 3]);
>> size(tsStack)

ans =
     5    5    2    3   10

Note: You must be careful that you specify the dimensions in theappropriate order, exactly as interleaved in the stack. Also, if the stackcontains multiple samples per pixel in native TIFF format, thesamples-per-pixel dimension will always be pushed to the final dimension.

Publications

This work was published in Frontiers in Neuroinformatics: DR Muir andBM Kampa. 2015. FocusStack and StimServer: A new open source MATLABtoolchain for visual stimulation and analysis of two-photon calciumneuronal imaging data, Frontiers in Neuroinformatics 8 85. DOI: dx.doi.org/10.3389/fninf.2014.00085.Please cite our publication in lieu of thanks, if you use this code.

References

[1] Francois Nedelec, Thomas Surrey and A.C. Maggs. Physical ReviewLetters 86: 3192-3195; 2001. DOI: 10.1103/PhysRevLett.86.3192

[2] http://www.cytosim.org

Acknowledgements

This work optionally uses tiffread from Francois Nedelec to access the data inthe TIFF file. Matlab includes the ability to read TIFF files inimread, including niceties such as only reading a region of interestfrom each frame, but imread is incredibly slow and amazingly buggy (asof July 2011). TIFFStack uses tiffread in an optimised fashion, byreading and caching the header information (the image file directories —IFDs). Each frame can then be read directly without re-opening the fileand re-reading the IFDs.

License

TIFFStack by Dylan Muir is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.
Based on a work at http://github.com/DylanMuir/TIFFStack.