Mercurial > hg > orthanc-book

comparison Sphinx/source/faq/transcoding.rst @ 428:943515b68158

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
documented transcoding
author Sebastien Jodogne <s.jodogne@gmail.com>
date Fri, 22 May 2020 11:19:41 +0200
parents 71281b540ca1
children 2922fb1bd65e
comparison
equal deleted inserted replaced
427:71281b540ca1 428:943515b68158
13 :ref:`transfer syntax <dicom-pixel-data>` of some DICOM instance. 13 :ref:`transfer syntax <dicom-pixel-data>` of some DICOM instance.
14 14
15 Transcoding can be used to **compress** DICOM images, which is useful 15 Transcoding can be used to **compress** DICOM images, which is useful
16 to reduce the required storage area or to optimize the network 16 to reduce the required storage area or to optimize the network
17 bandwidth for exchanges between sites. Conversely, transcoding can be 17 bandwidth for exchanges between sites. Conversely, transcoding can be
18 used to **uncompress** DICOM images, which is needed as many DICOM 18 used to **decompress** DICOM images, which is needed as many DICOM
19 viewers or specialized analysis software do not provide support for 19 viewers or specialized analysis software do not provide support for
20 compressed transfer syntaxes. 20 compressed transfer syntaxes.
21 21
22 Support for transcoding was introduced in Orthanc 1.7.0. 22 Support for transcoding was introduced in Orthanc 1.7.0.
23 23
63 63
64 Transcoding in Orthanc 64 Transcoding in Orthanc
65 ---------------------- 65 ----------------------
66 66
67 Orthanc 1.7.0 was the first release of Orthanc to feature built-in 67 Orthanc 1.7.0 was the first release of Orthanc to feature built-in
68 support for DICOM transcoding. 68 support for DICOM transcoding. Transcoding is available at multiple
69 69 levels, as depicted by the green arrows on the following drawing:
70 70
71 71 .. image:: ../images/Transcoding-1.7.0.svg
72 * Explanation of DICOM protocol (transparent transcoding from 72 :align: center
73 compressed transfer syntaxes to uncompressed transfer syntaxes). 73 :width: 500px
74 74
75 * ``TranscodeDicomProtocol`` global configuration option 75
76 76 * **Automated transcoding while ingesting**. Orthanc can be configured
77 * ``AllowTranscoding`` in ``DicomModalities`` configuration option 77 to automatically transcode each DICOM instance it receives (either
78 78 by DICOM protocol or by REST API) to a fixed transfer syntax. This
79 * ``/instances/.../modify`` route: ``Transcode`` option 79 is especially useful to either create an archive of compressed files
80 80 (for long-term archiving), or to create a DICOM buffer with
81 * ``IngestTranscoding`` 81 uncompressed files (for interfacing with DICOM modalities that do
82 82 not support compressed transfer syntaxes). If the transcoding fails,
83 * ``BuiltinDecoderTranscoderOrder`` 83 the DICOM instance is still stored using its original transfer
84 84 syntax.
85 * ``DicomLossyCompressionLevel`` 85
86 86 Automated transcoding is enabled by setting the :ref:`configuration
87 * Routes to create archives: ``Transcode`` option 87 option <configuration>` ``IngestTranscoding`` to the transfer syntax
88 88 UID of interest. For instance, setting ``IngestTranscoding`` to
89 You might therefore have to **disable 89 ``1.2.840.10008.1.2.1`` will decompress all the received DICOM
90 transfer syntaxes** by setting the ``*TransferSyntaxAccepted`` options 90 instances. Conversely, setting it to ``1.2.840.10008.1.2.4.70`` will
91 to ``false`` in the :ref:`configuration file of Orthanc 91 compress and store images using JPEG-LS (lossless).
92 <configuration>` (by default, all the transfer syntaxes are enabled). 92
93 * **Decompression while sending instances using the DICOM protocol**.
94 Orthanc can be configured to automatically decompress DICOM images
95 on its outgoing connections, if the remote modality does not support
96 the compressed transfer syntax of the source DICOM instances. This
97 feature is available for both :ref:`DICOM C-Move and C-Get commands
98 <dicom-move>`. Note that Orthanc won't transcode DICOM instances to
99 a compressed transfer syntax over the DICOM protocol.
100
101 By default, this automated decompression is enabled. This might be
102 undesirable if you want to limit the resources that are used by
103 Orthanc. As a consequence, you can disable this feature either
104 globally (by setting configuration option ``TranscodeDicomProtocol``
105 to ``false``), or on a per-modality basis (by setting the option
106 ``AllowTranscoding`` to ``false`` in the ``DicomModalities``
107 section).
108
109 .. highlight:: bash
110
111 * **Transcoding while sending instances to an Orthanc peer**. The
112 ``/peers/{id}/store`` route in the Orthanc REST API allows to send
113 DICOM resources (patients, studies, series or instances) to
114 :ref:`another Orthanc server over HTTP/HTTPS <peering>`. Starting
115 with Orthanc 1.7.0, the ``Transcode`` option can be used in the JSON
116 POST body to instruct to transcode the DICOM files before they are
117 sent. For instance::
118
119 $ curl -X POST http://localhost:8042/peers/sample/store -d '{"Transcode":"1.2.840.10008.1.2.4.70","Resources":["66c8e41e-ac3a9029-0b85e42a-8195ee0a-92c2e62e"]}'
120
121 * **Transcoding using the REST API**. Starting with Orthanc 1.7.0,
122 some routes in the REST API also accept the ``Transcode`` option
123 in their JSON POST body. Those routes notably include:
124
125 * The routes to create ZIP files or DICOMDIR archives (``.../media``
126 and ``.../archive``).
127
128 * The routes to modify DICOM resources
129 (``/{patients|studies|series|instances}/{id}/modify``).
130
131 Importantly, if you need to transcode JPEG2k DICOM instances, you'll
132 have to install the :ref:`GDCM plugin <gdcm>` that replaces the
133 built-in transcoder of Orthanc based on DCMTK, by the GDCM transcoder.
134
135 The following :ref:`advanced configuration options <configuration>`
136 are also available to control transcoding:
137
138 * ``BuiltinDecoderTranscoderOrder`` controls the transcoder that is
139 used by Orthanc. It specifies whether the built-in transcoder of
140 Orthanc (that uses DCMTK) is applied before or after the transcoding
141 plugins, or not applied at all. "After" means that the built-in
142 transcoder is applied if all the transcoding plugins have failed to
143 transcode the image.
144
145 * ``DicomLossyTranscodingQuality`` controls the quality level of lossy
146 compression (notably for JPEG transcoding).
93 147
94 148
95 Solutions to avoid transcoding 149 Solutions to avoid transcoding
96 ------------------------------ 150 ------------------------------
97 151