File Exchange

image thumbnail


version (677 KB) by Dylan Muir
Read a TIFF stack as a memory-mapped tensor. Handles a large range of internal TIFF formats.


Updated 12 Dec 2017

From GitHub

View Version History

View license on GitHub

See also
If this code is useful to your academic work, please cite the publication in lieu of thanks:
Muir and Kampa, "FocusStack and StimServer: A new open source MATLAB toolchain for visual stimulation and analysis of two-photon calcium neuronal imaging data". Frontiers in Neuroinformatics 2015.

Usage: tsStack = TIFFStack(strFilename <, bInvert>)

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

This class attempts to use the version of tifflib built-in to recent versions of Matlab, if available. Otherwise this class uses a modified version of tiffread [1, 2] to read data. Code is included (but disabled) to use the matlab imread function, but imread returns invalid data for some TIFF formats.
permute, ipermute and transpose are now transparantly supported. Note that to read a pixel, the entire frame containing that pixel is read. So reading a Z-slice of the stack will read in the entire stack.

>> 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
bInvert: 0
strFilename: [1x9 char]
sImageInfo: [5x1 struct]
strDataClass: 'uint16'
>> 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
Support for de-interleaving of channels and slices into the frame axis is also supported (see help text for TIFFStack).

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

Cite As

