Mercurial > hg > orthanc

changeset 3937:41eec97c23ef transcoding

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
documented new primitives in plugin SDK
author Sebastien Jodogne <s.jodogne@gmail.com>
date Mon, 18 May 2020 11:16:18 +0200
parents 01d4667f5c44
children 54dbebbcc032
files NEWS Plugins/Include/orthanc/OrthancCPlugin.h Resources/Configuration.json Resources/Orthanc.doxygen Resources/OrthancPlugin.doxygen
diffstat 5 files changed, 161 insertions(+), 14 deletions(-) [+]
line wrap: on
line diff
--- a/NEWS	Fri May 15 18:35:09 2020 +0200
+++ b/NEWS	Mon May 18 11:16:18 2020 +0200
@@ -32,14 +32,17 @@
 
 * New functions in the SDK:
   - OrthancPluginCreateDicomInstance()
+  - OrthancPluginCreateMemoryBuffer()
   - OrthancPluginEncodeDicomWebJson2()
   - OrthancPluginEncodeDicomWebXml2()
   - OrthancPluginFreeDicomInstance()
+  - OrthancPluginGetInstanceAdvancedJson()
   - OrthancPluginGetInstanceDecodedFrame()
   - OrthancPluginGetInstanceDicomWebJson()
   - OrthancPluginGetInstanceDicomWebXml()
   - OrthancPluginGetInstanceFramesCount()
   - OrthancPluginGetInstanceRawFrame()
+  - OrthancPluginRegisterTranscoderCallback()
   - OrthancPluginSerializeDicomInstance()
   - OrthancPluginTranscodeDicomInstance()
 * "OrthancPluginDicomInstance" structure wrapped in "OrthancPluginCppWrapper.h"
