# HG changeset patch
# User Sebastien Jodogne <s.jodogne@gmail.com>
# Date 1692863763 -7200
# Node ID bc531449c0241b36bb3a29b5de2d0123341a22ff
# Parent  7abb7c8ff544456512ba9eb893454f22dcc23b86
altering the content of a single instance

diff -r 7abb7c8ff544 -r bc531449c024 Sphinx/source/users/anonymization.rst
--- a/Sphinx/source/users/anonymization.rst	Wed Aug 23 18:58:43 2023 +0200
+++ b/Sphinx/source/users/anonymization.rst	Thu Aug 24 09:56:03 2023 +0200
@@ -411,3 +411,41 @@
 * ``KeepSource`` (Boolean value), if set to ``true``, instructs
   Orthanc to keep the source studies and series.  By default, the
   original resources are deleted from Orthanc.
+
+
+.. _altering-dicom:
+
+Altering the content of a single instance
+-----------------------------------------
+
+People often want to add/remove specific DICOM tags in an existing
+DICOM instance, i.e. to ask ``/instances/{id}/modify`` to keep the
+existing ``SOPInstanceUID (0008,0018)``. This operation is **strongly
+discouraged**, as it **breaks medical traceability** by dropping the
+history of the modifications that were applied to a DICOM
+instance. Furthermore, the altered DICOM instance may be ignored by
+further DICOM software. Indeed, the DICOM standard expects two DICOM
+instances with the same SOP Instance UID to contain exactly the same
+set of DICOM tags. Consequently, a DICOM software could perfectly
+decide to only consider the original version of the DICOM instance.
+
+Consequently, **Orthanc implements safeguards** in its REST API to
+avoid such dangerous situations to occur. That being said, **if you
+understand the risks**, it is possible to bypass those safeguards. The
+trick is to pass both the ``Keep`` and ``Force`` arguments to the
+``/instances/{id}/modify`` call. Here is a sample Python script that
+implements this trick:
+
+.. literalinclude:: anonymization_bypass.py
+                    :language: python
+
+This sample script downloads an altered version of a DICOM instance
+from Orthanc (with the same ``SOPInstanceUID``), then uploads it again
+to Orthanc. By default, Orthanc will ignore the upload of the altered
+DICOM instance and will answer with the ``AlreadyStored`` message,
+because ``SOPInstanceUID`` is already present in the Orthanc database.
+To force the upload of the altered DICOM instance, one can either
+(1) DELETE the instance before POST-ing it again, or (2) set the
+``OverwriteInstances`` :ref:`configuration option <configuration>` of
+Orthanc to ``true``. Both strategies are implemented in the sample
+script.
diff -r 7abb7c8ff544 -r bc531449c024 Sphinx/source/users/anonymization_bypass.py
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Sphinx/source/users/anonymization_bypass.py	Thu Aug 24 09:56:03 2023 +0200
@@ -0,0 +1,26 @@
+import json
+import pprint
+import requests
+
+INSTANCE = '19816330-cb02e1cf-df3a8fe8-bf510623-ccefe9f5'
+OVERWRITE_INSTANCES = True   # Whether the "OverwriteInstance" is set to "true" in the Orthanc config
+
+r = requests.post('http://localhost:8042/instances/%s/modify' % INSTANCE, json.dumps({
+    'Replace' : {
+        'PatientName' : 'Hello'
+    },
+    'Keep' : [ 'SOPInstanceUID' ],  # Don't generate a new SOPInstanceUID
+    'Force' : True                  # Mandatory if SOPInstanceUID must be kept constant
+    }))
+
+r.raise_for_status()
+
+dicom = r.content
+
+if not OVERWRITE_INSTANCES:
+    r = requests.delete('http://localhost:8042/instances/%s' % INSTANCE)
+    r.raise_for_status()
+
+r = requests.post('http://localhost:8042/instances', dicom)
+r.raise_for_status()
+pprint.pprint(r.json())