OpenSlide: openslide.h File Reference

OpenSlide

Typedefs
openslide.h File Reference

The API for the OpenSlide library. More...

`#include "openslide-features.h"`
`#include <stddef.h>`
`#include <stdint.h>`
`#include <stdbool.h>`

Go to the source code of this file.

## Macros
Predefined Properties
Some predefined properties.
#define | OPENSLIDE_PROPERTY_NAME_BACKGROUND_COLOR "openslide.background-color"
| The name of the property containing a slide's background color, if any.
#define | OPENSLIDE_PROPERTY_NAME_BARCODE "openslide.barcode"
| The name of the property containing a slide's barcode, if any.
#define | OPENSLIDE_PROPERTY_NAME_BOUNDS_HEIGHT "openslide.bounds-height"
| The name of the property containing the height of the rectangle bounding the non-empty region of the slide, if available.
#define | OPENSLIDE_PROPERTY_NAME_BOUNDS_WIDTH "openslide.bounds-width"
| The name of the property containing the width of the rectangle bounding the non-empty region of the slide, if available.
#define | OPENSLIDE_PROPERTY_NAME_BOUNDS_X "openslide.bounds-x"
| The name of the property containing the X coordinate of the rectangle bounding the non-empty region of the slide, if available.
#define | OPENSLIDE_PROPERTY_NAME_BOUNDS_Y "openslide.bounds-y"
| The name of the property containing the Y coordinate of the rectangle bounding the non-empty region of the slide, if available.
#define | OPENSLIDE_PROPERTY_NAME_COMMENT "openslide.comment"
| The name of the property containing a slide's comment, if any.
#define | OPENSLIDE_PROPERTY_NAME_ICC_SIZE "openslide.icc-size"
| The name of the property containing the size of a slide's ICC color profile, if any.
#define | OPENSLIDE_PROPERTY_NAME_MPP_X "openslide.mpp-x"
| The name of the property containing the number of microns per pixel in the X dimension of level 0, if known.
#define | OPENSLIDE_PROPERTY_NAME_MPP_Y "openslide.mpp-y"
| The name of the property containing the number of microns per pixel in the Y dimension of level 0, if known.
#define | OPENSLIDE_PROPERTY_NAME_OBJECTIVE_POWER "openslide.objective-power"
| The name of the property containing a slide's objective power, if known.
#define | OPENSLIDE_PROPERTY_NAME_QUICKHASH1 "openslide.quickhash-1"
| The name of the property containing the "quickhash-1" sum.
#define | OPENSLIDE_PROPERTY_NAME_VENDOR "openslide.vendor"
| The name of the property containing an identification of the vendor.

## Typedefs
typedef struct _openslide | openslide_t
| The main OpenSlide type.
typedef struct _openslide_cache | openslide_cache_t
| An OpenSlide tile cache.

