Mercurial > hg > orthanc-book
annotate Sphinx/source/users/anonymization.rst @ 691:b8a744941e58
DicomVersion 2021b for anonymization
author | Sebastien Jodogne <s.jodogne@gmail.com> |
---|---|
date | Thu, 03 Jun 2021 21:19:42 +0200 |
parents | fcd2c2b66297 |
children | 549824ebdf5a |
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 | |
19 the resulting anonymized DICOM file. Anonymization consists in erasing | |
691
b8a744941e58
DicomVersion 2021b for anonymization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
648
diff
changeset
|
20 all the tags that are specified in `Table E.1-1 from PS 3.15 |
b8a744941e58
DicomVersion 2021b for anonymization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
648
diff
changeset
|
21 <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
|
22 of the DICOM standard 2008, 2017c or 2021b (default). Example:: |
0 | 23 |
24 $ curl http://localhost:8042/instances/6e67da51-d119d6ae-c5667437-87b9a8a5-0f07c49f/anonymize -X POST -d '{}' > Anonymized.dcm | |
25 | |
26 It is possible to control how anonymization is achieved by specifying | |
27 a JSON body:: | |
28 | |
444 | 29 $ curl http://localhost:8042/instances/6e67da51-d119d6ae-c5667437-87b9a8a5-0f07c49f/anonymize -X POST \ |
30 --data '{ | |
31 "Replace": { | |
32 "PatientName": "Hello", | |
33 "0010-1001": "World" | |
34 }, | |
35 "Keep": [ | |
36 "StudyDescription", | |
37 "SeriesDescription" | |
38 ], | |
39 "KeepPrivateTags": true, | |
40 "DicomVersion" : "2017c" | |
41 }' > Anonymized.dcm | |
0 | 42 |
43 Explanations: | |
44 | |
45 * New UUIDs are automatically generated for the study, the series and | |
46 the instance. | |
112
6d357adfd892
updates for the new 1.3.0 API
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
111
diff
changeset
|
47 * 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
|
48 (``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
|
49 above, ``0010-1001`` corresponds to ``Other Patient Names``). |
0 | 50 * ``Replace`` is an associative array that associates a DICOM tag with its |
51 new string value. The value is dynamically cast to the proper DICOM | |
52 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
|
53 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
|
54 You may also use the ``Replace`` field to add new tags to the file. |
0 | 55 * ``Keep`` specifies a list of tags that should be preserved from full |
56 anonymization. | |
112
6d357adfd892
updates for the new 1.3.0 API
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
111
diff
changeset
|
57 * 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
|
58 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
|
59 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
|
60 the private tags, as such tags can contain patient-specific |
0 | 61 information. |
691
b8a744941e58
DicomVersion 2021b for anonymization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
648
diff
changeset
|
62 * ``DicomVersion`` specifies which version of the DICOM standard shall |
b8a744941e58
DicomVersion 2021b for anonymization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
648
diff
changeset
|
63 be used for anonymization. Allowed values are ``2008``, ``2017c``, |
b8a744941e58
DicomVersion 2021b for anonymization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
648
diff
changeset
|
64 or ``2021b`` (default value is ``2021b`` if the parameter is |
b8a744941e58
DicomVersion 2021b for anonymization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
648
diff
changeset
|
65 absent). This parameter has been introduced in Orthanc 1.3.0. In |
b8a744941e58
DicomVersion 2021b for anonymization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
648
diff
changeset
|
66 earlier version, the ``2008`` standard was used. |
b8a744941e58
DicomVersion 2021b for anonymization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
648
diff
changeset
|
67 |
b8a744941e58
DicomVersion 2021b for anonymization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
648
diff
changeset
|
68 |
b8a744941e58
DicomVersion 2021b for anonymization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
648
diff
changeset
|
69 **Implementation:** Internally, the setup of the anonymization |
b8a744941e58
DicomVersion 2021b for anonymization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
648
diff
changeset
|
70 profiles can be found in the methods ``SetupAnonymizationXXX()`` of |
b8a744941e58
DicomVersion 2021b for anonymization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
648
diff
changeset
|
71 the class ``Orthanc::DicomModification`` (cf. `source code |
b8a744941e58
DicomVersion 2021b for anonymization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
648
diff
changeset
|
72 <https://hg.orthanc-server.com/orthanc/file/tip/OrthancFramework/Sources/DicomParsing/DicomModification.cpp>`__). |
0 | 73 |
74 | |
75 Modification of a Single Instance | |
76 --------------------------------- | |
77 | |
78 Orthanc allows to modify a set of specified tags in a single DICOM | |
648
fcd2c2b66297
Fixed typo (anonymized --> modified)
Benjamin Golinvaux <bgo@osimis.io>
parents:
444
diff
changeset
|
79 instance and to download the resulting modified DICOM |
0 | 80 file. Example:: |
81 | |
444 | 82 $ curl -X POST http://localhost:8042/instances/6e67da51-d119d6ae-c5667437-87b9a8a5-0f07c49f/modify \ |
83 --data '{ | |
84 "Replace": { | |
85 "PatientName":"hello", | |
86 "PatientID":"world" | |
87 }, | |
88 "Remove":[ | |
89 "InstitutionName" | |
90 ], | |
91 "RemovePrivateTags": true, | |
92 "Force": true, | |
93 "Transcode": "1.2.840.10008.1.2.4.70" | |
94 }' > Modified.dcm | |
0 | 95 |
96 Remarks: | |
97 | |
98 * The ``Remove`` array specifies the list of the tags to remove. | |
99 * 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
|
100 * 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
|
101 (i.e. manufacturer-specific tags) are removed. |
444 | 102 * The ``Transcode`` option allows you to define the TransferSyntax |
103 of the modified file. | |
112
6d357adfd892
updates for the new 1.3.0 API
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
111
diff
changeset
|
104 * 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
|
105 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
|
106 :ref:`DICOM identifiers <dicom-identifiers>` might lead to breaking |
113 | 107 the DICOM model of the real-world. In general, any explicit |
108 modification to one of the ``PatientID``, ``StudyInstanceUID``, | |
109 ``SeriesInstanceUID``, and ``SOPInstanceUID`` requires ``Force`` to | |
110 be set to ``true``, in order to prevent any unwanted side effect. | |
0 | 111 |
291
829ce317d215
added sample for /modify for sequences and binary fields
Alain Mazy <alain@mazy.be>
parents:
224
diff
changeset
|
112 .. highlight:: json |
0 | 113 |
291
829ce317d215
added sample for /modify for sequences and binary fields
Alain Mazy <alain@mazy.be>
parents:
224
diff
changeset
|
114 * 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
|
115 |
829ce317d215
added sample for /modify for sequences and binary fields
Alain Mazy <alain@mazy.be>
parents:
224
diff
changeset
|
116 |
829ce317d215
added sample for /modify for sequences and binary fields
Alain Mazy <alain@mazy.be>
parents:
224
diff
changeset
|
117 { |
829ce317d215
added sample for /modify for sequences and binary fields
Alain Mazy <alain@mazy.be>
parents:
224
diff
changeset
|
118 "Replace" : { |
829ce317d215
added sample for /modify for sequences and binary fields
Alain Mazy <alain@mazy.be>
parents:
224
diff
changeset
|
119 "ProcedureCodeSequence" : [ |
829ce317d215
added sample for /modify for sequences and binary fields
Alain Mazy <alain@mazy.be>
parents:
224
diff
changeset
|
120 { |
829ce317d215
added sample for /modify for sequences and binary fields
Alain Mazy <alain@mazy.be>
parents:
224
diff
changeset
|
121 "CodeValue" : "2", |
829ce317d215
added sample for /modify for sequences and binary fields
Alain Mazy <alain@mazy.be>
parents:
224
diff
changeset
|
122 "CodingSchemeDesignator" : "1", |
829ce317d215
added sample for /modify for sequences and binary fields
Alain Mazy <alain@mazy.be>
parents:
224
diff
changeset
|
123 "CodeMeaning": "1" |
829ce317d215
added sample for /modify for sequences and binary fields
Alain Mazy <alain@mazy.be>
parents:
224
diff
changeset
|
124 } |
829ce317d215
added sample for /modify for sequences and binary fields
Alain Mazy <alain@mazy.be>
parents:
224
diff
changeset
|
125 ] |
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 * 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
|
130 |
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 "Replace" : { |
829ce317d215
added sample for /modify for sequences and binary fields
Alain Mazy <alain@mazy.be>
parents:
224
diff
changeset
|
133 "EncryptedAttributesSequence" : [ |
829ce317d215
added sample for /modify for sequences and binary fields
Alain Mazy <alain@mazy.be>
parents:
224
diff
changeset
|
134 { |
829ce317d215
added sample for /modify for sequences and binary fields
Alain Mazy <alain@mazy.be>
parents:
224
diff
changeset
|
135 "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
|
136 "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
|
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 } |
300
22d567933381
tutorials about plugins by Marco Barnig
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
291
diff
changeset
|
141 |
331
48673b8abae3
documentation of storage commitment scu
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
300
diff
changeset
|
142 .. _study-modification: |
48673b8abae3
documentation of storage commitment scu
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
300
diff
changeset
|
143 |
0 | 144 Modification of Studies or Series |
145 --------------------------------- | |
146 | |
147 .. highlight:: bash | |
148 | |
149 It is possible to modify all the instances from a study or from a | |
150 series in a single request. In this case, the modified instances are | |
151 stored back into the Orthanc store. Here is how to modify a series:: | |
152 | |
153 $ curl http://localhost:8042/series/95a6e2bf-9296e2cc-bf614e2f-22b391ee-16e010e0/modify -X POST -d '{"Replace":{"InstitutionName":"My own clinic"}}' | |
154 | |
155 | |
156 .. highlight:: json | |
157 | |
158 The parameters are identical to those used to modify a single | |
159 instance. Orthanc will answer a JSON message that tells where the | |
160 modified series has been stored:: | |
161 | |
162 { | |
163 "ID" : "3bd3d343-82879d86-da77321c-1d23fd6b-faa07bce", | |
164 "Path" : "/series/3bd3d343-82879d86-da77321c-1d23fd6b-faa07bce" | |
165 } | |
166 | |
167 | |
168 .. highlight:: bash | |
169 | |
170 Similarly, here is an interaction to modify a study:: | |
171 | |
172 $ curl http://localhost:8042/studies/ef2ce55f-9342856a-aee23907-2667e859-9f3b734d/modify -X POST -d '{"Replace":{"InstitutionName":"My own clinic"}}' | |
173 | |
174 .. highlight:: json | |
175 | |
176 :: | |
177 | |
178 { | |
179 "ID" : "1c3f7bf4-85b4aa20-236e6315-5d450dcc-3c1bcf28", | |
180 "Path" : "/studies/1c3f7bf4-85b4aa20-236e6315-5d450dcc-3c1bcf28" | |
181 } | |
182 | |
183 | |
184 Modification of Patients | |
185 ------------------------ | |
186 | |
187 .. highlight:: bash | |
188 | |
189 Starting with Orthanc 0.7.5, Orthanc can also modify all the instances | |
190 of a patient with a single REST call. Here is a sample:: | |
191 | |
112
6d357adfd892
updates for the new 1.3.0 API
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
111
diff
changeset
|
192 $ curl http://localhost:8042/patients/6fb47ef5-072f4557-3215aa29-f99515c1-6fa22bf0/modify -X POST -d '{"Replace":{"PatientID":"Hello","PatientName":"Sample patient name"},"Force":true}' |
0 | 193 |
194 .. highlight:: json | |
195 | |
196 :: | |
197 | |
198 { | |
199 "ID" : "f7ff9e8b-7bb2e09b-70935a5d-785e0cc5-d9d0abf0", | |
200 "Path" : "/patients/f7ff9e8b-7bb2e09b-70935a5d-785e0cc5-d9d0abf0", | |
201 "PatientID" : "f7ff9e8b-7bb2e09b-70935a5d-785e0cc5-d9d0abf0", | |
202 "Type" : "Patient" | |
203 } | |
204 | |
205 Please note that, in this case, you have to set the value of the | |
206 ``PatientID (0010,0020)`` tag for Orthanc to accept this modification: | |
207 This is a security to prevent the merging of patient data before and | |
208 after anonymization, if the user does not explicitly tell Orthanc to | |
209 do so. | |
210 | |
211 | |
212 Anonymization of Patients, Studies or Series | |
213 -------------------------------------------- | |
214 | |
215 .. highlight:: bash | |
216 | |
217 Study and series can be anonymized the same way as they are modified:: | |
218 | |
219 $ curl http://localhost:8042/patients/6fb47ef5-072f4557-3215aa29-f99515c1-6fa22bf0/anonymize -X POST -d '{}' | |
220 $ curl http://localhost:8042/studies/ef2ce55f-9342856a-aee23907-2667e859-9f3b734d/anonymize -X POST -d '{}' | |
221 $ curl http://localhost:8042/series/95a6e2bf-9296e2cc-bf614e2f-22b391ee-16e010e0/anonymize -X POST -d '{}' | |
222 | |
223 As written above, the anonymization process can be fine-tuned by using | |
224 a JSON body. | |
167 | 225 |
226 | |
224
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
178
diff
changeset
|
227 .. _split-merge: |
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
178
diff
changeset
|
228 |
167 | 229 Split/merge of DICOM studies |
230 ---------------------------- | |
231 | |
178 | 232 Starting with Orthanc 1.5.0, Orthanc supports splitting and merging |
167 | 233 DICOM studies through its REST API. |
234 | |
224
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
178
diff
changeset
|
235 .. _split: |
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
178
diff
changeset
|
236 |
167 | 237 Splitting |
238 ^^^^^^^^^ | |
239 | |
240 Here is the syntax to **split** a DICOM study:: | |
241 | |
242 $ curl http://localhost:8042/studies/6e2c0ec2-5d99c8ca-c1c21cee-79a09605-68391d12/split -d \ | |
243 '{"Series":["6ca4c9f3-5e895cb3-4d82c6da-09e060fe-9c59f228"],"Replace":{"PatientName":"HELLO"},"Remove":["AccessionNumber"]}' | |
244 | |
245 By issuing this command, the series whose :ref:`Orthanc identifier | |
246 <dicom-identifiers>` is | |
247 ``6ca4c9f3-5e895cb3-4d82c6da-09e060fe-9c59f228``, and that is part of | |
248 the source study with identifier | |
249 ``6e2c0ec2-5d99c8ca-c1c21cee-79a09605-68391d12``, will be removed from | |
250 the source study, and will be moved to a brand new study. | |
251 | |
252 This is done by generating a new value for all the following DICOM | |
253 tags in the DICOM instances of the series of interest: | |
254 ``StudyInstanceUID (0x0020, 0x000d)``, ``SeriesInstanceUID (0x0020, | |
255 0x000e)``, and ``SOPInstanceUID (0x0008, 0x0018)``. Here are the | |
256 arguments of this ``/studies/{study}/split`` URI: | |
257 | |
258 * ``Series`` gives the list of series to be separated from the parent | |
259 study (mandatory option). These series must all be children of the | |
260 same source study, that is specified in the URI. | |
261 * ``Replace`` allows to overwrite the DICOM tags that are part of the | |
262 "Patient Module Attributes" and the "General Study Module | |
263 Attributes", as specified by the DICOM 2011 standard in Tables C.7-1 | |
264 and C.7-3. | |
265 * ``Remove`` allows to remove DICOM tags from the same modules as in | |
266 the ``Replace`` options. | |
267 * ``KeepSource`` (Boolean value), if set to ``true``, instructs | |
268 Orthanc to keep a copy of the original series in the source study. | |
269 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
|
270 |
224
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
178
diff
changeset
|
271 .. _merge: |
167 | 272 |
273 Merging | |
274 ^^^^^^^ | |
275 | |
276 Here is the syntax to **merge** DICOM series, into another DICOM study:: | |
277 | |
278 $ curl http://localhost:8042/studies/6e2c0ec2-5d99c8ca-c1c21cee-79a09605-68391d12/merge -d \ | |
279 '{"Resources":["ef2ce55f-9342856a-aee23907-2667e859-9f3b734d"]}' | |
280 | |
281 By issuing this command, the DICOM series whose :ref:`Orthanc | |
282 identifier <dicom-identifiers>` is | |
283 ``ef2ce55f-9342856a-aee23907-2667e859-9f3b734d``, will be merged into | |
284 target study with identifier | |
285 ``6e2c0ec2-5d99c8ca-c1c21cee-79a09605-68391d12``. | |
286 | |
287 As in the case of splitting, this is done by updating the following | |
288 DICOM tags: ``StudyInstanceUID (0x0020, 0x000d)``, ``SeriesInstanceUID | |
289 (0x0020, 0x000e)``, and ``SOPInstanceUID (0x0008, | |
290 0x0018)``. Furthermore, all the DICOM tags that are part of the | |
291 "Patient Module Attributes" and the "General Study Module Attributes" | |
292 (as specified by the DICOM 2011 standard in Tables C.7-1 and C.7-3), | |
293 are modified to match the target study. Here are the | |
294 arguments of this ``/studies/{study}/merge`` URI: | |
295 | |
296 * ``Resources`` gives the list of source studies or source series | |
297 that are to be merged into the target study. | |
298 * ``KeepSource`` (Boolean value), if set to ``true``, instructs | |
299 Orthanc to keep the source studies and series. By default, the | |
300 original resources are deleted from Orthanc. |