Orthanc Plugin SDK: Images and compression

| Orthanc Plugin SDK 1.3.0 Documentation of the plugin interface of Orthanc

Typedefs | Enumerations | Functions
Images and compression

Functions to deal with images and compressed buffers. More...

## Typedefs
typedef struct _OrthancPluginImage_t | OrthancPluginImage
| Opaque structure that represents an image that is uncompressed in memory.
typedef struct _OrthancPluginStorageArea_t | OrthancPluginStorageArea
| Opaque structure that represents the storage area that is actually used by Orthanc.

## Enumerations
enum | OrthancPluginPixelFormat { OrthancPluginPixelFormat_Grayscale8 , OrthancPluginPixelFormat_Grayscale16 , OrthancPluginPixelFormat_SignedGrayscale16 , OrthancPluginPixelFormat_RGB24 , OrthancPluginPixelFormat_RGBA32 , OrthancPluginPixelFormat_Unknown , _OrthancPluginPixelFormat_INTERNAL }
enum | OrthancPluginCompressionType { OrthancPluginCompressionType_Zlib , OrthancPluginCompressionType_ZlibWithSize , OrthancPluginCompressionType_Gzip , OrthancPluginCompressionType_GzipWithSize , _OrthancPluginCompressionType_INTERNAL }
enum | OrthancPluginImageFormat { OrthancPluginImageFormat_Png , OrthancPluginImageFormat_Jpeg , OrthancPluginImageFormat_Dicom , _OrthancPluginImageFormat_INTERNAL }

## Functions
OrthancPluginErrorCode | OrthancPluginBufferCompression (OrthancPluginContext *context, OrthancPluginMemoryBuffer *target, const void *source, uint32_t size, OrthancPluginCompressionType compression, uint8_t uncompress)
| Compress or decompress a buffer. More...
OrthancPluginPixelFormat | OrthancPluginGetImagePixelFormat (OrthancPluginContext *context, const OrthancPluginImage *image)
| Return the pixel format of an image. More...
uint32_t | OrthancPluginGetImageWidth (OrthancPluginContext *context, const OrthancPluginImage *image)
| Return the width of an image. More...
uint32_t | OrthancPluginGetImageHeight (OrthancPluginContext *context, const OrthancPluginImage *image)
| Return the height of an image. More...
uint32_t | OrthancPluginGetImagePitch (OrthancPluginContext *context, const OrthancPluginImage *image)
| Return the pitch of an image. More...
void * | OrthancPluginGetImageBuffer (OrthancPluginContext *context, const OrthancPluginImage *image)
| Return a pointer to the content of an image. More...
OrthancPluginImage * | OrthancPluginUncompressImage (OrthancPluginContext *context, const void *data, uint32_t size, OrthancPluginImageFormat format)
| Decode a compressed image. More...
void | OrthancPluginFreeImage (OrthancPluginContext *context, OrthancPluginImage *image)
| Free an image. More...
OrthancPluginErrorCode | OrthancPluginCompressPngImage (OrthancPluginContext *context, OrthancPluginMemoryBuffer *target, OrthancPluginPixelFormat format, uint32_t width, uint32_t height, uint32_t pitch, const void *buffer)
| Encode a PNG image. More...
OrthancPluginErrorCode | OrthancPluginCompressJpegImage (OrthancPluginContext *context, OrthancPluginMemoryBuffer *target, OrthancPluginPixelFormat format, uint32_t width, uint32_t height, uint32_t pitch, const void *buffer, uint8_t quality)
| Encode a JPEG image. More...
OrthancPluginImage * | OrthancPluginConvertPixelFormat (OrthancPluginContext *context, const OrthancPluginImage *source, OrthancPluginPixelFormat targetFormat)
| Change the pixel format of an image. More...
uint32_t | OrthancPluginGetFontsCount (OrthancPluginContext *context)
| Return the number of available fonts. More...
const char * | OrthancPluginGetFontName (OrthancPluginContext *context, uint32_t fontIndex)
| Return the name of a font. More...
uint32_t | OrthancPluginGetFontSize (OrthancPluginContext *context, uint32_t fontIndex)
| Return the size of a font. More...
OrthancPluginErrorCode | OrthancPluginDrawText (OrthancPluginContext *context, OrthancPluginImage *image, uint32_t fontIndex, const char *utf8Text, int32_t x, int32_t y, uint8_t r, uint8_t g, uint8_t b)
| Draw text on an image. More...
OrthancPluginImage * | OrthancPluginCreateImage (OrthancPluginContext *context, OrthancPluginPixelFormat format, uint32_t width, uint32_t height)
| Create an image. More...
OrthancPluginImage * | OrthancPluginCreateImageAccessor (OrthancPluginContext *context, OrthancPluginPixelFormat format, uint32_t width, uint32_t height, uint32_t pitch, void *buffer)
| Create an image pointing to a memory buffer. More...
OrthancPluginImage * | OrthancPluginDecodeDicomImage (OrthancPluginContext *context, const void *buffer, uint32_t bufferSize, uint32_t frameIndex)
| Decode one frame from a DICOM instance. More...

