wsic 0.9.0
Whole Slide Image (WSI) conversion for brightfield histology images
Requires Python: >=3.8
Keywords: wsic

# wsic

[![Gitmoji](https://img.shields.io/badge/gitmoji-%20%F0%9F%98%9C%20%F0%9F%98%8D-FFDD67.svg)](https://gitmoji.dev)
[![image](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
[![image](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)

[![Python application](https://github.com/John-P/wsic/actions/workflows/python-app.yml/badge.svg?branch=dev)](https://github.com/John-P/wsic/actions/workflows/python-app.yml)
[![Documentation
Status](https://readthedocs.org/projects/pip/badge/?version=stable)](https://wsic.readthedocs.io/en/latest/)

[![image](https://img.shields.io/pypi/v/wsic)](https://pypi.org/project/wsic/)
[![image](https://codecov.io/gh/John-P/wsic/branch/main/graph/badge.svg?token=ICCWDKJG5J)](https://codecov.io/gh/John-P/wsic)
[![image](https://deepsource.io/gh/John-P/wsic.svg/?label=active+issues&show_trend=true&token=D-sO1mhzQv1n9FPl0RFaAfGt)](https://deepsource.io/gh/John-P/wsic/?ref=repository-badge)

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:

```bash
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.
```

![A demonstration of converting a JP2 file to a pyramid
TIFF.](https://github.com/John-P/wsic/raw/main/docs/_static/wsic_convert_demo.gif)

## Getting Started

For basic usage see the documentation page ["How do
I...?"](https://wsic.readthedocs.io/en/latest/how_do_i.html).

## 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](https://openslide.org/) 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](https://github.com/cgohlke/tifffile) supported
  formats)
  - Tiled with various codecs: e.g. JPEG XL, JPEG 2000, WebP, and zstd.
  - RGB/brightfield [OME-TIFF](https://docs.openmicroscopy.org/ome-model/5.6.3/ome-tiff/).
- [JP2](https://jpeg.org/jpeg2000/) (via
  [glymur](https://glymur.readthedocs.io/en/latest/) and
  [OpenJPEG](https://www.openjpeg.org/))
  - Including Omnyx JP2 files.
- [Zarr](https://zarr.readthedocs.io/en/stable/)
  - Single array.
  - Group of (multiresolution) arrays.
  - [NGFF v0.4](https://ngff.openmicroscopy.org/0.4/index.html).
- [DICOM WSI](https://dicom.nema.org/dicom/dicomwsi/) (via
  [wsidicom](https://github.com/imi-bigpicture/wsidicom))
  - [DICOM VL Whole Slide Image IODs](https://dicom.innolitics.com/ciods/vl-whole-slide-microscopy-image).

### 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](https://github.com/audreyr/cookiecutter) and the
[audreyr/cookiecutter-pypackage](https://github.com/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.