--- a/Plugins/Include/orthanc/OrthancCPlugin.h	Fri May 15 18:35:09 2020 +0200
+++ b/Plugins/Include/orthanc/OrthancCPlugin.h	Mon May 18 11:16:18 2020 +0200
@@ -5241,8 +5241,11 @@
   /**
    * @brief Register a callback to handle the decoding of DICOM images.
    *
-   * This function registers a custom callback to the decoding of
-   * DICOM images, replacing the built-in decoder of Orthanc.
+   * This function registers a custom callback to decode DICOM images,
+   * extending the built-in decoder of Orthanc that uses
+   * DCMTK. Starting with Orthanc 1.7.0, the exact behavior is
+   * affected by the configuration option
+   * "BuiltinDecoderTranscoderOrder" of Orthanc.
    *
    * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
    * @param callback The callback.
@@ -5374,6 +5377,7 @@
    * @param frameIndex The index of the frame of interest in a multi-frame image.
    * @return The uncompressed image. It must be freed with OrthancPluginFreeImage().
    * @ingroup Images
+   * @see OrthancPluginGetInstanceDecodedFrame()
    **/
   ORTHANC_PLUGIN_INLINE OrthancPluginImage* OrthancPluginDecodeDicomImage(
     OrthancPluginContext*  context,
@@ -6888,7 +6892,7 @@
    * @param dicom Pointer to the DICOM instance.
    * @param dicomSize Size of the DICOM instance.
    * @param callback Callback to set the value of the binary tags.
-   * @return The NULL value in case of error, or the JSON document. This string must
+   * @return The NULL value in case of error, or the XML document. This string must
    * be freed by OrthancPluginFreeString().
    * @see OrthancPluginCreateDicom()
    * @deprecated OrthancPluginEncodeDicomWebXml2()
@@ -6941,9 +6945,9 @@
    * @param dicomSize Size of the DICOM instance.
    * @param callback Callback to set the value of the binary tags.
    * @param payload User payload.
-   * @see OrthancPluginCreateDicom()
    * @return The NULL value in case of error, or the JSON document. This string must
    * be freed by OrthancPluginFreeString().
+   * @see OrthancPluginCreateDicom()
    * @ingroup Toolbox
    **/
   ORTHANC_PLUGIN_INLINE char* OrthancPluginEncodeDicomWebJson2(
@@ -6985,10 +6989,9 @@
    * @param dicomSize Size of the DICOM instance.
    * @param callback Callback to set the value of the binary tags.
    * @param payload User payload.
-   * @return The NULL value in case of error, or the JSON document. This string must
+   * @return The NULL value in case of error, or the XML document. This string must
    * be freed by OrthancPluginFreeString().
    * @see OrthancPluginCreateDicom()
-   * @deprecated OrthancPluginEncodeDicomWebXml2()
    * @ingroup Toolbox
    **/
   ORTHANC_PLUGIN_INLINE char* OrthancPluginEncodeDicomWebXml2(
@@ -7819,6 +7822,24 @@
     }
   }
 
+
+  /**
+   * @brief Get the raw content of a frame in a DICOM instance.
+   *
+   * 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.
+   * 
+   * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
+   * @param target The target memory buffer. It must be freed with OrthancPluginFreeMemoryBuffer().
+   * @param instance The instance of interest.
+   * @param frameIndex The index of the frame of interest.
+   * @return 0 if success, or the error code if failure.
+   * @ingroup DicomInstance
+   **/
   ORTHANC_PLUGIN_INLINE OrthancPluginErrorCode OrthancPluginGetInstanceRawFrame(
     OrthancPluginContext*             context,
     OrthancPluginMemoryBuffer*        target,
@@ -7834,6 +7855,19 @@
     return context->InvokeService(context, _OrthancPluginService_GetInstanceRawFrame, &params);
   }
 
+
+  /**
+   * @brief Decode one frame from a DICOM instance.
+   *
+   * This function decodes one frame of a DICOM image that is managed
+   * by the Orthanc core.
+   * 
+   * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
+   * @param instance The instance of interest.
+   * @param frameIndex The index of the frame of interest.
+   * @return The uncompressed image. It must be freed with OrthancPluginFreeImage().
+   * @ingroup DicomInstance
+   **/
   ORTHANC_PLUGIN_INLINE OrthancPluginImage* OrthancPluginGetInstanceDecodedFrame(
     OrthancPluginContext*             context,
     const OrthancPluginDicomInstance* instance,
@@ -7857,6 +7891,22 @@
     }
   }
 
+  
+  /**
+   * @brief Parse and transcode a DICOM instance.
+   *
+   * 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.
+   *
+   * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
+   * @param buffer The memory buffer containing the DICOM instance.
+   * @param size The size of the memory buffer.
+   * @param transferSyntax The transfer syntax UID for the transcoding.
+   * @return The newly allocated DICOM instance. It must be freed with OrthancPluginFreeDicomInstance().
+   * @ingroup DicomInstance
+   **/
   ORTHANC_PLUGIN_INLINE OrthancPluginDicomInstance* OrthancPluginTranscodeDicomInstance(
     OrthancPluginContext*  context,
     const void*            buffer,
@@ -7882,6 +7932,19 @@
     }
   }
 
+  /**
+   * @brief Writes a DICOM instance to a memory buffer.
+   *
+   * This function returns a memory buffer containing the
+   * serialization of a DICOM instance that is managed by the Orthanc
+   * core.
+   * 
+   * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
+   * @param target The target memory buffer. It must be freed with OrthancPluginFreeMemoryBuffer().
+   * @param instance The instance of interest.
+   * @return 0 if success, or the error code if failure.
+   * @ingroup DicomInstance
+   **/
   ORTHANC_PLUGIN_INLINE OrthancPluginErrorCode OrthancPluginSerializeDicomInstance(
     OrthancPluginContext*             context,
     OrthancPluginMemoryBuffer*        target,
@@ -7894,12 +7957,13 @@
 
     return context->InvokeService(context, _OrthancPluginService_SerializeDicomInstance, &params);
   }