## Functions
Basic Usage
Opening, reading, and closing whole slide images.
const char * | openslide_detect_vendor (const char *filename)
| Quickly determine whether a whole slide image is recognized.
openslide_t * | openslide_open (const char *filename)
| Open a whole slide image.
int32_t | openslide_get_level_count (openslide_t *osr)
| Get the number of levels in the whole slide image.
void | openslide_get_level0_dimensions (openslide_t *osr, int64_t *w, int64_t *h)
| Get the dimensions of level 0 (the largest level).
void | openslide_get_level_dimensions (openslide_t *osr, int32_t level, int64_t *w, int64_t *h)
| Get the dimensions of a level.
double | openslide_get_level_downsample (openslide_t *osr, int32_t level)
| Get the downsampling factor of a given level.
int32_t | openslide_get_best_level_for_downsample (openslide_t *osr, double downsample)
| Get the best level to use for displaying the given downsample.
void | openslide_read_region (openslide_t *osr, uint32_t *dest, int64_t x, int64_t y, int32_t level, int64_t w, int64_t h)
| Copy pre-multiplied ARGB data from a whole slide image.
int64_t | openslide_get_icc_profile_size (openslide_t *osr)
| Get the size in bytes of the ICC color profile for the whole slide image.
void | openslide_read_icc_profile (openslide_t *osr, void *dest)
| Copy the ICC color profile from a whole slide image.
void | openslide_close (openslide_t *osr)
| Close an OpenSlide object.
Error Handling
A simple mechanism for detecting errors. Sometimes an unrecoverable error can occur that will invalidate the OpenSlide object. (This is typically something like an I/O error or data corruption.) When such an error happens in an OpenSlide object, the object will move terminally into an error state. While an object is in an error state, no OpenSlide functions will have any effect on it except for openslide_close(). Functions that are expected to return values will instead return an error value, typically something like NULL or -1. openslide_read_region() will clear its destination buffer instead of painting into it. openslide_get_error() will return a non-NULL string containing an error message. See the documentation for each function for details on what is returned in case of error. This style of error handling allows programs written in C to check for errors only when convenient, because the error state is terminal and the OpenSlide functions return harmlessly when there has been an error. If writing wrappers for OpenSlide in languages that support exceptions, it is recommended that the error state be checked after each call and converted into an exception for that language.
const char * | openslide_get_error (openslide_t *osr)
| Get the current error string.
Properties
Querying properties. Properties are string key-value pairs containing metadata about a whole slide image. These functions allow listing the available properties and obtaining their values. Some properties are officially documented and are expected to be stable; others are undocumented but may still be useful. Many properties are uninterpreted data gathered directly from the slide files. New properties may be added in future releases of OpenSlide.
const char *const * | openslide_get_property_names (openslide_t *osr)
| Get the NULL-terminated array of property names.
const char * | openslide_get_property_value (openslide_t *osr, const char *name)
| Get the value of a single property.
Associated Images
Reading associated images. Certain vendor-specific associated images may exist within a whole slide image, such as label and thumbnail images. Each associated image has a name, dimensions, and pixel data. These functions allow listing the available associated images and reading their contents.
const char *const * | openslide_get_associated_image_names (openslide_t *osr)
| Get the NULL-terminated array of associated image names.
void | openslide_get_associated_image_dimensions (openslide_t *osr, const char *name, int64_t *w, int64_t *h)
| Get the dimensions of an associated image.
void | openslide_read_associated_image (openslide_t *osr, const char *name, uint32_t *dest)
| Copy pre-multiplied ARGB data from an associated image.
int64_t | openslide_get_associated_image_icc_profile_size (openslide_t *osr, const char *name)
| Get the size in bytes of the ICC color profile for an associated image.
void | openslide_read_associated_image_icc_profile (openslide_t *osr, const char *name, void *dest)
| Copy the ICC color profile from an associated image.
Caching
Managing the in-memory tile cache. By default, each OpenSlide object has its own internal cache. These functions can be used to configure a cache with a custom size, which may be shared between multiple OpenSlide objects.
openslide_cache_t * | openslide_cache_create (size_t capacity)
| Create a new tile cache, unconnected to any OpenSlide object.
void | openslide_set_cache (openslide_t *osr, openslide_cache_t *cache)
| Attach a cache to the specified OpenSlide object, replacing the current cache.
void | openslide_cache_release (openslide_cache_t *cache)
| Release the cache.
Miscellaneous
Utility functions.
const char * | openslide_get_version (void)
| Get the version of the OpenSlide library.

## Detailed Description

The API for the OpenSlide library.

All functions except openslide_close() are thread-safe. See the openslide_close() documentation for its restrictions.

## Macro Definition Documentation

## ◆ OPENSLIDE_PROPERTY_NAME_BACKGROUND_COLOR

#define OPENSLIDE_PROPERTY_NAME_BACKGROUND_COLOR "openslide.background-color"

The name of the property containing a slide's background color, if any.

It is represented as an RGB hex triplet.

Since
  3.2.3

## ◆ OPENSLIDE_PROPERTY_NAME_BARCODE

#define OPENSLIDE_PROPERTY_NAME_BARCODE "openslide.barcode"

The name of the property containing a slide's barcode, if any.

Since
  4.0.1

## ◆ OPENSLIDE_PROPERTY_NAME_BOUNDS_HEIGHT

