From 86bd2eb99d2323effac8a35da4544321bedfd0b6 Mon Sep 17 00:00:00 2001
From: Ruben Verweij <verweij@physics.leidenuniv.nl>
Date: Mon, 30 Oct 2017 15:26:25 +0100
Subject: [PATCH] Version 3.0.6: Add FOV support

---
 docs                  |  2 +-
 nd2reader/__init__.py |  2 +-
 nd2reader/reader.py   | 10 ++++++----
 setup.py              |  2 +-
 sphinx/conf.py        |  4 ++--
 sphinx/tutorial.md    | 44 ++++++++++++++++++++++++++++++++++++++++++-
 6 files changed, 54 insertions(+), 10 deletions(-)

diff --git a/docs b/docs
index 438ef09..f3f986b 160000
--- a/docs
+++ b/docs
@@ -1 +1 @@
-Subproject commit 438ef091834dbeab162f0255ff81db3396623b2a
+Subproject commit f3f986bb87ac932bc45fc494c7b72fa485848a87
diff --git a/nd2reader/__init__.py b/nd2reader/__init__.py
index eb2f484..8ecf552 100644
--- a/nd2reader/__init__.py
+++ b/nd2reader/__init__.py
@@ -1,4 +1,4 @@
 from nd2reader.reader import ND2Reader
 from nd2reader.legacy import Nd2
 
-__version__ = '3.0.5'
+__version__ = '3.0.6'
diff --git a/nd2reader/reader.py b/nd2reader/reader.py
index b27259c..30c3c1e 100644
--- a/nd2reader/reader.py
+++ b/nd2reader/reader.py
@@ -1,4 +1,4 @@
-from pims.base_frames import FramesSequenceND, Frame
+from pims.base_frames import FramesSequenceND
 
 from nd2reader.exceptions import EmptyFileError
 from nd2reader.parser import Parser
@@ -52,7 +52,7 @@ class ND2Reader(FramesSequenceND):
         except KeyError:
             return 0
 
-    def get_frame_2D(self, c=0, t=0, z=0, x=0, y=0):
+    def get_frame_2D(self, c=0, t=0, z=0, x=0, y=0, v=0):
         """Gets a given frame using the parser
 
         Args:
@@ -61,6 +61,7 @@ class ND2Reader(FramesSequenceND):
             c: The color channel number
             t: The frame number
             z: The z stack number
+            v: The field of view index
 
         Returns:
             numpy.ndarray: The requested frame
@@ -73,7 +74,7 @@ class ND2Reader(FramesSequenceND):
 
         x = self.metadata["width"] if x <= 0 else x
         y = self.metadata["height"] if y <= 0 else y
-        return self._parser.get_image_by_attributes(t, 0, c_name, z, y, x)
+        return self._parser.get_image_by_attributes(t, v, c_name, z, y, x)
 
     @property
     def parser(self):
@@ -136,6 +137,7 @@ class ND2Reader(FramesSequenceND):
         self._init_axis_if_exists('c', len(self._get_metadata_property("channels", default=[])), min_size=2)
         self._init_axis_if_exists('t', len(self._get_metadata_property("frames", default=[])))
         self._init_axis_if_exists('z', len(self._get_metadata_property("z_levels", default=[])), min_size=2)
+        self._init_axis_if_exists('v', len(self._get_metadata_property("fields_of_view", default=[])), min_size=2)
 
         if len(self.sizes) == 0:
             raise EmptyFileError("No axes were found for this .nd2 file.")
@@ -153,7 +155,7 @@ class ND2Reader(FramesSequenceND):
         Returns:
             the axis to iterate over
         """
-        priority = ['t', 'z', 'c']
+        priority = ['t', 'z', 'c', 'v']
         found_axes = []
         for axis in priority:
             try:
diff --git a/setup.py b/setup.py
index 5d48b11..77a3fa2 100644
--- a/setup.py
+++ b/setup.py
@@ -1,6 +1,6 @@
 from setuptools import setup
 
-VERSION = '3.0.5'
+VERSION = '3.0.6'
 
 if __name__ == '__main__':
     setup(
diff --git a/sphinx/conf.py b/sphinx/conf.py
index 1c618a2..fc42bf5 100644
--- a/sphinx/conf.py
+++ b/sphinx/conf.py
@@ -44,9 +44,9 @@ author = 'Ruben Verweij'
 # built documents.
 #
 # The short X.Y version.
-version = '3.0.5'
+version = '3.0.6'
 # The full version, including alpha/beta/rc tags.
-release = '3.0.5'
+release = '3.0.6'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
diff --git a/sphinx/tutorial.md b/sphinx/tutorial.md
index 932fc04..6be8c49 100644
--- a/sphinx/tutorial.md
+++ b/sphinx/tutorial.md
@@ -57,7 +57,6 @@ 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:
@@ -74,4 +73,47 @@ All metadata properties are:
 * `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:
+```python
+from nd2reader import ND2Reader
 
+with ND2Reader('my_directory/example.nd2') as images:
+    # width and height of the image
+    print(images.metadata)
+```
+will output
+```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:
+```python
+    print(images.sizes)
+```
+```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:
+```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).