OpenSlide
Typedefs
openslide.h File Reference

The API for the OpenSlide library. More...

#include <openslide-features.h>
#include <stdio.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_COMMENT   "openslide.comment"
 The name of the property containing a slide's comment, if any.
#define OPENSLIDE_PROPERTY_NAME_VENDOR   "openslide.vendor"
 The name of the property containing an identification of the vendor.
#define OPENSLIDE_PROPERTY_NAME_QUICKHASH1   "openslide.quickhash-1"
 The name of the property containing the "quickhash-1" sum.
#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_OBJECTIVE_POWER   "openslide.objective-power"
 The name of the property containing a slide's objective power, if known.
#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.

Typedefs

typedef struct _openslide openslide_t
 The main OpenSlide type.

Functions

Basic Usage

Opening, reading, and closing.

bool openslide_can_open (const char *filename)
 Do a quick check to see if a whole slide image is valid.
openslide_topenslide_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.
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.

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.

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

Utility functions.

const char * openslide_get_version (void)
 Get the version of the OpenSlide library.
Deprecated Functions

Functions that will be removed in the next major release.

Before version 3.3.0, OpenSlide used the term "layer" to refer to a slide level. Many of these functions use the older terminology.

int32_t openslide_get_layer_count (openslide_t *osr)
 Get the number of levels in the whole slide image.
void openslide_get_layer0_dimensions (openslide_t *osr, int64_t *w, int64_t *h)
 Get the dimensions of level 0 (the largest level).
void openslide_get_layer_dimensions (openslide_t *osr, int32_t level, int64_t *w, int64_t *h)
 Get the dimensions of a level.
double openslide_get_layer_downsample (openslide_t *osr, int32_t level)
 Get the downsampling factor of a given level.
int32_t openslide_get_best_layer_for_downsample (openslide_t *osr, double downsample)
 Get the best level to use for displaying the given downsample.
const char * openslide_get_comment (openslide_t *osr)
 Get the comment (if any) for this image.

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

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

Function Documentation

bool openslide_can_open ( const char *  filename)

Do a quick check to see if a whole slide image is valid.

This function is more efficient than openslide_open() if you do not necessarily intend to open the specified file (for example, when creating a list of available slide files). If you definitely intend to open the file, calling this function will only reduce performance; you should call openslide_open() directly.

Parameters:
filenameThe filename to check.
Returns:
If openslide_open() will succeed.
void openslide_close ( openslide_t osr)

Close an OpenSlide object.

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

Parameters:
osrThe OpenSlide object.
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:
osrThe OpenSlide object.
nameThe name of the desired associated image. Must be a valid name as given by openslide_get_associated_image_names().
[out]wThe width of the associated image, or -1 if an error occurred.
[out]hThe height of the associated image, or -1 if an error occurred.
const char* const* openslide_get_associated_image_names ( openslide_t osr)

Get the NULL-terminated array of associated image names.

Certain vendor-specific associated images may exist within a whole slide image. They are encoded as key-value pairs. This call provides a list of names as strings that can be used to read associated images with openslide_get_associated_image_dimensions() and openslide_read_associated_image().

Parameters:
osrThe OpenSlide object.
Returns:
A NULL-terminated string array of associated image names, or an empty array if an error occurred.
int32_t openslide_get_best_layer_for_downsample ( openslide_t osr,
double  downsample 
)

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

Parameters:
osrThe OpenSlide object.
downsampleThe downsample factor.
Returns:
The level identifier, or -1 if an error occurred.
Deprecated:
Use openslide_get_best_level_for_downsample() instead.
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:
osrThe OpenSlide object.
downsampleThe downsample factor.
Returns:
The level identifier, or -1 if an error occurred.
Since:
3.3.0
const char* openslide_get_comment ( openslide_t osr)

Get the comment (if any) for this image.

Exactly equivalent to calling openslide_get_property_value() with OPENSLIDE_PROPERTY_NAME_COMMENT.

