Merge pull request #33 from jimrybarski/27-write-good-readme

27 write good readme

README.md

@@ -1,20 +1,116 @@
-nd2reader
-=========
+# nd2reader
 
-## Simple access to hierarchical .nd2 files 
+### About
 
-# About
+`nd2reader` is a pure-Python package that reads images produced by NIS Elements.
 
-`nd2reader` is a pure-Python package that reads images produced by Nikon microscopes. Though it more or less works, it is currently under development and is not quite ready for use by the general public. Version 1.0 should be released in early 2015.
+.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.
 
-.nd2 files contain images and metadata, which can be split along multiple dimensions: time, fields of view (xy-axis), focus (z-axis), and filter channel. `nd2reader` allows you to view any subset of images based on any or all of these dimensions.
+`nd2reader` produces data in numpy arrays, which makes it trivial to use with the image analysis packages such as `scikit-image` and `OpenCV`.
 
-`nd2reader` holds data in numpy arrays, which makes it trivial to use with the image analysis packages `scikit-image` and `OpenCV`.
+### Installation
 
-# Dependencies
+Just use pip:
 
-numpy 
+`pip install nd2reader`
 
-# Installation
+If you want to install via git, clone the repo and run:
 
-I'll write this eventually.
+`python setup.py install`
+
+### ND2s
+
+A quick summary of ND2 metadata can be obtained as shown below.
+```python
+>>> import nd2reader
+>>> nd2 = nd2reader.Nd2("/path/to/my_images.nd2")
+>>> nd2
+<ND2 /path/to/my_images.nd2>
+Created: 2014-11-11 15:59:19
+Image size: 1280x800 (HxW)
+Image cycles: 636
+Channels: '', 'GFP'
+Fields of View: 8
+Z-Levels: 3
+```
+
+### Simple Iteration
+
+For most cases, you'll just want to iterate over each image:
+
+```python
+import nd2reader
+nd2 = nd2reader.Nd2("/path/to/my_images.nd2")
+for image in nd2:
+    do_something(image.data)
+```
+
+### Image Sets
+
+If you have complicated hierarchical data, it may be easier to use image sets, which groups images together if they
+share the same time index and field of view:
+
+```python
+import nd2reader
+nd2 = nd2reader.Nd2("/path/to/my_complicated_images.nd2")
+for image_set in nd2.image_sets:
+    # you can select images by channel
+    gfp_image = image_set.get("GFP")
+    do_something_gfp_related(gfp_image)
+
+    # you can also specify the z-level. this defaults to 0 if not given
+    out_of_focus_image = image_set.get("Bright Field", z_level=1)
+    do_something_out_of_focus_related(out_of_focus_image)
+```
+
+### Direct Image Access
+
+There is a method, `get_image`, which allows random access to images. This might not always return an image, however,
+if you acquired different numbers of images in each cycle of a program. For example, if you acquire GFP images every
+other minute, but acquire bright field images every minute, `get_image` will return `None` at certain time indexes.
+
+### Images
+
+`Image` objects provide several pieces of useful data.
+
+```python
+>>> import nd2reader
+>>> nd2 = nd2reader.Nd2("/path/to/my_images.nd2")
+>>> image = nd2.get_image(14, 2, "GFP", 1)
+>>> image.data
+array([[1809, 1783, 1830, ..., 1923, 1920, 1914],
+       [1687, 1855, 1792, ..., 1986, 1903, 1889],
+       [1758, 1901, 1849, ..., 1911, 2010, 1954],
+       ...,
+       [3363, 3370, 3570, ..., 3565, 3601, 3459],
+       [3480, 3428, 3328, ..., 3542, 3461, 3575],
+       [3497, 3666, 3635, ..., 3817, 3867, 3779]])
+>>> image.channel
+'GFP'
+>>> image.timestamp
+1699.7947813408175
+>>> image.field_of_view
+2
+>>> image.z_level
+1
+
+# You can also get a quick summary of image data:
+
+>>> image
+<ND2 Image>
+1280x800 (HxW)
+Timestamp: 1699.79478134
+Field of View: 2
+Channel: GFP
+Z-Level: 1
+```
+
+### Bug Reports and Features
+
+If this fails to work exactly as expected, please open a Github issue. If you get an unhandled exception, please
+paste the entire stack trace into the issue as well.
+
+### Contributing
+
+Please feel free to submit a pull request with any new features you think would be useful. You can also create an
+issue if you'd just like to propose or discuss a potential idea.