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. 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...
OrthancPluginImage *	OrthancPluginGetInstanceDecodedFrame (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...
OrthancPluginDicomInstance *	OrthancPluginLoadDicomInstance (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...
OrthancPluginDicomInstance *	OrthancPluginTranscodeDicomInstance (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

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().