Orthanc Plugin SDK  1.12.3
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

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

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
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
bufferThe memory buffer containing the DICOM instance.
sizeThe 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
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
dicomThe 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
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
instanceThe DICOM instance of interest.
formatThe output format.
flagsFlags governing the output.
maxStringLengthThe 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
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
instanceThe 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
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
instanceThe instance of interest.
frameIndexThe 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
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
instanceThe DICOM instance of interest.
callbackCallback to set the value of the binary tags.
payloadUser 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
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
instanceThe DICOM instance of interest.
callbackCallback to set the value of the binary tags.
payloadUser 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
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
instanceThe 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
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
instanceThe 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
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
instanceThe instance of interest.
metadataThe 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
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
instanceThe 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
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
targetThe target memory buffer. It must be freed with OrthancPluginFreeMemoryBuffer().
instanceThe instance of interest.
frameIndexThe 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
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
instanceThe 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
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
instanceThe 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
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
instanceThe 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
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
instanceThe 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
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
instanceThe instance of interest.
metadataThe 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
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
instanceThe 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
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
instanceIdThe Orthanc identifier of the DICOM instance of interest.
modeFlag 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
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
targetThe target memory buffer. It must be freed with OrthancPluginFreeMemoryBuffer().
instanceThe 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
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
bufferThe memory buffer containing the DICOM instance.
sizeThe size of the memory buffer.
transferSyntaxThe transfer syntax UID for the transcoding.
Returns
The newly allocated DICOM instance. It must be freed with OrthancPluginFreeDicomInstance().