## Detailed Description

## Enumeration Type Documentation

## ◆ OrthancPluginCompressionType

enum OrthancPluginCompressionType

The compression algorithms that are supported by the Orthanc core.

Enumerator
OrthancPluginCompressionType_Zlib | Standard zlib compression
OrthancPluginCompressionType_ZlibWithSize | zlib, prefixed with uncompressed size (uint64_t)
OrthancPluginCompressionType_Gzip | Standard gzip compression
OrthancPluginCompressionType_GzipWithSize | gzip, prefixed with uncompressed size (uint64_t)

## ◆ OrthancPluginImageFormat

enum OrthancPluginImageFormat

The image formats that are supported by the Orthanc core.

Enumerator
OrthancPluginImageFormat_Png | Image compressed using PNG
OrthancPluginImageFormat_Jpeg | Image compressed using JPEG
OrthancPluginImageFormat_Dicom | Image compressed using DICOM

## ◆ OrthancPluginPixelFormat

enum OrthancPluginPixelFormat

The memory layout of the pixels of an image.

Enumerator
OrthancPluginPixelFormat_Grayscale8 | Graylevel 8bpp image. The image is graylevel. Each pixel is unsigned and stored in one byte.
OrthancPluginPixelFormat_Grayscale16 | Graylevel, unsigned 16bpp image. The image is graylevel. Each pixel is unsigned and stored in two bytes.
OrthancPluginPixelFormat_SignedGrayscale16 | Graylevel, signed 16bpp image. The image is graylevel. Each pixel is signed and stored in two bytes.
OrthancPluginPixelFormat_RGB24 | Color image in RGB24 format. This format describes a color image. The pixels are stored in 3 consecutive bytes. The memory layout is RGB.
OrthancPluginPixelFormat_RGBA32 | Color image in RGBA32 format. This format describes a color image. The pixels are stored in 4 consecutive bytes. The memory layout is RGBA.
OrthancPluginPixelFormat_Unknown | Unknown pixel format

## Function Documentation

## ◆ OrthancPluginBufferCompression()

OrthancPluginErrorCode OrthancPluginBufferCompression | ( | OrthancPluginContext * | context,
|  | OrthancPluginMemoryBuffer * | target,
|  | const void * | source,
|  | uint32_t | size,
|  | OrthancPluginCompressionType | compression,
|  | uint8_t | uncompress
| ) |  |

This function compresses or decompresses a buffer, using the version of the zlib library that is used by the Orthanc core.

Parameters

  context | The Orthanc plugin context, as received by OrthancPluginInitialize().
  target | The target memory buffer. It must be freed with OrthancPluginFreeMemoryBuffer().
  source | The source buffer.
  size | The size in bytes of the source buffer.
  compression | The compression algorithm.
  uncompress | If set to "0", the buffer must be compressed. If set to "1", the buffer must be uncompressed.

Returns
  0 if success, or the error code if failure.

## ◆ OrthancPluginCompressJpegImage()

OrthancPluginErrorCode OrthancPluginCompressJpegImage | ( | OrthancPluginContext * | context,
|  | OrthancPluginMemoryBuffer * | target,
|  | OrthancPluginPixelFormat | format,
|  | uint32_t | width,
|  | uint32_t | height,
|  | uint32_t | pitch,
|  | const void * | buffer,
|  | uint8_t | quality
| ) |  |

This function compresses the given memory buffer containing an image using the JPEG specification, and stores the result of the compression into a newly allocated memory buffer.

Parameters

  context | The Orthanc plugin context, as received by OrthancPluginInitialize().
  target | The target memory buffer. It must be freed with OrthancPluginFreeMemoryBuffer().
  format | The memory layout of the uncompressed image.
  width | The width of the image.
  height | The height of the image.
  pitch | The pitch of the image (i.e. the number of bytes between 2 successive lines of the image in the memory buffer).
  buffer | The memory buffer containing the uncompressed image.
  quality | The quality of the JPEG encoding, between 1 (worst quality, best compression) and 100 (best quality, worst compression).

Returns
  0 if success, or the error code if failure.

## ◆ OrthancPluginCompressPngImage()