#define OPENSLIDE_PROPERTY_NAME_BOUNDS_HEIGHT "openslide.bounds-height"

The name of the property containing the height of the rectangle bounding the non-empty region of the slide, if available.

Since
  3.4.0

## ◆ OPENSLIDE_PROPERTY_NAME_BOUNDS_WIDTH

#define OPENSLIDE_PROPERTY_NAME_BOUNDS_WIDTH "openslide.bounds-width"

The name of the property containing the width of the rectangle bounding the non-empty region of the slide, if available.

Since
  3.4.0

## ◆ OPENSLIDE_PROPERTY_NAME_BOUNDS_X

#define OPENSLIDE_PROPERTY_NAME_BOUNDS_X "openslide.bounds-x"

The name of the property containing the X coordinate of the rectangle bounding the non-empty region of the slide, if available.

Since
  3.4.0

## ◆ OPENSLIDE_PROPERTY_NAME_BOUNDS_Y

#define OPENSLIDE_PROPERTY_NAME_BOUNDS_Y "openslide.bounds-y"

The name of the property containing the Y coordinate of the rectangle bounding the non-empty region of the slide, if available.

Since
  3.4.0

## ◆ OPENSLIDE_PROPERTY_NAME_COMMENT

#define OPENSLIDE_PROPERTY_NAME_COMMENT "openslide.comment"

The name of the property containing a slide's comment, if any.

Since
  3.0.0

## ◆ OPENSLIDE_PROPERTY_NAME_ICC_SIZE

#define OPENSLIDE_PROPERTY_NAME_ICC_SIZE "openslide.icc-size"

The name of the property containing the size of a slide's ICC color profile, if any.

Since
  4.0.0

## ◆ OPENSLIDE_PROPERTY_NAME_MPP_X

#define OPENSLIDE_PROPERTY_NAME_MPP_X "openslide.mpp-x"

The name of the property containing the number of microns per pixel in the X dimension of level 0, if known.

Since
  3.3.0

## ◆ OPENSLIDE_PROPERTY_NAME_MPP_Y

#define OPENSLIDE_PROPERTY_NAME_MPP_Y "openslide.mpp-y"

The name of the property containing the number of microns per pixel in the Y dimension of level 0, if known.

Since
  3.3.0

## ◆ OPENSLIDE_PROPERTY_NAME_OBJECTIVE_POWER

#define OPENSLIDE_PROPERTY_NAME_OBJECTIVE_POWER "openslide.objective-power"

The name of the property containing a slide's objective power, if known.

Since
  3.3.0

## ◆ OPENSLIDE_PROPERTY_NAME_QUICKHASH1

#define OPENSLIDE_PROPERTY_NAME_QUICKHASH1 "openslide.quickhash-1"

The name of the property containing the "quickhash-1" sum.

Since
  3.0.0

## ◆ OPENSLIDE_PROPERTY_NAME_VENDOR

#define OPENSLIDE_PROPERTY_NAME_VENDOR "openslide.vendor"

The name of the property containing an identification of the vendor.

Since
  3.0.0

## Typedef Documentation

## ◆ openslide_cache_t

typedef struct _openslide_cache openslide_cache_t

An OpenSlide tile cache.

An openslide_cache_t object can be used concurrently from multiple threads without locking. (But you must lock or otherwise use memory barriers when passing the object between threads.)

## ◆ openslide_t

typedef struct _openslide openslide_t

The main OpenSlide type.

An openslide_t object can be used concurrently from multiple threads without locking. (But you must lock or otherwise use memory barriers when passing the object between threads.)

## Function Documentation

## ◆ openslide_cache_create()

openslide_cache_t * openslide_cache_create | ( | size_t | capacity | ) |

Create a new tile cache, unconnected to any OpenSlide object.

The cache can be attached to one or more OpenSlide objects with openslide_set_cache(). The cache must be released with openslide_cache_release() when done.

Parameters

  capacity | The capacity of the cache, in bytes.

Returns
  A new cache.

Since
  4.0.0

References openslide_cache_create().

Referenced by openslide_cache_create().

## ◆ openslide_cache_release()

void openslide_cache_release | ( | openslide_cache_t * | cache | ) |

