Mercurial > hg > orthanc-book
annotate Sphinx/source/faq/transcoding.rst @ 427:71281b540ca1
updating old documentation about transcoding
author | Sebastien Jodogne <s.jodogne@gmail.com> |
---|---|
date | Fri, 22 May 2020 10:10:21 +0200 |
parents | 24b1c64002b8 |
children | 943515b68158 |
rev | line source |
---|---|
275 | 1 .. _transcoding: |
2 | |
3 Transcoding of DICOM files | |
4 ========================== | |
5 | |
411 | 6 .. contents:: |
7 | |
8 | |
275 | 9 General information |
10 ------------------- | |
11 | |
427
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
12 **DICOM transcoding** refers to the process of changing the |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
13 :ref:`transfer syntax <dicom-pixel-data>` of some DICOM instance. |
275 | 14 |
427
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
15 Transcoding can be used to **compress** DICOM images, which is useful |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
16 to reduce the required storage area or to optimize the network |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
17 bandwidth for exchanges between sites. Conversely, transcoding can be |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
18 used to **uncompress** DICOM images, which is needed as many DICOM |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
19 viewers or specialized analysis software do not provide support for |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
20 compressed transfer syntaxes. |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
21 |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
22 Support for transcoding was introduced in Orthanc 1.7.0. |
275 | 23 |
24 | |
25 Motivation for transcoding | |
26 -------------------------- | |
27 | |
28 Let's consider the following basic workflow, in which some imaging | |
29 workstation must access a medical image that originates from a PACS | |
30 and that is served through an Orthanc proxy: | |
31 | |
32 .. image:: ../images/Transcoding1.svg | |
33 :align: center | |
34 :width: 700px | |
35 | |
36 This is quite a common situation, e.g. in university hospitals where | |
37 researchers must access medical images without having authorization to | |
38 log in the clinical PACS. It is also common if the main PACS restricts | |
39 the number of workstations that can directly be connected to it, or if | |
40 Orthanc acts as gateway through Internet. | |
41 | |
42 The problem is that the software running on workstations might not be | |
43 able to display some DICOM transfer syntaxes. This is especially true | |
44 in research software, that is often limited to uncompressed transfer | |
45 syntaxes. For instance, let's consider the following scenario where a | |
46 workstation wants to access an image from the PACS: | |
47 | |
48 .. image:: ../images/Transcoding2.svg | |
49 :align: center | |
50 :width: 700px | |
51 | |
52 A typical PACS system will decide, when requested to export an image | |
53 using DICOM C-Store, to compress the image in order to reduce the | |
54 network bandwidth and the storage requirements. Orthanc is fine with | |
55 it: As a vendor neutral archive, Orthanc can basically | |
56 receive/store/transmit any DICOM transfer syntax. Unfortunately, this | |
57 might not be the case of the target workstation, that is often limited | |
58 to some selected transfer syntaxes. As a consequence, the workstation | |
427
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
59 will complain about not being to use the DICOM file (in the situation |
275 | 60 depicted above, because the PACS has decided to send the DICOM image |
61 using the JPEG2k transfer syntax). | |
62 | |
63 | |
427
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
64 Transcoding in Orthanc |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
65 ---------------------- |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
66 |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
67 Orthanc 1.7.0 was the first release of Orthanc to feature built-in |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
68 support for DICOM transcoding. |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
69 |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
70 |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
71 |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
72 * Explanation of DICOM protocol (transparent transcoding from |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
73 compressed transfer syntaxes to uncompressed transfer syntaxes). |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
74 |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
75 * ``TranscodeDicomProtocol`` global configuration option |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
76 |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
77 * ``AllowTranscoding`` in ``DicomModalities`` configuration option |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
78 |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
79 * ``/instances/.../modify`` route: ``Transcode`` option |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
80 |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
81 * ``IngestTranscoding`` |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
82 |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
83 * ``BuiltinDecoderTranscoderOrder`` |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
84 |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
85 * ``DicomLossyCompressionLevel`` |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
86 |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
87 * Routes to create archives: ``Transcode`` option |
275 | 88 |
427
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
89 You might therefore have to **disable |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
90 transfer syntaxes** by setting the ``*TransferSyntaxAccepted`` options |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
91 to ``false`` in the :ref:`configuration file of Orthanc |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
92 <configuration>` (by default, all the transfer syntaxes are enabled). |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
93 |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
94 |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
95 Solutions to avoid transcoding |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
96 ------------------------------ |
275 | 97 |
427
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
98 Up to release 1.6.1, Orthanc didn't feature support for transcoding |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
99 DICOM instances. In other words, the Orthanc core never changed the |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
100 :ref:`transfer syntax <dicom-pixel-data>` of some DICOM instance when |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
101 it had to send it to another modality using the DICOM protocol. |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
102 |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
103 Three workarounds were available to bypass the need for DICOM |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
104 transcoding in Orthanc <= 1.6.1. These workarounds are still valid in |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
105 Orthanc >= 1.7.0, if transcoding is undesirable (e.g. if Orthanc is |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
106 being run on a computer with sparse CPU/RAM resources). |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
107 |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
108 |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
109 Refusing transfer syntaxes |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
110 ^^^^^^^^^^^^^^^^^^^^^^^^^^ |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
111 |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
112 The first solution consists in making Orthanc **refuse to accept the |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
113 transfer syntaxes** that are not supported by the workstation. This is |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
114 depicted in the following diagram: |
275 | 115 |
116 .. image:: ../images/Transcoding3.svg | |
117 :align: center | |
118 :width: 700px | |
119 | |
120 .. highlight:: json | |
121 | |
122 If Orthanc tells the PACS that is doesn't accept, say, DICOM JPEG2k, | |
427
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
123 the source PACS will be aware of this, and will take care of |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
124 transcoding the DICOM files before they are sent to Orthanc. This is |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
125 the role of the following :ref:`configuration options <configuration>` |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
126 that specifies which transfer syntaxes are accepted by Orthanc:: |
275 | 127 |
128 { | |
129 "DeflatedTransferSyntaxAccepted" : true, | |
130 "JpegTransferSyntaxAccepted" : true, | |
131 "Jpeg2000TransferSyntaxAccepted" : true, | |
132 "JpegLosslessTransferSyntaxAccepted" : true, | |
133 "JpipTransferSyntaxAccepted" : true, | |
134 "Mpeg2TransferSyntaxAccepted" : true, | |
135 "RleTransferSyntaxAccepted" : true, | |
136 "UnknownSopClassAccepted" : false | |
137 } | |
138 | |
139 If all of those options are set to ``false``, Orthanc will only | |
140 receive uncompressed transfer syntaxes (obviously provided that the | |
427
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
141 source PACS itself supports DICOM transcoding). |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
142 |
275 | 143 |
427
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
144 Using external conversion tools |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
145 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
146 |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
147 The second solution consists in **applying an external conversion |
275 | 148 tool** to every DICOM image that is received by Orthanc. The standard |
149 command-line tools ``gdcmconv`` from `GDCM | |
150 <http://gdcm.sourceforge.net/html/gdcmconv.html>`__ or ``dcmconv`` | |
151 from `DCMTK <https://support.dcmtk.org/docs/dcmconv.html>`__ can be | |
152 used to change the transfer syntax of a given DICOM file. These tools | |
153 can be invoked from a :ref:`Lua script <lua>` (check out | |
154 ``OnStoredInstance()`` callback) or from an :ref:`Orthanc plugin | |
155 <creating-plugins>` (check out | |
156 ``OrthancPluginRegisterOnStoredInstanceCallback()`` function). A | |
157 sample Lua script that converts every incoming DICOM file to the | |
158 JPEG2k transfer syntax is `part of the Orthanc sources | |
427
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
159 <https://hg.orthanc-server.com/orthanc/file/default/Resources/Samples/Lua/AutomatedJpeg2kCompression.lua>`__. Note |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
160 that this solution makes no sense anymore in Orthanc 1.7.0, as it |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
161 provides built-in support for transcoding. |
275 | 162 |
163 | |
427
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
164 Transcoding buffer |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
165 ^^^^^^^^^^^^^^^^^^ |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
166 |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
167 Finally, as a third solution, it is possible to **combine two Orthanc |
275 | 168 servers**, the first one being configured to accept any transfer |
169 syntax, and the second one being responsible to serve the DICOM files | |
170 after conversion to uncompressed transfer syntax (which should be | |
171 compatible with any workstation): | |
172 | |
173 .. image:: ../images/Transcoding4.svg | |
174 :align: center | |
175 :width: 700px | |
176 | |
427
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
177 In this solution, the first Orthanc server acts as a transient server |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
178 that implements the decompression (i.e. it transcodes all the DICOM |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
179 instances it receives to an uncompressed transfer syntax). To carry on |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
180 the transcoding, this first Orthanc server can be: |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
181 |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
182 * either an instance Orthanc >= 1.7.0, with transcoding enabled, or |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
183 |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
184 * an instance of Orthanc (any version) equipped with a plugin or an |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
185 external script to do the necessary conversions to an uncompressed |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
186 transfer syntax, as explained in the second solution above. |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
187 |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
188 Whenever a DICOM instance is received by the first Orthanc, the DICOM |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
189 instance is thus transcoded. The first Orthanc server automatically |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
190 forwards all the transcoded instances to the second instance of |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
191 Orthanc, thanks to a :ref:`Lua script <lua>` or an :ref:`external |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
192 script <rest>`, taking advantage of :ref:`Orthanc peering <peering>`. |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
193 |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
194 Contrarily to the second solution, this solution has the advantage of |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
195 better scalability (as decompression can be a time-consuming |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
196 operation). The second instance of Orthanc can run even on a low-end |
71281b540ca1
updating old documentation about transcoding
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
419
diff
changeset
|
197 computer, with any version of Orthanc. |