# *opentile*
*opentile* is a Python library for reading tiles from wsi tiff files. The aims of the proect are:
- Allow compressed tiles to be losslessly read from wsi tiffs using 2D coordinates (tile position x, y).
- Provide unified interface for relevant metadata.
- Support all file formats supported by tifffile that has a non-overlapping tile structure.
*opentile* does `not` provide methods for reading regions from images (e.g. `get_region()`). See [openslide-python](https://github.com/openslide/openslide-python), [tiffslide](https://github.com/bayer-science-for-a-better-life/tiffslide), or [wsidicomizer](https://github.com/imi-bigpicture/wsidicomizer) for such use.
Currently implemented file formats are listed and described under *Implemented file formats*.
## Installing *opentile*
*opentile* is available on PyPI:
```console
pip install opentile
```
Alternatively, it can be installed via conda:
```console
conda install -c conda-forge opentile
```
## Important note
Please note that this is an early release and the API is not frozen yet. Function names and functionality is prone to change.
## Requirements
*opentile* requires python >=3.8 and uses numpy, Pillow, TiffFile, and PyTurboJPEG (with lib-turbojpeg >= 2.1 ), imagecodecs, defusedxml, and ome-types.
## Limitations
Files with z-stacks are currently not fully supported for all formats.
## Implemented file formats
The following description of the workings of the implemented file formats does not include the additional specifics for each format that is handled by tifffile. Additional formats supported by tifffile and that have non-overlapping tile layout are likely to be added in future release.
***Hamamatsu Ndpi***
The Ndpi-format uses non-rectangular tile size typically 8 pixels high, i.e. stripes. To form tiles, first multiple stripes are concatenated to form a frame covering the tile region. Second, if the stripes are longer than the tile width, the tile is croped out of the frame. The concatenation and crop transformations are performed losslessly.
A ndpi-file can also contain non-tiled images. If these are part of a pyramidal series, *opentile* tiles the image.
The macro page in ndpi-files images the whole slide including label. A label and overview is created by cropping the macro image.
***Philips tiff***
The Philips tiff-format allows tiles to be sparse, i.e. missing. For such tiles, *opentile* instead provides a blank (currently white) tile image using the same jpeg header as the rest of the image.
***Aperio svs***
Some Asperio svs-files have corrupt tile data at edges of non-base pyramidal levels. This is observed as tiles with 0-byte length and tiles with incorrect pixel data. *opentile* detects such corruption and instead returns downscaled image data from lower levels. Associated images (label, overview) are currently not handled correctly.
***3DHistech tiff***
Only the pyramidal levels are supported (not overviews or labels).
***OME tiff***
Metadata parsing is not yet implemented.
## Metadata
File metadata can be accessed through the `metadata`-property of a tiler. Depending on file format and content, the following metadata is available:
- Magnification
- Scanner manufacturer
- Scanner model
- Scanner software versions
- Scanner serial number
- Acquisition datetime
## Basic usage
***Load a Ndpi-file using tile size (1024, 1024) pixels.***
```python
from opentile import OpenTile
tile_size = (1024, 1024)
tiler = OpenTile.open(path_to_ndpi_file, tile_size)
```
***Load a file using fsspec and with some file options.***
```python
from opentile import OpenTile
tiler = OpenTile.open("s3://bucket/key", file_options={"s3": "anon": True})
```
***If turbo jpeg library path is not found.***
```python
from opentile import OpenTile
tile_size = (1024, 1024)
turbo_path = 'C:/libjpeg-turbo64/bin/turbojpeg.dll'
tiler = OpenTile.open(path_to_ndpi_file, tile_size, turbo_path)
```
***Get rectangular tile at level 0 and position x=0, y=0.***
```python
level = tiler.get_evel(0)
tile = level.get_tile((0, 0))
```
***Close the tiler object.***
```python
tiler.close()
```
***Usage as context manager***
The tiler can also be used as context manager:
```python
from opentile import OpenTile
tile_size = (1024, 1024)
with OpenTile.open(path_to_ndpi_file, tile_size) as tiler:
level = tiler.get_evel(0)
tile = level.get_tile((0, 0))
```
## Setup environment for development
Requires poetry and pytest and pytest-watch installed in the virtual environment.
```console
git clone https://github.com/imi-bigpicture/opentile.git
poetry install
```
By default the tests looks for slides in 'tests/testdata'. This can be overridden by setting the OPENTILE_TESTDIR environment variable. The script 'tests/download_test_images.py' can be used to download publicly available [openslide testdata](https://openslide.cs.cmu.edu/download/openslide-testdata/) into the set testdata folder:
```console
python tests/download_test_images.py
```
The test data used for philips tiff is currently not publicly available as we dont have permission to share them. If you have slides in philips tiff format that can be freely shared we would be happy to use them instead.
To watch unit tests use:
```console
poetry run pytest-watch -- -m unittest
```
## Other TIFF python tools
- [tifffile](https://github.com/cgohlke/tifffile)
- [tiffslide](https://github.com/bayer-science-for-a-better-life/tiffslide)
## Contributing
We welcome any contributions to help improve this tool for the WSI community!
We recommend first creating an issue before creating potential contributions to check that the contribution is in line with the goals of the project. To submit your contribution, please issue a pull request on the imi-bigpicture/opentile repository with your changes for review.
Our aim is to provide constructive and positive code reviews for all submissions. The project relies on gradual typing and roughly follows PEP8. However, we are not dogmatic. Most important is that the code is easy to read and understand.
## Acknowledgement
*opentile*: Copyright 2021-2024 Sectra AB, licensed under Apache 2.0.
This project is part of a project that has received funding from the Innovative Medicines Initiative 2 Joint Undertaking under grant agreement No 945358. This Joint Undertaking receives support from the European Union’s Horizon 2020 research and innovation programme and EFPIA. IMI website: www.imi.europa.eu
Raw data
{
"_id": null,
"home_page": "https://github.com/imi-bigpicture/opentile",
"name": "opentile",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.9",
"maintainer_email": null,
"keywords": "whole slide image, digital pathology, tiff",
"author": "Erik O Gabrielsson",
"author_email": "erik.o.gabrielsson@sectra.com",
"download_url": "https://files.pythonhosted.org/packages/97/6f/fb2527e3bdd0027a7dc268bab8e3f2554cf8e2b610b54aa8a59041a82f01/opentile-0.13.4.tar.gz",
"platform": null,
"description": "# *opentile*\n\n*opentile* is a Python library for reading tiles from wsi tiff files. The aims of the proect are:\n\n- Allow compressed tiles to be losslessly read from wsi tiffs using 2D coordinates (tile position x, y).\n- Provide unified interface for relevant metadata.\n- Support all file formats supported by tifffile that has a non-overlapping tile structure.\n\n*opentile* does `not` provide methods for reading regions from images (e.g. `get_region()`). See [openslide-python](https://github.com/openslide/openslide-python), [tiffslide](https://github.com/bayer-science-for-a-better-life/tiffslide), or [wsidicomizer](https://github.com/imi-bigpicture/wsidicomizer) for such use.\n\nCurrently implemented file formats are listed and described under *Implemented file formats*.\n\n## Installing *opentile*\n\n*opentile* is available on PyPI:\n\n```console\npip install opentile\n```\n\nAlternatively, it can be installed via conda:\n\n```console\nconda install -c conda-forge opentile\n```\n\n## Important note\n\nPlease note that this is an early release and the API is not frozen yet. Function names and functionality is prone to change.\n\n## Requirements\n\n*opentile* requires python >=3.8 and uses numpy, Pillow, TiffFile, and PyTurboJPEG (with lib-turbojpeg >= 2.1 ), imagecodecs, defusedxml, and ome-types.\n\n## Limitations\n\nFiles with z-stacks are currently not fully supported for all formats.\n\n## Implemented file formats\n\nThe following description of the workings of the implemented file formats does not include the additional specifics for each format that is handled by tifffile. Additional formats supported by tifffile and that have non-overlapping tile layout are likely to be added in future release.\n\n***Hamamatsu Ndpi***\nThe Ndpi-format uses non-rectangular tile size typically 8 pixels high, i.e. stripes. To form tiles, first multiple stripes are concatenated to form a frame covering the tile region. Second, if the stripes are longer than the tile width, the tile is croped out of the frame. The concatenation and crop transformations are performed losslessly.\n\nA ndpi-file can also contain non-tiled images. If these are part of a pyramidal series, *opentile* tiles the image.\n\nThe macro page in ndpi-files images the whole slide including label. A label and overview is created by cropping the macro image.\n\n***Philips tiff***\nThe Philips tiff-format allows tiles to be sparse, i.e. missing. For such tiles, *opentile* instead provides a blank (currently white) tile image using the same jpeg header as the rest of the image.\n\n***Aperio svs***\nSome Asperio svs-files have corrupt tile data at edges of non-base pyramidal levels. This is observed as tiles with 0-byte length and tiles with incorrect pixel data. *opentile* detects such corruption and instead returns downscaled image data from lower levels. Associated images (label, overview) are currently not handled correctly.\n\n***3DHistech tiff***\nOnly the pyramidal levels are supported (not overviews or labels).\n\n***OME tiff***\nMetadata parsing is not yet implemented.\n\n## Metadata\n\nFile metadata can be accessed through the `metadata`-property of a tiler. Depending on file format and content, the following metadata is available:\n\n- Magnification\n- Scanner manufacturer\n- Scanner model\n- Scanner software versions\n- Scanner serial number\n- Acquisition datetime\n\n## Basic usage\n\n***Load a Ndpi-file using tile size (1024, 1024) pixels.***\n\n```python\nfrom opentile import OpenTile\ntile_size = (1024, 1024)\ntiler = OpenTile.open(path_to_ndpi_file, tile_size)\n```\n\n***Load a file using fsspec and with some file options.***\n\n```python\nfrom opentile import OpenTile\ntiler = OpenTile.open(\"s3://bucket/key\", file_options={\"s3\": \"anon\": True})\n```\n\n***If turbo jpeg library path is not found.***\n\n```python\nfrom opentile import OpenTile\ntile_size = (1024, 1024)\nturbo_path = 'C:/libjpeg-turbo64/bin/turbojpeg.dll'\ntiler = OpenTile.open(path_to_ndpi_file, tile_size, turbo_path)\n```\n\n***Get rectangular tile at level 0 and position x=0, y=0.***\n\n```python\nlevel = tiler.get_evel(0)\ntile = level.get_tile((0, 0))\n```\n\n***Close the tiler object.***\n\n```python\ntiler.close()\n```\n\n***Usage as context manager***\n\nThe tiler can also be used as context manager:\n\n```python\nfrom opentile import OpenTile\ntile_size = (1024, 1024)\nwith OpenTile.open(path_to_ndpi_file, tile_size) as tiler:\n level = tiler.get_evel(0)\n tile = level.get_tile((0, 0))\n```\n\n## Setup environment for development\n\nRequires poetry and pytest and pytest-watch installed in the virtual environment.\n\n```console\ngit clone https://github.com/imi-bigpicture/opentile.git\npoetry install\n```\n\nBy default the tests looks for slides in 'tests/testdata'. This can be overridden by setting the OPENTILE_TESTDIR environment variable. The script 'tests/download_test_images.py' can be used to download publicly available [openslide testdata](https://openslide.cs.cmu.edu/download/openslide-testdata/) into the set testdata folder:\n\n```console\npython tests/download_test_images.py\n```\n\nThe test data used for philips tiff is currently not publicly available as we dont have permission to share them. If you have slides in philips tiff format that can be freely shared we would be happy to use them instead.\n\nTo watch unit tests use:\n\n```console\npoetry run pytest-watch -- -m unittest\n```\n\n## Other TIFF python tools\n\n- [tifffile](https://github.com/cgohlke/tifffile)\n- [tiffslide](https://github.com/bayer-science-for-a-better-life/tiffslide)\n\n## Contributing\n\nWe welcome any contributions to help improve this tool for the WSI community!\n\nWe recommend first creating an issue before creating potential contributions to check that the contribution is in line with the goals of the project. To submit your contribution, please issue a pull request on the imi-bigpicture/opentile repository with your changes for review.\n\nOur aim is to provide constructive and positive code reviews for all submissions. The project relies on gradual typing and roughly follows PEP8. However, we are not dogmatic. Most important is that the code is easy to read and understand.\n\n## Acknowledgement\n\n*opentile*: Copyright 2021-2024 Sectra AB, licensed under Apache 2.0.\n\nThis project is part of a project that has received funding from the Innovative Medicines Initiative 2 Joint Undertaking under grant agreement No 945358. This Joint Undertaking receives support from the European Union\u2019s Horizon 2020 research and innovation programme and EFPIA. IMI website: www.imi.europa.eu\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Read tiles from wsi-TIFF files",
"version": "0.13.4",
"project_urls": {
"Homepage": "https://github.com/imi-bigpicture/opentile",
"Repository": "https://github.com/imi-bigpicture/opentile"
},
"split_keywords": [
"whole slide image",
" digital pathology",
" tiff"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e194440830c1922659d6a358819c70ae8449bc00eff7a6216345ca2c088ea94c",
"md5": "e91c578c6a66790c4ab58c09de302b58",
"sha256": "f89de52524c231bcbef5119ca0d9901d57a569c365a2e2619ff20a0b4f6693a5"
},
"downloads": -1,
"filename": "opentile-0.13.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e91c578c6a66790c4ab58c09de302b58",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 55892,
"upload_time": "2024-11-06T08:03:41",
"upload_time_iso_8601": "2024-11-06T08:03:41.523767Z",
"url": "https://files.pythonhosted.org/packages/e1/94/440830c1922659d6a358819c70ae8449bc00eff7a6216345ca2c088ea94c/opentile-0.13.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "976ffb2527e3bdd0027a7dc268bab8e3f2554cf8e2b610b54aa8a59041a82f01",
"md5": "0af4b67dd5e22afab631b15c058799a9",
"sha256": "4ae56512ae40a39c55ff115abdaf6f3ca5052393f102646f5bd37768c7376303"
},
"downloads": -1,
"filename": "opentile-0.13.4.tar.gz",
"has_sig": false,
"md5_digest": "0af4b67dd5e22afab631b15c058799a9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9",
"size": 33640,
"upload_time": "2024-11-06T08:03:42",
"upload_time_iso_8601": "2024-11-06T08:03:42.761844Z",
"url": "https://files.pythonhosted.org/packages/97/6f/fb2527e3bdd0027a7dc268bab8e3f2554cf8e2b610b54aa8a59041a82f01/opentile-0.13.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-06 08:03:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "imi-bigpicture",
"github_project": "opentile",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "opentile"
}
JSON