Release the cache.

The cache may be released while it is still attached to OpenSlide objects. It will be freed once the last attached OpenSlide object is closed.

Parameters

  cache | The cache to release.

Since
  4.0.0

References openslide_cache_release().

Referenced by openslide_cache_release().

## ◆ openslide_close()

void openslide_close | ( | openslide_t * | osr | ) |

Close an OpenSlide object.

No other threads may be using the object. After this function returns, the object cannot be used anymore.

Parameters

  osr | The OpenSlide object.

References openslide_close().

Referenced by openslide_close().

## ◆ openslide_detect_vendor()

const char * openslide_detect_vendor | ( | const char * | filename | ) |

Quickly determine whether a whole slide image is recognized.

If OpenSlide recognizes the file referenced by `filename`, return a string identifying the slide format vendor. This is equivalent to the value of the OPENSLIDE_PROPERTY_NAME_VENDOR property. Calling openslide_open() on this file will return a valid OpenSlide object or an OpenSlide object in error state.

Otherwise, return NULL. Calling openslide_open() on this file will also return NULL.

Parameters

  filename | The filename to check. On Windows, this must be in UTF-8.

Returns
  An identification of the format vendor for this file, or NULL.

Since
  3.4.0

References openslide_detect_vendor().

Referenced by openslide_detect_vendor().

## ◆ openslide_get_associated_image_dimensions()

void openslide_get_associated_image_dimensions | ( | openslide_t * | osr,
|  | const char * | name,
|  | int64_t * | w,
|  | int64_t * | h )

Get the dimensions of an associated image.

This function returns the width and height of an associated image associated with a whole slide image. Once the dimensions are known, use openslide_read_associated_image() to read the image.

Parameters

  | osr | The OpenSlide object.
  | name | The name of the desired associated image. Must be a valid name as given by openslide_get_associated_image_names().
  [out] | w | The width of the associated image, or -1 if an error occurred.
  [out] | h | The height of the associated image, or -1 if an error occurred.

References openslide_get_associated_image_dimensions().

Referenced by openslide_get_associated_image_dimensions().

## ◆ openslide_get_associated_image_icc_profile_size()

int64_t openslide_get_associated_image_icc_profile_size | ( | openslide_t * | osr,
|  | const char * | name )

Get the size in bytes of the ICC color profile for an associated image.

Parameters

  osr | The OpenSlide object.
  name | The name of the desired associated image. Must be a valid name as given by openslide_get_associated_image_names().

Returns
  -1 on error, 0 if no profile is available, otherwise the profile size in bytes.

References openslide_get_associated_image_icc_profile_size().

Referenced by openslide_get_associated_image_icc_profile_size().

## ◆ openslide_get_associated_image_names()

const char *const * openslide_get_associated_image_names | ( | openslide_t * | osr | ) |

Get the NULL-terminated array of associated image names.

This function returns an array of strings naming associated images available in the whole slide image.

Parameters

  osr | The OpenSlide object.

Returns
  A NULL-terminated string array of associated image names, or an empty array if an error occurred.

References openslide_get_associated_image_names().

Referenced by openslide_get_associated_image_names().

## ◆ openslide_get_best_level_for_downsample()

int32_t openslide_get_best_level_for_downsample | ( | openslide_t * | osr,
|  | double | downsample )

Get the best level to use for displaying the given downsample.

Parameters

  osr | The OpenSlide object.
  downsample | The downsample factor.

Returns
  The level identifier, or -1 if an error occurred.

Since
  3.3.0

References openslide_get_best_level_for_downsample().

Referenced by openslide_get_best_level_for_downsample().

## ◆ openslide_get_error()

const char * openslide_get_error | ( | openslide_t * | osr | ) |

Get the current error string.

For a given OpenSlide object, once this function returns a non-NULL value, the only useful operation on the object is to call openslide_close() to free its resources.

Parameters

  osr | The OpenSlide object.

Returns
  A string describing the original error that caused the problem, or NULL if no error has occurred.

Since
  3.2.0

References openslide_get_error().

Referenced by openslide_get_error().

## ◆ openslide_get_icc_profile_size()

