[](https://github.com/wimpomp/ndbioimage/actions/workflows/pytest.yml)
# ndbioimage
Exposes (bio) images as a numpy ndarray-like object, but without loading the whole
image into memory, reading from the file only when needed. Some metadata is read
and stored in an [ome](https://genomebiology.biomedcentral.com/articles/10.1186/gb-2005-6-5-r47) structure.
Additionally, it can automatically calculate an affine transform that corrects for chromatic aberrations etc. and apply
it on the fly to the image.
Currently, it supports imagej tif files, czi files, micromanager tif sequences and anything
[bioformats](https://www.openmicroscopy.org/bio-formats/) can handle.
## Installation
```
pip install ndbioimage
```
### Installation with option to write mp4 or mkv:
Work in progress! Make sure ffmpeg is installed.
```
pip install ndbioimage[write]
```
## Usage
### Python
- Reading an image file and plotting the frame at channel=2, time=1
```
import matplotlib.pyplot as plt
from ndbioimage import Imread
with Imread('image_file.tif', axes='ctyx', dtype=int) as im:
plt.imshow(im[2, 1])
```
- Showing some image metadata
```
from ndbioimage import Imread
from pprint import pprint
with Imread('image_file.tif') as im:
pprint(im)
```
- Slicing the image without loading the image into memory
```
from ndbioimage import Imread
with Imread('image_file.tif', axes='cztyx') as im:
sliced_im = im[1, :, :, 100:200, 100:200]
```
sliced_im is an instance of Imread which will load any image data from file only when needed
- Converting (part) of the image to a numpy ndarray
```
from ndbioimage import Imread
import numpy as np
with Imread('image_file.tif', axes='cztyx') as im:
array = np.asarray(im[0, 0])
```
### Command line
```ndbioimage --help```: show help
```ndbioimage image```: show metadata about image
```ndbioimage image {name}.tif -r```: copy image into image.tif (replacing {name} with image), while registering channels
```ndbioimage image image.mp4 -C cyan lime red``` copy image into image.mp4 (z will be max projected), make channel colors cyan lime and red
## Adding more formats
Readers for image formats subclass AbstractReader. When an image reader is imported, Imread will
automatically recognize it and use it to open the appropriate file format. Image readers
are required to implement the following methods:
- staticmethod _can_open(path): return True if path can be opened by this reader
- \_\_frame__(self, c, z, t): return the frame at channel=c, z-slice=z, time=t from the file
Optional methods:
- get_ome: reads metadata from file and adds them to an OME object imported
from the ome-types library
- open(self): maybe open some file handle
- close(self): close any file handles
Optional fields:
- priority (int): Imread will try readers with a lower number first, default: 99
- do_not_pickle (strings): any attributes that should not be included when the object is pickled,
for example: any file handles
# TODO
- more image formats
Raw data
{
"_id": null,
"home_page": "https://github.com/wimpomp/ndbioimage",
"name": "ndbioimage",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": null,
"keywords": "bioformats, imread, numpy, metadata",
"author": "W. Pomp",
"author_email": "w.pomp@nki.nl",
"download_url": "https://files.pythonhosted.org/packages/fd/80/de26b14568453a0a5f4c07b4dd8cee49c6cacc4d3526c8751722c733474f/ndbioimage-2024.10.0.tar.gz",
"platform": null,
"description": "[](https://github.com/wimpomp/ndbioimage/actions/workflows/pytest.yml)\n\n# ndbioimage\n\nExposes (bio) images as a numpy ndarray-like object, but without loading the whole\nimage into memory, reading from the file only when needed. Some metadata is read\nand stored in an [ome](https://genomebiology.biomedcentral.com/articles/10.1186/gb-2005-6-5-r47) structure.\nAdditionally, it can automatically calculate an affine transform that corrects for chromatic aberrations etc. and apply\nit on the fly to the image.\n\nCurrently, it supports imagej tif files, czi files, micromanager tif sequences and anything\n[bioformats](https://www.openmicroscopy.org/bio-formats/) can handle. \n\n## Installation\n\n```\npip install ndbioimage\n```\n\n### Installation with option to write mp4 or mkv:\nWork in progress! Make sure ffmpeg is installed.\n\n```\npip install ndbioimage[write]\n```\n\n## Usage\n### Python\n\n- Reading an image file and plotting the frame at channel=2, time=1\n\n```\nimport matplotlib.pyplot as plt\nfrom ndbioimage import Imread\nwith Imread('image_file.tif', axes='ctyx', dtype=int) as im:\n plt.imshow(im[2, 1])\n``` \n \n- Showing some image metadata\n\n```\nfrom ndbioimage import Imread\nfrom pprint import pprint\nwith Imread('image_file.tif') as im:\n pprint(im)\n```\n\n- Slicing the image without loading the image into memory\n\n```\nfrom ndbioimage import Imread\nwith Imread('image_file.tif', axes='cztyx') as im:\n sliced_im = im[1, :, :, 100:200, 100:200]\n```\n\nsliced_im is an instance of Imread which will load any image data from file only when needed\n\n\n- Converting (part) of the image to a numpy ndarray\n\n```\nfrom ndbioimage import Imread\nimport numpy as np\nwith Imread('image_file.tif', axes='cztyx') as im:\n array = np.asarray(im[0, 0])\n```\n\n### Command line\n```ndbioimage --help```: show help \n```ndbioimage image```: show metadata about image \n```ndbioimage image {name}.tif -r```: copy image into image.tif (replacing {name} with image), while registering channels \n```ndbioimage image image.mp4 -C cyan lime red``` copy image into image.mp4 (z will be max projected), make channel colors cyan lime and red\n\n## Adding more formats\nReaders for image formats subclass AbstractReader. When an image reader is imported, Imread will\nautomatically recognize it and use it to open the appropriate file format. Image readers\nare required to implement the following methods:\n\n- staticmethod _can_open(path): return True if path can be opened by this reader\n- \\_\\_frame__(self, c, z, t): return the frame at channel=c, z-slice=z, time=t from the file\n\nOptional methods:\n- get_ome: reads metadata from file and adds them to an OME object imported\nfrom the ome-types library \n- open(self): maybe open some file handle\n- close(self): close any file handles\n\nOptional fields:\n- priority (int): Imread will try readers with a lower number first, default: 99\n- do_not_pickle (strings): any attributes that should not be included when the object is pickled,\nfor example: any file handles\n\n# TODO\n- more image formats\n\n",
"bugtrack_url": null,
"license": "GPLv3",
"summary": "Bio image reading, metadata and some affine registration.",
"version": "2024.10.0",
"project_urls": {
"Homepage": "https://github.com/wimpomp/ndbioimage",
"Repository": "https://github.com/wimpomp/ndbioimage"
},
"split_keywords": [
"bioformats",
" imread",
" numpy",
" metadata"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ab74d92909240ee6fae997331a4567722476d9d2760a77f1f472bff293de69c9",
"md5": "d7bd77d66ae5d0724c0194904c66f508",
"sha256": "187ab5bdde60c8958f02678682e5424db9a2a6e1b8785c498f6674888fb55430"
},
"downloads": -1,
"filename": "ndbioimage-2024.10.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d7bd77d66ae5d0724c0194904c66f508",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 52240,
"upload_time": "2024-10-17T15:18:56",
"upload_time_iso_8601": "2024-10-17T15:18:56.864876Z",
"url": "https://files.pythonhosted.org/packages/ab/74/d92909240ee6fae997331a4567722476d9d2760a77f1f472bff293de69c9/ndbioimage-2024.10.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "fd80de26b14568453a0a5f4c07b4dd8cee49c6cacc4d3526c8751722c733474f",
"md5": "00600ab9d61d933b12aa4dad3e9eda73",
"sha256": "d3551c9bfdd6316e3b11876ce205604bf5d6d52ad6ec3af6d7ea1d9755bf1359"
},
"downloads": -1,
"filename": "ndbioimage-2024.10.0.tar.gz",
"has_sig": false,
"md5_digest": "00600ab9d61d933b12aa4dad3e9eda73",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 47707,
"upload_time": "2024-10-17T15:18:58",
"upload_time_iso_8601": "2024-10-17T15:18:58.662144Z",
"url": "https://files.pythonhosted.org/packages/fd/80/de26b14568453a0a5f4c07b4dd8cee49c6cacc4d3526c8751722c733474f/ndbioimage-2024.10.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-17 15:18:58",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "wimpomp",
"github_project": "ndbioimage",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "ndbioimage"
}
JSON
