From b4c01b7c8a70844ffed42b2358ffe6ea1e2786cc Mon Sep 17 00:00:00 2001 From: Jim Rybarski Date: Sat, 23 May 2015 18:20:22 +0000 Subject: [PATCH 1/6] #27 began writing tutorial --- README.md | 86 ++++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 75 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 8d3f555..c7c8213 100644 --- a/README.md +++ b/README.md @@ -1,20 +1,84 @@ -nd2reader -========= +# nd2reader -## Simple access to hierarchical .nd2 files +## Simple access to .nd2 files -# About +### About -`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. +`nd2reader` is a pure-Python package that reads images produced by NIS Elements. -.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. +.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. -`nd2reader` holds data in numpy arrays, which makes it trivial to use with the image analysis packages `scikit-image` and `OpenCV`. +`nd2reader` produces data in numpy arrays, which makes it trivial to use with the image analysis packages `scikit-image` and `OpenCV`. -# Dependencies +### Installation -numpy +Just use pip: -# Installation +`pip install nd2reader` -I'll write this eventually. +If you want to install via git, clone the repo and run: + +`python setup.py install` + +### Usage + +nd2reader provides two main ways to view image data. For most cases, you'll just want to iterate over each image: + +``` +import nd2reader +nd2 = nd2reader.Nd2("/path/to/my_images.nd2") +for image in nd2: + do_something(image.data) +``` + +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: + +``` +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) +``` + +`Image` objects provide several pieces of useful data. + +``` +>>> 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 + +1280x800 (HxW) +Timestamp: 1699.79478134 +Field of View: 2 +Channel: GFP +Z-Level: 1 +``` \ No newline at end of file From ae06dca96c5614278fe8ed017d63a071775178d5 Mon Sep 17 00:00:00 2001 From: Jim Rybarski Date: Sat, 23 May 2015 18:32:27 +0000 Subject: [PATCH 2/6] #27 better instructions --- README.md | 20 ++++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index c7c8213..709db26 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,12 @@ # nd2reader -## Simple access to .nd2 files - ### About `nd2reader` is a pure-Python package that reads images produced by NIS Elements. .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. -`nd2reader` produces data in numpy arrays, which makes it trivial to use with the image analysis packages `scikit-image` and `OpenCV`. +`nd2reader` produces data in numpy arrays, which makes it trivial to use with the image analysis packages such as `scikit-image` and `OpenCV`. ### Installation @@ -20,9 +18,9 @@ If you want to install via git, clone the repo and run: `python setup.py install` -### Usage +### Simple Iteration -nd2reader provides two main ways to view image data. For most cases, you'll just want to iterate over each image: +For most cases, you'll just want to iterate over each image: ``` import nd2reader @@ -31,10 +29,12 @@ 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: @@ -47,6 +47,14 @@ for image_set in nd2.image_sets: 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. ``` From 1daac4a2d9a7f535f8eb7bf914ec5931fcc2ce87 Mon Sep 17 00:00:00 2001 From: Jim Rybarski Date: Sat, 23 May 2015 18:33:53 +0000 Subject: [PATCH 3/6] #27 syntax highlighting --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 709db26..9f7532c 100644 --- a/README.md +++ b/README.md @@ -22,7 +22,7 @@ If you want to install via git, clone the repo and run: 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: @@ -57,7 +57,7 @@ other minute, but acquire bright field images every minute, `get_image` will ret `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) @@ -81,7 +81,7 @@ array([[1809, 1783, 1830, ..., 1923, 1920, 1914], You can also get a quick summary of image data. -``` +```python >>> image 1280x800 (HxW) From b182e4a02318c3d7041a0881dd7644587f240970 Mon Sep 17 00:00:00 2001 From: Jim Rybarski Date: Sat, 23 May 2015 18:37:31 +0000 Subject: [PATCH 4/6] #27 more sensible example --- README.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/README.md b/README.md index 9f7532c..afad4e8 100644 --- a/README.md +++ b/README.md @@ -77,11 +77,9 @@ array([[1809, 1783, 1830, ..., 1923, 1920, 1914], 2 >>> image.z_level 1 -``` -You can also get a quick summary of image data. +# You can also get a quick summary of image data: -```python >>> image 1280x800 (HxW) From c3d659cfd3d2c9f2883da31ee609cb326091c51f Mon Sep 17 00:00:00 2001 From: Jim Rybarski Date: Sat, 23 May 2015 18:51:08 +0000 Subject: [PATCH 5/6] #27 added contribution instructions --- README.md | 27 ++++++++++++++++++++++++++- 1 file changed, 26 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index afad4e8..1db47a8 100644 --- a/README.md +++ b/README.md @@ -18,6 +18,21 @@ If you want to install via git, clone the repo and run: `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 + +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: @@ -87,4 +102,14 @@ Timestamp: 1699.79478134 Field of View: 2 Channel: GFP Z-Level: 1 -``` \ No newline at end of file +``` + +### 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. \ No newline at end of file From 5791d5fc808a8664a9b9c4a321296bfea8d59032 Mon Sep 17 00:00:00 2001 From: Jim Rybarski Date: Sat, 23 May 2015 18:52:07 +0000 Subject: [PATCH 6/6] #27 fixed formatting error --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index 1db47a8..d001757 100644 --- a/README.md +++ b/README.md @@ -32,6 +32,7 @@ Image cycles: 636 Channels: '', 'GFP' Fields of View: 8 Z-Levels: 3 +``` ### Simple Iteration