Add application: Denoising-Inhomogeneity Correction Tool

[Palollo]

denoising_inhomogeneity_correction_tool

Description

Denoising-Inhomogeneity Correction Tool is designed to perform a customisable image pre-processing to reduce noise and inhomogeneity field effect, thus improving image quality and reproducibility of radiomics features. This tool consists of two independent steps: one for denoising using one of the 5 integrated filters (Bilateral Filter, Anisotropic Diffusion Filter (ADF), Curvature Flow Filter (CFF), SUSAN and Non Local Means (NLM)), and another for the ANTs N4 and another for the ANT's N4 bias correction filter. The parameter configuration of this tool has been optimised for TW1, T2W, DWI and DCE sequences in neuroblastoma (NB) and paediatric brain tumours, but it can also be configured with some of their parameters using a JSON parameter configuration file.

Reference

Please cite the following paper when using this tool:

Fernández Patón M, Cerdá Alberich L, Sangüesa Nebot C, Martínez de Las Heras B, Veiga Canuto D, Cañete Nieto A, Martí-Bonmatí L. MR Denoising Increases Radiomic Biomarker Precision and Reproducibility in Oncologic Imaging. J Digit Imaging. 2021 Oct;34(5):1134-1145. doi: 10.1007/s10278-021-00512-8. Epub 2021 Sep 10. PMID: 34505958; PMCID: PMC8554919.	

And the following one:

Martí-Bonmatí L, Alberich-Bayarri Á, Ladenstein R, Blanquer I, Segrelles JD, Cerdá-Alberich L, Gkontra P, Hero B, García-Aznar JM, Keim D, Jentner W, Seymour K, Jiménez-Pastor A, González-Valverde I, Martínez de Las Heras B, Essiaf S, Walker D, Rochette M, Bubak M, Mestres J, Viceconti M, Martí-Besa G, Cañete A, Richmond P, Wertheim KY, Gubala T, Kasztelnik M, Meizner J, Nowakowski P, Gilpérez S, Suárez A, Aznar M, Restante G, Neri E. PRIMAGE project: predictive in silico multiscale analytics to support childhood cancer personalised evaluation empowered by imaging biomarkers. Eur Radiol Exp. 2020 Apr 3;4(1):22. doi: 10.1186/s41747-020-00150-9. PMID: 32246291; PMCID: PMC7125275.

Usage

Option 1: Example using JSON Configuration File

Create a parameter_configuration.json file with the following structure:

{ 
  "Paths": [
    "~/datasets/87f3be56-4725-45c3-9baa-d338de530f73/Patient_1/Study/T1W_Sequence",
    "~/datasets/87f3be56-4725-45c3-9baa-d338de530f73/Patient_1/Study/T2W_Sequence",
    "~/datasets/87f3be56-4725-45c3-9baa-d338de530f73/Patient_2/Study/DWI_Sequence"
  ],
  
  "_comment": "Optional: Uncomment to override defaults",
  "_series_number": 2000,
  "_series_description_suffix": " - Harmonized",
  
  "Denoising_adf": [{
    "Conductance": 0.5,
    "Iterations": 3,
    "Time_step": 0.0625
  }],
  
  "N4": [{
    "BSpline_size": 50,
    "Iterations": [50, 30],
    "Shrink_factor": 2
  }]
}

Behavior:

• Without series_number: Original SeriesNumber + 1000 (e.g., 5 → 1005) ✅ Recommended
• With series_number: 2000: SeriesNumber = 2000 (absolute value)

Run with Jobman:

jobman submit -i denoising_inhomogeneity_correction_tool -- \
  --config ~/persistent-home/denoising/parameter_configuration.json \
  --output ~/persistent-home/denoising/output

Note the config file and the output directory path should be any within the persistent-home, which is shared between all desktops and jobs created by the user, otherwise the config file will not be found and the results will be lost after the end of the job.

---

Option 2: Using Command-Line Arguments

You can run the tool directly with command-line arguments (instead of using a config file):

