Metadata-Version: 2.1
Name: tiffslide
Version: 2.4.0
Summary: tifffile-based drop-in replacement for openslide-python
Author-email: Andreas Poehlmann <andreas.poehlmann@bayer.com>
License: New BSD License
        
        Copyright (c) 2020, Bayer AG
        All rights reserved.
        
        
        Redistribution and use in source and binary forms, with or without
        modification, are permitted provided that the following conditions are met:
        
          a. Redistributions of source code must retain the above copyright notice,
             this list of conditions and the following disclaimer.
          b. Redistributions in binary form must reproduce the above copyright
             notice, this list of conditions and the following disclaimer in the
             documentation and/or other materials provided with the distribution.
          c. Neither the name of the tiffslide developers nor the names of
             its contributors may be used to endorse or promote products
             derived from this software without specific prior written
             permission.
        
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
        ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR
        ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
        LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
        OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
        DAMAGE.
        
Project-URL: Homepage, https://github.com/Bayer-Group/tiffslide
Project-URL: Download, https://github.com/Bayer-Group/tiffslide
Project-URL: Source, https://github.com/Bayer-Group/tiffslide
Project-URL: Changelog, https://github.com/Bayer-Group/tiffslide/blob/main/CHANGELOG.md
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Utilities
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX
Classifier: Operating System :: Unix
Classifier: Operating System :: MacOS
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: imagecodecs
Requires-Dist: fsspec!=2022.11.0,!=2023.1.0
Requires-Dist: pillow
Requires-Dist: tifffile>=2021.6.14
Requires-Dist: zarr>=2.11.0
Requires-Dist: typing_extensions>=4.0
Provides-Extra: dev
Requires-Dist: pre-commit; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: pytest>=6; extra == "dev"
Requires-Dist: pytest-benchmark; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: mypy; extra == "dev"

# tiffslide: a drop-in replacement for openslide-python

