Mercurial > hg > orthanc-book

changeset 1237:c4658464a0eb

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
pixels-masker
author Alain Mazy <am@orthanc.team>
date Fri, 05 Dec 2025 15:41:40 +0100
parents 1696a417ca7a
children 779e3ed3325e
files Sphinx/source/images/pixels-masker-fill-face.png Sphinx/source/images/pixels-masker-mean-filter-30-face.png Sphinx/source/images/pixels-masker-us.png Sphinx/source/plugins.rst Sphinx/source/plugins/pixels-masker.rst
diffstat 5 files changed, 159 insertions(+), 0 deletions(-) [+]
line wrap: on
line diff
Binary file Sphinx/source/images/pixels-masker-fill-face.png has changed
Binary file Sphinx/source/images/pixels-masker-mean-filter-30-face.png has changed
Binary file Sphinx/source/images/pixels-masker-us.png has changed
--- a/Sphinx/source/plugins.rst	Wed Dec 03 09:38:37 2025 +0100
+++ b/Sphinx/source/plugins.rst	Fri Dec 05 15:41:40 2025 +0100
@@ -121,6 +121,8 @@
    plugins/multitenant-dicom.rst
    plugins/serve-folders.rst
    plugins/transfers.rst
+   plugins/pixels-masker.rst
+
 
 Samples
 ^^^^^^^
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Sphinx/source/plugins/pixels-masker.rst	Fri Dec 05 15:41:40 2025 +0100
@@ -0,0 +1,157 @@
+.. _pixels-masker-plugin:
+
+
+Pixels Masker plugin
+====================
+
+.. contents::
+
+This page describes a plugin that extends the ``/modify`` and ``/anonymize``
+REST API routes enabling masking of pixels in the image.
+
+.. Disclaimer::
+  This plugin is very low-level and does not detect the area to masks.
+  This plugin does not have a UI; it is only available through the REST API.
+
+
+Configuration
+-------------
+
+.. highlight:: json
+
+Here's a sample configuration section for this plugin with its default values::
+
+  {
+    "PixelsMasker": {
+
+      // Enables/disables the plugin
+      "Enable": false
+  }
+
+
+REST API
+--------
+
+The plugins does not replace the default ``/modify`` and ``/anonymize`` API routes but provides new
+variants at:
+
+- ``/plugins/pixels-masker/studies/../modify``
+- ``/plugins/pixels-masker/studies/../anonymize``
+- ``/plugins/pixels-masker/series/../modify``
+- ``/plugins/pixels-masker/series/../anonymize``
+- ``/plugins/pixels-masker/instances/../modify``
+- ``/plugins/pixels-masker/instances/../anonymize``
+
+
+These are the additional fields that can be added to regular ``/modify`` and ``/anonymize`` payloads::
+
+    {
+        "MaskPixelData" : {
+            "Regions": [
+                {
+                    "MaskType": "MeanFilter",
+                    "FilterWidth": 20,
+                    "RegionType" : "2D",             // area is defined by an area in pixel coordinates
+                    "Origin": [150, 100],            // X, Y in pixel coordinates
+                    "End": [400, 200],               // X, Y in pixel coordinates
+                    "TargetSeries" : [               // the series the pixel mask applies to.  If empty -> applies to all series
+                        "cd589a09-6e705e06-57997219-7812eb49-709873a9"
+                    ],
+                    "TargetInstances" : [            // the instances the pixel mask applies to.  If empty -> applies to all instances
+                    ]
+                },
+                {
+                    "MaskType": "Fill",
+                    "FillValue": 0,
+                    "RegionType" : "3D",                // area is defined by a volume in world coordinates
+                    "Origin": [-150.5, -250.4, -811],   // X, Y, Z in World coordinates
+                    "End": [148.4, 220.7, -955],        // X, Y, Z in World coordinates
+                    "TargetSeries" : [                  // in this mode, no need to list the instances since the Z coordinate shall handle that !
+                        "94df9100-3b476f5b-f4e8c381-d78c327f-a387bc7e"
+                    ]
+                }
+            ]
+        }
+    }
+
+
+Here's a sample REST API call to mask the pixels with a constant value in a 3D image::
+
+    $ curl -X POST http://localhost:8042/plugins/pixels-masker/studies/321d3848-40c81c82-49f6f235-df6b1ec7-ed52f2fa/modify \
+        --data-binary '{
+                "Replace" : {
+                    "StudyInstanceUID": "1.2.3", 
+                    "StudyDescription": "Filled Area"
+                },
+                "Force": true,
+                "MaskPixelData": {
+                    "Regions": [{
+                        "MaskType": "Fill",
+                        "FillValue": 0,
+                        "RegionType" : "3D",
+                        "Origin": [-150.0, -300, -750],
+                        "End": [150.0, -250, -1000]
+                }]
+                }
+            }'
+
+.. image:: ../images/pixels-masker-fill-face.png
+           :align: center
+           :width: 250px
+
+
+And the same request to apply a mean filter on the same area::
+
+    $ curl -X POST http://localhost:8042/plugins/pixels-masker/studies/321d3848-40c81c82-49f6f235-df6b1ec7-ed52f2fa/modify \
+        --data-binary '{
+                "Replace" : {
+                    "StudyInstanceUID": "1.2.4", 
+                    "StudyDescription": "Mean Filter"
+                },
+                "Force": true,
+                "MaskPixelData": {
+                    "Regions": [{
+                        "MaskType": "MeanFilter",
+                        "FilterWidth": 30,
+                        "RegionType" : "3D",
+                        "Origin": [-150.0, -300, -750],
+                        "End": [150.0, -250, -1000]
+                }]
+                }
+            }'
+
+.. image:: ../images/pixels-masker-mean-filter-30-face.png
+           :align: center
+           :width: 250px
+
+Here is a request to apply multiple 2D masks on an US series::
+
+    $ curl -X POST http://localhost:8042/plugins/pixels-masker/series/4583e108-24b5e113-2be9a691-7183e535-902578c7/modify \
+        --data-binary '{
+                "Replace" : {
+                    "StudyInstanceUID": "1.2.5", 
+                    "StudyDescription": "Masked US"
+                },
+                "Force": true,
+                "MaskPixelData": {
+                    "Regions": [{
+                        "MaskType": "MeanFilter",
+                        "FilterWidth": 20,
+                        "RegionType" : "2D",
+                        "Origin": [0, 0],
+                        "End": [400, 60]
+                }, {
+                        "MaskType": "Fill",
+                        "FillValue": 100,
+                        "RegionType" : "2D",
+                        "Origin": [1080, 0],
+                        "End": [1380, 60]
+                }]
+                }
+            }'
+
+.. image:: ../images/pixels-masker-us.png
+           :align: center
+           :width: 400px
+
+