jobman submit -i denoising_inhomogeneity_correction_tool -- \
  --paths ~/datasets/87f3be56-4725-45c3-9baa-d338de530f73/Patient_1/Study/T1W ~/datasets/87f3be56-4725-45c3-9baa-d338de530f73/Patient_2/Study/T2W \
  --series_number 2000 \
  --series_description_suffix " - Harmonized" \
  --denoising adf \
  --conductance 0.5 \
  --iterations 3 \
  --time_step 0.0625 \
  --n4 \
  --bspline_size 50 \
  --n4_iterations 50 30 \
  --shrink_factor 2 \
  --output ~/persistent-home/denoising/output

---

Configuration Parameters

Whether using option 1 or 2, below are the paramateres you can specify.

Paths (Required)

• Paths: List of DICOM folder paths

Series Metadata (Optional)

Control how the harmonized series appears in DICOM viewers:

• series_number (optional): Absolute SeriesNumber for harmonized series

  • If not specified (recommended): Original SeriesNumber + 1000
  • If specified: Uses exact value provided
  • Example: Original series 5 → Harmonized series 1005 (default) or 2000 (if configured)
  • Note: Default behavior (+1000) is recommended to avoid conflicts

• series_description_suffix (optional): Text appended to original SeriesDescription

  • Default: "_harmonized"
  • Example: "series_description_suffix": " - Harmonized"

Note: The tool automatically generates:

• SeriesInstanceUID: Deterministic UID (same input always produces same UID)
• SOPInstanceUID: Unique for each DICOM slice
• DerivationDescription: Documents applied filters (e.g., "Denoising: ADF; N4 Bias Field Correction")

Denoising Filters (Optional)

Choose one of the following:

Anisotropic Diffusion Filter (ADF)

"Denoising_adf": [{
  "Conductance": 0.5,
  "Iterations": 3,
  "Time_step": 0.0625
}]

CLI arguments:

• --denoising adf
• --conductance <value> (default: 0.5)
• --iterations <value> (default: 3)
• --time_step <value> (default: 0.0625)

Curvature Flow Filter (CFF)

"Denoising_cff": [{
  "Iterations": 3,
  "Time_step": 0.0625
}]

CLI arguments:

• --denoising cff
• --iterations <value> (default: 3)
• --time_step <value> (default: 0.0625)

Bilateral Filter

"Denoising_bilateral": [{
  "DomainSigma": 1.5,
  "RangeSigma": 50.0
}]

CLI arguments:

• --denoising bilateral
• --domain_sigma <value> (default: 1.5)
• --range_sigma <value> (default: 50.0)

SUSAN Filter

"Denoising_susan": [{
  "brightness_threshold": 0.75,
  "fwhm": 3.0
}]

CLI arguments:

• --denoising susan
• --brightness_threshold <value> (default: 0.75, multiplier of Otsu threshold)
• --fwhm <value> (default: 3.0)

Non-Local Means (NLM)

"Denoising_nlm": [{
  "Sigma": 1.0,
  "Patch_radius": 1,
  "Block_radius": 5
}]

CLI arguments:

• --denoising nlm
• --sigma <value> (default: 1.0)
• --patch_radius <value> (default: 1)
• --block_radius <value> (default: 5)

N4 Bias Field Correction (Optional)

"N4": [{
  "BSpline_size": 50,
  "Iterations": [50, 30],
  "Shrink_factor": 2
}]

CLI arguments:

• --n4 (flag to enable)
• --bspline_size <value> (default: 50)
• --n4_iterations <values...> (default: 50 30)
• --shrink_factor <value> (default: 2)

---

Optimal Parameters

Optimized configurations for different tumor types and sequences:

The optimised parameter configuration for each tumour and sequence is shown in the table below:

Examples

Example 1: ADF Denoising + N4 Correction (JSON config)

parameter_configuration.json:

{
  "Paths": [
    "~/datasets/87f3be56-4725-45c3-9baa-d338de530f73/Patient_1/Study/T1W_Sequence"
  ],
  "Denoising_adf": [{
    "Conductance": 0.5,
    "Iterations": 3,
    "Time_step": 0.0625
  }],
  "N4": [{
    "BSpline_size": 50,
    "Iterations": [50, 30],
    "Shrink_factor": 2
  }]
}

