You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

123 lines
3.4 KiB

10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
  1. # nd2reader
  2. ### About
  3. `nd2reader` is a pure-Python package that reads images produced by NIS Elements.
  4. .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.
  5. `nd2reader` produces data in numpy arrays, which makes it trivial to use with the image analysis packages such as `scikit-image` and `OpenCV`.
  6. ### Installation
  7. Just use pip (`numpy` is required):
  8. `pip install numpy nd2reader`
  9. If you want to install via git, clone the repo and run:
  10. ```
  11. pip install numpy
  12. python setup.py install
  13. ```
  14. ### ND2s
  15. A quick summary of ND2 metadata can be obtained as shown below.
  16. ```python
  17. >>> import nd2reader
  18. >>> nd2 = nd2reader.Nd2("/path/to/my_images.nd2")
  19. >>> nd2
  20. <ND2 /path/to/my_images.nd2>
  21. Created: 2014-11-11 15:59:19
  22. Image size: 1280x800 (HxW)
  23. Image cycles: 636
  24. Channels: '', 'GFP'
  25. Fields of View: 8
  26. Z-Levels: 3
  27. ```
  28. ### Simple Iteration
  29. For most cases, you'll just want to iterate over each image:
  30. ```python
  31. import nd2reader
  32. nd2 = nd2reader.Nd2("/path/to/my_images.nd2")
  33. for image in nd2:
  34. do_something(image.data)
  35. ```
  36. ### Image Sets
  37. If you have complicated hierarchical data, it may be easier to use image sets, which groups images together if they
  38. share the same time index and field of view:
  39. ```python
  40. import nd2reader
  41. nd2 = nd2reader.Nd2("/path/to/my_complicated_images.nd2")
  42. for image_set in nd2.image_sets:
  43. # you can select images by channel
  44. gfp_image = image_set.get("GFP")
  45. do_something_gfp_related(gfp_image)
  46. # you can also specify the z-level. this defaults to 0 if not given
  47. out_of_focus_image = image_set.get("Bright Field", z_level=1)
  48. do_something_out_of_focus_related(out_of_focus_image)
  49. ```
  50. ### Direct Image Access
  51. There is a method, `get_image`, which allows random access to images. This might not always return an image, however,
  52. if you acquired different numbers of images in each cycle of a program. For example, if you acquire GFP images every
  53. other minute, but acquire bright field images every minute, `get_image` will return `None` at certain time indexes.
  54. ### Images
  55. `Image` objects provide several pieces of useful data.
  56. ```python
  57. >>> import nd2reader
  58. >>> nd2 = nd2reader.Nd2("/path/to/my_images.nd2")
  59. >>> image = nd2.get_image(14, 2, "GFP", 1)
  60. >>> image.data
  61. array([[1809, 1783, 1830, ..., 1923, 1920, 1914],
  62. [1687, 1855, 1792, ..., 1986, 1903, 1889],
  63. [1758, 1901, 1849, ..., 1911, 2010, 1954],
  64. ...,
  65. [3363, 3370, 3570, ..., 3565, 3601, 3459],
  66. [3480, 3428, 3328, ..., 3542, 3461, 3575],
  67. [3497, 3666, 3635, ..., 3817, 3867, 3779]])
  68. >>> image.channel
  69. 'GFP'
  70. >>> image.timestamp
  71. 1699.7947813408175
  72. >>> image.field_of_view
  73. 2
  74. >>> image.z_level
  75. 1
  76. # You can also get a quick summary of image data:
  77. >>> image
  78. <ND2 Image>
  79. 1280x800 (HxW)
  80. Timestamp: 1699.79478134
  81. Field of View: 2
  82. Channel: GFP
  83. Z-Level: 1
  84. ```
  85. ### Bug Reports and Features
  86. If this fails to work exactly as expected, please open a Github issue. If you get an unhandled exception, please
  87. paste the entire stack trace into the issue as well.
  88. ### Contributing
  89. Please feel free to submit a pull request with any new features you think would be useful. You can also create an
  90. issue if you'd just like to propose or discuss a potential idea.
  91. ### Acknowledgments
  92. Support for the development of this package was provided by the [Finkelstein Laboratory](http://finkelsteinlab.org/).