Browse Source

made a few readme updates and clarified documentation

zolfa-add_slices_loading
Jim Rybarski 9 years ago
parent
commit
a1704c53cb
1 changed files with 44 additions and 43 deletions
  1. +44
    -43
      README.md

+ 44
- 43
README.md View File

@ -2,7 +2,7 @@
### About ### 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. .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 ### Installation
If you don't already have the packages `numpy` and `six`, they will be installed automatically:
`pip3 install nd2reader` for Python 3.x `pip3 install nd2reader` for Python 3.x
`pip install nd2reader` for Python 2.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 ### ND2s
@ -22,17 +24,49 @@ A quick summary of ND2 metadata can be obtained as shown below.
```python ```python
>>> import nd2reader >>> import nd2reader
>>> nd2 = nd2reader.Nd2("/path/to/my_images.nd2") >>> nd2 = nd2reader.Nd2("/path/to/my_images.nd2")
>>> nd2
>>> print(nd2)
<ND2 /path/to/my_images.nd2> <ND2 /path/to/my_images.nd2>
Created: 2014-11-11 15:59:19 Created: 2014-11-11 15:59:19
Image size: 1280x800 (HxW) Image size: 1280x800 (HxW)
Image cycles: 636 Image cycles: 636
Channels: '', 'GFP'
Channels: 'brightfield', 'GFP'
Fields of View: 8 Fields of View: 8
Z-Levels: 3 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 ```python
>>> nd2.height >>> nd2.height
@ -43,13 +77,13 @@ You can also get some metadata about the nd2 programatically:
30528 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 ### Images
@ -79,39 +113,6 @@ array([[1894, 1949, 1941, ..., 2104, 2135, 2114],
0 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 ### Bug Reports and Features
If this fails to work exactly as expected, please open a Github issue. If you get an unhandled exception, please If this fails to work exactly as expected, please open a Github issue. If you get an unhandled exception, please


Loading…
Cancel
Save