Supported image formats

QuPath can handle a wide range of image formats, including many whole slide formats. These include:

• Whole slide image formats supported by OpenSlide:
  • Aperio (.svs, .tif)
  • Hamamatsu (.vms, .vmu, .ndpi)
  • Leica (.scn)
  • MIRAX (.mrxs)
  • Philips (.tiff)
  • Sakura (.svslide)
  • Trestle (.tif)
  • Ventana (.bif, .tif)
  • Generic tiled TIFF (.tif)
• ImageJ TIFF
• JPEG
• PNG

The OpenSlide list was copied from the OpenSlide website. However, note that the support for all formats using OpenSlide may not be complete. For example, OpenSlide can only return 2D RGB images for all formats - even if the original data was (for example) a z-stack.

For an image file to work with QuPath, an open source reader needs to exist. Proprietary formats that don't have a reader available can't be used, unfortunately.

Other image formats

Using Bio-Formats

The popular Bio-Formats library can support reading a much wider range of image formats - including many microscopy formats.

The QuPath Bioformats extension provides a way of using Bio-Formats with QuPath.

Using ImageJ

Alternatively, for other types of data (e.g. 16-bit, multichannel/multidimensional fluorescence images) then one approach is to convert these to TIFF using ImageJ. In this case, QuPath will use ImageJ itself to read the images - which means that calibration information (i.e. pixel sizes) should be preserved.

However, this is only appropriate for small images, since ImageJ does not support whole slide data directly.

Issues & discussions

Questions about file formats are frequent; here are some links to previous discussions:

• .mrxs https://github.com/qupath/qupath/issues/187
• .scn https://github.com/qupath/qupath/issues/184

Additional notes

Notes on JPEG-XR

Zeiss CZI

Since the release of Bio-Formats v5.3.0, it is possible to use QuPath with Zeiss' .czi files - including those with JPEG-XR compression.

You should just need to install the QuPath Bioformats extension along with the latest version of Bio-Formats.

If CZI files still do not open on Windows, it may also be necessary to install the Visual Studio 2015 C++ Redistributable - see https://www.openmicroscopy.org/site/support/bio-formats5.3/formats/zeiss-czi.html for more information (with thanks to bpavie for reporting this).

MRXS

Some MRXS files may also use JPEG-XR compression, which OpenSlide does not currently handle, while Bio-Formats does not handle MRXS files at all.

If you encounter problems with MRXS images within QuPath whereby only the low-resolution version of the image is readable, this may be the source of the problem. If so, to be able to open the images in QuPath you could try:

• changing your settings when saving your images in the first place to avoid JPEG-XR (regular JPEG compression should work), or
• opening the images within Pannoramic Viewer and exporting (all or part of the image) to an alternative format that does not use JPEG-XR

Z-stacks, time series & multichannel data

Bio-Formats supports z-stacks, time series and images with multiple color channels (e.g. multiplexed images) - but OpenSlide does not. Therefore if you have a file format that is only supported by OpenSlide (e.g. mrxs) it will only be possible to work with a single plane or RGB data (at best), and not the full image.