Version 3.3.0

.gitmodules

@@ -1,4 +1,4 @@
 [submodule "docs"]
 	path = docs
-	url = https://github.com/rbnvrw/nd2reader.git
+	url = git@github.com:rbnvrw/nd2reader.git
 	branch = gh-pages

setup.py

@@ -1,6 +1,6 @@
 from setuptools import setup
 
-VERSION = '3.2.3'
+VERSION = '3.3.0'
 
 if __name__ == '__main__':
     setup(

sphinx/tutorial.rst

@@ -0,0 +1,148 @@
+Tutorial
+========
+
+Installation
+~~~~~~~~~~~~
+
+The package is available on PyPi. Install it using:
+
+::
+
+    pip install nd2reader
+
+If you don't already have the packages ``numpy``, ``pims``, ``six`` and
+``xmltodict``, they will be installed automatically if you use the
+``setup.py`` script. ``nd2reader`` is an order of magnitude faster in
+Python 3. I recommend using it unless you have no other choice. Python
+2.7 and Python >= 3.4 are supported.
+
+Installation via Conda Forge
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Installing ``nd2reader`` from the ``conda-forge`` channel can be
+achieved by adding ``conda-forge`` to your channels with:
+
+::
+
+    conda config --add channels conda-forge
+
+Once the ``conda-forge`` channel has been enabled, ``nd2reader`` can be
+installed with:
+
+::
+
+    conda install nd2reader
+
+It is possible to list all of the versions of ``nd2reader`` available on
+your platform with:
+
+::
+
+    conda search nd2reader --channel conda-forge
+
+Opening ND2s
+~~~~~~~~~~~~
+
+``nd2reader`` follows the `pims <https://github.com/soft-matter/pims>`__
+framework. To open a file and show the first frame:
+
+.. code:: python
+
+    from nd2reader import ND2Reader
+    import matplotlib.pyplot as plt
+
+    with ND2Reader('my_directory/example.nd2') as images:
+      plt.imshow(images[0])
+
+After opening the file, all ``pims`` features are supported. Please
+refer to the `pims
+documentation <http://soft-matter.github.io/pims/>`__.
+
+ND2 metadata
+~~~~~~~~~~~~
+
+The ND2 file contains various metadata, such as acquisition information,
+regions of interest and custom user comments. Most of this metadata is
+parsed and available in dictionary form. For example:
+
+.. code:: python
+
+    from nd2reader import ND2Reader
+
+    with ND2Reader('my_directory/example.nd2') as images:
+        # width and height of the image
+        print('%d x %d px' % (images.metadata['width'], images.metadata['height']))
+
+All metadata properties are:
+
+-  ``width``: the width of the image in pixels
+-  ``height``: the height of the image in pixels
+-  ``date``: the date the image was taken
+-  ``fields_of_view``: the fields of view in the image
+-  ``frames``: a list of all frame numbers
+-  ``z_levels``: the z levels in the image
+-  ``total_images_per_channel``: the number of images per color channel
+-  ``channels``: the color channels
+-  ``pixel_microns``: the amount of microns per pixel
+-  ``rois``: the regions of interest (ROIs) defined by the user
+-  ``experiment``: information about the nature and timings of the ND
+   experiment
+
+Iterating over fields of view
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Using ``NDExperiments`` in the Nikon software, it is possible to acquire
+images on different ``(x, y)`` positions. This is referred to as
+different fields of view. Using this reader, the fields of view are on
+the ``v`` axis. For example:
+
+.. code:: python
+
+    from nd2reader import ND2Reader
+
+    with ND2Reader('my_directory/example.nd2') as images:
+        # width and height of the image
+        print(images.metadata)
+
+will output
+
+.. code:: python
+
+    {'channels': ['BF100xoil-1x-R', 'BF+RITC'],
+     'date': datetime.datetime(2017, 10, 30, 14, 35, 18),
+     'experiment': {'description': 'ND Acquisition',
+      'loops': [{'duration': 0,
+        'sampling_interval': 0.0,
+        'start': 0,
+        'stimulation': False}]},
+     'fields_of_view': [0, 1],
+     'frames': [0],
+     'height': 1895,
+     'num_frames': 1,
+     'pixel_microns': 0.09214285714285715,
+     'total_images_per_channel': 6,
+     'width': 2368,
+     'z_levels': [0, 1, 2]}
+
+for our example file. As you can see from the metadata, it has two
+fields of view. We can also look at the sizes of the axes:
+
+.. code:: python
+
+        print(images.sizes)
+
+.. code:: python
+
+    {'c': 2, 't': 1, 'v': 2, 'x': 2368, 'y': 1895, 'z': 3}
+
+As you can see, the fields of view are listed on the ``v`` axis. It is
+therefore possible to loop over them like this:
+
+.. code:: python
+
+        images.iter_axes = 'v'
+        for fov in images:
+            print(fov) # Frame containing one field of view
+
+For more information on axis bundling and iteration, refer to the `pims
+documentation <http://soft-matter.github.io/pims/v0.4/multidimensional.html#axes-bundling>`__.