+  
 
   /**
    * @brief Format a DICOM memory buffer as a JSON string.
    *
-   * This function takes as input a memory buffer containing a DICOM
-   * file, and outputs a JSON string representing the tags of this
+   * This function takes as DICOM instance managed by the Orthanc
+   * core, and outputs a JSON string representing the tags of this
    * DICOM file.
    *
    * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
@@ -7910,7 +7974,7 @@
    * be output as "null". The 0 value means no maximum length.
    * @return The NULL value if the case of an error, or the JSON
    * string. This string must be freed by OrthancPluginFreeString().
-   * @ingroup Toolbox
+   * @ingroup DicomInstance
    * @see OrthancPluginDicomBufferToJson
    **/
   ORTHANC_PLUGIN_INLINE char* OrthancPluginGetInstanceAdvancedJson(
@@ -7942,6 +8006,20 @@
   }
 
 
+  /**
+   * @brief Convert a DICOM instance to DICOMweb JSON.
+   *
+   * This function converts a DICOM instance that is managed by the
+   * Orthanc core, into its DICOMweb JSON representation.
+   *
+   * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
+   * @param instance The DICOM instance of interest.
+   * @param callback Callback to set the value of the binary tags.
+   * @param payload User payload.
+   * @return The NULL value in case of error, or the JSON document. This string must
+   * be freed by OrthancPluginFreeString().
+   * @ingroup DicomInstance
+   **/
   ORTHANC_PLUGIN_INLINE char* OrthancPluginGetInstanceDicomWebJson(
     OrthancPluginContext*                 context,
     const OrthancPluginDicomInstance*     instance,
@@ -7968,6 +8046,20 @@
   }
   
 
+  /**
+   * @brief Convert a DICOM instance to DICOMweb XML.
+   *
+   * This function converts a DICOM instance that is managed by the
+   * Orthanc core, into its DICOMweb XML representation.
+   *
+   * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
+   * @param instance The DICOM instance of interest.
+   * @param callback Callback to set the value of the binary tags.
+   * @param payload User payload.
+   * @return The NULL value in case of error, or the XML document. This string must
+   * be freed by OrthancPluginFreeString().
+   * @ingroup DicomInstance
+   **/
   ORTHANC_PLUGIN_INLINE char* OrthancPluginGetInstanceDicomWebXml(
     OrthancPluginContext*                 context,
     const OrthancPluginDicomInstance*     instance,
@@ -7995,7 +8087,28 @@
 
 
 
-
+  /**
+   * @brief Signature of a callback function to transcode a DICOM instance.
+   * @param transcoded Target memory buffer. It must be allocated by the
+   * plugin using OrthancPluginCreateMemoryBuffer().
+   * @param hasSopInstanceUidChanged Whether the SOP Instance UID of the
+   * DICOM instance has changed because of the transcoding. This value
+   * should be "true" if and only if the selected transfer syntax is
+   * affected by lossy compression.
+   * @param buffer Memory buffer containing the source DICOM instance.
+   * @param size Size of the source memory buffer.
+   * @param allowedSyntaxes A C array of possible transfer syntaxes UIDs for the
+   * result of the transcoding. The plugin must choose by itself the 
+   * transfer syntax that will be used for the resulting DICOM image.
+   * @param countSyntaxes The number of transfer syntaxes that are contained
+   * in the "allowedSyntaxes" array.
+   * @param allowNewSopInstanceUid Whether the transcoding plugin can select
+   * a transfer syntax that will change the SOP instance UID (or, in other 
+   * terms, whether the plugin can transcode using lossy compression).
+   * @return 0 if success (i.e. image successfully transcoded and stored into
+   * "transcoded"), or the error code if failure.
+   * @ingroup Callbacks
+   **/
   typedef OrthancPluginErrorCode (*OrthancPluginTranscoderCallback) (
     OrthancPluginMemoryBuffer* transcoded /* out */,
     uint8_t*                   hasSopInstanceUidChanged /* out */,
@@ -8011,6 +8124,19 @@
     OrthancPluginTranscoderCallback callback;
   } _OrthancPluginTranscoderCallback;
 
+  /**
+   * @brief Register a callback to handle the transcoding of DICOM images.
+   *
+   * This function registers a custom callback to transcode DICOM
+   * images, extending the built-in transcoder of Orthanc that uses
+   * DCMTK. The exact behavior is affected by the configuration option
+   * "BuiltinDecoderTranscoderOrder" of Orthanc.
+   *
+   * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
+   * @param callback The callback.
+   * @return 0 if success, other value if error.
+   * @ingroup Callbacks
+   **/
   ORTHANC_PLUGIN_INLINE OrthancPluginErrorCode OrthancPluginRegisterTranscoderCallback(
     OrthancPluginContext*            context,
     OrthancPluginTranscoderCallback  callback)
@@ -8029,6 +8155,23 @@
     uint32_t                    size;
   } _OrthancPluginCreateMemoryBuffer;
 