int64_t openslide_get_icc_profile_size | ( | openslide_t * | osr | ) |

Get the size in bytes of the ICC color profile for the whole slide image.

Parameters

  osr | The OpenSlide object.

Returns
  -1 on error, 0 if no profile is available, otherwise the profile size in bytes.

References openslide_get_icc_profile_size().

Referenced by openslide_get_icc_profile_size().

## ◆ openslide_get_level0_dimensions()

void openslide_get_level0_dimensions | ( | openslide_t * | osr,
|  | int64_t * | w,
|  | int64_t * | h )

Get the dimensions of level 0 (the largest level).

Exactly equivalent to calling openslide_get_level_dimensions(osr, 0, w, h).

Parameters

  | osr | The OpenSlide object.
  [out] | w | The width of the image, or -1 if an error occurred.
  [out] | h | The height of the image, or -1 if an error occurred.

Since
  3.3.0

References openslide_get_level0_dimensions().

Referenced by openslide_get_level0_dimensions().

## ◆ openslide_get_level_count()

int32_t openslide_get_level_count | ( | openslide_t * | osr | ) |

Get the number of levels in the whole slide image.

Parameters

  osr | The OpenSlide object.

Returns
  The number of levels, or -1 if an error occurred.

Since
  3.3.0

References openslide_get_level_count().

Referenced by openslide_get_level_count().

## ◆ openslide_get_level_dimensions()

void openslide_get_level_dimensions | ( | openslide_t * | osr,
|  | int32_t | level,
|  | int64_t * | w,
|  | int64_t * | h )

Get the dimensions of a level.

Parameters

  | osr | The OpenSlide object.
  | level | The desired level.
  [out] | w | The width of the image, or -1 if an error occurred or the level was out of range.
  [out] | h | The height of the image, or -1 if an error occurred or the level was out of range.

Since
  3.3.0

References openslide_get_level_dimensions().

Referenced by openslide_get_level_dimensions().

## ◆ openslide_get_level_downsample()

double openslide_get_level_downsample | ( | openslide_t * | osr,
|  | int32_t | level )

Get the downsampling factor of a given level.

Parameters

  osr | The OpenSlide object.
  level | The desired level.

Returns
  The downsampling factor for this level, or -1.0 if an error occurred or the level was out of range.

Since
  3.3.0

References openslide_get_level_downsample().

Referenced by openslide_get_level_downsample().

## ◆ openslide_get_property_names()

const char *const * openslide_get_property_names | ( | openslide_t * | osr | ) |

Get the NULL-terminated array of property names.

This function returns an array of strings naming properties available in the whole slide image.

Parameters

  osr | The OpenSlide object.

Returns
  A NULL-terminated string array of property names, or an empty array if an error occurred.

References openslide_get_property_names().

Referenced by openslide_get_property_names().

## ◆ openslide_get_property_value()

const char * openslide_get_property_value | ( | openslide_t * | osr,
|  | const char * | name )

Get the value of a single property.

This function returns the value of the property given by `name`.

Parameters

  osr | The OpenSlide object.
  name | The name of the desired property. Must be a valid name as given by openslide_get_property_names().

Returns
  The value of the named property, or NULL if the property doesn't exist or an error occurred.

References openslide_get_property_value().

Referenced by openslide_get_property_value().

## ◆ openslide_get_version()

const char * openslide_get_version | ( | void |  | ) |

Get the version of the OpenSlide library.

Returns
  A string describing the OpenSlide version.

Since
  3.3.0

References openslide_get_version().

Referenced by openslide_get_version().

## ◆ openslide_open()

openslide_t * openslide_open | ( | const char * | filename | ) |

Open a whole slide image.

This function can be expensive; avoid calling it unnecessarily. For example, a tile server should not call openslide_open() on every tile request. Instead, it should maintain a cache of OpenSlide objects and reuse them when possible.

Parameters

  filename | The filename to open. On Windows, this must be in UTF-8.

Returns
  On success, a new OpenSlide object. If the file is not recognized by OpenSlide, NULL. If the file is recognized but an error occurred, an OpenSlide object in error state.