Parameters:
osrThe OpenSlide object.
Returns:
The comment for this image, or NULL if an error occurred.
Deprecated:
Call openslide_get_property_value() with OPENSLIDE_PROPERTY_NAME_COMMENT instead.
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:
osrThe OpenSlide object.
Returns:
A string describing the original error that caused the problem, or NULL if no error has occurred.
Since:
3.2.0
void openslide_get_layer0_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:
osrThe OpenSlide object.
[out]wThe width of the image, or -1 if an error occurred.
[out]hThe height of the image, or -1 if an error occurred.
Deprecated:
Use openslide_get_level0_dimensions() instead.
int32_t openslide_get_layer_count ( openslide_t osr)

Get the number of levels in the whole slide image.

Parameters:
osrThe OpenSlide object.
Returns:
The number of levels, or -1 if an error occurred.
Deprecated:
Use openslide_get_level_count() instead.
void openslide_get_layer_dimensions ( openslide_t osr,
int32_t  level,
int64_t *  w,
int64_t *  h 
)

Get the dimensions of a level.

Parameters:
osrThe OpenSlide object.
levelThe desired level.
[out]wThe width of the image, or -1 if an error occurred or the level was out of range.
[out]hThe height of the image, or -1 if an error occurred or the level was out of range.
Deprecated:
Use openslide_get_level_dimensions() instead.
double openslide_get_layer_downsample ( openslide_t osr,
int32_t  level 
)

Get the downsampling factor of a given level.

Parameters:
osrThe OpenSlide object.
levelThe desired level.
Returns:
The downsampling factor for this level, or -1.0 if an error occurred or the level was out of range.
Deprecated:
Use openslide_get_level_downsample() instead.
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:
osrThe OpenSlide object.
[out]wThe width of the image, or -1 if an error occurred.
[out]hThe height of the image, or -1 if an error occurred.
Since:
3.3.0
int32_t openslide_get_level_count ( openslide_t osr)

Get the number of levels in the whole slide image.

Parameters:
osrThe OpenSlide object.
Returns:
The number of levels, or -1 if an error occurred.
Since:
3.3.0
void openslide_get_level_dimensions ( openslide_t osr,
int32_t  level,
int64_t *  w,
int64_t *  h 
)

Get the dimensions of a level.

Parameters:
osrThe OpenSlide object.
levelThe desired level.
[out]wThe width of the image, or -1 if an error occurred or the level was out of range.
[out]hThe height of the image, or -1 if an error occurred or the level was out of range.
Since:
3.3.0
double openslide_get_level_downsample ( openslide_t osr,
int32_t  level 
)

Get the downsampling factor of a given level.

Parameters:
osrThe OpenSlide object.
levelThe 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
const char* const* openslide_get_property_names ( openslide_t osr)

Get the NULL-terminated array of property names.

Certain vendor-specific metadata properties may exist within a whole slide image. They are encoded as key-value pairs. This call provides a list of names as strings that can be used to read properties with openslide_get_property_value().

Parameters:
osrThe OpenSlide object.
Returns:
A NULL-terminated string array of property names, or an empty array if an error occurred.
const char* openslide_get_property_value ( openslide_t osr,
const char *  name 
)

Get the value of a single property.

Certain vendor-specific metadata properties may exist within a whole slide image. They are encoded as key-value pairs. This call provides the value of the property given by name.

Parameters:
osrThe OpenSlide object.
nameThe 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.
const char* openslide_get_version ( void  )

Get the version of the OpenSlide library.

Returns:
A string describing the OpenSlide version.
Since:
3.3.0
openslide_t* openslide_open ( const char *  filename)

Open a whole slide image.

Parameters:
filenameThe filename to open.
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.
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(). This call does nothing if an error occurred.

Parameters:
osrThe OpenSlide object.
destThe destination buffer for the ARGB data.
nameThe name of the desired associated image. Must be a valid name as given by openslide_get_associated_image_names().
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.

Parameters:
osrThe OpenSlide object.
destThe destination buffer for the ARGB data.
xThe top left x-coordinate, in the level 0 reference frame.
yThe top left y-coordinate, in the level 0 reference frame.
levelThe desired level.
wThe width of the region. Must be non-negative.
hThe height of the region. Must be non-negative.