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

OpenSlide 3.4.1

• New formats: Philips TIFF, Ventana TIFF
• Support OpenJPEG 2.1.0
• Improve performance of JPEG and JP2K decoding
• Add openslide.region[i].* properties
• Improve MATLAB compatibility
• Enable function deprecation warnings with MSVC
• Many portability fixes
• aperio: Detect OpenJPEG chroma subsampling breakage during open
• aperio: Fill in missing tiles with downsampled data
• aperio: Report MPP for slides scanned in locales with decimal comma
• hamamatsu: Support NDPI files > 4 GB
• hamamatsu: Properly detect NDPI slides produced by NDP.toolkit
• hamamatsu: Support VMS/VMU slides without a NoLayers key
• hamamatsu: Report MPP for VMS/VMU
• leica: Support slides with 2010/03/10 XML namespace
• leica: Base64-decode leica.barcode property in 2010/10/01 namespace
• sakura: Support slides with multiple focal planes
• sakura: Support slides without tile table
• ventana: Support slides with multiple focal planes
• ventana: Improve positioning of AOIs within level
• ventana: Fix failure to recognize macro image on some slides

OpenSlide 3.4.0

• Major internal restructuring
• New formats: Hamamatsu NDPI, Sakura SVSLIDE, Ventana BIF (preliminary)
• Add openslide_detect_vendor()
• Deprecate openslide_can_open() (not very useful and often misused)
• Document performance considerations for openslide_open()
• Add properties giving the bounds of the non-empty region of the slide
• leica: Support multiple main images if their levels are coplanar
• leica: Use slide size as level size
• mirax: Support PNG- and BMP-formatted slides
• mirax: Fix "Expected first 0 value" error opening some slides
• mirax: Fix incorrect tile placement on some slides without overlaps
• mirax: Never synthesize downsampled levels
• Add OPENSLIDE_DEBUG environment variable (OPENSLIDE_DEBUG=? for help)
• Fix some crashes in error paths
• Add tests for many error paths

OpenSlide 3.3.3

• Fix inclusion of openslide.h with MSVC
• Properly handle Aperio JP2K slides with zero-length tiles
• Support Hamamatsu slides with blank MacroImage key

OpenSlide 3.3.2

• Fix seams in MIRAX 2.2 slides (thanks, Agelos Pappas)
• Fix associated image naming in single-level Aperio slides
• Stop decoding MIRAX tiles outside requested region
• Stop decoding unneeded tiles during tile-aligned accesses
• Increase Hamamatsu VMU tile size to reduce rendering overhead
• Document performance considerations for openslide_can_open()

OpenSlide 3.3.1

• Parallelize concurrent openslide_read_region calls on an openslide_t
• Eliminate background scanning of tile headers in MIRAX
• Scan many fewer tiles during first accesses to Hamamatsu VMS
• Ignore Leica Z-planes other than 0
• Add experimental tile-size properties
• Document API thread safety

OpenSlide 3.3.0

• Support Leica SCN format (requires libtiff >= 4) (thanks, Agelos Pappas)
• Allow opening MIRAX 2.2 slides (though there are seams, bug #92)
• Add standardized microns-per-pixel and objective-power properties
• Add "macro" associated image in Trestle
• Rename "layer" to "level" throughout the API (deprecate "layer" functions;
  remove "layer" properties)
• Report parse errors in openslide_open() by returning an openslide_t in
  error state
• Deprecate openslide_get_comment()
• Add openslide_get_version()
• Improve command-line tools; add manpages
• Support building with MinGW-w64; drop CMake, MSVC, mingw32
• Add tests for many error paths

OpenSlide 3.2.6

• Support downsampled MIRAX files
• Improve performance on MIRAX slides without tile overlaps
• Fix openslide_read_region for large dimensions on layer > 0
  (3.2.5 regression)
• Correct subpixel error in MIRAX tile placement
• Fix unlikely use-after-free with Hamamatsu VMU

OpenSlide 3.2.5

• Support MIRAX 1.03 files (thanks, Jan Harkes)
• Fix openslide_read_region for large dimensions
• Use subpixel precision in all backends
• Don't keep associated images in memory
• Disable quickhash-1 for TIFF files with very large top layer
• Various build fixes (thanks, Jan, Marco Feuerstein, and
  Mathieu Malaterre)
• Fix some unlikely memory leaks

OpenSlide 3.2.4

• Support MIRAX files that do not have non-hierarchical data
  (thanks, Jan Harkes)
• Fix compilation on Windows (thanks Hauke Heibel)
• Work around a bug in GKeyFile parser (thanks, Jan)