Orthanc Plugin SDK: DicomInstance

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

Typedefs | Functions
DicomInstance

Functions to access DICOM images that are managed by the Orthanc core. More...

## Typedefs
typedef struct _OrthancPluginDicomInstance_t | OrthancPluginDicomInstance
| Opaque structure that represents a DICOM instance that is managed by the Orthanc core.

## Functions
OrthancPluginDicomInstance * | OrthancPluginCreateDicomInstance (OrthancPluginContext *context, const void *buffer, uint32_t size)
| Parse a DICOM instance.
void | OrthancPluginFreeDicomInstance (OrthancPluginContext *context, OrthancPluginDicomInstance *dicom)
| Free a DICOM instance.
char * | OrthancPluginGetInstanceAdvancedJson (OrthancPluginContext *context, const OrthancPluginDicomInstance *instance, OrthancPluginDicomToJsonFormat format, OrthancPluginDicomToJsonFlags flags, uint32_t maxStringLength)
| Format a DICOM memory buffer as a JSON string.
const void * | OrthancPluginGetInstanceData (OrthancPluginContext *context, const OrthancPluginDicomInstance *instance)
| Get the data of a DICOM file.
OrthancPluginImage * | OrthancPluginGetInstanceDecodedFrame (OrthancPluginContext *context, const OrthancPluginDicomInstance *instance, uint32_t frameIndex)
| Decode one frame from a DICOM instance.
char * | OrthancPluginGetInstanceDicomWebJson (OrthancPluginContext *context, const OrthancPluginDicomInstance *instance, OrthancPluginDicomWebBinaryCallback2 callback, void *payload)
| Convert a DICOM instance to DICOMweb JSON.
char * | OrthancPluginGetInstanceDicomWebXml (OrthancPluginContext *context, const OrthancPluginDicomInstance *instance, OrthancPluginDicomWebBinaryCallback2 callback, void *payload)
| Convert a DICOM instance to DICOMweb XML.
uint32_t | OrthancPluginGetInstanceFramesCount (OrthancPluginContext *context, const OrthancPluginDicomInstance *instance)
| Get the number of frames in a DICOM instance.
char * | OrthancPluginGetInstanceJson (OrthancPluginContext *context, const OrthancPluginDicomInstance *instance)
| Get the DICOM tag hierarchy as a JSON file.
const char * | OrthancPluginGetInstanceMetadata (OrthancPluginContext *context, const OrthancPluginDicomInstance *instance, const char *metadata)
| Get the value of some metadata associated with a given DICOM instance.
OrthancPluginInstanceOrigin | OrthancPluginGetInstanceOrigin (OrthancPluginContext *context, const OrthancPluginDicomInstance *instance)
| Get the origin of a DICOM file.
OrthancPluginErrorCode | OrthancPluginGetInstanceRawFrame (OrthancPluginContext *context, OrthancPluginMemoryBuffer *target, const OrthancPluginDicomInstance *instance, uint32_t frameIndex)
| Get the raw content of a frame in a DICOM instance.
const char * | OrthancPluginGetInstanceRemoteAet (OrthancPluginContext *context, const OrthancPluginDicomInstance *instance)
| Get the AET of a DICOM instance.
char * | OrthancPluginGetInstanceSimplifiedJson (OrthancPluginContext *context, const OrthancPluginDicomInstance *instance)
| Get the DICOM tag hierarchy as a JSON file (with simplification).
int64_t | OrthancPluginGetInstanceSize (OrthancPluginContext *context, const OrthancPluginDicomInstance *instance)
| Get the size of a DICOM file.
char * | OrthancPluginGetInstanceTransferSyntaxUid (OrthancPluginContext *context, const OrthancPluginDicomInstance *instance)
| Get the transfer syntax of a DICOM file.
int32_t | OrthancPluginHasInstanceMetadata (OrthancPluginContext *context, const OrthancPluginDicomInstance *instance, const char *metadata)
| Check whether a DICOM instance is associated with some metadata.
int32_t | OrthancPluginHasInstancePixelData (OrthancPluginContext *context, const OrthancPluginDicomInstance *instance)
| Check whether the DICOM file has pixel data.
OrthancPluginDicomInstance * | OrthancPluginLoadDicomInstance (OrthancPluginContext *context, const char *instanceId, OrthancPluginLoadDicomInstanceMode mode)
| Load a DICOM instance from the Orthanc server.
OrthancPluginErrorCode | OrthancPluginSerializeDicomInstance (OrthancPluginContext *context, OrthancPluginMemoryBuffer *target, const OrthancPluginDicomInstance *instance)
| Writes a DICOM instance to a memory buffer.
OrthancPluginDicomInstance * | OrthancPluginTranscodeDicomInstance (OrthancPluginContext *context, const void *buffer, uint32_t size, const char *transferSyntax)
| Parse and transcode a DICOM instance.

