wsic 0.6.1

Whole Slide Image (WSI) conversion for brightfield histology images

wsic

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

Note: This is in early development and there will likely be frequent and breaking changes.

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-XML).
  --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.
  -h, --help                      Show this message and exit.

Features

• Read image data from:
  • 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)
    • E.g. JPEG XL compressed
  • OME-TIFF (via (tifffile)
  • JP2 (via glymur and OpenJPEG)
  • Zarr / NGFF (single array or pyramid group of arrays)
  • DICOM WSI (via wsidicom)
• Write image data to:
  • Tiled / Pyramid Generic TIFF
  • OME-TIFF
  • JP2
  • Pyramid Zarr (NGFF)
• Custom tile size
• Compression codecs
• Lossless repackaging / transcoding (to zarr/NGFF) 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)

Dependencies

• numpy
• zarr
• click (CLI)

Optional Dependencies

• OpenSlide and openslide-python (reading OpenSlide Formats)
• tifffile (reading tiled TIFFs)
• wsidicom (reading DICOM WSI)
• glymur and OpenJPEG (reading JP2)
• tqdm (progress bars)
• scipy (faster pyramid downsampling)
• opencv-python (even faster pyramid downsampling)
• imagecodecs (additional codecs and transcoding)

To-Dos

For a list of To-Dos see the project board.

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.

https://www.openmicroscopy.org/bio-formats/downloads/

biofromats2raw

Convert from Bio-Formats formats to zarr.

https://github.com/glencoesoftware/bioformats2raw

isyntax2raw

Convert from Philips' iSyntax format to a zarr.

https://github.com/glencoesoftware/isyntax2raw

wsidicomiser

Convert OpenSlide images to WSI DICOM.

https://github.com/sectra-medical/wsidicomizer

Credits

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

History

0.6.1 (2022-10-21)

• Select Writer class based on file extension from CLI.
• Bug fixes:
  • Fix writing MPP to NGFF v0.4.
  • Change coordinate transformation ordering.
  • Fix reading TIFF resolution tag. Previously only the numerator of the resolution fraction was being read.
  • Other minor bug fixes.

0.6.0 (2022-10-03)

• Add ability to write resolution metadata to JP2. Thanks to @quintusdias for helping get this implemented in glymur.
• Remove QOI codec code as this is not included in imagecodes. Thanks to Christoph Gohlke for adding this.
• Add a "How do I?" documentation page.

0.5.1 (2022-06-27)

• Bug fixes:
  • Fix parsing of OpenSlide MPP to float.

0.5.0 (2022-06-25)

• Add ability to transcode/repackage to a TIFF file (from DICOM or SVS).
• Refactor ZarrReaderWriter to seperate ZarrWriter and ZarrReader.
• Bug fixes:
  • Fix thumbnaiul generation for zarr.
  • Fix NGFF metadata CoordinateTransformation field default factor.

0.4.0 (2022-06-20)

• Add ability to write JPEG compressed SVS files.
• Add support for thumbnail generation and a CLI command.
• Swap from strings to enums for codecs and color spaces.

0.3.0 (2022-05-13)

• Remove unused CLI debug option.
• Add generation of OME-NGFF metadata (JSON .zattrs file).
• Add timeout when copying tiles to prevent indefinite hanging.
• Improve joining/termination of child processes at shutdown.
• Use the TIFF resolution tag if present.
• Add get_tile method to all Reader classes.
• Update supported Python versions to 3.8, 3.9, 3.10.
• Bug fixes:
  • Fix and issue with concatenation of pyramid downsamples.
  • Add a custom Queue class for multiprocessing on macOS.
  • Fix handling of pyramid_downsamples argument when None.

0.2.0 (2022-03-22)

• Add Support To Read DICOM WSI and transform to zarr.

0.1.0 (2022-02-22)

• First release on PyPI.