wsic

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-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)

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.9.0 (2023-05-25)

• Update documentation.
• Bump dependencies.
• Improved validation of TIFF write arguments.
• Add ability to speciy store when writing Zarr e.g. zarr.SQliteStore.
• Update CLI:
  • New -s argment for convert to specify store for zarr.
• Bug fixes:
  • Fix MPP writing for .dcm files.
  • Fix parsing of NGFF metadata (zattrs JSON), including getting MPP.

0.8.2 (2023-04-02)

• Bug fixes:
  • Fix issue where DICOMWSIReader required user input at init.
  • Fix level offset when printing the level number during TIFFWriter pyramid building.
  • Refactor slow DICOMWSIReader init warning and only warn from the main process.

0.8.0 (2023-04-01)

• Add DICOM writer.
• Avoid decoding entire TIFF before conversion starts.
• TIFFReader can now expose a dask array view (using tiffile Zarr view underneath).
• Add overwrite option to transcode CLI mode.
• Refactor to use persistent worker subprocesses. This avoids recreating the reader object for each region read. For some reader such as DICOMWSIReader this significantly improves performance.
• General refactoring and code cleanup.
• Bug fixes:
  • Fix writing MPP for SVSWriter.
  • Remove OpenSlide thumbnail generation method. This would cause the process to run out of memory for some files and the base implementation works just as well without this memory issue.

0.7.0 (2022-12-15)

• Normalise TIFF array axes (to YXC order) when reading using tiffile.
• Bug fixes:
  • Fix reading/writing JP2 resoluion metadata (vres/hres are in m not cm).
  • Join child processes when finishing writing / exiting.
  • Copy the reader tile size for transcode mode.
  • Return None for MPP when JP2 has no resolution box.
  • Set resolution units to cm when writing TIFFs.
  • Use the MPP from the reader when writing JP2.
  • Add a zarr intermediate for JP2 writing (allows different read and write tile sizes).

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.