From a1704c53cbf3ca563a0c52f5f0ee5b84905478dc Mon Sep 17 00:00:00 2001 From: Jim Rybarski Date: Fri, 27 Nov 2015 10:51:13 -0600 Subject: [PATCH 1/4] made a few readme updates and clarified documentation --- README.md | 87 ++++++++++++++++++++++++++++--------------------------- 1 file changed, 44 insertions(+), 43 deletions(-) diff --git a/README.md b/README.md index 7932c8f..5ceb5ee 100644 --- a/README.md +++ b/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 @@ -22,17 +24,49 @@ A quick summary of ND2 metadata can be obtained as shown below. ```python >>> import nd2reader >>> nd2 = nd2reader.Nd2("/path/to/my_images.nd2") ->>> nd2 +>>> print(nd2) 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 +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: + do_something(image) + +# get every other image in the first 100 images +for image in nd2[:100:2]: + do_something(image) + +# iterate backwards over every image +for image in nd2[::-1]: + do_something(image) +``` + +You can also just index a single images: + +```python +# gets the 18th image +my_important_image = nd2[17] +``` + +The `Nd2` object has some useful metadata: ```python >>> nd2.height @@ -43,13 +77,13 @@ You can also get some metadata about the nd2 programatically: 30528 ``` -`Nd2` is also a context manager, if you care about that sort of thing: +It can also be used as a context manager: ``` ->>> import nd2reader ->>> with nd2reader.Nd2("/path/to/my_images.nd2") as nd2: -... for image in nd2: -... do_something(image) +import nd2reader +with nd2reader.Nd2("/path/to/my_images.nd2") as nd2: + for image in nd2: + do_something(image) ``` ### Images @@ -79,39 +113,6 @@ array([[1894, 1949, 1941, ..., 2104, 2135, 2114], 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: - do_something(image) -``` - -Step sizes are also accepted: - -```python -for image in nd2[:100:2]: - # gets every other image in the first 100 images - do_something(image) - -for image in nd2[::-1]: - # iterate backwards over every image, if you're into that kind of thing - do_something(image) -``` - -### Protips - -nd2reader is about 14 times faster under Python 3.4 compared to Python 2.7. If you know why, please get in touch! - ### Bug Reports and Features If this fails to work exactly as expected, please open a Github issue. If you get an unhandled exception, please From bd3725dc9b7b2db3cb15883af79fdf747d7ce526 Mon Sep 17 00:00:00 2001 From: Jim Rybarski Date: Fri, 27 Nov 2015 11:26:28 -0600 Subject: [PATCH 2/4] fixed some typos --- README.md | 15 ++------------- 1 file changed, 2 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 5ceb5ee..24f25ca 100644 --- a/README.md +++ b/README.md @@ -46,8 +46,7 @@ for image in nd2: 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) # get every other image in the first 100 images @@ -59,7 +58,7 @@ for image in nd2[::-1]: do_something(image) ``` -You can also just index a single images: +You can also just index a single image: ```python # gets the 18th image @@ -76,16 +75,6 @@ The `Nd2` object has some useful metadata: >>> len(nd2) 30528 ``` - -It can also be used as a context manager: - -``` -import nd2reader -with nd2reader.Nd2("/path/to/my_images.nd2") as nd2: - for image in nd2: - do_something(image) -``` - ### Images `Image` objects are just Numpy arrays with some extra metadata bolted on: From 852a26091c0cd7d47c82f674add0f398a243cd27 Mon Sep 17 00:00:00 2001 From: Jim Rybarski Date: Fri, 27 Nov 2015 11:47:58 -0600 Subject: [PATCH 3/4] reordered documentation --- README.md | 51 +++++++++++++++++++++++++-------------------------- 1 file changed, 25 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index 24f25ca..5a7d2e4 100644 --- a/README.md +++ b/README.md @@ -43,6 +43,31 @@ for image in nd2: do_something(image) ``` +`Image` objects are just Numpy arrays with some extra metadata bolted on: + +```python +>>> image = nd2[20] +>>> print(image) +array([[1894, 1949, 1941, ..., 2104, 2135, 2114], + [1825, 1846, 1848, ..., 1994, 2149, 2064], + [1909, 1820, 1821, ..., 1995, 1952, 2062], + ..., + [3487, 3512, 3594, ..., 3603, 3643, 3492], + [3642, 3475, 3525, ..., 3712, 3682, 3609], + [3687, 3777, 3738, ..., 3784, 3870, 4008]], dtype=uint16) + +>>> print(image.timestamp) +10.1241241248 +>>> print(image.frame_number) +11 +>>> print(image.field_of_view) +6 +>>> print(image.channel) +'GFP' +>>> print(image.z_level) +0 +``` + Slicing is also supported and is extremely memory efficient, as images are only read when directly accessed: ```python @@ -75,32 +100,6 @@ The `Nd2` object has some useful metadata: >>> len(nd2) 30528 ``` -### Images - -`Image` objects are just Numpy arrays with some extra metadata bolted on: - -```python ->>> image = nd2[20] ->>> print(image) -array([[1894, 1949, 1941, ..., 2104, 2135, 2114], - [1825, 1846, 1848, ..., 1994, 2149, 2064], - [1909, 1820, 1821, ..., 1995, 1952, 2062], - ..., - [3487, 3512, 3594, ..., 3603, 3643, 3492], - [3642, 3475, 3525, ..., 3712, 3682, 3609], - [3687, 3777, 3738, ..., 3784, 3870, 4008]], dtype=uint16) - ->>> print(image.timestamp) -10.1241241248 ->>> print(image.frame_number) -11 ->>> print(image.field_of_view) -6 ->>> print(image.channel) -'GFP' ->>> print(image.z_level) -0 -``` ### Bug Reports and Features From e016c8e321c53a848f5e338994be39197bdc55b8 Mon Sep 17 00:00:00 2001 From: Jim Rybarski Date: Fri, 27 Nov 2015 12:33:48 -0600 Subject: [PATCH 4/4] more consistent documentation --- README.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 5a7d2e4..5646de7 100644 --- a/README.md +++ b/README.md @@ -24,7 +24,7 @@ A quick summary of ND2 metadata can be obtained as shown below. ```python >>> import nd2reader >>> nd2 = nd2reader.Nd2("/path/to/my_images.nd2") ->>> print(nd2) +>>> nd2 Created: 2014-11-11 15:59:19 Image size: 1280x800 (HxW) @@ -47,7 +47,7 @@ for image in nd2: ```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], @@ -56,15 +56,15 @@ 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 ``` @@ -90,7 +90,7 @@ You can also just index a single image: my_important_image = nd2[17] ``` -The `Nd2` object has some useful metadata: +The `Nd2` object has some programmatically-accessible metadata: ```python >>> nd2.height