Squashed '@TIFFStack/' changes from 90dffa4..9e73c53

9e73c53 * Added a flag to force `TIFFStack` to use slower `tiffread` library, if desired * Fixed a bug where linear indexing would not be range checked as early as possible * Fixed a bug in `tiffread` support * Improved unit testing to only require a [3x3x3] stack * Added unit tests for empty subreferences * Added unit tests for slower `tiffread` library support
cc5539f Documentation fix. Added `.gitignore` to repository
f77a0d4 Merge pull request #3 from jennan/pr/2
4768eea Fixed bug with deinterleaving + permutation + slicing
6ddc0d9 Added documentation regarding the de-interleaving functionality.
2ae0dd5 * Renamed de-interleaving argument * Improved parameter checking for de-interleaving argument * Re-allowed de-interleaving argument to leave off final frames, similar to `reshape`
f011b6f Bugfixes and improvements related to de-interleaving
e692bef Merge branch 'master' into pr/2
a32b839 Unit test now includes logical indexing
7a8a065 Merge branch 'master' into pr/2
356d33a * Added a unit testing function for `TIFFStack` * Added property accessor methods to `TIFFStack`, since otherwise properties were inaccessible * Fixed a bug when referencing inverted stacks with multiple samples per pixel * Fixed a referencing bug, where out of range subscripts would not raise an error, if fewer dimensions than the total were referenced * Modified an error identifier
36ad2ad Add special case with colon indexing of reinterpreted frame dimension
69e1360 Fix consistency in error style (CamelCase)
3251086 Move deinterleaving in the constructor, fixed for a TIFFStack
db994c7 Add deinterleaving method to reinterpret the frame dim as several dims
65c1a85 Fixed a referencing bug in `TIFFStack`
7362e2c Speed improvements to `TIFFStack`
92e4244 Fixed bugs relating to data returned by linear indexing having a different shape to the index vector.
1742646 Fixed a bug in `TIFFStack`, when referencing a stack with trailing dimensions of `1`
ce7e820 * `TIFFStack` can now read an entire stack in an accelerated fashion, with any number of referencing dimensions
a6abdfe Fixed a bug in `TIFFStack`, which caused a warning "Closing open TIFF file handle..." when clearing variables.
07bd9d5 Fixed a bug in `TIFFStack` on older systems, where referencing frame 1 of the stack would fail.
6504550 Made `fhCastFunction` a private `TIFFStack` property
13fa2f9 Added information to `TIFFStack` about disabling `tifflib` warnings.
e940e75 Fixed a bug in `TIFFStack`, where if the stack data class was an integer type, then stack data inversion would fail with an error.
ae27a64 `TIFFStack` now supports logical indexing.

git-subtree-dir: @tiffstack
git-subtree-split: 9e73c533a09782ad7f103157e02a0f5b40120806

Author: DylanMuir

.gitignore

@@ -0,0 +1,2 @@
+private/mapped_tensor_repsum.mexmaci64
+private/tifflib.mexmaci64

README.md

@@ -32,13 +32,13 @@ directory — not the *@TIFFStack* directory — to the [Matlab] path.
     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 the
+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 Matlab tifflib interface, if available.
+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, but
+Code is included (but disabled) to use the matlab `imread` function, but
 this function returns invalid data for some TIFF formats.
 
 ## Construction of a `TIFFStack` object
@@ -66,6 +66,55 @@ this function returns invalid data for some TIFF formats.
     >> 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 as
+interleaved frames in a TIFF file. Other complex stacks may include
+multiple different images per frame of time (e.g. multiple cameras or
+different imaged locations per frame). `TIFFStack` allows these files to be
+de-interleaved, such that each conceptual data dimension has its own
+referencing dimension within Matlab.
+
+This functionality uses the optional `vnInterleavedFrameDims` argument.
+This is a vector of dimensions that were interleaved into the single
+frame dimension in the stack.
+
+For example, a stack contains 2 channels of data per pixel, and 3 imaged
+locations per frame, all interleaved into the TIFF frame dimension. The
+stack contains 10 conceptual frames, and each frame contains 5x5 pixels.
+
+The stack is therefore conceptually of dimensions [5 5 2 3 10 1], but
+appears on disk with dimensions [5 5 60 1]. (The final dimension
+corresponds 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 each
+conceptual dimension de-interleaved.
+
+If desired, the final number of frames can be left off
+`vnInterleavedFrameDims`; 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 the
+appropriate order, exactly as interleaved in the stack. Also, if the stack
+contains multiple samples per pixel in native TIFF format, the
+samples-per-pixel dimension will always be pushed to the final dimension.
+
 ## Publications
 
 This work was published in [Frontiers in Neuroinformatics]: DR Muir and