## Detailed Description

## Function Documentation

## ◆ OrthancPluginCreateDicomInstance()

OrthancPluginDicomInstance * OrthancPluginCreateDicomInstance | ( | OrthancPluginContext * | context,
|  | const void * | buffer,
|  | uint32_t | size )

This function parses a memory buffer that contains a DICOM file. The function returns a new pointer to a data structure that is managed by the Orthanc core.

Parameters

  context | The Orthanc plugin context, as received by OrthancPluginInitialize().
  buffer | The memory buffer containing the DICOM instance.
  size | The size of the memory buffer.

Returns
  The newly allocated DICOM instance. It must be freed with OrthancPluginFreeDicomInstance().

## ◆ OrthancPluginFreeDicomInstance()

void OrthancPluginFreeDicomInstance | ( | OrthancPluginContext * | context,
|  | OrthancPluginDicomInstance * | dicom )

This function frees a DICOM instance that was parsed using OrthancPluginCreateDicomInstance().

Parameters

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

## ◆ OrthancPluginGetInstanceAdvancedJson()

char * OrthancPluginGetInstanceAdvancedJson | ( | OrthancPluginContext * | context,
|  | const OrthancPluginDicomInstance * | instance,
|  | OrthancPluginDicomToJsonFormat | format,
|  | OrthancPluginDicomToJsonFlags | flags,
|  | uint32_t | maxStringLength )

This function takes as DICOM instance managed by the Orthanc core, and outputs a JSON string representing the tags of this DICOM file.

Parameters

  context | The Orthanc plugin context, as received by OrthancPluginInitialize().
  instance | The DICOM instance of interest.
  format | The output format.
  flags | Flags governing the output.
  maxStringLength | The maximum length of a field. Too long fields will be output as "null". The 0 value means no maximum length.

Returns
  The NULL value if the case of an error, or the JSON string. This string must be freed by OrthancPluginFreeString().

See also
  OrthancPluginDicomBufferToJson()

## ◆ OrthancPluginGetInstanceData()

const void * OrthancPluginGetInstanceData | ( | OrthancPluginContext * | context,
|  | const OrthancPluginDicomInstance * | instance )

This function returns a pointer to the content of the given DICOM instance.

Parameters

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

Returns
  The pointer to the DICOM data, NULL in case of error.

## ◆ OrthancPluginGetInstanceDecodedFrame()

OrthancPluginImage * OrthancPluginGetInstanceDecodedFrame | ( | OrthancPluginContext * | context,
|  | const OrthancPluginDicomInstance * | instance,
|  | uint32_t | frameIndex )

This function decodes one frame of a DICOM image that is managed by the Orthanc core.

Parameters

  context | The Orthanc plugin context, as received by OrthancPluginInitialize().
  instance | The instance of interest.
  frameIndex | The index of the frame of interest.

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

## ◆ OrthancPluginGetInstanceDicomWebJson()

char * OrthancPluginGetInstanceDicomWebJson | ( | OrthancPluginContext * | context,
|  | const OrthancPluginDicomInstance * | instance,
|  | OrthancPluginDicomWebBinaryCallback2 | callback,
|  | void * | payload )

This function converts a DICOM instance that is managed by the Orthanc core, into its DICOMweb JSON representation.

Parameters

  context | The Orthanc plugin context, as received by OrthancPluginInitialize().
  instance | The DICOM instance of interest.
  callback | Callback to set the value of the binary tags.
  payload | User payload.

