OpenSlide
|
The API for the OpenSlide library. More...
#include "openslide-features.h"
#include <stdint.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. More... | |
#define | OPENSLIDE_PROPERTY_NAME_OBJECTIVE_POWER "openslide.objective-power" |
The name of the property containing a slide's objective power, if known. More... | |
#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. More... | |
#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. More... | |
#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. More... | |
#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. More... | |
#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. More... | |
#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. More... | |
Typedefs | |
typedef struct _openslide | openslide_t |
The main OpenSlide type. | |
Functions | |
Basic Usage | |
Opening, reading, and closing. | |
const char * | openslide_detect_vendor (const char *filename) |
Quickly determine whether a whole slide image is recognized. More... | |
openslide_t * | openslide_open (const char *filename) |
Open a whole slide image. More... | |
int32_t | openslide_get_level_count (openslide_t *osr) |
Get the number of levels in the whole slide image. More... | |
void | openslide_get_level0_dimensions (openslide_t *osr, int64_t *w, int64_t *h) |
Get the dimensions of level 0 (the largest level). More... | |
void | openslide_get_level_dimensions (openslide_t *osr, int32_t level, int64_t *w, int64_t *h) |
Get the dimensions of a level. More... | |
double | openslide_get_level_downsample (openslide_t *osr, int32_t level) |
Get the downsampling factor of a given level. More... | |
int32_t | openslide_get_best_level_for_downsample (openslide_t *osr, double downsample) |
Get the best level to use for displaying the given downsample. More... | |
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. More... | |
void | openslide_close (openslide_t *osr) |
Close an OpenSlide object. More... | |
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. More... | |
Properties | |
Querying properties. | |
const char *const * | openslide_get_property_names (openslide_t *osr) |
Get the NULL-terminated array of property names. More... | |
const char * | openslide_get_property_value (openslide_t *osr, const char *name) |
Get the value of a single property. More... | |
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. More... | |
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. More... | |
void | openslide_read_associated_image (openslide_t *osr, const char *name, uint32_t *dest) |
Copy pre-multiplied ARGB data from an associated image. More... | |
Miscellaneous | |
Utility functions. | |
const char * | openslide_get_version (void) |
Get the version of the OpenSlide library. More... | |
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. | |
bool | openslide_can_open (const char *filename) |
Return whether openslide_open() will succeed. More... | |
int32_t | openslide_get_layer_count (openslide_t *osr) |
Get the number of levels in the whole slide image. More... | |
void | openslide_get_layer0_dimensions (openslide_t *osr, int64_t *w, int64_t *h) |
Get the dimensions of level 0 (the largest level). More... | |
void | openslide_get_layer_dimensions (openslide_t *osr, int32_t level, int64_t *w, int64_t *h) |
Get the dimensions of a level. More... | |
double | openslide_get_layer_downsample (openslide_t *osr, int32_t level) |
Get the downsampling factor of a given level. More... | |
int32_t | openslide_get_best_layer_for_downsample (openslide_t *osr, double downsample) |
Get the best level to use for displaying the given downsample. More... | |
const char * | openslide_get_comment (openslide_t *osr) |
Get the comment (if any) for this image. More... | |
The API for the OpenSlide library.
All functions except openslide_close() are thread-safe. See the openslide_close() documentation for its restrictions.
#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.
#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_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.
bool openslide_can_open | ( | const char * | filename | ) |
Return whether openslide_open() will succeed.
This function returns true
if openslide_open() will return a valid openslide_t, or false
if it will return NULL or an openslide_t in error state. As such, there's no reason to use it; just call openslide_open(). For a less-expensive test that provides weaker guarantees, see openslide_detect_vendor().
Before version 3.4.0, this function could be slightly faster than calling openslide_open(), but it could also erroneously return true
in some cases where openslide_open() would fail.
filename | The filename to check. |
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.
osr | The OpenSlide object. |
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.
filename | The filename to check. |
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.
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. |
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().
osr | The OpenSlide object. |
int32_t openslide_get_best_layer_for_downsample | ( | openslide_t * | osr, |
double | downsample | ||
) |
Get the best level to use for displaying the given downsample.
osr | The OpenSlide object. |
downsample | The downsample factor. |
int32_t openslide_get_best_level_for_downsample | ( | openslide_t * | osr, |
double | downsample | ||
) |
Get the best level to use for displaying the given downsample.
osr | The OpenSlide object. |
downsample | The downsample factor. |
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.
osr | The OpenSlide object. |
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.
osr | The OpenSlide object. |
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).
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. |
int32_t openslide_get_layer_count | ( | openslide_t * | osr | ) |
Get the number of levels in the whole slide image.
osr | The OpenSlide object. |
void openslide_get_layer_dimensions | ( | openslide_t * | osr, |
int32_t | level, | ||
int64_t * | w, | ||
int64_t * | h | ||
) |
Get the dimensions of a level.
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. |
double openslide_get_layer_downsample | ( | openslide_t * | osr, |
int32_t | level | ||
) |
Get the downsampling factor of a given level.
osr | The OpenSlide object. |
level | The desired level. |
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).
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. |
int32_t openslide_get_level_count | ( | openslide_t * | osr | ) |
Get the number of levels in the whole slide image.
osr | The OpenSlide object. |
void openslide_get_level_dimensions | ( | openslide_t * | osr, |
int32_t | level, | ||
int64_t * | w, | ||
int64_t * | h | ||
) |
Get the dimensions of a level.
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. |
double openslide_get_level_downsample | ( | openslide_t * | osr, |
int32_t | level | ||
) |
Get the downsampling factor of a given level.
osr | The OpenSlide object. |
level | The desired level. |
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().
osr | The OpenSlide object. |
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
.
osr | The OpenSlide object. |
name | The name of the desired property. Must be a valid name as given by openslide_get_property_names(). |
const char* openslide_get_version | ( | void | ) |
Get the version of the OpenSlide library.
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.
filename | The filename to open. |
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.
osr | The OpenSlide object. |
dest | The destination buffer for the ARGB data. |
name | The 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.
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. |