Command:

jobman submit -i denoising_inhomogeneity_correction_tool -- \
  --config ~/persistent-home/denoising/parameter_configuration.json \
  --output ~/persistent-home/denoising/output

Example 2: NLM Denoising Only (CLI)

jobman submit -i denoising_inhomogeneity_correction_tool -- \
  --paths ~/datasets/87f3be56-4725-45c3-9baa-d338de530f73/Patient_1/Study/DWI ~/datasets/87f3be56-4725-45c3-9baa-d338de530f73/Patient_2/Study/DWI \
  --denoising nlm \
  --sigma 1.0 \
  --patch_radius 1 \
  --block_radius 5 \
  --output ~/persistent-home/denoising/output

Example 3: N4 Correction Only (CLI)

jobman submit -i denoising_inhomogeneity_correction_tool -- \
  --paths ~/datasets/87f3be56-4725-45c3-9baa-d338de530f73/Patient_1/Study/T1W \
  --n4 \
  --bspline_size 50 \
  --n4_iterations 50 30 \
  --shrink_factor 2 \
  --output ~/persistent-home/denoising/output

---

DICOM Metadata and UIDs

The tool generates harmonized DICOM files with properly structured metadata following DICOM standards:

Generated UIDs

• SeriesInstanceUID: Deterministically generated using SHA256 hash

  • Same original series always produces the same harmonized SeriesInstanceUID
  • Format: 2.25.{hash_integer} (UUID-derived UID standard)
  • All slices in a harmonized series share this UID

• SOPInstanceUID: Unique identifier for each DICOM instance

  • Generated using pydicom.uid.generate_uid()
  • Ensures each slice has a globally unique identifier

Series Metadata

• SeriesNumber: Configurable via series_number parameter

  • Default: Original SeriesNumber + 1000
  • Example: Original series 5 → Harmonized series 1005 (or 2000 if configured)

• SeriesDescription: Original description + configurable suffix

  • Default suffix: "_harmonized"
  • Example: "T1W_MPRAGE" → "T1W_MPRAGE_harmonized"
  • Or with custom suffix: "T1W_MPRAGE - Harmonized"

• DerivationDescription: Automatically documents processing steps

  • Lists applied filters in order
  • Example: "Denoising: ADF; N4 Bias Field Correction"

Authors

This tool was developed by Matías Fernández Patón in collaboration with the GIBI230 Research Group at La Fe Health Research Institute (IIS La Fe), Valencia, Spain.

Contact info

pedromiguel_martinez@iislafe.es
carina_soler@iislafe.es
matias_fernandez@iislafe.es

URL

User manual:
https://drive.google.com/file/d/1W0aHAIG_bdU9Z1J3aDNsb1r39WBuX9Ot/view?usp=drive_link

EUCAIM Catalogue:
https://bio.tools/denoising-inhomogeneity_correction_tool

EUCAIM Harbor:
https://harbor.eucaim.cancerimage.eu/harbor/projects/4/repositories/denoising_inhomogeneity_correction_tool/artifacts-tab

Public dockerfile repository:
https://bitbucket.org/gibi230/harmonization_tool/src/cd1ed47c578c77de631772623f7df0f3c976c329/?at=release%2FEUCAIM

License

https://drive.google.com/file/d/1w1tdjaLdjBZYJTp_EpETN6nwyQIsy4vg/view?usp=drive_link

[Palollo]

It is a draft pending to be reviewed by the author.

I've provisionally added the parameter --output at the end of all examples to allow the user specify the output dir path. It should be added in the source code as currently seems it is fixed to /output, which cannot work in the UPV reference node.

[Palollo]

Recommendation: the COPY command with "." is discouraged because it copies all, including files not required in the image like the Dockerfile, .gitignore, etc. but even personal data which are your local git configurations for the repo in the directory ".git". I recommend to change your first COPY line with this:

COPY  functions.py main.py requirements.txt utils.py VERSION README.md LICENSE /app
COPY  n4 /app/n4
COPY  Parameters_config /app/Parameters_config