Mercurial > hg > orthanc-book
annotate Sphinx/source/users/anonymization.rst @ 872:f72b2dd172da Orthanc-1.11.2
Orthanc 1.11.2
author | Alain Mazy <am@osimis.io> |
---|---|
date | Wed, 31 Aug 2022 12:06:15 +0200 |
parents | 3e8a3a900e9e |
children | 900033cffeb2 |
rev | line source |
---|---|
0 | 1 .. highlight:: bash |
2 .. _anonymization: | |
3 | |
4 Anonymization and modification | |
5 ============================== | |
6 | |
7 .. contents:: | |
8 :depth: 2 | |
9 | |
10 Orthanc 0.5.0 introduces the anonymization of DICOM resources | |
11 (i.e. patients, studies, series or instances). This page summarizes | |
12 how to use this feature. | |
13 | |
14 | |
15 Anonymization of a Single Instance | |
16 ---------------------------------- | |
17 | |
18 Orthanc allows to anonymize a single DICOM instance and to download | |
716
33500fc0c0bb
clarification about modification
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
712
diff
changeset
|
19 the resulting anonymized DICOM file (without storing the anonymized |
33500fc0c0bb
clarification about modification
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
712
diff
changeset
|
20 DICOM instance into Orthanc). Anonymization consists in erasing all |
33500fc0c0bb
clarification about modification
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
712
diff
changeset
|
21 the tags that are specified in `Table E.1-1 from PS 3.15 |
691
b8a744941e58
DicomVersion 2021b for anonymization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
648
diff
changeset
|
22 <http://dicom.nema.org/medical/dicom/current/output/chtml/part15/chapter_E.html#table_E.1-1>`__ |
b8a744941e58
DicomVersion 2021b for anonymization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
648
diff
changeset
|
23 of the DICOM standard 2008, 2017c or 2021b (default). Example:: |
0 | 24 |
25 $ curl http://localhost:8042/instances/6e67da51-d119d6ae-c5667437-87b9a8a5-0f07c49f/anonymize -X POST -d '{}' > Anonymized.dcm | |
26 | |
27 It is possible to control how anonymization is achieved by specifying | |
28 a JSON body:: | |
29 | |
444 | 30 $ curl http://localhost:8042/instances/6e67da51-d119d6ae-c5667437-87b9a8a5-0f07c49f/anonymize -X POST \ |
31 --data '{ | |
32 "Replace": { | |
33 "PatientName": "Hello", | |
34 "0010-1001": "World" | |
35 }, | |
36 "Keep": [ | |
37 "StudyDescription", | |
38 "SeriesDescription" | |
39 ], | |
40 "KeepPrivateTags": true, | |
41 "DicomVersion" : "2017c" | |
42 }' > Anonymized.dcm | |
0 | 43 |
694
bcd1a6a89280
replace, keep and remove accept sequences in Orthanc 1.9.4
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
692
diff
changeset
|
44 **Explanations:** |
0 | 45 |
46 * New UUIDs are automatically generated for the study, the series and | |
47 the instance. | |
112
6d357adfd892
updates for the new 1.3.0 API
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
111
diff
changeset
|
48 * The DICOM tags can be specified either by their name |
6d357adfd892
updates for the new 1.3.0 API
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
111
diff
changeset
|
49 (``PatientName``) or by their hexadecimal identifier (in the example |
6d357adfd892
updates for the new 1.3.0 API
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
111
diff
changeset
|
50 above, ``0010-1001`` corresponds to ``Other Patient Names``). |
0 | 51 * ``Replace`` is an associative array that associates a DICOM tag with its |
52 new string value. The value is dynamically cast to the proper DICOM | |
53 data type (an HTTP error will occur if the cast fails). Replacements | |
291
829ce317d215
added sample for /modify for sequences and binary fields
Alain Mazy <alain@mazy.be>
parents:
224
diff
changeset
|
54 are applied after all the tags to anonymize have been removed. |
829ce317d215
added sample for /modify for sequences and binary fields
Alain Mazy <alain@mazy.be>
parents:
224
diff
changeset
|
55 You may also use the ``Replace`` field to add new tags to the file. |
0 | 56 * ``Keep`` specifies a list of tags that should be preserved from full |
57 anonymization. | |
112
6d357adfd892
updates for the new 1.3.0 API
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
111
diff
changeset
|
58 * If ``KeepPrivateTags`` is set to ``true`` in the JSON request, |
6d357adfd892
updates for the new 1.3.0 API
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
111
diff
changeset
|
59 private tags (i.e. manufacturer-specific tags) are not removed by |
6d357adfd892
updates for the new 1.3.0 API
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
111
diff
changeset
|
60 the anonymization process. The default behavior consists in removing |
6d357adfd892
updates for the new 1.3.0 API
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
111
diff
changeset
|
61 the private tags, as such tags can contain patient-specific |
0 | 62 information. |
691
b8a744941e58
DicomVersion 2021b for anonymization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
648
diff
changeset
|
63 * ``DicomVersion`` specifies which version of the DICOM standard shall |
692 | 64 be used for anonymization. Allowed values are ``2008``, ``2017c``, |
65 or ``2021b`` (new in Orthanc 1.9.4). This parameter has been | |
66 introduced in Orthanc 1.3.0. In earlier version, the ``2008`` | |
67 standard was used. If the parameter is absent, the highest version | |
68 that is supported by Orthanc is used. | |
694
bcd1a6a89280
replace, keep and remove accept sequences in Orthanc 1.9.4
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
692
diff
changeset
|
69 * ``Remove`` can also be used to provide a list of tags to be manually |
bcd1a6a89280
replace, keep and remove accept sequences in Orthanc 1.9.4
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
692
diff
changeset
|
70 deleted. |
691
b8a744941e58
DicomVersion 2021b for anonymization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
648
diff
changeset
|
71 |
694
bcd1a6a89280
replace, keep and remove accept sequences in Orthanc 1.9.4
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
692
diff
changeset
|
72 **Important:** Starting with Orthanc 1.9.4, the ``Replace``, ``Keep`` |
bcd1a6a89280
replace, keep and remove accept sequences in Orthanc 1.9.4
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
692
diff
changeset
|
73 and ``Remove`` fields can also specify sequences, using the same |
bcd1a6a89280
replace, keep and remove accept sequences in Orthanc 1.9.4
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
692
diff
changeset
|
74 syntax as the ``dcmodify`` command-line tool (wildcards are supported |
bcd1a6a89280
replace, keep and remove accept sequences in Orthanc 1.9.4
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
692
diff
changeset
|
75 as well). Earlier versions were limited to top-level tags in the DICOM |
bcd1a6a89280
replace, keep and remove accept sequences in Orthanc 1.9.4
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
692
diff
changeset
|
76 dataset. Check out the integration test ``test_modify_subsequences`` |
bcd1a6a89280
replace, keep and remove accept sequences in Orthanc 1.9.4
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
692
diff
changeset
|
77 for `examples |
bcd1a6a89280
replace, keep and remove accept sequences in Orthanc 1.9.4
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
692
diff
changeset
|
78 <https://hg.orthanc-server.com/orthanc-tests/file/default/Tests/Tests.py>`__. |
691
b8a744941e58
DicomVersion 2021b for anonymization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
648
diff
changeset
|
79 |
b8a744941e58
DicomVersion 2021b for anonymization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
648
diff
changeset
|
80 **Implementation:** Internally, the setup of the anonymization |
b8a744941e58
DicomVersion 2021b for anonymization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
648
diff
changeset
|
81 profiles can be found in the methods ``SetupAnonymizationXXX()`` of |
b8a744941e58
DicomVersion 2021b for anonymization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
648
diff
changeset
|
82 the class ``Orthanc::DicomModification`` (cf. `source code |
872 | 83 <https://hg.orthanc-server.com/orthanc/file/Orthanc-1.11.2/OrthancFramework/Sources/DicomParsing/DicomModification.cpp>`__). |
0 | 84 |
85 | |
86 Modification of a Single Instance | |
87 --------------------------------- | |
88 | |
89 Orthanc allows to modify a set of specified tags in a single DICOM | |
716
33500fc0c0bb
clarification about modification
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
712
diff
changeset
|
90 instance and to download the resulting modified DICOM file (without |
33500fc0c0bb
clarification about modification
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
712
diff
changeset
|
91 storing the modified DICOM instance into Orthanc). Example:: |
0 | 92 |
444 | 93 $ curl -X POST http://localhost:8042/instances/6e67da51-d119d6ae-c5667437-87b9a8a5-0f07c49f/modify \ |
94 --data '{ | |
95 "Replace": { | |
96 "PatientName":"hello", | |
97 "PatientID":"world" | |
98 }, | |
99 "Remove":[ | |
100 "InstitutionName" | |
101 ], | |
102 "RemovePrivateTags": true, | |
103 "Force": true, | |
104 "Transcode": "1.2.840.10008.1.2.4.70" | |
105 }' > Modified.dcm | |
0 | 106 |
694
bcd1a6a89280
replace, keep and remove accept sequences in Orthanc 1.9.4
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
692
diff
changeset
|
107 **Remarks:** |
0 | 108 |
109 * The ``Remove`` array specifies the list of the tags to remove. | |
110 * The ``Replace`` associative array specifies the substitions to be applied (cf. anonymization). | |
112
6d357adfd892
updates for the new 1.3.0 API
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
111
diff
changeset
|
111 * If ``RemovePrivateTags`` is set to ``true``, the private tags |
6d357adfd892
updates for the new 1.3.0 API
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
111
diff
changeset
|
112 (i.e. manufacturer-specific tags) are removed. |
444 | 113 * The ``Transcode`` option allows you to define the TransferSyntax |
114 of the modified file. | |
112
6d357adfd892
updates for the new 1.3.0 API
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
111
diff
changeset
|
115 * The ``Force`` option must be set to ``true``, in order to allow the |
6d357adfd892
updates for the new 1.3.0 API
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
111
diff
changeset
|
116 modification of the ``PatientID``, as such a modification of the |
6d357adfd892
updates for the new 1.3.0 API
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
111
diff
changeset
|
117 :ref:`DICOM identifiers <dicom-identifiers>` might lead to breaking |
113 | 118 the DICOM model of the real-world. In general, any explicit |
119 modification to one of the ``PatientID``, ``StudyInstanceUID``, | |
120 ``SeriesInstanceUID``, and ``SOPInstanceUID`` requires ``Force`` to | |
121 be set to ``true``, in order to prevent any unwanted side effect. | |
694
bcd1a6a89280
replace, keep and remove accept sequences in Orthanc 1.9.4
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
692
diff
changeset
|
122 |
291
829ce317d215
added sample for /modify for sequences and binary fields
Alain Mazy <alain@mazy.be>
parents:
224
diff
changeset
|
123 .. highlight:: json |
0 | 124 |
291
829ce317d215
added sample for /modify for sequences and binary fields
Alain Mazy <alain@mazy.be>
parents:
224
diff
changeset
|
125 * To replace a sequence of tags, you may use this syntax:: |
829ce317d215
added sample for /modify for sequences and binary fields
Alain Mazy <alain@mazy.be>
parents:
224
diff
changeset
|
126 |
829ce317d215
added sample for /modify for sequences and binary fields
Alain Mazy <alain@mazy.be>
parents:
224
diff
changeset
|
127 |
829ce317d215
added sample for /modify for sequences and binary fields
Alain Mazy <alain@mazy.be>
parents:
224
diff
changeset
|
128 { |
829ce317d215
added sample for /modify for sequences and binary fields
Alain Mazy <alain@mazy.be>
parents:
224
diff
changeset
|
129 "Replace" : { |
829ce317d215
added sample for /modify for sequences and binary fields
Alain Mazy <alain@mazy.be>
parents:
224
diff
changeset
|
130 "ProcedureCodeSequence" : [ |
829ce317d215
added sample for /modify for sequences and binary fields
Alain Mazy <alain@mazy.be>
parents:
224
diff
changeset
|
131 { |
829ce317d215
added sample for /modify for sequences and binary fields
Alain Mazy <alain@mazy.be>
parents:
224
diff
changeset
|
132 "CodeValue" : "2", |
829ce317d215
added sample for /modify for sequences and binary fields
Alain Mazy <alain@mazy.be>
parents:
224
diff
changeset
|
133 "CodingSchemeDesignator" : "1", |
829ce317d215
added sample for /modify for sequences and binary fields
Alain Mazy <alain@mazy.be>
parents:
224
diff
changeset
|
134 "CodeMeaning": "1" |
829ce317d215
added sample for /modify for sequences and binary fields
Alain Mazy <alain@mazy.be>
parents:
224
diff
changeset
|
135 } |
829ce317d215
added sample for /modify for sequences and binary fields
Alain Mazy <alain@mazy.be>
parents:
224
diff
changeset
|
136 ] |
829ce317d215
added sample for /modify for sequences and binary fields
Alain Mazy <alain@mazy.be>
parents:
224
diff
changeset
|
137 } |
829ce317d215
added sample for /modify for sequences and binary fields
Alain Mazy <alain@mazy.be>
parents:
224
diff
changeset
|
138 } |
829ce317d215
added sample for /modify for sequences and binary fields
Alain Mazy <alain@mazy.be>
parents:
224
diff
changeset
|
139 |
829ce317d215
added sample for /modify for sequences and binary fields
Alain Mazy <alain@mazy.be>
parents:
224
diff
changeset
|
140 * To replace a binary tag, you should encode it in base64 and use:: |
829ce317d215
added sample for /modify for sequences and binary fields
Alain Mazy <alain@mazy.be>
parents:
224
diff
changeset
|
141 |
829ce317d215
added sample for /modify for sequences and binary fields
Alain Mazy <alain@mazy.be>
parents:
224
diff
changeset
|
142 { |
829ce317d215
added sample for /modify for sequences and binary fields
Alain Mazy <alain@mazy.be>
parents:
224
diff
changeset
|
143 "Replace" : { |
829ce317d215
added sample for /modify for sequences and binary fields
Alain Mazy <alain@mazy.be>
parents:
224
diff
changeset
|
144 "EncryptedAttributesSequence" : [ |
829ce317d215
added sample for /modify for sequences and binary fields
Alain Mazy <alain@mazy.be>
parents:
224
diff
changeset
|
145 { |
829ce317d215
added sample for /modify for sequences and binary fields
Alain Mazy <alain@mazy.be>
parents:
224
diff
changeset
|
146 "EncryptedContentTransferSyntaxUID" : "1.2.840.10008.1.2", |
829ce317d215
added sample for /modify for sequences and binary fields
Alain Mazy <alain@mazy.be>
parents:
224
diff
changeset
|
147 "EncryptedContent" : "data:application/octet-stream;base64,SSB3YXMgaGVyZSBpbiAyMDE5LiAgTWFydHkgTWNGbHku" |
829ce317d215
added sample for /modify for sequences and binary fields
Alain Mazy <alain@mazy.be>
parents:
224
diff
changeset
|
148 } |
829ce317d215
added sample for /modify for sequences and binary fields
Alain Mazy <alain@mazy.be>
parents:
224
diff
changeset
|
149 ] |
829ce317d215
added sample for /modify for sequences and binary fields
Alain Mazy <alain@mazy.be>
parents:
224
diff
changeset
|
150 } |
829ce317d215
added sample for /modify for sequences and binary fields
Alain Mazy <alain@mazy.be>
parents:
224
diff
changeset
|
151 } |
300
22d567933381
tutorials about plugins by Marco Barnig
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
291
diff
changeset
|
152 |
853 | 153 * To add a Private DICOM tag, you should use this syntax (provided that you have defined an entry ``"7001,0001" : [ "CS", "MyPrivateTag", 1, 1, "MyPrivateCreator"]`` in the ``Dictionary`` configuration):: |
154 | |
155 { | |
156 "Replace" : { | |
157 "MyPrivateTag" : "Hello" | |
158 }, | |
159 "PrivateCreator" : "MyPrivateCreator" | |
160 } | |
161 | |
694
bcd1a6a89280
replace, keep and remove accept sequences in Orthanc 1.9.4
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
692
diff
changeset
|
162 |
bcd1a6a89280
replace, keep and remove accept sequences in Orthanc 1.9.4
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
692
diff
changeset
|
163 **Important:** Similarly to anonymization, starting with Orthanc |
bcd1a6a89280
replace, keep and remove accept sequences in Orthanc 1.9.4
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
692
diff
changeset
|
164 1.9.4, the ``Replace``, ``Keep`` and ``Remove`` fields can also |
bcd1a6a89280
replace, keep and remove accept sequences in Orthanc 1.9.4
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
692
diff
changeset
|
165 specify sequences, using the same syntax as the ``dcmodify`` |
bcd1a6a89280
replace, keep and remove accept sequences in Orthanc 1.9.4
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
692
diff
changeset
|
166 command-line tool (wildcards are supported as well). Earlier versions |
bcd1a6a89280
replace, keep and remove accept sequences in Orthanc 1.9.4
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
692
diff
changeset
|
167 were limited to top-level tags in the DICOM dataset. Check out the |
bcd1a6a89280
replace, keep and remove accept sequences in Orthanc 1.9.4
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
692
diff
changeset
|
168 integration test ``test_modify_subsequences`` for `examples |
bcd1a6a89280
replace, keep and remove accept sequences in Orthanc 1.9.4
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
692
diff
changeset
|
169 <https://hg.orthanc-server.com/orthanc-tests/file/default/Tests/Tests.py>`__. |
bcd1a6a89280
replace, keep and remove accept sequences in Orthanc 1.9.4
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
692
diff
changeset
|
170 |
bcd1a6a89280
replace, keep and remove accept sequences in Orthanc 1.9.4
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
692
diff
changeset
|
171 |
331
48673b8abae3
documentation of storage commitment scu
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
300
diff
changeset
|
172 .. _study-modification: |
48673b8abae3
documentation of storage commitment scu
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
300
diff
changeset
|
173 |
0 | 174 Modification of Studies or Series |
175 --------------------------------- | |
176 | |
177 .. highlight:: bash | |
178 | |
179 It is possible to modify all the instances from a study or from a | |
180 series in a single request. In this case, the modified instances are | |
181 stored back into the Orthanc store. Here is how to modify a series:: | |
182 | |
183 $ curl http://localhost:8042/series/95a6e2bf-9296e2cc-bf614e2f-22b391ee-16e010e0/modify -X POST -d '{"Replace":{"InstitutionName":"My own clinic"}}' | |
184 | |
185 | |
186 .. highlight:: json | |
187 | |
188 The parameters are identical to those used to modify a single | |
189 instance. Orthanc will answer a JSON message that tells where the | |
190 modified series has been stored:: | |
191 | |
192 { | |
193 "ID" : "3bd3d343-82879d86-da77321c-1d23fd6b-faa07bce", | |
194 "Path" : "/series/3bd3d343-82879d86-da77321c-1d23fd6b-faa07bce" | |
195 } | |
196 | |
197 | |
198 .. highlight:: bash | |
199 | |
200 Similarly, here is an interaction to modify a study:: | |
201 | |
202 $ curl http://localhost:8042/studies/ef2ce55f-9342856a-aee23907-2667e859-9f3b734d/modify -X POST -d '{"Replace":{"InstitutionName":"My own clinic"}}' | |
203 | |
204 .. highlight:: json | |
205 | |
206 :: | |
207 | |
208 { | |
209 "ID" : "1c3f7bf4-85b4aa20-236e6315-5d450dcc-3c1bcf28", | |
210 "Path" : "/studies/1c3f7bf4-85b4aa20-236e6315-5d450dcc-3c1bcf28" | |
211 } | |
212 | |
716
33500fc0c0bb
clarification about modification
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
712
diff
changeset
|
213 Pay attention to the fact that Orthanc implements safety checks to |
33500fc0c0bb
clarification about modification
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
712
diff
changeset
|
214 preserve the :ref:`DICOM model of the real world <model-world>`. These |
33500fc0c0bb
clarification about modification
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
712
diff
changeset
|
215 checks prevent the modification of some tags that are known to belong |
33500fc0c0bb
clarification about modification
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
712
diff
changeset
|
216 to a level in the patient/study/series/instance hierarchy that is |
33500fc0c0bb
clarification about modification
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
712
diff
changeset
|
217 higher than the level that corresponds to the REST API call. For |
33500fc0c0bb
clarification about modification
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
712
diff
changeset
|
218 instance, the tag ``PatientID`` cannot be modified if using the |
33500fc0c0bb
clarification about modification
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
712
diff
changeset
|
219 ``/studies/{id}/modify`` route (in the latter case, the |
33500fc0c0bb
clarification about modification
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
712
diff
changeset
|
220 ``/patients/{id}/modify`` route must be used, cf. next section). You |
33500fc0c0bb
clarification about modification
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
712
diff
changeset
|
221 also have to set the ``Force`` argument to ``true`` if modifying one |
33500fc0c0bb
clarification about modification
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
712
diff
changeset
|
222 of the :ref:`DICOM identifiers tags <orthanc-ids>` |
33500fc0c0bb
clarification about modification
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
712
diff
changeset
|
223 (i.e. ``PatientID``, ``StudyInstanceUID``, ``SeriesInstanceUID`` and |
33500fc0c0bb
clarification about modification
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
712
diff
changeset
|
224 ``SOPInstanceUID``). |
33500fc0c0bb
clarification about modification
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
712
diff
changeset
|
225 |
0 | 226 |
227 Modification of Patients | |
228 ------------------------ | |
229 | |
230 .. highlight:: bash | |
231 | |
232 Starting with Orthanc 0.7.5, Orthanc can also modify all the instances | |
233 of a patient with a single REST call. Here is a sample:: | |
234 | |
112
6d357adfd892
updates for the new 1.3.0 API
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
111
diff
changeset
|
235 $ curl http://localhost:8042/patients/6fb47ef5-072f4557-3215aa29-f99515c1-6fa22bf0/modify -X POST -d '{"Replace":{"PatientID":"Hello","PatientName":"Sample patient name"},"Force":true}' |
0 | 236 |
237 .. highlight:: json | |
238 | |
239 :: | |
240 | |
241 { | |
242 "ID" : "f7ff9e8b-7bb2e09b-70935a5d-785e0cc5-d9d0abf0", | |
243 "Path" : "/patients/f7ff9e8b-7bb2e09b-70935a5d-785e0cc5-d9d0abf0", | |
244 "PatientID" : "f7ff9e8b-7bb2e09b-70935a5d-785e0cc5-d9d0abf0", | |
245 "Type" : "Patient" | |
246 } | |
247 | |
248 Please note that, in this case, you have to set the value of the | |
249 ``PatientID (0010,0020)`` tag for Orthanc to accept this modification: | |
250 This is a security to prevent the merging of patient data before and | |
251 after anonymization, if the user does not explicitly tell Orthanc to | |
252 do so. | |
253 | |
254 | |
255 Anonymization of Patients, Studies or Series | |
256 -------------------------------------------- | |
257 | |
258 .. highlight:: bash | |
259 | |
260 Study and series can be anonymized the same way as they are modified:: | |
261 | |
262 $ curl http://localhost:8042/patients/6fb47ef5-072f4557-3215aa29-f99515c1-6fa22bf0/anonymize -X POST -d '{}' | |
263 $ curl http://localhost:8042/studies/ef2ce55f-9342856a-aee23907-2667e859-9f3b734d/anonymize -X POST -d '{}' | |
264 $ curl http://localhost:8042/series/95a6e2bf-9296e2cc-bf614e2f-22b391ee-16e010e0/anonymize -X POST -d '{}' | |
265 | |
266 As written above, the anonymization process can be fine-tuned by using | |
267 a JSON body. | |
167 | 268 |
269 | |
711
4f658c25addd
bulk anonymization/modification
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
694
diff
changeset
|
270 .. _bulk-modification: |
4f658c25addd
bulk anonymization/modification
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
694
diff
changeset
|
271 |
4f658c25addd
bulk anonymization/modification
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
694
diff
changeset
|
272 Bulk modification or anonymization |
4f658c25addd
bulk anonymization/modification
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
694
diff
changeset
|
273 ---------------------------------- |
4f658c25addd
bulk anonymization/modification
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
694
diff
changeset
|
274 |
4f658c25addd
bulk anonymization/modification
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
694
diff
changeset
|
275 Starting with Orthanc 1.9.4, it is possible to use the new routes |
4f658c25addd
bulk anonymization/modification
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
694
diff
changeset
|
276 ``/tools/bulk-modify`` and ``/tools/bulk-anonymize`` to respectively |
4f658c25addd
bulk anonymization/modification
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
694
diff
changeset
|
277 modify or anonymize a set of multiple DICOM resources that are not |
4f658c25addd
bulk anonymization/modification
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
694
diff
changeset
|
278 related (i.e. that don't share any parent DICOM resource). A typical |
4f658c25addd
bulk anonymization/modification
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
694
diff
changeset
|
279 use case is to modify/anonymize a list of DICOM instances that don't |
4f658c25addd
bulk anonymization/modification
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
694
diff
changeset
|
280 belong to the same parent patient/study/series. |
4f658c25addd
bulk anonymization/modification
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
694
diff
changeset
|
281 |
4f658c25addd
bulk anonymization/modification
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
694
diff
changeset
|
282 .. highlight:: bash |
4f658c25addd
bulk anonymization/modification
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
694
diff
changeset
|
283 |
4f658c25addd
bulk anonymization/modification
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
694
diff
changeset
|
284 These two routes accept the same arguments as described above, but |
4f658c25addd
bulk anonymization/modification
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
694
diff
changeset
|
285 must also be provided with an additional argument ``Resources`` that |
4f658c25addd
bulk anonymization/modification
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
694
diff
changeset
|
286 lists the :ref:`Orthanc identifiers <orthanc-ids>` of the resources of |
4f658c25addd
bulk anonymization/modification
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
694
diff
changeset
|
287 interest (that may indifferently correspond to patients, studies, |
4f658c25addd
bulk anonymization/modification
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
694
diff
changeset
|
288 series or instances). Here are two sample calls:: |
4f658c25addd
bulk anonymization/modification
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
694
diff
changeset
|
289 |
4f658c25addd
bulk anonymization/modification
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
694
diff
changeset
|
290 $ curl http://localhost:8042/tools/bulk-modify -d '{"Replace":{"SeriesDescription":"HELLO"},"Resources":["b6da0b16-a25ae9e7-1a80fc33-20df01a9-a6f7a1b0","d6634d97-24379e4a-1e68d3af-e6d0451f-e7bcd3d1"]}' |
4f658c25addd
bulk anonymization/modification
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
694
diff
changeset
|
291 $ curl http://localhost:8042/tools/bulk-anonymize -d '{"Resources":["b6da0b16-a25ae9e7-1a80fc33-20df01a9-a6f7a1b0","d6634d97-24379e4a-1e68d3af-e6d0451f-e7bcd3d1"]}' |
4f658c25addd
bulk anonymization/modification
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
694
diff
changeset
|
292 |
4f658c25addd
bulk anonymization/modification
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
694
diff
changeset
|
293 .. highlight:: json |
4f658c25addd
bulk anonymization/modification
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
694
diff
changeset
|
294 |
4f658c25addd
bulk anonymization/modification
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
694
diff
changeset
|
295 The output of the modification/anonymization lists all the resources |
4f658c25addd
bulk anonymization/modification
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
694
diff
changeset
|
296 that have been altered by the call (including their parents). Here is |
4f658c25addd
bulk anonymization/modification
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
694
diff
changeset
|
297 the output of the second sample above:: |
4f658c25addd
bulk anonymization/modification
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
694
diff
changeset
|
298 |
4f658c25addd
bulk anonymization/modification
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
694
diff
changeset
|
299 { |
712 | 300 "Description" : "REST API", |
301 "FailedInstancesCount" : 0, | |
302 "InstancesCount" : 2, | |
303 "IsAnonymization" : true, | |
304 "Resources" : [ | |
711
4f658c25addd
bulk anonymization/modification
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
694
diff
changeset
|
305 { |
4f658c25addd
bulk anonymization/modification
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
694
diff
changeset
|
306 "ID" : "04c04806-27b01a5a-08ea66cb-cb36c8b9-ebe62fe3", |
4f658c25addd
bulk anonymization/modification
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
694
diff
changeset
|
307 "Path" : "/instances/04c04806-27b01a5a-08ea66cb-cb36c8b9-ebe62fe3", |
4f658c25addd
bulk anonymization/modification
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
694
diff
changeset
|
308 "Type" : "Instance" |
4f658c25addd
bulk anonymization/modification
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
694
diff
changeset
|
309 }, |
4f658c25addd
bulk anonymization/modification
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
694
diff
changeset
|
310 { |
4f658c25addd
bulk anonymization/modification
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
694
diff
changeset
|
311 "ID" : "4e37fce9-6b33b8ba-7bb378e1-abc7e2c4-fca4ade3", |
4f658c25addd
bulk anonymization/modification
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
694
diff
changeset
|
312 "Path" : "/instances/4e37fce9-6b33b8ba-7bb378e1-abc7e2c4-fca4ade3", |
4f658c25addd
bulk anonymization/modification
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
694
diff
changeset
|
313 "Type" : "Instance" |
4f658c25addd
bulk anonymization/modification
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
694
diff
changeset
|
314 }, |
4f658c25addd
bulk anonymization/modification
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
694
diff
changeset
|
315 { |
4f658c25addd
bulk anonymization/modification
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
694
diff
changeset
|
316 "ID" : "6438ee62-b58a4788-517931b3-e10321eb-d1ab2613", |
4f658c25addd
bulk anonymization/modification
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
694
diff
changeset
|
317 "Path" : "/series/6438ee62-b58a4788-517931b3-e10321eb-d1ab2613", |
4f658c25addd
bulk anonymization/modification
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
694
diff
changeset
|
318 "Type" : "Series" |
4f658c25addd
bulk anonymization/modification
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
694
diff
changeset
|
319 }, |
4f658c25addd
bulk anonymization/modification
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
694
diff
changeset
|
320 { |
4f658c25addd
bulk anonymization/modification
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
694
diff
changeset
|
321 "ID" : "660494fd-1ddd661b-4358d996-ba600e5a-066d94cc", |
4f658c25addd
bulk anonymization/modification
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
694
diff
changeset
|
322 "Path" : "/studies/660494fd-1ddd661b-4358d996-ba600e5a-066d94cc", |
4f658c25addd
bulk anonymization/modification
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
694
diff
changeset
|
323 "Type" : "Study" |
4f658c25addd
bulk anonymization/modification
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
694
diff
changeset
|
324 }, |
4f658c25addd
bulk anonymization/modification
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
694
diff
changeset
|
325 { |
4f658c25addd
bulk anonymization/modification
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
694
diff
changeset
|
326 "ID" : "5faa0bf8-8a45520b-3a07e536-fc24f241-f59ae3e1", |
4f658c25addd
bulk anonymization/modification
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
694
diff
changeset
|
327 "Path" : "/patients/5faa0bf8-8a45520b-3a07e536-fc24f241-f59ae3e1", |
4f658c25addd
bulk anonymization/modification
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
694
diff
changeset
|
328 "Type" : "Patient" |
4f658c25addd
bulk anonymization/modification
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
694
diff
changeset
|
329 } |
712 | 330 ] |
331 } | |
711
4f658c25addd
bulk anonymization/modification
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
694
diff
changeset
|
332 |
4f658c25addd
bulk anonymization/modification
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
694
diff
changeset
|
333 |
4f658c25addd
bulk anonymization/modification
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
694
diff
changeset
|
334 |
224
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
178
diff
changeset
|
335 .. _split-merge: |
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
178
diff
changeset
|
336 |
167 | 337 Split/merge of DICOM studies |
338 ---------------------------- | |
339 | |
178 | 340 Starting with Orthanc 1.5.0, Orthanc supports splitting and merging |
167 | 341 DICOM studies through its REST API. |
342 | |
224
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
178
diff
changeset
|
343 .. _split: |
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
178
diff
changeset
|
344 |
167 | 345 Splitting |
346 ^^^^^^^^^ | |
347 | |
348 Here is the syntax to **split** a DICOM study:: | |
349 | |
350 $ curl http://localhost:8042/studies/6e2c0ec2-5d99c8ca-c1c21cee-79a09605-68391d12/split -d \ | |
351 '{"Series":["6ca4c9f3-5e895cb3-4d82c6da-09e060fe-9c59f228"],"Replace":{"PatientName":"HELLO"},"Remove":["AccessionNumber"]}' | |
352 | |
353 By issuing this command, the series whose :ref:`Orthanc identifier | |
354 <dicom-identifiers>` is | |
355 ``6ca4c9f3-5e895cb3-4d82c6da-09e060fe-9c59f228``, and that is part of | |
356 the source study with identifier | |
357 ``6e2c0ec2-5d99c8ca-c1c21cee-79a09605-68391d12``, will be removed from | |
358 the source study, and will be moved to a brand new study. | |
359 | |
360 This is done by generating a new value for all the following DICOM | |
361 tags in the DICOM instances of the series of interest: | |
362 ``StudyInstanceUID (0x0020, 0x000d)``, ``SeriesInstanceUID (0x0020, | |
363 0x000e)``, and ``SOPInstanceUID (0x0008, 0x0018)``. Here are the | |
364 arguments of this ``/studies/{study}/split`` URI: | |
365 | |
366 * ``Series`` gives the list of series to be separated from the parent | |
367 study (mandatory option). These series must all be children of the | |
368 same source study, that is specified in the URI. | |
369 * ``Replace`` allows to overwrite the DICOM tags that are part of the | |
370 "Patient Module Attributes" and the "General Study Module | |
371 Attributes", as specified by the DICOM 2011 standard in Tables C.7-1 | |
372 and C.7-3. | |
373 * ``Remove`` allows to remove DICOM tags from the same modules as in | |
374 the ``Replace`` options. | |
375 * ``KeepSource`` (Boolean value), if set to ``true``, instructs | |
376 Orthanc to keep a copy of the original series in the source study. | |
377 By default, the original series are deleted from Orthanc. | |
691
b8a744941e58
DicomVersion 2021b for anonymization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
648
diff
changeset
|
378 |
224
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
178
diff
changeset
|
379 .. _merge: |
167 | 380 |
381 Merging | |
382 ^^^^^^^ | |
383 | |
384 Here is the syntax to **merge** DICOM series, into another DICOM study:: | |
385 | |
386 $ curl http://localhost:8042/studies/6e2c0ec2-5d99c8ca-c1c21cee-79a09605-68391d12/merge -d \ | |
387 '{"Resources":["ef2ce55f-9342856a-aee23907-2667e859-9f3b734d"]}' | |
388 | |
389 By issuing this command, the DICOM series whose :ref:`Orthanc | |
390 identifier <dicom-identifiers>` is | |
391 ``ef2ce55f-9342856a-aee23907-2667e859-9f3b734d``, will be merged into | |
392 target study with identifier | |
393 ``6e2c0ec2-5d99c8ca-c1c21cee-79a09605-68391d12``. | |
394 | |
395 As in the case of splitting, this is done by updating the following | |
396 DICOM tags: ``StudyInstanceUID (0x0020, 0x000d)``, ``SeriesInstanceUID | |
397 (0x0020, 0x000e)``, and ``SOPInstanceUID (0x0008, | |
398 0x0018)``. Furthermore, all the DICOM tags that are part of the | |
399 "Patient Module Attributes" and the "General Study Module Attributes" | |
400 (as specified by the DICOM 2011 standard in Tables C.7-1 and C.7-3), | |
401 are modified to match the target study. Here are the | |
402 arguments of this ``/studies/{study}/merge`` URI: | |
403 | |
404 * ``Resources`` gives the list of source studies or source series | |
405 that are to be merged into the target study. | |
406 * ``KeepSource`` (Boolean value), if set to ``true``, instructs | |
407 Orthanc to keep the source studies and series. By default, the | |
408 original resources are deleted from Orthanc. |