View source for Documentation/Labs/ImageStacks

== Background ==

Image stacks are generated in a lot of scenarios, like microscopes, microCT, and other non-medical sources.

Examples are like:
<pre>
    directoryPath = '/Volumes/SSD2T/data/SlicerMorph/Sample_for_steve/1326_Rec'
    pathFormat = '%s/1326__rec%04d.png'
</pre>

== Common issues ==
* Data is really grayscale, but encoded using jpg or other color format
* Data may be large and needs to be cropped or resampled for use
* Data will not have any consistent metadata
** pixel / slice spacing
** orientation (e.g. mapping to anatomical coordinates)
** acquisition time, equipment, operator, etc
* Only a subset of data may actually be wanted (ROI or subsampled volume)

== Current reader ==

Delegates to ITK via vtkITKArchetype mechanism.  Lots of hidden logic to guess possible mapping from image files to volumes.
* Guesses filename pattern, which can easily fail
* Creates vector volume for RGB and user must manually convert to scalar
* Reads full volume and then must crop or resample
* Can be slow to read / decompress large files

== Available readers ==

* vtkPNGReader
* itk image IO
* Qt Image
* PIL / PILLOW python packages (not currently bundled in Slicer, but pip installable)
* QWebEngine

== Desired properties ==

* fast, ideally multithreaded
* compatible with multiple file formats (at least jpg, tiff, bmp, png)
* clean slicer integration
* support arbitrary file naming conventions with different ways of mapping names to volumes or other structures
* ability to map anatomical coordinates (e.g. click on nose, right ear, and top of head)
* ability to convert to scalar and/or crop/resample while reading
* store pyramid encoded volumes for later reuse
* use a single-file format for simplicity (avoid creating even more single slice image files)
* store metadata for later reuse
* allow scripted use outside slicer
* use reference volume or ROI to define desired geometry (e.g. reuse crop volume logic)
* handle greater than 8 bits per pixel if the source format supports it

== Options ==

Implementation
* stand-alone processing script with command line options -- too difficult for users in general, no interactive feedback
* plugin for Add Data module that exposes some options -- not enough room for gui, not interactive
* Independent importer module -- probably the best option with reusable logic

Features
* store pyramid files in nrrd or some minimal dicom
* option: put dicom files in database for reuse
* option: use low-res as visualization proxy but use fill res for processing

== Work in Progress ==

As of October 2019, the repo below has an implementation that works for slice files ready by SimpleITK (png, tiff, etc) extracting one component and options for 50% downsampling.

* https://github.com/pieper/SlicerImageStacks