OpenSlide 4.0.0

OpenSlide is a C library that provides a simple way to read whole-slide images, also known as virtual slides. OpenSlide 4.0.0, the first new OpenSlide release in 8 years, is a major release that adds support for DICOM WSI slides, ICC color profiles, tile cache customization, adds the slidetool command-line utility, removes deprecated APIs, and improves format compatibility.

OpenSlide is released under the terms of the GNU Lesser General Public License, version 2.1.

DICOM WSI support

OpenSlide can now read slide images in DICOM format using libdicom (see demo). It supports uncompressed, JPEG, and JPEG 2000 images, full and sparse tiling, associated images, and DICOM metadata properties.

OpenSlide aims to support most popular DICOM WSI variants. If you have a sample file which does not work well, please open an issue.

ICC color profile support

Several scanner vendors now include ICC color profiles in their slide formats. These profiles can be used to improve the color rendering of slide images. OpenSlide now has APIs to read these profiles:

openslide_get_icc_profile_size(osr)
openslide_read_icc_profile(osr, dest)
openslide_get_associated_image_icc_profile_size(osr, name)
openslide_read_associated_image_icc_profile(osr, name, dest)

openslide-write-png and slidetool now attach ICC profiles to PNG images they write. ICC profiles are currently supported by the Aperio, DICOM, Ventana, and generic TIFF vendor drivers.

Tile cache customization

OpenSlide has new APIs to share tile caches between OpenSlide objects and to configure their capacity:

openslide_cache_create(capacity)
openslide_set_cache(osr, cache)
openslide_cache_release(cache)

By default, OpenSlide objects continue to use non-shared 32 MiB caches.

New slidetool utility

OpenSlide 4.0 introduces the slidetool command-line program, with subcommands providing access to all OpenSlide functionality. The openslide-quickhash1sum, openslide-show-properties, and openslide-write-png commands are still provided but will not receive additional functionality in the future.

Breaking API changes

OpenSlide 4.0 introduces several API changes, all of which are unlikely to affect applications:

• Removed nine API functions which have been deprecated since 2014
• openslide_read_associated_image() now clears the dest buffer on error, and no longer accepts a NULL dest
• The GLib log domain changed from Openslide to OpenSlide

The soname has been changed, which renames the library file to libopenslide.so.1 on Linux, libopenslide.1.dylib on macOS, and libopenslide-1.dll on Windows. Dependent packages will need to be rebuilt, and any code that dynamically loads OpenSlide at runtime will need to use the new filenames.

Building from source

The Autotools-based build system has been replaced with Meson. OpenSlide 4.0 can be built with these commands:

meson setup builddir
meson compile -C builddir
meson test -C builddir          # optional
sudo meson install -C builddir

Getting binaries

OpenSlide Windows build 20231011 now provides a single DLL containing OpenSlide and all its dependencies. In addition, the DLL now uses the Universal C Runtime (UCRT) rather than MSVCRT.

OpenSlide now provides a Fedora Copr and an Ubuntu PPA, enabling users of Fedora, Ubuntu, and RHEL-compatible enterprise Linux to easily install the latest OpenSlide and OpenSlide Python releases before they reach the official repositories. See the download page for instructions on enabling these repos.

How to help

If you have a slide scanner that can produce files we don't have, or ones OpenSlide can't read, please consider contributing a sample. If you grant us permission to redistribute your sample under the Creative Commons Zero license, we can use it in automated tests and share it with other developers working on open source WSI support!

Acknowledgements

Development of DICOM and ICC functionality was supported by NCI Imaging Data Commons and has been funded in whole or in part with Federal funds from the National Cancer Institute, National Institutes of Health, under Task Order No. HHSN26110071 under Contract No. HHSN261201500003l.

Full changelog

Breaking changes

• Update soname to libopenslide.so.1
• Remove all deprecated functions
• Clear openslide_read_associated_image() output buffer on error
• Remove undocumented NULL dest support in openslide_read_associated_image()
• Change GLib log domain to OpenSlide
• Convert build system to Meson (thanks, Jan Harkes)

New features

• New format: DICOM WSI (thanks, John Cupitt and Jim O'Donnell)
• Add APIs to read ICC color profiles (thanks, John)
• Add APIs to configure tile cache size and share caches between slides
• Add properties for associated image metadata
• generic-tiff: Set MPP properties if available
• philips: Set objective power property if available
• Add slidetool command-line tool which supports all OpenSlide features
• Combine all command-line tools into the same binary
• Add ICC profile to PNG images written by command-line tools
• Add self-test that doesn't require sample data (run with meson test)

Changes

• Require libtiff ≥ 4, OpenJPEG ≥ 2.1, GLib ≥ 2.56, SQLite ≥ 3.14
• Require libdicom ≥ 1.0, with build-time fallback for now
• Remove support for including openslide.h in Visual Studio < 2013
• Fail openslide_open() with a broken pixman 0.38.x
• Avoid extra buffer copy in openslide_read_region()
• Replace goto-based cleanup with g_autoptr
• Stop using deprecated GLib slice allocator
• Use internal wrappers for file I/O
• Documentation improvements

Bug fixes

• Use UTF-8 filenames on Windows
• Improve openslide-write-png performance for very large regions
• Fix assertions on JPEG decode errors when compiled with Clang
• Portability fixes (thanks, Billy Robert O'Neal III and Kleis Auke Wolthuizen)
• aperio: Set objective power property even if floating point
• hamamatsu: Fix Restart marker not found on VMS slides with multiple Z-layers
• hamamatsu: Fix integer overflow in VMS parsing (thanks, Adam Goode)
• mirax: Fix Expected 1 value error
• philips: Don't cache missing tiles
• sakura: Fix memory leak reading missing tile