OrthancPluginErrorCode OrthancPluginCompressPngImage | ( | OrthancPluginContext * | context,
|  | OrthancPluginMemoryBuffer * | target,
|  | OrthancPluginPixelFormat | format,
|  | uint32_t | width,
|  | uint32_t | height,
|  | uint32_t | pitch,
|  | const void * | buffer
| ) |  |

This function compresses the given memory buffer containing an image using the PNG specification, and stores the result of the compression into a newly allocated memory buffer.

Parameters

  context | The Orthanc plugin context, as received by OrthancPluginInitialize().
  target | The target memory buffer. It must be freed with OrthancPluginFreeMemoryBuffer().
  format | The memory layout of the uncompressed image.
  width | The width of the image.
  height | The height of the image.
  pitch | The pitch of the image (i.e. the number of bytes between 2 successive lines of the image in the memory buffer).
  buffer | The memory buffer containing the uncompressed image.

Returns
  0 if success, or the error code if failure.

See also
  OrthancPluginCompressAndAnswerPngImage()

## ◆ OrthancPluginConvertPixelFormat()

OrthancPluginImage* OrthancPluginConvertPixelFormat | ( | OrthancPluginContext * | context,
|  | const OrthancPluginImage * | source,
|  | OrthancPluginPixelFormat | targetFormat
| ) |  |

This function creates a new image, changing the memory layout of the pixels.

Parameters

  context | The Orthanc plugin context, as received by OrthancPluginInitialize().
  source | The source image.
  targetFormat | The target pixel format.

Returns
  The resulting image. It must be freed with OrthancPluginFreeImage().

## ◆ OrthancPluginCreateImage()

OrthancPluginImage* OrthancPluginCreateImage | ( | OrthancPluginContext * | context,
|  | OrthancPluginPixelFormat | format,
|  | uint32_t | width,
|  | uint32_t | height
| ) |  |

This function creates an image of given size and format.

Parameters

  context | The Orthanc plugin context, as received by OrthancPluginInitialize().
  format | The format of the pixels.
  width | The width of the image.
  height | The height of the image.

Returns
  The newly allocated image. It must be freed with OrthancPluginFreeImage().

## ◆ OrthancPluginCreateImageAccessor()

OrthancPluginImage* OrthancPluginCreateImageAccessor | ( | OrthancPluginContext * | context,
|  | OrthancPluginPixelFormat | format,
|  | uint32_t | width,
|  | uint32_t | height,
|  | uint32_t | pitch,
|  | void * | buffer
| ) |  |

This function creates an image whose content points to a memory buffer managed by the plugin. Note that the buffer is directly accessed, no memory is allocated and no data is copied.

Parameters

  context | The Orthanc plugin context, as received by OrthancPluginInitialize().
  format | The format of the pixels.
  width | The width of the image.
  height | The height of the image.
  pitch | The pitch of the image (i.e. the number of bytes between 2 successive lines of the image in the memory buffer).
  buffer | The memory buffer.

Returns
  The newly allocated image. It must be freed with OrthancPluginFreeImage().

## ◆ OrthancPluginDecodeDicomImage()

OrthancPluginImage* OrthancPluginDecodeDicomImage | ( | OrthancPluginContext * | context,
|  | const void * | buffer,
|  | uint32_t | bufferSize,
|  | uint32_t | frameIndex
| ) |  |

This function decodes one frame of a DICOM image that is stored in a memory buffer. This function will give the same result as OrthancPluginUncompressImage() for single-frame DICOM images.

Parameters

  context | The Orthanc plugin context, as received by OrthancPluginInitialize().
  buffer | Pointer to a memory buffer containing the DICOM image.
  bufferSize | Size of the memory buffer containing the DICOM image.
  frameIndex | The index of the frame of interest in a multi-frame image.

Returns
  The uncompressed image. It must be freed with OrthancPluginFreeImage().

## ◆ OrthancPluginDrawText()

OrthancPluginErrorCode OrthancPluginDrawText | ( | OrthancPluginContext * | context,
|  | OrthancPluginImage * | image,
|  | uint32_t | fontIndex,
|  | const char * | utf8Text,
|  | int32_t | x,
|  | int32_t | y,
|  | uint8_t | r,
|  | uint8_t | g,
|  | uint8_t | b
| ) |  |

This function draws some text on some image.

Parameters

  context | The Orthanc plugin context, as received by OrthancPluginInitialize().
  image | The image upon which to draw the text.
  fontIndex | The index of the font. This value must be less than OrthancPluginGetFontsCount().
  utf8Text | The text to be drawn, encoded as an UTF-8 zero-terminated string.
  x | The X position of the text over the image.
  y | The Y position of the text over the image.
  r | The value of the red color channel of the text.
  g | The value of the green color channel of the text.
  b | The value of the blue color channel of the text.