Dylan Muir (2021). DylanMuir/TIFFStack (, GitHub. Retrieved .

Comments and Ratings (32)

Praneet Prakash

Hi Dylan,

I have a image stack which I am not able to load. Below is the complete error message from compiler. Please let me know if you have any suggestions.

Thank you,
Warning: --- MappedTensor: Could not compile MEX functions. Using slow matlab versions.
> In MappedTensor>GetMexFunctionHandles (line 2175)
In MappedTensor (line 208)
In TIFFStack>OpenImageJBigStack (line 1866)
In TIFFStack (line 247)
Warning: --- MappedTensor/delete: Could not delete temporary file.
Error: Invalid file identifier. Use fopen to generate a valid file identifier.
> In MappedTensor/delete (line 410)
In MappedTensor (line 206)
In TIFFStack>OpenImageJBigStack (line 1866)
In TIFFStack (line 247)
Error using TIFFStack (line 484)
*** TIFFStack: Could not open file

Caused by:
Error using fopen
First input must be a file name or a file identifier.

Daniel Dickinson

@bei liu: The error with TIFFStack and an invalid MEX-file happened to me too when I upgraded from R2017a to R2019b. The fix was simple: Delete the whole @TIFFStack folder and re-clone the git repository from The first time TIFFStack runs in the new version of MATLAB, it will re-compile itself and the error will disappear.

srishti garg

HI Dylan,
Thank you for writing this code.
I am trying to use this code for my work and getting the erroe at 151 line of TIFFStack.m (classdef TIFFStack < handle)
Error is 'Class name and filename do not agree'. Please help me fixing this.

bei liu

HI Dylan, I have been using TIFFStack for years and it works just amazing. Recently, I upgraded my MATLAB to 2018a (also tried 2017b), and it gives me some error on tifflib.mex when I try to construct a TIFF stack. Any idea on this? Thanks!

The error looks like this:
Caused by:
Invalid MEX-file 'C:\Users\xx\@TIFFStack\private\tifflib.mexw64':
Missing symbol '?get_chars@mxArray_tag@@QEBAPEA_WXZ' in 'C:\Program Files\MATLAB\R2018a/bin/win64\libmx.dll' required by 'C:\Users\xx\3rdparty\@TIFFStack\private\tifflib.mexw64'
Missing symbol '?get_ustring@matrix@@YA?AV?$basic_string@_WU?$char_traits@_W@std@@V?$allocator@_W@2@@std@@PEBUmxArray_tag@@@Z' in 'C:\Program Files\MATLAB\R2018a/bin/win64\libmx.dll' required by
Missing symbol '?get_string@matrix@@YA?AV?$basic_string@DU?$char_traits@D@std@@V?$allocator@D@2@@std@@PEBUmxArray_tag@@AEBV?$converter@D_W@i18n@fl@@@Z' in 'C:\Program Files\MATLAB\R2018a/bin/win64\libmx.dll' required by

Bing Fu

Dylan Muir

Hi John, please open an issue at the TIFFStack github and we can try to debug your problem. Thanks, Dylan.

John Szymanski

Great tool but I am having an issue with imageJ 2-channel stacks >4GB. Under 4GB, these 2 channel composite stacks load fine, but over 4GB i get errors.

Without MappedTensor, I get this:
Warning: The reported size of this stack does not match the number of IFDs.
I will attempt to continue.
> In TIFFStack>IsImageJBigStack (line 1856)
In TIFFStack (line 243)
Warning: --- TIFFStack: Warning: This is an ImageJ "fake" TIF file. MappedTensor must be available to read this file.
> In TIFFStack (line 255)
Warning: TIFF library warning - 'TIFFReadDirectory: Unknown field with tag 50838 (0xc696) encountered.'
> In TIFFStack (line 280)
Warning: TIFF library warning - 'TIFFReadDirectory: Unknown field with tag 50839 (0xc697) encountered.'
> In TIFFStack (line 280)

With MappedTensor, I get this:
Error using TIFFStack (line 484)
*** TIFFStack: Could not open file [X:\new era\catalog\cb2\Composite.tif].

Caused by:
Error using MappedTensor (line 332)
*** MappedTensor: Error: 'vnTensorSize' must be a positive integer vector.

Any ideas on a fix?



Fantastic tool - strongly recommended!

Dylan Muir

Hi Ryan, thanks for your feedback.

TIFF files with non-standard tags (there are thousands of them!) will definitely raise warnings. The warnings can be switched off using the matlab `warning` function.

Best regards,

Ryan Muir

Seems to work well, except that I get a flood of warning messages every time I read or access my stack. They all say:

Warning: TIFF library warning - 'TIFFReadDirectory: Unknown field with tag
50288 (0xc470) encountered.'

I used microsoft windows SDK 7.1 as my mex C compiler. I am running windows 7.

Dylan Muir

Hi Rachel,

I will take a look at the problem to see if I can reproduce it. I have created an issue on github ( to track this; please check there and respond if necessary.

Best regards,

Adrien Peyrache


I am running into a problem with TiffStack specifically when I try to load >4GB uint16 tiff stacks that have been saved in imageJ (ie 'big stacks' dealt with by the 'OpenImageJBigStack' fx).

After TiffStack is done running on these faulty-headed tiff files (successfully calling MappedTensor), when I plot frames from the resultant tsStack object, for example using imagesc(tsStack(:,:,1)), the image appears circularly shifted along the 1st dimension, as Avinash mentioned in the comments section of your MappedTensor fx on FileExchange. Unfortunately, the fix mentioned in your response doesn't work for me (I'm assuming the output of >4GB ImageJ tiff stacks that display the error re: headers are binarized, as mentioned elsewhere).

All is working for tiff stacks saved in imageJ that are smaller than this limit.

Any help re: how to trouble shoot would be fantastic - as this fx for my smaller files is a life-savor for setting up efficient parallel processing.


Dylan Muir

Hi Sandeep,

TIFFStack uses compiled code for some operations, to speed up manipulations of an image stack. This requires the MEX compiler from matlab to be properly configured for your system. TIFFStack will work without these compiled versions, but will be slower. If you would like to use the MEX versions, then you will have to configure your system to successfully compile code.


sandeep manandhar


I get this warning
--- TIFFStack: Compiling MEX functions.
Warning: --- TIFFStack: Could not compile MEX functions. Using
slow matlab versions.
> In TIFFStack>GetMexFunctionHandles (line 1728)
In TIFFStack (line 205)

My Matlab version is (R2015b).

Rob Campbell

Vijay Iyer

Please disregard my previous rating. I have not used the tool, so cannot rate or comment on it fairly. I was testing something randomly & apparently rating entries get submitted without pressing the submit button. Apologies for the noise! Long live signal.

Vijay Iyer


Hi, I've figured out the problem by repairing my Visual Studio 2013. Thanks at all!


Somehow my problem description got lost. Could you please help?

--- TIFFStack: Compiling MEX functions.
Warning: --- TIFFStack: Could not compile MEX functions. Using slow matlab versions.
> In TIFFStack.TIFFStack>GetMexFunctionHandles at 1703
In TIFFStack.TIFFStack>TIFFStack.TIFFStack at 205
In temp at 29


additional information:

>> ver
MATLAB Version: (R2014b)
MATLAB License Number: 981334
Operating System: Microsoft Windows 7 Professional Version 6.1 (Build 7601: Service Pack 1)
Java Version: Java 1.7.0_11-b21 with Oracle Corporation Java HotSpot(TM) 64-Bit Server VM mixed mode

Sébastien MAILFERT

Hi Dylan,
You are right, the path was not correcly defined.

Now, my questions is how can I use the mex compiler please?
Best regards.

Dylan Muir

Hi Sébastien,

The warning indicates that matlab can't use the mex compiler, which is required by TIFFStack for accelerated reading.

The error indicates that matlab can't find the file 'tiffread31_header.m', which is the 'private' subdirectory of TIFFStack. The TIFFStack directory needs to be added to the matlab path; perhaps you could check that.

I just downloaded the latest version, and can't reproduce the problem, even if I force TIFFStack to use the non-MEX versions of the access functions.

If you have further problems, please start an issue on github.

Best regards,

Sébastien MAILFERT


I tried your function and I saw this error:

Warning: --- TIFFStack: Using slower non-TiffLib access.
> In TIFFStack (line 187)
Warning: --- TIFFStack: Could not compile MEX functions. Using slow matlab versions.
> In TIFFStack>GetMexFunctionHandles (line 1354)
In TIFFStack (line 192)
Error using TIFFStack (line 390)
*** TIFFStack: Could not open file

Caused by:
Undefined function 'tiffread31_header' for input arguments of type 'char'.

Could you help me please?

Dylan Muir

Hi HCYU, Please pull the latest version and try again. There was a referencing bug for older versions of matlab -- I think this may have been your issue.
Best regards, Dylan.


new error message below:

Error using TIFFStack>TS_read_data_Tiff (line 761)
*** TIFFStack: Could not read data from image file.

Error in TIFFStack/subsref (line 438)
tfData = TS_read_data_Tiff(oStack, S.subs, bLinearIndexing);

Error in testvaa3d (line 6)
img = iStack(:, :, i);

Caused by:
Error using tifflib
Directory numbers must be greater than or equal to 1.

Dylan Muir

Hi HCYU, thanks for your bug report. I have fixed the bug in the latest commit of TIFFStack. You can pull it immediately from github; the file exchange version takes a day to update.
Best regards, Dylan.


note that: "tfData = oStack.sImageInfo(1).MaxSampleValue - (tfData - oStack.sImageInfo(1).MinSampleValue);"

error info:"Error using -
Integers can only be combined with integers of the same class, or scalar doubles."

Dylan Muir

Hi David, thanks for your message. I'm sorry about that regression. I've uploaded a new version which fixes the problem.
Best regards, Dylan,


With the most recent version getting errors when accessing object properties like strDataClass

Error using cellfun
Input #2 expected to be a cell array, was char instead.

Error in TIFFStack/subsref (line 289)
cellfun(@isvalidsubscript, S.subs);

Dylan Muir

Hi Jana, the class has documentation available if you type `help TIFFStack`. What seems to be the problem?

Can't get this to work. Is there a documentation on how to use it?


Best way, to my knowledge, to work with TIFF stacks on Matlab. Recommended.

MATLAB Release Compatibility
Created with R2010b
Compatible with any release
Platform Compatibility
Windows macOS Linux

Inspired by: tiffread2.m

Inspired: alexludwigklein/MATLAB-Videos

Community Treasure Hunt

Find the treasures in MATLAB Central and discover how the community can help you!

Start Hunting!