How do I...?

============

...convert a whole slide image?

-------------------------------

The CLI included with WSIC has the `convert` command for converting WSIs::

    wsic convert -i <input> -o <output>

The output format is determined from the output file extension according

to the following table:

=========  ===========

Extension  Format

=========  ===========

.tiff      Tiled TIFF

.svs       Aperio SVS

.zarr      Zarr/NGFF

.jp2       JPEG2000

.dcm       DICOM

=========  ===========

You can also use the WSIC API to do this programmatically. For example:

>>> import wsic

>>> reader = wsic.readers.OpenSlideReader("in_file.svs")

>>> writer = wsic.writers.ZarrWriter(

        "out_file.zarr",

        pyramid_levels=[2, 4, 8],

        compression="jpeg",

        compression_level=90,

    )

>>> writer.copy_from_reader(reader)

...change the tile size?

------------------------

The tile size can be specified with the `--tile-size` or `-t` option.

The default tile size is 256x256.::

    wsic convert -i <input> -o <output> --tile-size 512 512

...use a different compression codec?

-------------------------------------

There are many compression codecs available for use with WSIC. The

compression codec can be specified with the `--compression` or `-c`

option, and the 'level' of compression can be specified with the

`--compression-level` or `-cl` option.

    wsic convert -i <input> -o <output> -c jpeg -cl 90

Codecs Supported By File Format

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

======  ================================================================

Format  Codecs

======  ================================================================

TIFF    JPEG, JPEG-LS, JPEG XL, JPEG2000, DEFLATE, WebP, LZW, Zstd

Zarr    Blosc, JPEG, JPEG-LS, JPEG2000, DEFLATE, WebP, PNG, LZW, Zstd

SVS     JPEG

DICOM   JPEG, JPEG2000

JP2     JPEG2000

======  ================================================================

Interpretation of Level Option

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

=========  ===========================

Codec       Level

=========  ===========================

JPEG       'Quality' (0-100)

JPEG XL    'Effort' / Speed

JPEG-LS    Maximum Absolute Error (MAE)

JPEG 2000  PSNR (db)

PNG        'Effort' / Speed

Zstd       'Effort' / Speed

=========  ===========================

...add pyramid/resolution levels?

---------------------------------

Downsampled copies of the image stored in the WSI, known as

pyramid/resolution levels, can be specified with the `--dowmsample` or

`-d` option. For most formats these levels must be in ascending order.

It is also common that they must be powers of two. Each `-d`` option

will append a resolution level to the file in the order they are

given.::

    wsic convert -i <input> -o <output> -d 2 -d 4 -d 8

...speed up conversion?

-----------------------

There are a few different ways to speed up conversion: increasing the

read tile size, increasing the number of workers, or using repackaing /

transcoding instead of conversion by copying decoded pixel data.

Read Tile Size

^^^^^^^^^^^^^^

One way to speed up conversion is to increase the size of the area read

at each step of the conversion. This can be done from the CLI with the

`--read-size` or `-rt` option. The default read size is to use the tile

size of the input file or 4096x4096, whichever is lower.::

    wsic convert -i <input> -o <output> --read-size 512 512

Note that you may also need to increase the tile read timeout for large

tile read sizes using the `--timeout` or `-to` option. There is a

default timeout of 10 seconds to prevent the CLI tool from haning

indefinately. Setting this to a negative value will lead to an unbounded

read time allowed.::

    wsic convert -i <input> -o <output> --read-size 512 512 -to 30

Number of Workers

^^^^^^^^^^^^^^^^^

Reading data from the input image is performed with a number of worker

sub-processes. The number of workers can be set from the CLI with the

`--workers` or `-w` option. The default number of workers is to use the

number of (virtual) CPUs available.::

    wsic convert -i <input> -o <output> --workers 4

Repackaging

^^^^^^^^^^^^

Repackaging is a much faster way to convert the WSI from one format to

another. However, it is more restrictive. Only certain formats can be

repacked, and the compression codec must be preserved. This is because

repackaing is takeing the already encoded tile data and rearranging

those encoded tiles.::

    wsic transcode -i <input> -o <output> --repackage

This is currently supported with a source image in TIFF, Zarr, and DICOM

format and with an output format of TIFF or Zarr (NGFF).

...write an OME-TIFF

--------------------

To write out a TIFF with OME XML metadata in the description tag, use

the `--ome` flag with an `.ome.tiff` output path.::

    wsic convert -i <input> -o <output.ome.tiff> --ome

...write an NGFF Zarr

---------------------

To write a Zarr which follows the NGFF spec (v0.4), use the `--ome` flag

with a `.zarr`` output file path.::

    wsic convert -i <input> -o <output.zarr> --ome