Package: tiffslide
tiffslide: a drop-in replacement for openslide-pythonWelcome totiffslide:wave:, atifffilebased
drop-in replacement foropenslide-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 usingtiffslideis
unintuitive, slow, or if it's drop-in behavior differs from what you expect,
it's a bug intiffslide. Feel free to report any issues or feature requests in
the issue tracker!Developmenthappens on github:octocat:NotesTiffSlide 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:If there are any questions open an issue, and we'll do our best to help!CompatibilityHere's a list with currently supported formats.File Formatcan be openedfull supportreferencesAperio SVS:white_check_mark::white_check_mark:Generic TIFF:white_check_mark::white_check_mark:Hamamatsu NDPI:white_check_mark::warning:#35Leica SCN:white_check_mark::white_check_mark:Ventana:warning::warning:#37Hamamatsu VMS:no_entry_sign::no_entry_sign:DICOM:no_entry_sign::no_entry_sign:#32Mirax:no_entry_sign::no_entry_sign:#33Zeiss ZVI:no_entry_sign::no_entry_sign:DocumentationInstallationtiffslide's stable releases can be installed viapip:pipinstalltiffslideOr viaconda:condainstall-cconda-forgetiffslideUsagetiffslide'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# directlyfromtiffslideimportTiffSlideslide=TiffSlide('path/to/my/file.svs')# or via its drop-in behaviorimporttiffslideasopenslideslide=openslide.OpenSlide('path/to/my/file.svs')access files in the cloudA nice side effect of using tiffslide is that your code will also work withfilesystem_spec, which enables you
to access your whole slide images from various supported filesystems:importfsspecfromtiffslideimportTiffSlide# read from any io bufferwithfsspec.open("s3://my-bucket/file.svs")asf: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 locallyslide=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 imagesVery often you'd actually want your region returned as a numpy array instead
getting a PIL Image and then having to convert to numpy:importnumpyasnpfromtiffslideimportTiffSlideslide=TiffSlide("myfile.svs")arr=slide.read_region((100,200),0,(256,256),as_array=True)assertisinstance(arr,np.ndarray)Development InstallationIf you want to help improve tiffslide, you can setup your development environment
in two different ways:With conda:Clone tiffslidegit clone https://github.com/bayer-science-for-a-better-life/tiffslide.gitcd tiffslideconda env create -f environment.devenv.ymlActivate the environmentconda activate tiffslideWithout conda:Clone tiffslidegit clone https://github.com/bayer-science-for-a-better-life/tiffslide.gitcd tiffslidepython -m venv venv && source venv/bin/activate && python -m pip install -U pippip install -e .[dev]Note that in these environmentstiffslideis already installed in development
mode, so go ahead and hack.BenchmarksHere are some benchmarks comparingtiffslidetoopenslidefor 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,tiffslideoutperformsopenslidewhen reading data as numpy arrays.Ventanatile reading is not"correct"since as of now (1.5.0) tiffslide lacks compositing for the overlapping tiles.See thedocs/README.mdto run the benchmarks on your own machine.reading PIL imagesreading Numpy arraysContributing GuidelinesPlease followpep-8 conventionsbut:We allow 120 character long lines (try anyway to keep them short)Please usenumpy docstrings.When contributing code, please try to use Pull Requests.tests go hand in hand with modules ontestspackages at the same level. We usepytest.You can setup your IDE to help you adhering to these guidelines.(Santiis happy to help you setting up pycharm in 5 minutes)AcknowledgementsBuild with love by Andreas Poehlmann and Santi Villalba from theMachine Learning Researchgroup at Bayer.tiffslide: copyright 2020 Bayer AG, licensed underBSD