{"id":24432190,"url":"https://github.com/bayer-group/tiffslide","last_synced_at":"2025-12-12T01:04:15.466Z","repository":{"id":37079750,"uuid":"349027019","full_name":"Bayer-Group/tiffslide","owner":"Bayer-Group","description":"TiffSlide - cloud native openslide-python replacement based on tifffile","archived":false,"fork":false,"pushed_at":"2025-03-07T17:33:43.000Z","size":1380,"stargazers_count":97,"open_issues_count":22,"forks_count":12,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-04-04T00:07:07.758Z","etag":null,"topics":["digital-pathology","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Bayer-Group.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-03-18T10:14:54.000Z","updated_at":"2025-03-10T18:37:54.000Z","dependencies_parsed_at":"2023-11-08T04:38:51.925Z","dependency_job_id":"4afb0ca5-f765-44ad-873a-094d3abcb4eb","html_url":"https://github.com/Bayer-Group/tiffslide","commit_stats":null,"previous_names":["bayer-science-for-a-better-life/tiffslide"],"tags_count":34,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bayer-Group%2Ftiffslide","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bayer-Group%2Ftiffslide/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bayer-Group%2Ftiffslide/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bayer-Group%2Ftiffslide/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Bayer-Group","download_url":"https://codeload.github.com/Bayer-Group/tiffslide/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248625478,"owners_count":21135512,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["digital-pathology","python"],"created_at":"2025-01-20T15:35:17.147Z","updated_at":"2025-12-12T01:04:15.414Z","avatar_url":"https://github.com/Bayer-Group.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# tiffslide: a drop-in replacement for openslide-python\n\n[![PyPI Version](https://img.shields.io/pypi/v/tiffslide)](https://pypi.org/project/tiffslide/)\n[![Conda (channel only)](https://img.shields.io/conda/vn/conda-forge/tiffslide?label=conda)](https://anaconda.org/conda-forge/tiffslide)\n[![tiffslide ci](https://github.com/bayer-science-for-a-better-life/tiffslide/actions/workflows/run_pytests.yaml/badge.svg)](https://github.com/bayer-science-for-a-better-life/tiffslide/actions/workflows/run_pytests.yaml)\n[![GitHub issues](https://img.shields.io/github/issues/bayer-science-for-a-better-life/tiffslide)](https://github.com/bayer-science-for-a-better-life/tiffslide/issues)\n[![PyPI - Downloads](https://img.shields.io/pypi/dm/tiffslide?label=pypi)](https://pypi.org/project/tiffslide/)\n[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/tiffslide)](https://github.com/bayer-science-for-a-better-life/tiffslide)\n[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.6327079.svg)](https://doi.org/10.5281/zenodo.6327079)\n\nWelcome to `tiffslide` :wave:, a [tifffile](https://github.com/cgohlke/tifffile/) based\ndrop-in replacement for [openslide-python](https://github.com/openslide/openslide-python).\n\n`tiffslide`'s goal is to provide an easy way to migrate existing code from an\nopenslide dependency to the excellently maintained tifffile module.\n\nWe strive to make your lives as easy as possible: If using `tiffslide` is\nunintuitive, slow, or if it's drop-in behavior differs from what you expect,\nit's a bug in `tiffslide`. Feel free to report any issues or feature requests in\nthe issue tracker!\n\nDevelopment [happens on github](https://github.com/bayer-science-for-a-better-life/tiffslide) :octocat:\n\n\n## Notes\n\nTiffSlide aims to be compatible with all formats that openslide supports and more,\nbut not all are implemented yet. Aperio SVS is currently the most tested format.\nContributions to expand to a larger variety of file formats that tifffile supports are very welcome :heart:\n\u003cbr\u003e\nIf there are any questions open an issue, and we'll do our best to help!\n\n\n## Compatibility\n\nHere's a list with currently supported formats.\n\n| File Format    |   can be opened    |    full support    | references                                                                    |\n|----------------|:------------------:|:------------------:|-------------------------------------------------------------------------------|\n| Aperio SVS     | :white_check_mark: | :white_check_mark: |                                                                               |\n| Generic TIFF   | :white_check_mark: | :white_check_mark: |                                                                               |\n| Hamamatsu NDPI | :white_check_mark: |     :warning:      | [#35](https://github.com/bayer-science-for-a-better-life/tiffslide/issues/35) |\n| Leica SCN      | :white_check_mark: | :white_check_mark: |                                                                               |\n| Ventana        |     :warning:      |     :warning:      | [#37](https://github.com/bayer-science-for-a-better-life/tiffslide/issues/37) |\n| Hamamatsu VMS  |  :no_entry_sign:   |  :no_entry_sign:   |                                                                               |\n| DICOM          |  :no_entry_sign:   |  :no_entry_sign:   | [#32](https://github.com/bayer-science-for-a-better-life/tiffslide/issues/32) |\n| Mirax          |  :no_entry_sign:   |  :no_entry_sign:   | [#33](https://github.com/bayer-science-for-a-better-life/tiffslide/issues/33) |\n| Zeiss ZVI      |  :no_entry_sign:   |  :no_entry_sign:   |                                                                               |\n\n\n## Documentation\n\n### Installation\n\ntiffslide's stable releases can be installed via `pip`:\n```bash\npip install tiffslide\n```\nOr via `conda`:\n```bash\nconda install -c conda-forge tiffslide\n```\n\n### Usage\n\ntiffslide's behavior aims to be identical to openslide-python where it makes sense.\nIf you rely heavily on the internals of openslide, this is not the package you are looking for.\nIn case we add more features, we will add documentation here.\n\n#### as a drop-in replacement\n\n```python\n# directly\nfrom tiffslide import TiffSlide\nslide = TiffSlide('path/to/my/file.svs')\n\n# or via its drop-in behavior\nimport tiffslide as openslide\nslide = openslide.OpenSlide('path/to/my/file.svs')\n```\n\n#### access files in the cloud\n\nA nice side effect of using tiffslide is that your code will also work with\n[filesystem_spec](https://github.com/fsspec/filesystem_spec), which enables you\nto access your whole slide images from various supported filesystems:\n\n```python\nimport fsspec\nfrom tiffslide import TiffSlide\n\n# read from any io buffer\nwith fsspec.open(\"s3://my-bucket/file.svs\") as f:\n    slide = TiffSlide(f)\n    thumb = slide.get_thumbnail((200, 200))\n\n# read from fsspec urlpaths directly, using your AWS_PROFILE 'aws'\nslide = TiffSlide(\"s3://my-bucket/file.svs\", storage_options={'profile': 'aws'})\nthumb = slide.get_thumbnail((200, 200))\n\n# read via fsspec from google cloud and use fsspec's caching mechanism to cache locally\nslide = TiffSlide(\"simplecache::gcs://my-bucket/file.svs\", storage_options={'project': 'my-project'})\nregion = slide.read_region((300, 400), 0, (512, 512))\n```\n\n#### read numpy arrays instead of PIL images\n\nVery often you'd actually want your region returned as a numpy array instead\ngetting a PIL Image and then having to convert to numpy:\n\n```python\nimport numpy as np\nfrom tiffslide import TiffSlide\n\nslide = TiffSlide(\"myfile.svs\")\narr = slide.read_region((100, 200), 0, (256, 256), as_array=True)\nassert isinstance(arr, np.ndarray)\n```\n\n\n## Development Installation\n\nIf you want to help improve tiffslide, you can setup your development environment\nin two different ways:\n\nWith conda:\n\n1. Clone tiffslide `git clone https://github.com/bayer-science-for-a-better-life/tiffslide.git`\n2. `cd tiffslide`\n3. `conda env create -f environment.devenv.yml`\n4. Activate the environment `conda activate tiffslide`\n\nWithout conda:\n\n1. Clone tiffslide `git clone https://github.com/bayer-science-for-a-better-life/tiffslide.git`\n2. `cd tiffslide`\n3. `python -m venv venv \u0026\u0026 source venv/bin/activate \u0026\u0026 python -m pip install -U pip`\n4. `pip install -e .[dev]`\n\nNote that in these environments `tiffslide` is already installed in development\nmode, so go ahead and hack.\n\n## Benchmarks\n\nHere are some benchmarks comparing `tiffslide` to `openslide` for different\nsupported file types and access patterns. Please note that you should test the\ndifference in access time always for yourself on your target machine and your\nspecific use case.\n\nIn case you would like a specific use case to be added, please feel free to\nopen an issue or make a pull request.\n\nThe plots below were generated on a Thinkpad E495 and the files were stored on the\ninternal ssd.\nNote, that in general, on my test my machine, `tiffslide` outperforms `openslide`\nwhen reading data as numpy arrays. _Ventana_ tile reading is not _\"correct\"_\nsince as of now (`1.5.0`) tiffslide lacks compositing for the overlapping tiles.\n\nSee the [docs/README.md](docs/README.md) to run the benchmarks on your own machine.\n\n### reading PIL images\n\n![access times reading PIL](docs/images/benchmark_read_tiles_as_pil.png)\n\n### reading Numpy arrays\n\n![access times reading numpy](docs/images/benchmark_read_tiles_as_numpy.png)\n\n\n## Contributing Guidelines\n\n- Please follow [pep-8 conventions](https://www.python.org/dev/peps/pep-0008/) but:\n  - We allow 120 character long lines (try anyway to keep them short)\n- Please use [numpy docstrings](https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard).\n- When contributing code, please try to use Pull Requests.\n- tests go hand in hand with modules on ```tests``` packages at the same level. We use ```pytest```.\n\nYou can setup your IDE to help you adhering to these guidelines.\n\u003cbr\u003e\n_([Santi](https://github.com/sdvillal) is happy to help you setting up pycharm in 5 minutes)_\n\n\n## Acknowledgements\n\nBuild with love by Andreas Poehlmann and Santi Villalba from the _Machine Learning Research_ group at Bayer.\n\n`tiffslide`: copyright 2020 Bayer AG, licensed under [BSD](https://github.com/bayer-science-for-a-better-life/tiffslide/blob/master/LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbayer-group%2Ftiffslide","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbayer-group%2Ftiffslide","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbayer-group%2Ftiffslide/lists"}