Returns
  The NULL value in case of error, or the JSON document. This string must be freed by OrthancPluginFreeString().

## ◆ OrthancPluginGetInstanceDicomWebXml()

char * OrthancPluginGetInstanceDicomWebXml | ( | OrthancPluginContext * | context,
|  | const OrthancPluginDicomInstance * | instance,
|  | OrthancPluginDicomWebBinaryCallback2 | callback,
|  | void * | payload )

This function converts a DICOM instance that is managed by the Orthanc core, into its DICOMweb XML representation.

Parameters

  context | The Orthanc plugin context, as received by OrthancPluginInitialize().
  instance | The DICOM instance of interest.
  callback | Callback to set the value of the binary tags.
  payload | User payload.

Returns
  The NULL value in case of error, or the XML document. This string must be freed by OrthancPluginFreeString().

## ◆ OrthancPluginGetInstanceFramesCount()

uint32_t OrthancPluginGetInstanceFramesCount | ( | OrthancPluginContext * | context,
|  | const OrthancPluginDicomInstance * | instance )

This function returns the number of frames that are part of a DICOM image managed by the Orthanc core.

Parameters

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

Returns
  The number of frames (will be zero in the case of an error).

## ◆ OrthancPluginGetInstanceJson()

char * OrthancPluginGetInstanceJson | ( | OrthancPluginContext * | context,
|  | const OrthancPluginDicomInstance * | instance )

This function returns a pointer to a newly created string containing a JSON file. This JSON file encodes the tag hierarchy of the given DICOM instance.

Parameters

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

Returns
  The NULL value in case of error, or a string containing the JSON file. This string must be freed by OrthancPluginFreeString().

## ◆ OrthancPluginGetInstanceMetadata()

const char * OrthancPluginGetInstanceMetadata | ( | OrthancPluginContext * | context,
|  | const OrthancPluginDicomInstance * | instance,
|  | const char * | metadata )

This functions returns the value of some metadata that is associated with the DICOM instance of interest. Before calling this function, the existence of the metadata must have been checked with OrthancPluginHasInstanceMetadata().

Parameters

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

Returns
  The metadata value if success, NULL if error. Please note that the returned string belongs to the instance object and must NOT be deallocated. Please make a copy of the string if you wish to access it later.

## ◆ OrthancPluginGetInstanceOrigin()

OrthancPluginInstanceOrigin OrthancPluginGetInstanceOrigin | ( | OrthancPluginContext * | context,
|  | const OrthancPluginDicomInstance * | instance )

This function returns the origin of a DICOM instance that has been received by Orthanc.

Parameters

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

Returns
  The origin of the instance.

## ◆ OrthancPluginGetInstanceRawFrame()

OrthancPluginErrorCode OrthancPluginGetInstanceRawFrame | ( | OrthancPluginContext * | context,
|  | OrthancPluginMemoryBuffer * | target,
|  | const OrthancPluginDicomInstance * | instance,
|  | uint32_t | frameIndex )

This function returns a memory buffer containing the raw content of a frame in a DICOM instance that is managed by the Orthanc core. This is notably useful for compressed transfer syntaxes, as it gives access to the embedded files (such as JPEG, JPEG-LS or JPEG2k). The Orthanc core transparently reassembles the fragments to extract the raw frame.

Parameters

  context | The Orthanc plugin context, as received by OrthancPluginInitialize().
  target | The target memory buffer. It must be freed with OrthancPluginFreeMemoryBuffer().
  instance | The instance of interest.
  frameIndex | The index of the frame of interest.

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

## ◆ OrthancPluginGetInstanceRemoteAet()

const char * OrthancPluginGetInstanceRemoteAet | ( | OrthancPluginContext * | context,
|  | const OrthancPluginDicomInstance * | instance )

This function returns the Application Entity Title (AET) of the DICOM modality from which a DICOM instance originates.

Parameters

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

Returns
  The AET if success, NULL if error.

## ◆ OrthancPluginGetInstanceSimplifiedJson()

char * OrthancPluginGetInstanceSimplifiedJson | ( | OrthancPluginContext * | context,
|  | const OrthancPluginDicomInstance * | instance )