[![PyPI Version](https://img.shields.io/pypi/v/tiffslide)](https://pypi.org/project/tiffslide/)
[![Conda (channel only)](https://img.shields.io/conda/vn/conda-forge/tiffslide?label=conda)](https://anaconda.org/conda-forge/tiffslide)
[![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)
[![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)
[![PyPI - Downloads](https://img.shields.io/pypi/dm/tiffslide?label=pypi)](https://pypi.org/project/tiffslide/)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/tiffslide)](https://github.com/bayer-science-for-a-better-life/tiffslide)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.6327079.svg)](https://doi.org/10.5281/zenodo.6327079)

Welcome to `tiffslide` :wave:, a [tifffile](https://github.com/cgohlke/tifffile/) based
drop-in replacement for [openslide-python](https://github.com/openslide/openslide-python).

`tiffslide`'s goal is to provide an easy way to migrate existing code from an
openslide dependency to the excellently maintained tifffile module.

We strive to make your lives as easy as possible: If using `tiffslide` is
unintuitive, slow, or if it's drop-in behavior differs from what you expect,
it's a bug in `tiffslide`. Feel free to report any issues or feature requests in
the issue tracker!

Development [happens on github](https://github.com/bayer-science-for-a-better-life/tiffslide) :octocat:


## Notes

TiffSlide aims to be compatible with all formats that openslide supports and more,
but not all are implemented yet. Aperio SVS is currently the most tested format.
Contributions to expand to a larger variety of file formats that tifffile supports are very welcome :heart:
<br>
If there are any questions open an issue, and we'll do our best to help!


## Compatibility

Here's a list with currently supported formats.

| File Format    |   can be opened    |    full support    | references                                                                    |
|----------------|:------------------:|:------------------:|-------------------------------------------------------------------------------|
| Aperio SVS     | :white_check_mark: | :white_check_mark: |                                                                               |
| Generic TIFF   | :white_check_mark: | :white_check_mark: |                                                                               |
| Hamamatsu NDPI | :white_check_mark: |     :warning:      | [#35](https://github.com/bayer-science-for-a-better-life/tiffslide/issues/35) |
| Leica SCN      | :white_check_mark: | :white_check_mark: |                                                                               |
| Ventana        |     :warning:      |     :warning:      | [#37](https://github.com/bayer-science-for-a-better-life/tiffslide/issues/37) |
| Hamamatsu VMS  |  :no_entry_sign:   |  :no_entry_sign:   |                                                                               |
| DICOM          |  :no_entry_sign:   |  :no_entry_sign:   | [#32](https://github.com/bayer-science-for-a-better-life/tiffslide/issues/32) |
| Mirax          |  :no_entry_sign:   |  :no_entry_sign:   | [#33](https://github.com/bayer-science-for-a-better-life/tiffslide/issues/33) |
| Zeiss ZVI      |  :no_entry_sign:   |  :no_entry_sign:   |                                                                               |


## Documentation

### Installation

tiffslide's stable releases can be installed via `pip`:
```bash
pip install tiffslide
```
Or via `conda`:
```bash
conda install -c conda-forge tiffslide
```

### Usage

tiffslide's behavior aims to be identical to openslide-python where it makes sense.
If you rely heavily on the internals of openslide, this is not the package you are looking for.
In case we add more features, we will add documentation here.

#### as a drop-in replacement

```python
# directly
from tiffslide import TiffSlide
slide = TiffSlide('path/to/my/file.svs')

# or via its drop-in behavior
import tiffslide as openslide
slide = openslide.OpenSlide('path/to/my/file.svs')
```

#### access files in the cloud

A nice side effect of using tiffslide is that your code will also work with
[filesystem_spec](https://github.com/fsspec/filesystem_spec), which enables you
to access your whole slide images from various supported filesystems:

```python
import fsspec
from tiffslide import TiffSlide

# read from any io buffer
with fsspec.open("s3://my-bucket/file.svs") as f:
    slide = TiffSlide(f)
    thumb = slide.get_thumbnail((200, 200))

# read from fsspec urlpaths directly, using your AWS_PROFILE 'aws'
slide = TiffSlide("s3://my-bucket/file.svs", storage_options={'profile': 'aws'})
thumb = slide.get_thumbnail((200, 200))

# read via fsspec from google cloud and use fsspec's caching mechanism to cache locally
slide = TiffSlide("simplecache::gcs://my-bucket/file.svs", storage_options={'project': 'my-project'})
region = slide.read_region((300, 400), 0, (512, 512))
```

#### read numpy arrays instead of PIL images

Very often you'd actually want your region returned as a numpy array instead
getting a PIL Image and then having to convert to numpy:

```python
import numpy as np
from tiffslide import TiffSlide

slide = TiffSlide("myfile.svs")
arr = slide.read_region((100, 200), 0, (256, 256), as_array=True)
assert isinstance(arr, np.ndarray)
```


## Development Installation

If you want to help improve tiffslide, you can setup your development environment
in two different ways:

With conda:

1. Clone tiffslide `git clone https://github.com/bayer-science-for-a-better-life/tiffslide.git`
2. `cd tiffslide`
3. `conda env create -f environment.devenv.yml`
4. Activate the environment `conda activate tiffslide`

Without conda:

1. Clone tiffslide `git clone https://github.com/bayer-science-for-a-better-life/tiffslide.git`
2. `cd tiffslide`
3. `python -m venv venv && source venv/bin/activate && python -m pip install -U pip`
4. `pip install -e .[dev]`

Note that in these environments `tiffslide` is already installed in development
mode, so go ahead and hack.

## Benchmarks

Here are some benchmarks comparing `tiffslide` to `openslide` for different
supported file types and access patterns. Please note that you should test the
difference in access time always for yourself on your target machine and your
specific use case.

In case you would like a specific use case to be added, please feel free to
open an issue or make a pull request.

The plots below were generated on a Thinkpad E495 and the files were stored on the
internal ssd.
Note, that in general, on my test my machine, `tiffslide` outperforms `openslide`
when reading data as numpy arrays. _Ventana_ tile reading is not _"correct"_
since as of now (`1.5.0`) tiffslide lacks compositing for the overlapping tiles.

See the [docs/README.md](docs/README.md) to run the benchmarks on your own machine.

### reading PIL images

![access times reading PIL](docs/images/benchmark_read_tiles_as_pil.png)

### reading Numpy arrays

![access times reading numpy](docs/images/benchmark_read_tiles_as_numpy.png)


## Contributing Guidelines

- Please follow [pep-8 conventions](https://www.python.org/dev/peps/pep-0008/) but:
  - We allow 120 character long lines (try anyway to keep them short)
- Please use [numpy docstrings](https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard).
- When contributing code, please try to use Pull Requests.
- tests go hand in hand with modules on ```tests``` packages at the same level. We use ```pytest```.

You can setup your IDE to help you adhering to these guidelines.
<br>
_([Santi](https://github.com/sdvillal) is happy to help you setting up pycharm in 5 minutes)_


## Acknowledgements

Build with love by Andreas Poehlmann and Santi Villalba from the _Machine Learning Research_ group at Bayer.

`tiffslide`: copyright 2020 Bayer AG, licensed under [BSD](https://github.com/bayer-science-for-a-better-life/tiffslide/blob/master/LICENSE)