Returns
  0 if success, other value if error.

## ◆ OrthancPluginFreeImage()

void OrthancPluginFreeImage | ( | OrthancPluginContext * | context,
|  | OrthancPluginImage * | image
| ) |  |

This function frees an image that was decoded with OrthancPluginUncompressImage().

Parameters

  context | The Orthanc plugin context, as received by OrthancPluginInitialize().
  image | The image.

## ◆ OrthancPluginGetFontName()

const char* OrthancPluginGetFontName | ( | OrthancPluginContext * | context,
|  | uint32_t | fontIndex
| ) |  |

This function returns the name of a font that is built in the Orthanc core.

Parameters

  context | The Orthanc plugin context, as received by OrthancPluginInitialize().
  fontIndex | The index of the font. This value must be less than OrthancPluginGetFontsCount().

Returns
  The font name. This is a statically-allocated string, do not free it.

## ◆ OrthancPluginGetFontsCount()

uint32_t OrthancPluginGetFontsCount | ( | OrthancPluginContext * | context | ) |

This function returns the number of fonts that are built in the Orthanc core. These fonts can be used to draw texts on images through OrthancPluginDrawText().

Parameters

  context | The Orthanc plugin context, as received by OrthancPluginInitialize().

Returns
  The number of fonts.

## ◆ OrthancPluginGetFontSize()

uint32_t OrthancPluginGetFontSize | ( | OrthancPluginContext * | context,
|  | uint32_t | fontIndex
| ) |  |

This function returns the size of a font that is built in the Orthanc core.

Parameters

  context | The Orthanc plugin context, as received by OrthancPluginInitialize().
  fontIndex | The index of the font. This value must be less than OrthancPluginGetFontsCount().

Returns
  The font size.

## ◆ OrthancPluginGetImageBuffer()

void* OrthancPluginGetImageBuffer | ( | OrthancPluginContext * | context,
|  | const OrthancPluginImage * | image
| ) |  |

This function returns a pointer to the memory buffer that contains the pixels of the image.

Parameters

  context | The Orthanc plugin context, as received by OrthancPluginInitialize().
  image | The image of interest.

Returns
  The pointer.

## ◆ OrthancPluginGetImageHeight()

uint32_t OrthancPluginGetImageHeight | ( | OrthancPluginContext * | context,
|  | const OrthancPluginImage * | image
| ) |  |

This function returns the height of the given image.

Parameters

  context | The Orthanc plugin context, as received by OrthancPluginInitialize().
  image | The image of interest.

Returns
  The height.

## ◆ OrthancPluginGetImagePitch()

uint32_t OrthancPluginGetImagePitch | ( | OrthancPluginContext * | context,
|  | const OrthancPluginImage * | image
| ) |  |

This function returns the pitch of the given image. The pitch is defined as the number of bytes between 2 successive lines of the image in the memory buffer.

Parameters

  context | The Orthanc plugin context, as received by OrthancPluginInitialize().
  image | The image of interest.

Returns
  The pitch.

## ◆ OrthancPluginGetImagePixelFormat()

OrthancPluginPixelFormat OrthancPluginGetImagePixelFormat | ( | OrthancPluginContext * | context,
|  | const OrthancPluginImage * | image
| ) |  |

This function returns the type of memory layout for the pixels of the given image.

Parameters

  context | The Orthanc plugin context, as received by OrthancPluginInitialize().
  image | The image of interest.

Returns
  The pixel format.

## ◆ OrthancPluginGetImageWidth()

uint32_t OrthancPluginGetImageWidth | ( | OrthancPluginContext * | context,
|  | const OrthancPluginImage * | image
| ) |  |

This function returns the width of the given image.

Parameters

  context | The Orthanc plugin context, as received by OrthancPluginInitialize().
  image | The image of interest.

Returns
  The width.

## ◆ OrthancPluginUncompressImage()

OrthancPluginImage* OrthancPluginUncompressImage | ( | OrthancPluginContext * | context,
|  | const void * | data,
|  | uint32_t | size,
|  | OrthancPluginImageFormat | format
| ) |  |

This function decodes a compressed image from a memory buffer.

Parameters

  context | The Orthanc plugin context, as received by OrthancPluginInitialize().
  data | Pointer to a memory buffer containing the compressed image.
  size | Size of the memory buffer containing the compressed image.
  format | The file format of the compressed image.

Returns
  The uncompressed image. It must be freed with OrthancPluginFreeImage().