From c9b6bc2d890b62889f78e2e8563b314aa9172fc6 Mon Sep 17 00:00:00 2001 From: jim Date: Fri, 9 Oct 2015 19:00:44 -0500 Subject: [PATCH 1/2] resolves #87 --- CHANGELOG.md | 2 +- README.md | 94 ++++++++++------------------------------------------ setup.py | 2 +- 3 files changed, 20 insertions(+), 78 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 7607c2f..0217c26 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,4 +1,4 @@ -## [1.1.2] - 2015-10-09 +## [2.0.0] - 2015-10-09 ### CHANGED - `Image` objects now directly subclass Numpy arrays, so the `data` attribute is no longer needed (and has been removed). - Refactored code to permit parsing of different versions of ND2s, which will allow us to add support for NIS Elements 3.x. diff --git a/README.md b/README.md index 3b831e8..83cbd6b 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ .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 such as `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 @@ -54,13 +54,11 @@ You can also get some metadata about the nd2 programatically: ### Images -Every method returns an `Image` object, which contains some metadata about the image as well as the -raw pixel data itself. Images are always a 16-bit grayscale image. The `data` attribute holds the numpy array -with the image data: +`Image` objects are just Numpy arrays with some extra metadata bolted on: ```python >>> image = nd2[20] ->>> print(image.data) +>>> print(image) array([[1894, 1949, 1941, ..., 2104, 2135, 2114], [1825, 1846, 1848, ..., 1994, 2149, 2064], [1909, 1820, 1821, ..., 1995, 1952, 2062], @@ -68,49 +66,26 @@ array([[1894, 1949, 1941, ..., 2104, 2135, 2114], [3487, 3512, 3594, ..., 3603, 3643, 3492], [3642, 3475, 3525, ..., 3712, 3682, 3609], [3687, 3777, 3738, ..., 3784, 3870, 4008]], dtype=uint16) -``` - -You can get a quick summary of image data by examining the `Image` object: -```python ->>> image - -1280x800 (HxW) -Timestamp: 1699.79478134 -Field of View: 2 -Channel: GFP -Z-Level: 1 -``` - -Or you can access it programmatically: - -```python -image = nd2[0] -print(image.timestamp) -print(image.field_of_view) -print(image.channel) -print(image.z_level) +>>> 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 ``` -Often, you may want to just iterate over each image: +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.data) -``` - -You can also get an image directly by indexing. Here, we look at the 38th image: - -```python ->>> nd2[37] - -1280x800 (HxW) -Timestamp: 1699.79478134 -Field of View: 2 -Channel: GFP -Z-Level: 1 + do_something(image) ``` Slicing is also supported and is extremely memory efficient, as images are only read when directly accessed: @@ -118,7 +93,7 @@ Slicing is also supported and is extremely memory efficient, as images are only ```python my_subset = nd2[50:433] for image in my_subset: - do_something(image.data) + do_something(image) ``` Step sizes are also accepted: @@ -126,44 +101,11 @@ Step sizes are also accepted: ```python for image in nd2[:100:2]: # gets every other image in the first 100 images - do_something(image.data) + do_something(image) for image in nd2[::-1]: # iterate backwards over every image, if you're into that kind of thing - 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 (not timestamp!) 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.data) - - # 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.data) -``` - -To get an image from an image set, you must specify a channel. It defaults to the 0th z-level, so if you have -more than one z-level you will need to specify it when using `get`: - -```python -image = image_set.get("YFP") -image = image_set.get("YFP", z_level=2) -``` - -You can also see how many images are in your image set: - -```python ->>> len(image_set) -7 + do_something(image) ``` ### Protips diff --git a/setup.py b/setup.py index ee1b087..7de9875 100644 --- a/setup.py +++ b/setup.py @@ -1,6 +1,6 @@ from setuptools import setup -VERSION = "1.1.0" +VERSION = "2.0.0" setup( name="nd2reader", From d213ff64e53ef011a8a1f31046daea03ef712b8f Mon Sep 17 00:00:00 2001 From: jim Date: Fri, 9 Oct 2015 19:03:21 -0500 Subject: [PATCH 2/2] reverted to 1.1.2 --- CHANGELOG.md | 5 +++-- setup.py | 2 +- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0217c26..cfce502 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,9 +1,10 @@ -## [2.0.0] - 2015-10-09 +## [1.1.2] - 2015-10-09 ### CHANGED -- `Image` objects now directly subclass Numpy arrays, so the `data` attribute is no longer needed (and has been removed). +- `Image` objects now directly subclass Numpy arrays. - Refactored code to permit parsing of different versions of ND2s, which will allow us to add support for NIS Elements 3.x. ### DEPRECATED +- The `data` attribute is no longer needed since `Image` is now a Numpy array. - The `image_sets` iterator will be removed in the near future. You should implement this yourself. ## [1.1.1] - 2015-09-02 diff --git a/setup.py b/setup.py index 7de9875..d5feeaa 100644 --- a/setup.py +++ b/setup.py @@ -1,6 +1,6 @@ from setuptools import setup -VERSION = "2.0.0" +VERSION = "1.1.2" setup( name="nd2reader",