wsic

Whole Slide Image (WSI) conversion for brightfield histology images.

Provides a command line interface (CLI) for easy convertion between formats:

Usage: wsic convert [OPTIONS]

  Convert a WSI.

Options:
  -i, --in-path PATH              Path to WSI to read from.
  -o, --out-path PATH             The path to output to.
  -t, --tile-size <INTEGER INTEGER>...
                                  The size of the tiles to write.
  -rt, --read-tile-size <INTEGER INTEGER>...
                                  The size of the tiles to read.
  -w, --workers INTEGER           The number of workers to use.
  -c, --compression [blosc|deflate|jpeg xl|jpeg-ls|jpeg|jpeg2000|lzw|png|webp|zstd]
                                  The compression to use.
  -cl, --compression-level INTEGER
                                  The compression level to use.
  -d, --downsample INTEGER        The downsample factor to use.
  -mpp, --microns-per-pixel <FLOAT FLOAT>...
                                  The microns per pixel to use.
  -ome, --ome / --no-ome          Save with OME-TIFF metadata (OME-TIFF and
                                  NGFF).
  --overwrite / --no-overwrite    Whether to overwrite the output file.
  -to, --timeout FLOAT            Timeout in seconds for reading a tile.
  -W, --writer [auto|jp2|svs|tiff|zarr]
                                  The writer to use. Overrides writer detected
                                  by output file extension.
  -s, --store [dir|ndir|zip|sqlite]
                                  The store to use (zarr/NGFF only). Defaults
                                  to ndir (nested directory).
  -h, --help                      Show this message and exit.

Getting Started

For basic usage see the documentation page "How do I...?".

Features

Reading and writing several container formats.
Support for a wide range of compression codecs.
Custom tile size
Lossless repackaging / transcoding (to zarr/NGFF or TIFF) from:
- SVS (JPEG compressed)
- OME-TIFF (single image, JPEG and JPEG2000 (J2K) compressed)
- Generic Tiled TIFF (JPEG, JPEG2000, and WebP compressed)
- DICOM WSI (JPEG and JPEG2000 (J2K) compressed)

Read Container Formats

OpenSlide Formats:
- Aperio SVS (.svs)
- Hamamatsu (.vms, .vmu, .ndpi)
- Leica (.scn)
- Mirax MRXS (.mrxs)
- Sakura (.svslide)
- Trestle (.tif)
- Ventana (.bif, .tif)
- Generic tiled TIFF (.tif; DEFLATE, JPEG, and Webp compressed)
Other Tiled TIFFs (tifffile supported formats)
- Tiled with various codecs: e.g. JPEG XL, JPEG 2000, WebP, and zstd.
- RGB/brightfield OME-TIFF.
JP2 (via glymur and OpenJPEG)
- Including Omnyx JP2 files.
Zarr
- Single array.
- Group of (multiresolution) arrays.
- NGFF v0.4.
DICOM WSI (via wsidicom)
- DICOM VL Whole Slide Image IODs.

Write Container Formats

TIFF
- Generic Tiled / Pyramid TIFF
- OME-TIFF
- SVS
JP2
Zarr (NGFF v0.4)
DICOM (.dcm)

Notes & FAQs

Python on Windows handles multiprocessing differenly to POSIX/UNIX-like systems. I suggest using the Windows Subsystem for Linux on Windows to ensure that wsic functions correctly and efficiently.

Other Tools

There are many other great tools in this space. Below are some other tools for converting WSIs.

bfconvert Part of the Bio-Formats command line tools. Uses bioformats to convert from many formats to OME-TIFF.
biofromats2raw Convert from Bio-Formats formats to zarr.
isyntax2raw Convert from Philips' iSyntax format to a zarr using Philips' SDK.
wsidicomiser Convert OpenSlide images to WSI DICOM.

Credits

This package was created with Cookiecutter and the audreyr/cookiecutter-pypackage project template.

John-P/wsic