References openslide_open().

Referenced by openslide_open().

## ◆ openslide_read_associated_image()

void openslide_read_associated_image | ( | openslide_t * | osr,
|  | const char * | name,
|  | uint32_t * | dest )

Copy pre-multiplied ARGB data from an associated image.

This function reads and decompresses an associated image associated with a whole slide image. `dest` must be a valid pointer to enough memory to hold the image, at least (width * height * 4) bytes in length. Get the width and height with openslide_get_associated_image_dimensions().

If an error occurs or has occurred, then the memory pointed to by `dest` will be cleared. In versions prior to 4.0.0, this function did nothing if an error occurred.

The returned pixel data is in device color space. The associated image's ICC color profile, if available, can be read with openslide_read_associated_image_icc_profile() and used to transform the pixels for display.

For more information about processing pre-multiplied pixel data, see the OpenSlide website.

Parameters

  osr | The OpenSlide object.
  name | The name of the desired associated image. Must be a valid name as given by openslide_get_associated_image_names().
  dest | The destination buffer for the ARGB data.

References openslide_read_associated_image().

Referenced by openslide_read_associated_image().

## ◆ openslide_read_associated_image_icc_profile()

void openslide_read_associated_image_icc_profile | ( | openslide_t * | osr,
|  | const char * | name,
|  | void * | dest )

Copy the ICC color profile from an associated image.

This function reads the ICC color profile from an associated image into the specified memory location. `dest` must be a valid pointer to enough memory to hold the profile. Get the profile size with openslide_get_associated_image_icc_profile_size().

If an error occurs or has occurred, then the memory pointed to by `dest` will be cleared.

Parameters

  osr | The OpenSlide object.
  name | The name of the desired associated image. Must be a valid name as given by openslide_get_associated_image_names().
  dest | The destination buffer for the ICC color profile.

References openslide_read_associated_image_icc_profile().

Referenced by openslide_read_associated_image_icc_profile().

## ◆ openslide_read_icc_profile()

void openslide_read_icc_profile | ( | openslide_t * | osr,
|  | void * | dest )

Copy the ICC color profile from a whole slide image.

This function reads the ICC color profile from the slide into the specified memory location. `dest` must be a valid pointer to enough memory to hold the profile. Get the profile size with openslide_get_icc_profile_size().

If an error occurs or has occurred, then the memory pointed to by `dest` will be cleared.

Parameters

  osr | The OpenSlide object.
  dest | The destination buffer for the ICC color profile.

References openslide_read_icc_profile().

Referenced by openslide_read_icc_profile().

## ◆ openslide_read_region()

void openslide_read_region | ( | openslide_t * | osr,
|  | uint32_t * | dest,
|  | int64_t | x,
|  | int64_t | y,
|  | int32_t | level,
|  | int64_t | w,
|  | int64_t | h )

Copy pre-multiplied ARGB data from a whole slide image.

This function reads and decompresses a region of a whole slide image into the specified memory location. `dest` must be a valid pointer to enough memory to hold the region, at least (`w` * `h` * 4) bytes in length. If an error occurs or has occurred, then the memory pointed to by `dest` will be cleared.

The returned pixel data is in device color space. The slide's ICC color profile, if available, can be read with openslide_read_icc_profile() and used to transform the pixels for display.

For more information about processing pre-multiplied pixel data, see the OpenSlide website.

Parameters

  osr | The OpenSlide object.
  dest | The destination buffer for the ARGB data.
  x | The top left x-coordinate, in the level 0 reference frame.
  y | The top left y-coordinate, in the level 0 reference frame.
  level | The desired level.
  w | The width of the region. Must be non-negative.
  h | The height of the region. Must be non-negative.

References openslide_read_region().

Referenced by openslide_read_region().

## ◆ openslide_set_cache()

void openslide_set_cache | ( | openslide_t * | osr,
|  | openslide_cache_t * | cache )

Attach a cache to the specified OpenSlide object, replacing the current cache.

Parameters

  osr | The OpenSlide object.
  cache | The cache to attach.

Since
  4.0.0

References openslide_set_cache().

Referenced by openslide_set_cache().