OpenSlide 4.0.0 released

Thu Oct 12 01:09:29 EDT 2023

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 4.0.0 can be obtained at [0].  OpenSlide is released under
the terms of the GNU Lesser General Public License, version 2.1.

[0]: https://openslide.org/download/

## DICOM WSI support

OpenSlide can now read slide images in DICOM format using libdicom
[1]. 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 [2].

[1]: https://github.com/ImagingDataCommons/libdicom
[2]: https://github.com/openslide/openslide/issues/new/choose

## 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) [3]
openslide_read_icc_profile(osr, dest) [4]
openslide_get_associated_image_icc_profile_size(osr, name) [5]
openslide_read_associated_image_icc_profile(osr, name, dest) [6]

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

[3]: https://openslide.org/api/openslide_8h.html#a323af3836966ea1973d09b1a8ccf771f
[4]: https://openslide.org/api/openslide_8h.html#acaf491a585651d634735d0a61cf7fae2
[5]: https://openslide.org/api/openslide_8h.html#a4a31de687aefba75055769fba6e80b35
[6]: https://openslide.org/api/openslide_8h.html#a26322f1638fb8c4c683a08ca1b5d3d4a

## Tile cache customization

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

openslide_cache_create(capacity) [7]
openslide_set_cache(osr, cache) [8]
openslide_cache_release(cache) [9]

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

[7]: https://openslide.org/api/openslide_8h.html#a611c06edc3173aa7f5fa60544a5b3a18
[8]: https://openslide.org/api/openslide_8h.html#a15904ac24a0beb733f43667aab17b2a5
[9]: https://openslide.org/api/openslide_8h.html#a870e374a309aaf96cbd36ba49c55ec8a

## 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() [10] 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.

[10]: https://openslide.org/api/openslide_8h.html#a71ace07f87c9aeab328d3a6efcd2f983

## 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 [0] for
instructions on enabling these repos.

## How to help

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

[11]: https://github.com/openslide/openslide/wiki/DesiredTestData
[12]: https://openslide.org/submit/
[13]: https://creativecommons.org/public-domain/cc0/

## 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