Merge branch '2.0' into 125-more-metadata

README.md

@@ -2,7 +2,7 @@
 
 ### About
 
-`nd2reader` is a pure-Python package that reads images produced by NIS Elements 4.0+. It has only been definitively tested on NIS Elements 4.30.02 Build 1053. Support for older versions is planned.
+`nd2reader` is a pure-Python package that reads images produced by NIS Elements 4.0+. It has only been definitively tested on NIS Elements 4.30.02 Build 1053. Support for older versions is being actively worked on.
 
 .nd2 files contain images and metadata, which can be split along multiple dimensions: time, fields of view (xy-plane), focus (z-plane), and filter channel.
 
@@ -10,11 +10,13 @@
 
 ### Installation
 
+If you don't already have the packages `numpy` and `six`, they will be installed automatically:
+
 `pip3 install nd2reader` for Python 3.x
 
 `pip install nd2reader` for Python 2.x
 
-If you don't already have the packages `numpy` and `six`, they will be installed automatically.
+`nd2reader` is an order of magnitude faster in Python 3. I recommend using it unless you have no other choice.
 
 ### ND2s
 
@@ -27,38 +29,25 @@ A quick summary of ND2 metadata can be obtained as shown below.
 Created: 2014-11-11 15:59:19
 Image size: 1280x800 (HxW)
 Image cycles: 636
-Channels: '', 'GFP'
+Channels: 'brightfield', 'GFP'
 Fields of View: 8
 Z-Levels: 3
 ```
 
-You can also get some metadata about the nd2 programatically:
+You can iterate over each image in the order they were acquired:
 
 ```python
->>> nd2.height
-1280
->>> nd2.width
-800
->>> len(nd2)
-30528
-```
-
-`Nd2` is also a context manager, if you care about that sort of thing:
-
-```
->>> import nd2reader
->>> with nd2reader.Nd2("/path/to/my_images.nd2") as nd2:
-...     for image in nd2:
-...         do_something(image)
+import nd2reader
+nd2 = nd2reader.Nd2("/path/to/my_images.nd2")
+for image in nd2:
+    do_something(image)
 ```
 
-### Images
-
 `Image` objects are just Numpy arrays with some extra metadata bolted on:
 
 ```python
 >>> image = nd2[20]
->>> print(image)
+>>> image
 array([[1894, 1949, 1941, ..., 2104, 2135, 2114],
        [1825, 1846, 1848, ..., 1994, 2149, 2064],
        [1909, 1820, 1821, ..., 1995, 1952, 2062],
@@ -67,50 +56,50 @@ array([[1894, 1949, 1941, ..., 2104, 2135, 2114],
        [3642, 3475, 3525, ..., 3712, 3682, 3609],
        [3687, 3777, 3738, ..., 3784, 3870, 4008]], dtype=uint16)
 
->>> print(image.timestamp)
+>>> image.timestamp
 10.1241241248
->>> print(image.frame_number)
+>>> image.frame_number
 11
->>> print(image.field_of_view)
+>>> image.field_of_view
 6
->>> print(image.channel)
+>>> image.channel
 'GFP'
->>> print(image.z_level)
+>>> image.z_level
 0
 ```
 
-Often, you may want to just iterate over each image in the order they were acquired:
-
-```python
-import nd2reader
-nd2 = nd2reader.Nd2("/path/to/my_images.nd2")
-for image in nd2:
-    do_something(image)
-```
-
 Slicing is also supported and is extremely memory efficient, as images are only read when directly accessed:
 
 ```python
-my_subset = nd2[50:433]
-for image in my_subset:
+for image in nd2[50:433]:
     do_something(image)
-```
-
-Step sizes are also accepted:
 
-```python
+# get every other image in the first 100 images
 for image in nd2[:100:2]:
-    # gets every other image in the first 100 images
     do_something(image)
 
+# iterate backwards over every image
 for image in nd2[::-1]:
-    # iterate backwards over every image, if you're into that kind of thing
     do_something(image)
 ```
 
-### Protips
+You can also just index a single image:
+
+```python
+# gets the 18th image
+my_important_image = nd2[17] 
+```
+
+The `Nd2` object has some programmatically-accessible metadata: 
 
-nd2reader is about 14 times faster under Python 3.4 compared to Python 2.7. If you know why, please get in touch!
+```python
+>>> nd2.height
+1280
+>>> nd2.width
+800
+>>> len(nd2)
+30528
+```
 
 ### Bug Reports and Features