From ba020a0928c7dfddbf2911015a8fd5a1eae8ae3e Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 29 Nov 2025 16:32:40 +0000 Subject: [PATCH 1/7] Initial plan From 13b06a384564101b6c76fb8d000fdf7d78bb175a Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 29 Nov 2025 16:39:19 +0000 Subject: [PATCH 2/7] Create comprehensive README.md with badges, features, and usage examples Co-authored-by: neuronflow <7048826+neuronflow@users.noreply.github.com> --- README.md | 96 +++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 83 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 37aba65..c35d543 100644 --- a/README.md +++ b/README.md @@ -1,36 +1,106 @@ -[![PyPI version panoptica](https://badge.fury.io/py/auxiliary.svg)](https://pypi.python.org/pypi/auxiliary/) +# auxiliary + +[![Python Versions](https://img.shields.io/pypi/pyversions/auxiliary)](https://pypi.org/project/auxiliary/) +[![Stable Version](https://img.shields.io/pypi/v/auxiliary?label=stable)](https://pypi.org/project/auxiliary/) [![Documentation Status](https://readthedocs.org/projects/auxiliary/badge/?version=latest)](http://auxiliary.readthedocs.io/?badge=latest) [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) -# auxiliary +Auxiliary is a Python package providing utility functions for medical image processing. It is part of the [BrainLesion](https://github.com/BrainLesion) project and offers tools for: -TODO +- **Image I/O**: Reading and writing medical images (NIfTI, TIFF, DICOM) using SimpleITK +- **Image Normalization**: Percentile-based and windowing normalization methods +- **Format Conversion**: DICOM to NIfTI and NIfTI to DICOM conversion +- **Path Utilities**: Robust path handling with the turbopath module ## Installation -### PyPi +With a Python 3.10+ environment, you can install `auxiliary` directly from [PyPI](https://pypi.org/project/auxiliary/): -```sh +```bash pip install auxiliary ``` -### Conda +Or via conda: -```sh +```bash conda install conda-forge::auxiliary ``` -## deploy +### Optional Dependencies -### build +For DICOM to NIfTI conversion using `dcm2niix`: +```bash +pip install auxiliary[dcm2niix] ``` -python -m build -poetry build + +## Usage + +### Reading and Writing Images + +```python +from auxiliary.io import read_image, write_image + +# Read a NIfTI image +image_array = read_image("path/to/image.nii.gz") + +# Write a NumPy array to a NIfTI file +write_image(image_array, "path/to/output.nii.gz") + +# Write with reference image for spatial metadata +write_image(image_array, "path/to/output.nii.gz", reference_path="path/to/reference.nii.gz") ``` -### upload to pypi +### Image Normalization + +```python +from auxiliary.normalization.percentile_normalizer import PercentileNormalizer +from auxiliary.normalization.windowing_normalizer import WindowingNormalizer + +# Percentile-based normalization +normalizer = PercentileNormalizer(lower_percentile=1.0, upper_percentile=99.0) +normalized_image = normalizer.normalize(image_array) +# Windowing normalization (e.g., for CT images) +normalizer = WindowingNormalizer(center=40, width=400) +windowed_image = normalizer.normalize(image_array) ``` -twine upload dist/* + +### DICOM Conversion + +```python +from auxiliary.conversion import dcm2niix, dicom_to_nifti_itk, nifti_to_dicom_itk + +# Convert DICOM to NIfTI using dcm2niix (requires dcm2niix extra) +dcm2niix("path/to/dicom_dir", "path/to/output_dir") + +# Convert DICOM to NIfTI using SimpleITK +dicom_to_nifti_itk("path/to/dicom_dir", "path/to/output_dir") + +# Convert NIfTI to DICOM +nifti_to_dicom_itk("path/to/image.nii.gz", "path/to/output_dicom_dir") +``` + +### TIFF I/O + +```python +from auxiliary.tiff.io import read_tiff, write_tiff + +# Read a TIFF file +tiff_data = read_tiff("path/to/image.tiff") + +# Write a NumPy array to a TIFF file +write_tiff(tiff_data, "path/to/output.tiff") ``` + +## Contributing + +We welcome all kinds of contributions from the community! + +### Reporting Bugs, Feature Requests and Questions + +Please open a new issue [here](https://github.com/BrainLesion/auxiliary/issues). + +### Code Contributions + +Nice to have you on board! Please have a look at our [CONTRIBUTING.md](CONTRIBUTING.md) file. From 40053301fd595d4f70cc02cec0256d3b32be30e5 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 29 Nov 2025 16:44:23 +0000 Subject: [PATCH 3/7] Remove Contributing section from README Co-authored-by: neuronflow <7048826+neuronflow@users.noreply.github.com> --- README.md | 12 ------------ 1 file changed, 12 deletions(-) diff --git a/README.md b/README.md index c35d543..0992344 100644 --- a/README.md +++ b/README.md @@ -92,15 +92,3 @@ tiff_data = read_tiff("path/to/image.tiff") # Write a NumPy array to a TIFF file write_tiff(tiff_data, "path/to/output.tiff") ``` - -## Contributing - -We welcome all kinds of contributions from the community! - -### Reporting Bugs, Feature Requests and Questions - -Please open a new issue [here](https://github.com/BrainLesion/auxiliary/issues). - -### Code Contributions - -Nice to have you on board! Please have a look at our [CONTRIBUTING.md](CONTRIBUTING.md) file. From be6e583a6e490dd4ea82a4ea0fae5eee60ab6aed Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 29 Nov 2025 16:50:11 +0000 Subject: [PATCH 4/7] Reorganize README with I/O sections for each format (NIfTI, DICOM, TIFF) Co-authored-by: neuronflow <7048826+neuronflow@users.noreply.github.com> --- README.md | 51 +++++++++++++++++++++++++++++---------------------- 1 file changed, 29 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index 0992344..38960f2 100644 --- a/README.md +++ b/README.md @@ -36,7 +36,7 @@ pip install auxiliary[dcm2niix] ## Usage -### Reading and Writing Images +### NIfTI I/O ```python from auxiliary.io import read_image, write_image @@ -51,34 +51,26 @@ write_image(image_array, "path/to/output.nii.gz") write_image(image_array, "path/to/output.nii.gz", reference_path="path/to/reference.nii.gz") ``` -### Image Normalization +### DICOM I/O ```python -from auxiliary.normalization.percentile_normalizer import PercentileNormalizer -from auxiliary.normalization.windowing_normalizer import WindowingNormalizer +from auxiliary.conversion import dicom_to_nifti_itk, nifti_to_dicom_itk, dcm2niix -# Percentile-based normalization -normalizer = PercentileNormalizer(lower_percentile=1.0, upper_percentile=99.0) -normalized_image = normalizer.normalize(image_array) - -# Windowing normalization (e.g., for CT images) -normalizer = WindowingNormalizer(center=40, width=400) -windowed_image = normalizer.normalize(image_array) -``` - -### DICOM Conversion - -```python -from auxiliary.conversion import dcm2niix, dicom_to_nifti_itk, nifti_to_dicom_itk +# Read a DICOM series and convert to NIfTI using SimpleITK +dicom_to_nifti_itk("path/to/dicom_dir", "path/to/output_dir") -# Convert DICOM to NIfTI using dcm2niix (requires dcm2niix extra) +# Read a DICOM series and convert to NIfTI using dcm2niix (requires dcm2niix extra) dcm2niix("path/to/dicom_dir", "path/to/output_dir") -# Convert DICOM to NIfTI using SimpleITK -dicom_to_nifti_itk("path/to/dicom_dir", "path/to/output_dir") - -# Convert NIfTI to DICOM +# Write a NIfTI image to DICOM format nifti_to_dicom_itk("path/to/image.nii.gz", "path/to/output_dicom_dir") + +# Write with reference DICOM for metadata +nifti_to_dicom_itk( + "path/to/image.nii.gz", + "path/to/output_dicom_dir", + reference_dicom="path/to/reference_dicom_dir" +) ``` ### TIFF I/O @@ -92,3 +84,18 @@ tiff_data = read_tiff("path/to/image.tiff") # Write a NumPy array to a TIFF file write_tiff(tiff_data, "path/to/output.tiff") ``` + +### Image Normalization + +```python +from auxiliary.normalization.percentile_normalizer import PercentileNormalizer +from auxiliary.normalization.windowing_normalizer import WindowingNormalizer + +# Percentile-based normalization +normalizer = PercentileNormalizer(lower_percentile=1.0, upper_percentile=99.0) +normalized_image = normalizer.normalize(image_array) + +# Windowing normalization (e.g., for CT images) +normalizer = WindowingNormalizer(center=40, width=400) +windowed_image = normalizer.normalize(image_array) +``` From c23433cc44d6444f79c9fcd22721366e6f34dd99 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 29 Nov 2025 16:56:14 +0000 Subject: [PATCH 5/7] Add examples for writing NumPy arrays to DICOM with and without reference images Co-authored-by: neuronflow <7048826+neuronflow@users.noreply.github.com> --- README.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 38960f2..1953f24 100644 --- a/README.md +++ b/README.md @@ -55,6 +55,7 @@ write_image(image_array, "path/to/output.nii.gz", reference_path="path/to/refere ```python from auxiliary.conversion import dicom_to_nifti_itk, nifti_to_dicom_itk, dcm2niix +import numpy as np # Read a DICOM series and convert to NIfTI using SimpleITK dicom_to_nifti_itk("path/to/dicom_dir", "path/to/output_dir") @@ -65,9 +66,13 @@ dcm2niix("path/to/dicom_dir", "path/to/output_dir") # Write a NIfTI image to DICOM format nifti_to_dicom_itk("path/to/image.nii.gz", "path/to/output_dicom_dir") -# Write with reference DICOM for metadata +# Write a NumPy array to DICOM format +image_array = np.random.rand(128, 128, 64) # example 3D array +nifti_to_dicom_itk(image_array, "path/to/output_dicom_dir") + +# Write a NumPy array to DICOM with reference DICOM for metadata nifti_to_dicom_itk( - "path/to/image.nii.gz", + image_array, "path/to/output_dicom_dir", reference_dicom="path/to/reference_dicom_dir" ) From f170a74cfce2a791c210b764f755efacbb7a4623 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 29 Nov 2025 17:05:27 +0000 Subject: [PATCH 6/7] Update pyproject.toml license to Apache-2.0 Co-authored-by: neuronflow <7048826+neuronflow@users.noreply.github.com> --- pyproject.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pyproject.toml b/pyproject.toml index 0c04682..3152092 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -10,7 +10,7 @@ name = "auxiliary" version = "0.0.0" description = "TODO." authors = ["Florian Kofler "] -license = "AGPL-3.0" +license = "Apache-2.0" readme = "README.md" repository = "https://github.com/BrainLesion/auxiliary" From f1fab44a368ad5e8e22e9b08f92ccf1353e37dcf Mon Sep 17 00:00:00 2001 From: neuronflow <7048826+neuronflow@users.noreply.github.com> Date: Wed, 10 Dec 2025 12:40:01 +0100 Subject: [PATCH 7/7] Add citation section to README Added citation section with reference for the auxiliary framework. --- README.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/README.md b/README.md index 1953f24..124f51c 100644 --- a/README.md +++ b/README.md @@ -104,3 +104,25 @@ normalized_image = normalizer.normalize(image_array) normalizer = WindowingNormalizer(center=40, width=400) windowed_image = normalizer.normalize(image_array) ``` + + + +## Citation + +> [!IMPORTANT] +> If you use `auxiliary` in your research, please cite it to support the development! + +Kofler, F., Rosier, M., Astaraki, M., Möller, H., Mekki, I. I., Buchner, J. A., Schmick, A., Pfiffer, A., Oswald, E., Zimmer, L., Rosa, E. de la, Pati, S., Canisius, J., Piffer, A., Baid, U., Valizadeh, M., Linardos, A., Peeken, J. C., Shit, S., … Menze, B. (2025). *BrainLesion Suite: A Flexible and User-Friendly Framework for Modular Brain Lesion Image Analysis* [arXiv preprint arXiv:2507.09036](https://doi.org/10.48550/arXiv.2507.09036) + + +``` +@misc{kofler2025brainlesionsuiteflexibleuserfriendly, + title={BrainLesion Suite: A Flexible and User-Friendly Framework for Modular Brain Lesion Image Analysis}, + author={Florian Kofler and Marcel Rosier and Mehdi Astaraki and Hendrik Möller and Ilhem Isra Mekki and Josef A. Buchner and Anton Schmick and Arianna Pfiffer and Eva Oswald and Lucas Zimmer and Ezequiel de la Rosa and Sarthak Pati and Julian Canisius and Arianna Piffer and Ujjwal Baid and Mahyar Valizadeh and Akis Linardos and Jan C. Peeken and Surprosanna Shit and Felix Steinbauer and Daniel Rueckert and Rolf Heckemann and Spyridon Bakas and Jan Kirschke and Constantin von See and Ivan Ezhov and Marie Piraud and Benedikt Wiestler and Bjoern Menze}, + year={2025}, + eprint={2507.09036}, + archivePrefix={arXiv}, + primaryClass={cs.CV}, + url={https://arxiv.org/abs/2507.09036}, +} +```