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