Mercurial > hg > orthanc-book
annotate Sphinx/source/users/anonymization.rst @ 112:6d357adfd892
updates for the new 1.3.0 API
| author | Sebastien Jodogne <s.jodogne@gmail.com> |
|---|---|
| date | Thu, 20 Jul 2017 16:26:11 +0200 |
| parents | eaec5029ef01 |
| children | 2e826633420e |
| 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 | |
|
112
6d357adfd892
updates for the new 1.3.0 API
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
111
diff
changeset
|
28 $ curl http://localhost:8042/instances/6e67da51-d119d6ae-c5667437-87b9a8a5-0f07c49f/anonymize -X POST -d '{"Replace":{"PatientName":"Hello","0010-1001":"World"},"Keep":["StudyDescription", "SeriesDescription"],"KeepPrivateTags": true, "DicomVersion" : "2017c"}' > Anonymized.dcm |
| 0 | 29 |
| 30 Explanations: | |
| 31 | |
| 32 * New UUIDs are automatically generated for the study, the series and | |
| 33 the instance. | |
|
112
6d357adfd892
updates for the new 1.3.0 API
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
111
diff
changeset
|
34 * 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
|
35 (``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
|
36 above, ``0010-1001`` corresponds to ``Other Patient Names``). |
| 0 | 37 * ``Replace`` is an associative array that associates a DICOM tag with its |
| 38 new string value. The value is dynamically cast to the proper DICOM | |
| 39 data type (an HTTP error will occur if the cast fails). Replacements | |
| 40 are applied after all the tags to anonymize have been removed. | |
| 41 * ``Keep`` specifies a list of tags that should be preserved from full | |
| 42 anonymization. | |
|
112
6d357adfd892
updates for the new 1.3.0 API
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
111
diff
changeset
|
43 * 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
|
44 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
|
45 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
|
46 the private tags, as such tags can contain patient-specific |
| 0 | 47 information. |
| 111 | 48 * ``DicomVersion`` specifies which version of the DICOM standard shall be used |
| 49 for anonymization. Allowed values are ``2008`` and ``2017c`` (default value | |
| 50 if the parameter is absent). This parameter has been introduced in Orthanc | |
| 51 1.3.0. In earlier version, the ``2008`` standard was used. | |
| 0 | 52 |
| 53 | |
| 54 Modification of a Single Instance | |
| 55 --------------------------------- | |
| 56 | |
| 57 Orthanc allows to modify a set of specified tags in a single DICOM | |
| 58 instance and to download the resulting anonymized DICOM | |
| 59 file. Example:: | |
| 60 | |
|
112
6d357adfd892
updates for the new 1.3.0 API
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
111
diff
changeset
|
61 $ curl http://localhost:8042/instances/6e67da51-d119d6ae-c5667437-87b9a8a5-0f07c49f/modify -X POST -d '{"Replace":{"PatientName":"hello","PatientID":"world"},"Remove":["InstitutionName"],"RemovePrivateTags": true, "Force": true}' > Modified.dcm |
| 0 | 62 |
| 63 Remarks: | |
| 64 | |
| 65 * The ``Remove`` array specifies the list of the tags to remove. | |
| 66 * 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
|
67 * 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
|
68 (i.e. manufacturer-specific tags) are removed. |
|
6d357adfd892
updates for the new 1.3.0 API
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
111
diff
changeset
|
69 * 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
|
70 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
|
71 :ref:`DICOM identifiers <dicom-identifiers>` might lead to breaking |
|
6d357adfd892
updates for the new 1.3.0 API
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
111
diff
changeset
|
72 the DICOM model of the real-world. |
| 0 | 73 |
| 74 | |
| 75 Modification of Studies or Series | |
| 76 --------------------------------- | |
| 77 | |
| 78 .. highlight:: bash | |
| 79 | |
| 80 It is possible to modify all the instances from a study or from a | |
| 81 series in a single request. In this case, the modified instances are | |
| 82 stored back into the Orthanc store. Here is how to modify a series:: | |
| 83 | |
| 84 $ curl http://localhost:8042/series/95a6e2bf-9296e2cc-bf614e2f-22b391ee-16e010e0/modify -X POST -d '{"Replace":{"InstitutionName":"My own clinic"}}' | |
| 85 | |
| 86 | |
| 87 .. highlight:: json | |
| 88 | |
| 89 The parameters are identical to those used to modify a single | |
| 90 instance. Orthanc will answer a JSON message that tells where the | |
| 91 modified series has been stored:: | |
| 92 | |
| 93 { | |
| 94 "ID" : "3bd3d343-82879d86-da77321c-1d23fd6b-faa07bce", | |
| 95 "Path" : "/series/3bd3d343-82879d86-da77321c-1d23fd6b-faa07bce" | |
| 96 } | |
| 97 | |
| 98 | |
| 99 .. highlight:: bash | |
| 100 | |
| 101 Similarly, here is an interaction to modify a study:: | |
| 102 | |
| 103 $ curl http://localhost:8042/studies/ef2ce55f-9342856a-aee23907-2667e859-9f3b734d/modify -X POST -d '{"Replace":{"InstitutionName":"My own clinic"}}' | |
| 104 | |
| 105 .. highlight:: json | |
| 106 | |
| 107 :: | |
| 108 | |
| 109 { | |
| 110 "ID" : "1c3f7bf4-85b4aa20-236e6315-5d450dcc-3c1bcf28", | |
| 111 "Path" : "/studies/1c3f7bf4-85b4aa20-236e6315-5d450dcc-3c1bcf28" | |
| 112 } | |
| 113 | |
| 114 | |
| 115 Modification of Patients | |
| 116 ------------------------ | |
| 117 | |
| 118 .. highlight:: bash | |
| 119 | |
| 120 Starting with Orthanc 0.7.5, Orthanc can also modify all the instances | |
| 121 of a patient with a single REST call. Here is a sample:: | |
| 122 | |
|
112
6d357adfd892
updates for the new 1.3.0 API
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
111
diff
changeset
|
123 $ curl http://localhost:8042/patients/6fb47ef5-072f4557-3215aa29-f99515c1-6fa22bf0/modify -X POST -d '{"Replace":{"PatientID":"Hello","PatientName":"Sample patient name"},"Force":true}' |
| 0 | 124 |
| 125 .. highlight:: json | |
| 126 | |
| 127 :: | |
| 128 | |
| 129 { | |
| 130 "ID" : "f7ff9e8b-7bb2e09b-70935a5d-785e0cc5-d9d0abf0", | |
| 131 "Path" : "/patients/f7ff9e8b-7bb2e09b-70935a5d-785e0cc5-d9d0abf0", | |
| 132 "PatientID" : "f7ff9e8b-7bb2e09b-70935a5d-785e0cc5-d9d0abf0", | |
| 133 "Type" : "Patient" | |
| 134 } | |
| 135 | |
| 136 Please note that, in this case, you have to set the value of the | |
| 137 ``PatientID (0010,0020)`` tag for Orthanc to accept this modification: | |
| 138 This is a security to prevent the merging of patient data before and | |
| 139 after anonymization, if the user does not explicitly tell Orthanc to | |
| 140 do so. | |
| 141 | |
| 142 | |
| 143 Anonymization of Patients, Studies or Series | |
| 144 -------------------------------------------- | |
| 145 | |
| 146 .. highlight:: bash | |
| 147 | |
| 148 Study and series can be anonymized the same way as they are modified:: | |
| 149 | |
| 150 $ curl http://localhost:8042/patients/6fb47ef5-072f4557-3215aa29-f99515c1-6fa22bf0/anonymize -X POST -d '{}' | |
| 151 $ curl http://localhost:8042/studies/ef2ce55f-9342856a-aee23907-2667e859-9f3b734d/anonymize -X POST -d '{}' | |
| 152 $ curl http://localhost:8042/series/95a6e2bf-9296e2cc-bf614e2f-22b391ee-16e010e0/anonymize -X POST -d '{}' | |
| 153 | |
| 154 As written above, the anonymization process can be fine-tuned by using | |
| 155 a JSON body. |