.. currentmodule:: pims

ImageSequence
=============

An image sequence is a collection of image files with sequential
filenames.

``ImageSequence`` can be instatiated using:

* a directory name, such as a ``'my_directory'``
* a "glob" string, such as ``'my_directory/*.png'``, which is safer than
  using a directory because directories sometimes contain stray files
* the filepath of a zipped archive, such as ``'my_directory/all-images.zip'``
* a list of filepaths, such as ``['image1.png', 'image2.png']``

In all cases except the last one, to sort the filenames, sorting keys are
generated by splitting the names into digit and non-digit parts (effectively
sorting numbers numerically).  For example, ``['abc9.png', 'abc10.png',
'def9.png']`` are in sorted order.  If a list of paths is given, it is used as
is, with no additional sorting.

ImageSequenceND
---------------

.. seealso:: The section :doc:`multidimensional` describes how to deal with multidimensional files.

This class allows reading of N-dimensional Image Sequences with multiple indices
in the file name, for instance: ``['image_z00_t00.png', 'image_z01_t00.png']``.

ReaderSequence
--------------

This class allows stacking N-dimensional readers creating another N-dimensional
with an extra dimension. For example:

.. code-block:: python

   reader = pims.ReaderSequence('path/to/files/image*.tif', pims.BioformatsReader)

Dependencies
------------

Several widely-used Python packages have slightly different implementations
of ``imread``, a general purpose image-reading function that understands
popular formats like PNG, JPG, TIFF, and others. PIMS requires **one of
the following** packages, in order of decreasing preference.

* `scikit-image <http://scikit-image.org/>`_
* `imageio <https://imageio.readthedocs.io/en/stable/>`_

Scikit-image is installed with the PIMS conda package.