+  /**
+   * @brief Create a memory buffer.
+   *
+   * This function creates a memory buffer that is managed by the
+   * Orthanc core. The main use case of this function is for plugins
+   * that act as DICOM transcoders.
+   * 
+   * Your plugin should never call "free()" on the resulting memory
+   * buffer, as the C library that is used by the plugin is in general
+   * not the same as the one used by the Orthanc core.
+   *
+   * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
+   * @param target The target memory buffer. It must be freed with OrthancPluginFreeMemoryBuffer().
+   * @param size Size of the memory buffer to be created.
+   * @return 0 if success, or the error code if failure.
+   * @ingroup Toolbox
+   **/
   ORTHANC_PLUGIN_INLINE OrthancPluginErrorCode OrthancPluginCreateMemoryBuffer(
     OrthancPluginContext*       context,
     OrthancPluginMemoryBuffer*  target,
--- a/Resources/Configuration.json	Fri May 15 18:35:09 2020 +0200
+++ b/Resources/Configuration.json	Mon May 18 11:16:18 2020 +0200
@@ -551,7 +551,8 @@
   // If some plugin to decode/transcode DICOM instances is installed,
   // this option specifies whether the built-in decoder/transcoder of
   // Orthanc (that uses DCMTK) is applied before or after the plugins,
-  // or is not applied at all. The allowed values for this option are
-  // "After" (default value), "Before", or "Disabled". (new in Orthanc 1.7.0)
+  // or is not applied at all (new in Orthanc 1.7.0). The allowed
+  // values for this option are "After" (default value, corresponding
+  // to the behavior of Orthanc <= 1.6.1), "Before", or "Disabled".
   "BuiltinDecoderTranscoderOrder" : "After"
 }
--- a/Resources/Orthanc.doxygen	Fri May 15 18:35:09 2020 +0200
+++ b/Resources/Orthanc.doxygen	Mon May 18 11:16:18 2020 +0200
@@ -545,7 +545,7 @@
 # this will also influence the order of the classes in the class list.
 # The default value is: NO.
 
-SORT_BRIEF_DOCS        = NO
+SORT_BRIEF_DOCS        = YES
 
 # If the SORT_MEMBERS_CTORS_1ST tag is set to YES then doxygen will sort the
 # (brief and detailed) documentation of class members so that constructors and
--- a/Resources/OrthancPlugin.doxygen	Fri May 15 18:35:09 2020 +0200
+++ b/Resources/OrthancPlugin.doxygen	Mon May 18 11:16:18 2020 +0200
@@ -545,7 +545,7 @@
 # this will also influence the order of the classes in the class list.
 # The default value is: NO.
 
-SORT_BRIEF_DOCS        = NO
+SORT_BRIEF_DOCS        = YES
 
 # If the SORT_MEMBERS_CTORS_1ST tag is set to YES then doxygen will sort the
 # (brief and detailed) documentation of class members so that constructors and