This function returns a pointer to a newly created string containing a JSON file. This JSON file encodes the tag hierarchy of the given DICOM instance. In contrast with OrthancPluginGetInstanceJson(), the returned JSON file is in its simplified version.

Parameters

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

Returns
  The NULL value in case of error, or a string containing the JSON file. This string must be freed by OrthancPluginFreeString().

## ◆ OrthancPluginGetInstanceSize()

int64_t OrthancPluginGetInstanceSize | ( | OrthancPluginContext * | context,
|  | const OrthancPluginDicomInstance * | instance )

This function returns the number of bytes of the given DICOM instance.

Parameters

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

Returns
  The size of the file, -1 in case of error.

## ◆ OrthancPluginGetInstanceTransferSyntaxUid()

char * OrthancPluginGetInstanceTransferSyntaxUid | ( | OrthancPluginContext * | context,
|  | const OrthancPluginDicomInstance * | instance )

This function returns a pointer to a newly created string that contains the transfer syntax UID of the DICOM instance. The empty string might be returned if this information is unknown.

Parameters

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

Returns
  The NULL value in case of error, or a string containing the transfer syntax UID. This string must be freed by OrthancPluginFreeString().

## ◆ OrthancPluginHasInstanceMetadata()

int32_t OrthancPluginHasInstanceMetadata | ( | OrthancPluginContext * | context,
|  | const OrthancPluginDicomInstance * | instance,
|  | const char * | metadata )

This function checks whether the DICOM instance of interest is associated with some metadata. As of Orthanc 0.8.1, in the callbacks registered by OrthancPluginRegisterOnStoredInstanceCallback(), the only possibly available metadata are "ReceptionDate", "RemoteAET" and "IndexInSeries".

Parameters

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

Returns
  1 if the metadata is present, 0 if it is absent, -1 in case of error.

## ◆ OrthancPluginHasInstancePixelData()

int32_t OrthancPluginHasInstancePixelData | ( | OrthancPluginContext * | context,
|  | const OrthancPluginDicomInstance * | instance )

This function returns a Boolean value indicating whether the DICOM instance contains the pixel data (7FE0,0010) tag.

Parameters

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

Returns
  "1" if the DICOM instance contains pixel data, or "0" if the tag is missing, or "-1" in the case of an error.

## ◆ OrthancPluginLoadDicomInstance()

OrthancPluginDicomInstance * OrthancPluginLoadDicomInstance | ( | OrthancPluginContext * | context,
|  | const char * | instanceId,
|  | OrthancPluginLoadDicomInstanceMode | mode )

This function loads a DICOM instance from the content of the Orthanc database. The function returns a new pointer to a data structure that is managed by the Orthanc core.

Parameters

  context | The Orthanc plugin context, as received by OrthancPluginInitialize().
  instanceId | The Orthanc identifier of the DICOM instance of interest.
  mode | Flag specifying how to deal with pixel data.

Returns
  The newly allocated DICOM instance. It must be freed with OrthancPluginFreeDicomInstance().

## ◆ OrthancPluginSerializeDicomInstance()

OrthancPluginErrorCode OrthancPluginSerializeDicomInstance | ( | OrthancPluginContext * | context,
|  | OrthancPluginMemoryBuffer * | target,
|  | const OrthancPluginDicomInstance * | instance )

This function returns a memory buffer containing the serialization of a DICOM instance that is managed 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().
  instance | The instance of interest.

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

## ◆ OrthancPluginTranscodeDicomInstance()

OrthancPluginDicomInstance * OrthancPluginTranscodeDicomInstance | ( | OrthancPluginContext * | context,
|  | const void * | buffer,
|  | uint32_t | size,
|  | const char * | transferSyntax )

This function parses a memory buffer that contains a DICOM file, then transcodes it to the given transfer syntax. The function returns a new pointer to a data structure that is managed by the Orthanc core.

Parameters

  context | The Orthanc plugin context, as received by OrthancPluginInitialize().
  buffer | The memory buffer containing the DICOM instance.
  size | The size of the memory buffer.
  transferSyntax | The transfer syntax UID for the transcoding.

Returns
  The newly allocated DICOM instance. It must be freed with OrthancPluginFreeDicomInstance().