caideface 0.3.1__tar.gz → 0.3.3__tar.gz

{caideface-0.3.1 → caideface-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: caideface
-Version: 0.3.1
+Version: 0.3.3
 Summary: MRI defacing pipeline with skull-stripping and affine registration from cai4cai
 Author-email: Lorena Garcia-Foncillas <lorenagarfon00@gmail.com>
 License: Apache-2.0
@@ -31,28 +31,35 @@ Requires-Dist: TotalSegmentator; extra == "ct"
 
 # caideface
 
-**MRI defacing and text anonymisation toolkit** from the [cai4cai](https://cai4cai.ml/) research group (Contextual Artificial Intelligence for Computer Assisted Interventions).
+**MRI and CT defacing and text anonymisation toolkit** from the [cai4cai](https://cai4cai.ml/) research group (Contextual Artificial Intelligence for Computer Assisted Interventions).
 
 This package provides two complementary anonymisation capabilities:
 
-- **Image defacing** -- removes facial features from head MRI scans while preserving brain structures, as described in the paper *"A Generalisable Head MRI Defacing Pipeline: Evaluation on 2,566 Meningioma Scans"* ([arXiv:2505.12999](https://arxiv.org/abs/2505.12999)).
-- **Text anonymisation** -- detects personal names in medical reports using a trained spaCy NER model and replaces them with realistic fake names (Hiding in Plain Sight / HIPS technique).
+- **Image defacing** -- removes facial features from head MRI and CT scans while preserving brain structures. The MRI pipeline is described in the paper *"A Generalisable Head MRI Defacing Pipeline: Evaluation on 2,566 Meningioma Scans"* ([arXiv:2505.12999](https://arxiv.org/abs/2505.12999)).
+- **Text anonymisation** -- detects personal names in medical reports using a trained spaCy NER model and replaces them with realistic fake names (Hiding in Plain Sight / HIPS technique), as described in *"Evaluation of Named Entity Recognition for Automated Extraction of Present Tumor Size and Personal Names from Radiology Reports Using Spacy"* ([DOI:10.1055/s-0045-1803715](https://doi.org/10.1055/s-0045-1803715)).
 
 ## Pipeline overview
 
 ### Image defacing pipeline
 
-The defacing pipeline consists of three steps:
+The defacing pipeline supports both **MRI** and **CT** modalities, selected via the required `--modality {mri,ct}` flag. The pipeline consists of three steps, with modality-specific backends:
 
-1. **Reorientation** -- Aligns NIfTI scans to LAS canonical orientation (MNI152 standard) using nibabel.
-2. **Skull-stripping** -- Extracts brain masks using [HD-BET](https://github.com/MIC-DKFZ/HD-BET), then applies dynamic dilation to preserve peripheral brain structures.
-3. **Registration & Defacing** -- Registers each scan to the MNI152 template using BRAINSFit (affine), warps a face mask into the scan's space, and applies it to remove facial features.
+| Step | MRI | CT |
+|------|-----|-----|
+| 1. Reorientation | → RAS | → RAS |
+| 2. Brain extraction | [HD-BET](https://github.com/MIC-DKFZ/HD-BET) | [TotalSegmentator](https://github.com/wasserth/TotalSegmentator) |
+| 3. Registration template | MNI152 T1 (bundled) | CT brain atlas (from TotalSegmentator) |
+| Background value | Always 0 | Auto-detected per volume |
+
+1. **Reorientation** -- Aligns NIfTI scans to RAS canonical orientation (MNI152 standard) using nibabel, equivalent to FSL's `fslreorient2std`.
+2. **Skull-stripping** -- Extracts brain masks, then applies dynamic dilation to preserve peripheral brain structures. MRI uses [HD-BET](https://github.com/MIC-DKFZ/HD-BET); CT uses [TotalSegmentator](https://github.com/wasserth/TotalSegmentator) (brain class from the total segmentation task).
+3. **Registration & Defacing** -- Registers each scan to a modality-matched template using BRAINSFit (affine), warps a face mask into the scan's space, and applies it to remove facial features. For CT, the background fill value is automatically detected from the volume histogram (~-1000 HU for native encoding).
 
 ### Text anonymisation (NER + HIPS)
 
 The text anonymisation module uses a trained spaCy Named Entity Recognition (NER) model to identify personal names (`PER` entities) in `.txt` files and replaces them with realistic fake names generated by the [Faker](https://faker.readthedocs.io/) library. This "Hiding in Plain Sight" (HIPS) approach produces anonymised reports that remain naturally readable. Consistent name mapping ensures that the same real name is always replaced with the same fake name within a document.
 
-All required models and data are **bundled with the package**, so no additional downloads are needed.
+All required models and data for MRI defacing and text anonymisation are **bundled with the package**. CT defacing requires installing the optional `[ct]` extra (see [Installation](#installation)).
 
 ## Requirements
 
@@ -66,7 +73,7 @@ All required models and data are **bundled with the package**, so no additional
 |------|---------|---------|
 | **BRAINSFit** & **BRAINSResample** | Step 3 | Bundled with [3D Slicer](https://www.slicer.org/) |
 
-> **Note:** Step 1 (reorientation) no longer requires FSL -- it uses nibabel's orientation tools to reorient scans to LAS (equivalent to `fslreorient2std`).
+> **Note:** Step 1 (reorientation) no longer requires FSL -- it uses nibabel's orientation tools to reorient scans to RAS (equivalent to `fslreorient2std`).
 
 #### Finding BRAINSFit and BRAINSResample
 
@@ -96,13 +103,21 @@ We recommend using a conda environment:
 ```bash
 conda create -n caideface python=3.10 -y
 conda activate caideface
+
+# MRI defacing only
 pip install caideface
+
+# MRI + CT defacing (includes TotalSegmentator)
+pip install caideface[ct]
 ```
 
 Or install from GitHub:
 
 ```bash
 pip install "caideface @ git+https://github.com/cai4cai/defacing_pipeline.git#subdirectory=caideface"
+
+# With CT support
+pip install "caideface[ct] @ git+https://github.com/cai4cai/defacing_pipeline.git#subdirectory=caideface"
 ```
 
 Or install from source:
@@ -110,10 +125,13 @@ Or install from source:
 ```bash
 git clone https://github.com/cai4cai/defacing_pipeline.git
 cd defacing_pipeline/caideface
-pip install -e .
+pip install -e .        # MRI only
+pip install -e ".[ct]"  # MRI + CT
 ```
 
 > **Note:** caideface requires `numpy<2` (enforced automatically). Some dependencies (HD-BET / nnU-Net) are not yet compatible with NumPy 2.x.
+>
+> **Note:** CT support requires [TotalSegmentator](https://github.com/wasserth/TotalSegmentator), which downloads model weights (~1.5 GB) on first use to `~/.totalsegmentator/`. All inference runs locally -- no scan data is sent externally.
 
 ## Usage
 
@@ -122,7 +140,15 @@ pip install -e .
 Run all three steps in one command:
 
 ```bash
+# MRI
 caideface run ./input_nifti ./output \
+  --modality mri \
+  --brainsfit /path/to/BRAINSFit \
+  --brainsresample /path/to/BRAINSResample
+
+# CT
+caideface run ./input_nifti ./output \
+  --modality ct \
   --brainsfit /path/to/BRAINSFit \
   --brainsresample /path/to/BRAINSResample
 ```
@@ -136,12 +162,13 @@ This creates three subdirectories under `./output`:
 
 | Flag | Default | Description |
 |------|---------|-------------|
-| `--device` | auto-detected | `cpu` or `cuda` for HD-BET |
-| `--no-tta` | on | Disable HD-BET test-time augmentation (faster but less accurate) |
+| `--modality` | *required* | Image modality: `mri` or `ct` |
+| `--device` | auto-detected | `cpu` or `cuda` for brain extraction |
+| `--no-tta` | on | Disable HD-BET test-time augmentation (MRI only) |
 | `--dilation-mm` | `14.0` | Brain mask dilation in mm |
-| `--background` | `0` | Fill value for defaced regions (0 for MRI, -1024 for CT) |
-| `--template` | bundled | Custom MNI152 skull-stripped template |
-| `--face-mask` | bundled | Custom face mask in MNI152 space |
+| `--background` | auto-detected | Background fill value (auto-detected per volume; override with explicit value) |
+| `--template` | bundled | Custom skull-stripped template |
+| `--face-mask` | bundled | Custom face mask in template space |
 | `--steps` | `all` | Run specific steps: `reorient`, `skull_strip`, `deface` (comma-separated) |
 | `-v` | off | Verbose/debug logging |
 
@@ -151,13 +178,14 @@ Run each step separately for more control:
 
 ```bash
 # Step 1: Reorientation
-caideface reorient ./raw_nifti ./reoriented
+caideface reorient ./raw_nifti ./reoriented --modality mri
 
 # Step 2: Skull-stripping
-caideface skull-strip ./reoriented ./hdbet --device cpu
+caideface skull-strip ./reoriented ./hdbet --modality mri --device cpu
 
 # Step 3: Registration & Defacing
 caideface deface ./reoriented ./hdbet ./defaced \
+  --modality mri \
   --brainsfit /path/to/BRAINSFit \
   --brainsresample /path/to/BRAINSResample
 ```
@@ -249,6 +277,7 @@ from caideface import (
     anonymize_batch,          # Text anonymisation (batch)
     anonymize_single,         # Text anonymisation (single file)
     default_ner_model_path,   # Path to bundled NER model
+    detect_background_value,  # CT/MRI background detection
 )
 ```
 
@@ -299,7 +328,21 @@ If you use this tool, please cite:
 }
 ```
 
-If you use HD-BET (skull-stripping, Step 2), please also cite:
+If you use CT defacing (TotalSegmentator, Step 2), please also cite:
+
+```bibtex
+@article{Wasserthal2023,
+  author={Wasserthal, Jakob and Breit, Hanns-Christian and Meyer, Manfred T. and Pradella, Maurice and Hinck, Daniel and Sauter, Alexander W. and Heye, Tobias and Boll, Daniel T. and Cyriac, Joshy and Yang, Shan and Bach, Michael and Segeroth, Martin},
+  title={TotalSegmentator: Robust Segmentation of 104 Anatomic Structures in CT Images},
+  journal={Radiology: Artificial Intelligence},
+  volume={5},
+  number={5},
+  year={2023},
+  doi={10.1148/ryai.230024}
+}
+```
+
+If you use HD-BET (MRI skull-stripping, Step 2), please also cite:
 
 ```bibtex
 @article{Isensee2019,
@@ -330,4 +373,4 @@ If you use the text anonymisation (NER + HIPS), please also cite:
 
 ## License
 
-This project is licensed under the Apache License 2.0 -- see the [LICENSE](../LICENSE) file for details.
+This project is licensed under the Apache License 2.0 -- see the [LICENSE](https://github.com/cai4cai/defacing_pipeline/blob/main/LICENSE) file for details.

{caideface-0.3.1 → caideface-0.3.3}/README.md

@@ -1,27 +1,34 @@
 # caideface
 
-**MRI defacing and text anonymisation toolkit** from the [cai4cai](https://cai4cai.ml/) research group (Contextual Artificial Intelligence for Computer Assisted Interventions).
+**MRI and CT defacing and text anonymisation toolkit** from the [cai4cai](https://cai4cai.ml/) research group (Contextual Artificial Intelligence for Computer Assisted Interventions).
 
 This package provides two complementary anonymisation capabilities:
 
-- **Image defacing** -- removes facial features from head MRI scans while preserving brain structures, as described in the paper *"A Generalisable Head MRI Defacing Pipeline: Evaluation on 2,566 Meningioma Scans"* ([arXiv:2505.12999](https://arxiv.org/abs/2505.12999)).
-- **Text anonymisation** -- detects personal names in medical reports using a trained spaCy NER model and replaces them with realistic fake names (Hiding in Plain Sight / HIPS technique).
+- **Image defacing** -- removes facial features from head MRI and CT scans while preserving brain structures. The MRI pipeline is described in the paper *"A Generalisable Head MRI Defacing Pipeline: Evaluation on 2,566 Meningioma Scans"* ([arXiv:2505.12999](https://arxiv.org/abs/2505.12999)).
+- **Text anonymisation** -- detects personal names in medical reports using a trained spaCy NER model and replaces them with realistic fake names (Hiding in Plain Sight / HIPS technique), as described in *"Evaluation of Named Entity Recognition for Automated Extraction of Present Tumor Size and Personal Names from Radiology Reports Using Spacy"* ([DOI:10.1055/s-0045-1803715](https://doi.org/10.1055/s-0045-1803715)).
 
 ## Pipeline overview
 
 ### Image defacing pipeline
 
-The defacing pipeline consists of three steps:
+The defacing pipeline supports both **MRI** and **CT** modalities, selected via the required `--modality {mri,ct}` flag. The pipeline consists of three steps, with modality-specific backends:
 
-1. **Reorientation** -- Aligns NIfTI scans to LAS canonical orientation (MNI152 standard) using nibabel.
-2. **Skull-stripping** -- Extracts brain masks using [HD-BET](https://github.com/MIC-DKFZ/HD-BET), then applies dynamic dilation to preserve peripheral brain structures.
-3. **Registration & Defacing** -- Registers each scan to the MNI152 template using BRAINSFit (affine), warps a face mask into the scan's space, and applies it to remove facial features.
+| Step | MRI | CT |
+|------|-----|-----|
+| 1. Reorientation | → RAS | → RAS |
+| 2. Brain extraction | [HD-BET](https://github.com/MIC-DKFZ/HD-BET) | [TotalSegmentator](https://github.com/wasserth/TotalSegmentator) |
+| 3. Registration template | MNI152 T1 (bundled) | CT brain atlas (from TotalSegmentator) |
+| Background value | Always 0 | Auto-detected per volume |
+
+1. **Reorientation** -- Aligns NIfTI scans to RAS canonical orientation (MNI152 standard) using nibabel, equivalent to FSL's `fslreorient2std`.
+2. **Skull-stripping** -- Extracts brain masks, then applies dynamic dilation to preserve peripheral brain structures. MRI uses [HD-BET](https://github.com/MIC-DKFZ/HD-BET); CT uses [TotalSegmentator](https://github.com/wasserth/TotalSegmentator) (brain class from the total segmentation task).
+3. **Registration & Defacing** -- Registers each scan to a modality-matched template using BRAINSFit (affine), warps a face mask into the scan's space, and applies it to remove facial features. For CT, the background fill value is automatically detected from the volume histogram (~-1000 HU for native encoding).
 
 ### Text anonymisation (NER + HIPS)
 
 The text anonymisation module uses a trained spaCy Named Entity Recognition (NER) model to identify personal names (`PER` entities) in `.txt` files and replaces them with realistic fake names generated by the [Faker](https://faker.readthedocs.io/) library. This "Hiding in Plain Sight" (HIPS) approach produces anonymised reports that remain naturally readable. Consistent name mapping ensures that the same real name is always replaced with the same fake name within a document.
 
-All required models and data are **bundled with the package**, so no additional downloads are needed.
+All required models and data for MRI defacing and text anonymisation are **bundled with the package**. CT defacing requires installing the optional `[ct]` extra (see [Installation](#installation)).
 
 ## Requirements
 
@@ -35,7 +42,7 @@ All required models and data are **bundled with the package**, so no additional
 |------|---------|---------|
 | **BRAINSFit** & **BRAINSResample** | Step 3 | Bundled with [3D Slicer](https://www.slicer.org/) |
 
-> **Note:** Step 1 (reorientation) no longer requires FSL -- it uses nibabel's orientation tools to reorient scans to LAS (equivalent to `fslreorient2std`).
+> **Note:** Step 1 (reorientation) no longer requires FSL -- it uses nibabel's orientation tools to reorient scans to RAS (equivalent to `fslreorient2std`).
 
 #### Finding BRAINSFit and BRAINSResample
 
@@ -65,13 +72,21 @@ We recommend using a conda environment:
 ```bash
 conda create -n caideface python=3.10 -y
 conda activate caideface
+
+# MRI defacing only
 pip install caideface
+
+# MRI + CT defacing (includes TotalSegmentator)
+pip install caideface[ct]
 ```
 
 Or install from GitHub:
 
 ```bash
 pip install "caideface @ git+https://github.com/cai4cai/defacing_pipeline.git#subdirectory=caideface"
+
+# With CT support
+pip install "caideface[ct] @ git+https://github.com/cai4cai/defacing_pipeline.git#subdirectory=caideface"
 ```
 
 Or install from source:
@@ -79,10 +94,13 @@ Or install from source:
 ```bash
 git clone https://github.com/cai4cai/defacing_pipeline.git
 cd defacing_pipeline/caideface
-pip install -e .
+pip install -e .        # MRI only
+pip install -e ".[ct]"  # MRI + CT
 ```
 
 > **Note:** caideface requires `numpy<2` (enforced automatically). Some dependencies (HD-BET / nnU-Net) are not yet compatible with NumPy 2.x.
+>
+> **Note:** CT support requires [TotalSegmentator](https://github.com/wasserth/TotalSegmentator), which downloads model weights (~1.5 GB) on first use to `~/.totalsegmentator/`. All inference runs locally -- no scan data is sent externally.
 
 ## Usage
 
@@ -91,7 +109,15 @@ pip install -e .
 Run all three steps in one command:
 
 ```bash
+# MRI
 caideface run ./input_nifti ./output \
+  --modality mri \
+  --brainsfit /path/to/BRAINSFit \
+  --brainsresample /path/to/BRAINSResample
+
+# CT
+caideface run ./input_nifti ./output \
+  --modality ct \
   --brainsfit /path/to/BRAINSFit \
   --brainsresample /path/to/BRAINSResample
 ```
@@ -105,12 +131,13 @@ This creates three subdirectories under `./output`:
 
 | Flag | Default | Description |
 |------|---------|-------------|
-| `--device` | auto-detected | `cpu` or `cuda` for HD-BET |
-| `--no-tta` | on | Disable HD-BET test-time augmentation (faster but less accurate) |
+| `--modality` | *required* | Image modality: `mri` or `ct` |
+| `--device` | auto-detected | `cpu` or `cuda` for brain extraction |
+| `--no-tta` | on | Disable HD-BET test-time augmentation (MRI only) |
 | `--dilation-mm` | `14.0` | Brain mask dilation in mm |
-| `--background` | `0` | Fill value for defaced regions (0 for MRI, -1024 for CT) |
-| `--template` | bundled | Custom MNI152 skull-stripped template |
-| `--face-mask` | bundled | Custom face mask in MNI152 space |
+| `--background` | auto-detected | Background fill value (auto-detected per volume; override with explicit value) |
+| `--template` | bundled | Custom skull-stripped template |
+| `--face-mask` | bundled | Custom face mask in template space |
 | `--steps` | `all` | Run specific steps: `reorient`, `skull_strip`, `deface` (comma-separated) |
 | `-v` | off | Verbose/debug logging |
 
@@ -120,13 +147,14 @@ Run each step separately for more control:
 
 ```bash
 # Step 1: Reorientation
-caideface reorient ./raw_nifti ./reoriented
+caideface reorient ./raw_nifti ./reoriented --modality mri
 
 # Step 2: Skull-stripping
-caideface skull-strip ./reoriented ./hdbet --device cpu
+caideface skull-strip ./reoriented ./hdbet --modality mri --device cpu
 
 # Step 3: Registration & Defacing
 caideface deface ./reoriented ./hdbet ./defaced \
+  --modality mri \
   --brainsfit /path/to/BRAINSFit \
   --brainsresample /path/to/BRAINSResample
 ```
@@ -218,6 +246,7 @@ from caideface import (
     anonymize_batch,          # Text anonymisation (batch)
     anonymize_single,         # Text anonymisation (single file)
     default_ner_model_path,   # Path to bundled NER model
+    detect_background_value,  # CT/MRI background detection
 )
 ```
 
@@ -268,7 +297,21 @@ If you use this tool, please cite:
 }
 ```
 
-If you use HD-BET (skull-stripping, Step 2), please also cite:
+If you use CT defacing (TotalSegmentator, Step 2), please also cite:
+
+```bibtex
+@article{Wasserthal2023,
+  author={Wasserthal, Jakob and Breit, Hanns-Christian and Meyer, Manfred T. and Pradella, Maurice and Hinck, Daniel and Sauter, Alexander W. and Heye, Tobias and Boll, Daniel T. and Cyriac, Joshy and Yang, Shan and Bach, Michael and Segeroth, Martin},
+  title={TotalSegmentator: Robust Segmentation of 104 Anatomic Structures in CT Images},
+  journal={Radiology: Artificial Intelligence},
+  volume={5},
+  number={5},
+  year={2023},
+  doi={10.1148/ryai.230024}
+}
+```
+
+If you use HD-BET (MRI skull-stripping, Step 2), please also cite:
 
 ```bibtex
 @article{Isensee2019,
@@ -299,4 +342,4 @@ If you use the text anonymisation (NER + HIPS), please also cite:
 
 ## License
 
-This project is licensed under the Apache License 2.0 -- see the [LICENSE](../LICENSE) file for details.
+This project is licensed under the Apache License 2.0 -- see the [LICENSE](https://github.com/cai4cai/defacing_pipeline/blob/main/LICENSE) file for details.

{caideface-0.3.1 → caideface-0.3.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "caideface"
-version = "0.3.1"
+version = "0.3.3"
 description = "MRI defacing pipeline with skull-stripping and affine registration from cai4cai"
 readme = "README.md"
 license = {text = "Apache-2.0"}

{caideface-0.3.1 → caideface-0.3.3}/src/caideface/__init__.py

@@ -8,7 +8,7 @@ A three-step pipeline for anonymising head MRI scans:
 Plus standalone text anonymisation via NER + HIPS (Hiding in Plain Sight).
 """
 
-__version__ = "0.3.1"
+__version__ = "0.3.3"
 
 from .pipeline import DefacePipeline
 from .reorient import reorient_batch, reorient_single

{caideface-0.3.1 → caideface-0.3.3}/src/caideface/cli.py

@@ -49,10 +49,9 @@ def main():
     run_parser.add_argument("--steps", default="all", help="Steps to run: all, or comma-separated: reorient,skull_strip,deface")
 
     # --- reorient ---
-    reorient_parser = subparsers.add_parser("reorient", help="Step 1: Reorient NIfTI scans", parents=[parent])
+    reorient_parser = subparsers.add_parser("reorient", help="Step 1: Reorient NIfTI scans to RAS", parents=[parent])
     reorient_parser.add_argument("input_dir", help="Directory with NIfTI files")
     reorient_parser.add_argument("output_dir", help="Output directory for reoriented files")
-    reorient_parser.add_argument("--modality", required=True, choices=["mri", "ct"], help="Image modality (mri→LAS, ct→RAS)")
 
     # --- skull-strip ---
     ss_parser = subparsers.add_parser("skull-strip", help="Step 2: Skull-strip with HD-BET", parents=[parent])
@@ -118,7 +117,7 @@ def main():
             sys.exit(1)
 
     elif args.command == "reorient":
-        reorient_batch(args.input_dir, args.output_dir, modality=args.modality)
+        reorient_batch(args.input_dir, args.output_dir)
 
     elif args.command == "skull-strip":
         skull_strip_batch(

{caideface-0.3.1 → caideface-0.3.3}/src/caideface/pipeline.py

@@ -97,10 +97,9 @@ class DefacePipeline:
         # Step 1: Reorientation
         if "reorient" in run_steps:
             logger.info("=" * 60)
-            target = "RAS" if self.modality == "ct" else "LAS"
-            logger.info("STEP 1: Reorientation to %s", target)
+            logger.info("STEP 1: Reorientation to RAS")
             logger.info("=" * 60)
-            reorient_log = reorient_batch(input_dir, reoriented_dir, modality=self.modality)
+            reorient_log = reorient_batch(input_dir, reoriented_dir)
             results["reorient_log"] = reorient_log
         else:
             logger.info("Skipping Step 1 (reorientation)")

{caideface-0.3.1 → caideface-0.3.3}/src/caideface/reorient.py

@@ -1,4 +1,4 @@
-"""Step 1: Reorientation of NIfTI scans using nibabel."""
+"""Step 1: Reorientation of NIfTI scans to RAS using nibabel."""
 
 import os
 import logging
@@ -9,18 +9,15 @@ import pandas as pd
 
 logger = logging.getLogger(__name__)
 
-# Target orientations per modality
-TARGET_ORIENTATIONS = {
-    "mri": ("L", "A", "S"),  # LAS — matches fslreorient2std
-    "ct": ("R", "A", "S"),   # RAS — matches CT brain atlas
-}
+# RAS matches the MNI152 standard, fslreorient2std, HD-BET, and the CT brain atlas.
+TARGET_ORIENTATION = ("R", "A", "S")
 
 
-def reorient_single(input_file: str, output_file: str, modality: str = "mri") -> bool:
-    """Reorient a single NIfTI file to the target orientation for *modality*.
+def reorient_single(input_file: str, output_file: str) -> bool:
+    """Reorient a single NIfTI file to RAS orientation.
 
-    MRI is reoriented to LAS (matching ``fslreorient2std`` / MNI152).
-    CT is reoriented to RAS (matching the CT brain atlas).
+    This is equivalent to FSL's ``fslreorient2std`` and matches the
+    MNI152 template orientation used by both the MRI and CT pipelines.
 
     Parameters
     ----------
@@ -28,8 +25,6 @@ def reorient_single(input_file: str, output_file: str, modality: str = "mri") ->
         Path to the input NIfTI (.nii.gz) file.
     output_file : str
         Path where the reoriented file will be saved.
-    modality : str
-        ``'mri'`` (target LAS) or ``'ct'`` (target RAS).
 
     Returns
     -------
@@ -38,12 +33,10 @@ def reorient_single(input_file: str, output_file: str, modality: str = "mri") ->
     """
     os.makedirs(os.path.dirname(output_file), exist_ok=True)
 
-    target = TARGET_ORIENTATIONS.get(modality, TARGET_ORIENTATIONS["mri"])
-
     try:
         img = nib.load(input_file)
         orig_ornt = io_orientation(img.affine)
-        target_ornt = axcodes2ornt(target)
+        target_ornt = axcodes2ornt(TARGET_ORIENTATION)
         transform = ornt_transform(orig_ornt, target_ornt)
         reoriented = img.as_reoriented(transform)
         nib.save(reoriented, output_file)
@@ -54,8 +47,8 @@ def reorient_single(input_file: str, output_file: str, modality: str = "mri") ->
     return os.path.exists(output_file)
 
 
-def reorient_batch(input_dir: str, output_dir: str, modality: str = "mri") -> pd.DataFrame:
-    """Reorient all NIfTI files found recursively under *input_dir*.
+def reorient_batch(input_dir: str, output_dir: str) -> pd.DataFrame:
+    """Reorient all NIfTI files found recursively under *input_dir* to RAS.
 
     The directory structure is mirrored under *output_dir*.
 
@@ -66,8 +59,6 @@ def reorient_batch(input_dir: str, output_dir: str, modality: str = "mri") -> pd
     output_dir : str
         Root directory where reoriented files will be saved,
         preserving the subdirectory structure.
-    modality : str
-        ``'mri'`` (target LAS) or ``'ct'`` (target RAS).
 
     Returns
     -------
@@ -77,8 +68,7 @@ def reorient_batch(input_dir: str, output_dir: str, modality: str = "mri") -> pd
     input_dir = os.path.abspath(input_dir)
     output_dir = os.path.abspath(output_dir)
 
-    target = TARGET_ORIENTATIONS.get(modality, TARGET_ORIENTATIONS["mri"])
-    logger.info("Target orientation: %s (%s)", "".join(target), modality)
+    logger.info("Target orientation: RAS")
 
     log_rows = []
     for root, _dirs, files in os.walk(input_dir):
@@ -91,7 +81,7 @@ def reorient_batch(input_dir: str, output_dir: str, modality: str = "mri") -> pd
             out_path = os.path.join(output_dir, rel, fname)
 
             logger.info("Reorienting %s", input_path)
-            success = reorient_single(input_path, out_path, modality=modality)
+            success = reorient_single(input_path, out_path)
             log_rows.append({"input": input_path, "output": out_path, "success": success})
 
             if success:

{caideface-0.3.1 → caideface-0.3.3}/src/caideface/skull_strip.py

@@ -111,21 +111,31 @@ def _extract_brain_totalseg(
     """
     try:
         from totalsegmentator.python_api import totalsegmentator
+        import totalsegmentator.config as _ts_config
     except ImportError:
         raise ImportError(
             "TotalSegmentator is required for CT skull-stripping.\n"
             "Install it with: pip install caideface[ct]"
         )
 
+    # Disable anonymous usage statistics — no data should leave the machine.
+    # Patch send_usage_stats to a no-op so no network calls are made.
+    _orig_send = _ts_config.send_usage_stats
+    _ts_config.send_usage_stats = lambda *a, **kw: None
+
     ts_device = "cpu" if device == "cpu" else "gpu"
 
-    input_img = nib.load(input_file)
-    brain_mask = totalsegmentator(
-        input=input_img,
-        task="total",
-        roi_subset=["brain"],
-        device=ts_device,
-    )
+    try:
+        input_img = nib.load(input_file)
+        brain_mask = totalsegmentator(
+            input=input_img,
+            task="total",
+            roi_subset=["brain"],
+            device=ts_device,
+            quiet=True,
+        )
+    finally:
+        _ts_config.send_usage_stats = _orig_send
 
     # Save the raw binary brain mask
     mask_data = brain_mask.get_fdata().astype(np.uint8)

{caideface-0.3.1 → caideface-0.3.3}/src/caideface.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: caideface
-Version: 0.3.1
+Version: 0.3.3
 Summary: MRI defacing pipeline with skull-stripping and affine registration from cai4cai
 Author-email: Lorena Garcia-Foncillas <lorenagarfon00@gmail.com>
 License: Apache-2.0
@@ -31,28 +31,35 @@ Requires-Dist: TotalSegmentator; extra == "ct"
 
 # caideface
 
-**MRI defacing and text anonymisation toolkit** from the [cai4cai](https://cai4cai.ml/) research group (Contextual Artificial Intelligence for Computer Assisted Interventions).
+**MRI and CT defacing and text anonymisation toolkit** from the [cai4cai](https://cai4cai.ml/) research group (Contextual Artificial Intelligence for Computer Assisted Interventions).
 
 This package provides two complementary anonymisation capabilities:
 
-- **Image defacing** -- removes facial features from head MRI scans while preserving brain structures, as described in the paper *"A Generalisable Head MRI Defacing Pipeline: Evaluation on 2,566 Meningioma Scans"* ([arXiv:2505.12999](https://arxiv.org/abs/2505.12999)).
-- **Text anonymisation** -- detects personal names in medical reports using a trained spaCy NER model and replaces them with realistic fake names (Hiding in Plain Sight / HIPS technique).
+- **Image defacing** -- removes facial features from head MRI and CT scans while preserving brain structures. The MRI pipeline is described in the paper *"A Generalisable Head MRI Defacing Pipeline: Evaluation on 2,566 Meningioma Scans"* ([arXiv:2505.12999](https://arxiv.org/abs/2505.12999)).
+- **Text anonymisation** -- detects personal names in medical reports using a trained spaCy NER model and replaces them with realistic fake names (Hiding in Plain Sight / HIPS technique), as described in *"Evaluation of Named Entity Recognition for Automated Extraction of Present Tumor Size and Personal Names from Radiology Reports Using Spacy"* ([DOI:10.1055/s-0045-1803715](https://doi.org/10.1055/s-0045-1803715)).
 
 ## Pipeline overview
 
 ### Image defacing pipeline
 
-The defacing pipeline consists of three steps:
+The defacing pipeline supports both **MRI** and **CT** modalities, selected via the required `--modality {mri,ct}` flag. The pipeline consists of three steps, with modality-specific backends:
 
-1. **Reorientation** -- Aligns NIfTI scans to LAS canonical orientation (MNI152 standard) using nibabel.
-2. **Skull-stripping** -- Extracts brain masks using [HD-BET](https://github.com/MIC-DKFZ/HD-BET), then applies dynamic dilation to preserve peripheral brain structures.
-3. **Registration & Defacing** -- Registers each scan to the MNI152 template using BRAINSFit (affine), warps a face mask into the scan's space, and applies it to remove facial features.
+| Step | MRI | CT |
+|------|-----|-----|
+| 1. Reorientation | → RAS | → RAS |
+| 2. Brain extraction | [HD-BET](https://github.com/MIC-DKFZ/HD-BET) | [TotalSegmentator](https://github.com/wasserth/TotalSegmentator) |
+| 3. Registration template | MNI152 T1 (bundled) | CT brain atlas (from TotalSegmentator) |
+| Background value | Always 0 | Auto-detected per volume |
+
+1. **Reorientation** -- Aligns NIfTI scans to RAS canonical orientation (MNI152 standard) using nibabel, equivalent to FSL's `fslreorient2std`.
+2. **Skull-stripping** -- Extracts brain masks, then applies dynamic dilation to preserve peripheral brain structures. MRI uses [HD-BET](https://github.com/MIC-DKFZ/HD-BET); CT uses [TotalSegmentator](https://github.com/wasserth/TotalSegmentator) (brain class from the total segmentation task).
+3. **Registration & Defacing** -- Registers each scan to a modality-matched template using BRAINSFit (affine), warps a face mask into the scan's space, and applies it to remove facial features. For CT, the background fill value is automatically detected from the volume histogram (~-1000 HU for native encoding).
 
 ### Text anonymisation (NER + HIPS)
 
 The text anonymisation module uses a trained spaCy Named Entity Recognition (NER) model to identify personal names (`PER` entities) in `.txt` files and replaces them with realistic fake names generated by the [Faker](https://faker.readthedocs.io/) library. This "Hiding in Plain Sight" (HIPS) approach produces anonymised reports that remain naturally readable. Consistent name mapping ensures that the same real name is always replaced with the same fake name within a document.
 
-All required models and data are **bundled with the package**, so no additional downloads are needed.
+All required models and data for MRI defacing and text anonymisation are **bundled with the package**. CT defacing requires installing the optional `[ct]` extra (see [Installation](#installation)).
 
 ## Requirements
 
@@ -66,7 +73,7 @@ All required models and data are **bundled with the package**, so no additional
 |------|---------|---------|
 | **BRAINSFit** & **BRAINSResample** | Step 3 | Bundled with [3D Slicer](https://www.slicer.org/) |
 
-> **Note:** Step 1 (reorientation) no longer requires FSL -- it uses nibabel's orientation tools to reorient scans to LAS (equivalent to `fslreorient2std`).
+> **Note:** Step 1 (reorientation) no longer requires FSL -- it uses nibabel's orientation tools to reorient scans to RAS (equivalent to `fslreorient2std`).
 
 #### Finding BRAINSFit and BRAINSResample
 
@@ -96,13 +103,21 @@ We recommend using a conda environment:
 ```bash
 conda create -n caideface python=3.10 -y
 conda activate caideface
+
+# MRI defacing only
 pip install caideface
+
+# MRI + CT defacing (includes TotalSegmentator)
+pip install caideface[ct]
 ```
 
 Or install from GitHub:
 
 ```bash
 pip install "caideface @ git+https://github.com/cai4cai/defacing_pipeline.git#subdirectory=caideface"
+
+# With CT support
+pip install "caideface[ct] @ git+https://github.com/cai4cai/defacing_pipeline.git#subdirectory=caideface"
 ```
 
 Or install from source:
@@ -110,10 +125,13 @@ Or install from source:
 ```bash
 git clone https://github.com/cai4cai/defacing_pipeline.git
 cd defacing_pipeline/caideface
-pip install -e .
+pip install -e .        # MRI only
+pip install -e ".[ct]"  # MRI + CT
 ```
 
 > **Note:** caideface requires `numpy<2` (enforced automatically). Some dependencies (HD-BET / nnU-Net) are not yet compatible with NumPy 2.x.
+>
+> **Note:** CT support requires [TotalSegmentator](https://github.com/wasserth/TotalSegmentator), which downloads model weights (~1.5 GB) on first use to `~/.totalsegmentator/`. All inference runs locally -- no scan data is sent externally.
 
 ## Usage
 
@@ -122,7 +140,15 @@ pip install -e .
 Run all three steps in one command:
 
 ```bash
+# MRI
 caideface run ./input_nifti ./output \
+  --modality mri \
+  --brainsfit /path/to/BRAINSFit \
+  --brainsresample /path/to/BRAINSResample
+
+# CT
+caideface run ./input_nifti ./output \
+  --modality ct \
   --brainsfit /path/to/BRAINSFit \
   --brainsresample /path/to/BRAINSResample
 ```
@@ -136,12 +162,13 @@ This creates three subdirectories under `./output`:
 
 | Flag | Default | Description |
 |------|---------|-------------|
-| `--device` | auto-detected | `cpu` or `cuda` for HD-BET |
-| `--no-tta` | on | Disable HD-BET test-time augmentation (faster but less accurate) |
+| `--modality` | *required* | Image modality: `mri` or `ct` |
+| `--device` | auto-detected | `cpu` or `cuda` for brain extraction |
+| `--no-tta` | on | Disable HD-BET test-time augmentation (MRI only) |
 | `--dilation-mm` | `14.0` | Brain mask dilation in mm |
-| `--background` | `0` | Fill value for defaced regions (0 for MRI, -1024 for CT) |
-| `--template` | bundled | Custom MNI152 skull-stripped template |
-| `--face-mask` | bundled | Custom face mask in MNI152 space |
+| `--background` | auto-detected | Background fill value (auto-detected per volume; override with explicit value) |
+| `--template` | bundled | Custom skull-stripped template |
+| `--face-mask` | bundled | Custom face mask in template space |
 | `--steps` | `all` | Run specific steps: `reorient`, `skull_strip`, `deface` (comma-separated) |
 | `-v` | off | Verbose/debug logging |
 
@@ -151,13 +178,14 @@ Run each step separately for more control:
 
 ```bash
 # Step 1: Reorientation
-caideface reorient ./raw_nifti ./reoriented
+caideface reorient ./raw_nifti ./reoriented --modality mri
 
 # Step 2: Skull-stripping
-caideface skull-strip ./reoriented ./hdbet --device cpu
+caideface skull-strip ./reoriented ./hdbet --modality mri --device cpu
 
 # Step 3: Registration & Defacing
 caideface deface ./reoriented ./hdbet ./defaced \
+  --modality mri \
   --brainsfit /path/to/BRAINSFit \
   --brainsresample /path/to/BRAINSResample
 ```
@@ -249,6 +277,7 @@ from caideface import (
     anonymize_batch,          # Text anonymisation (batch)
     anonymize_single,         # Text anonymisation (single file)
     default_ner_model_path,   # Path to bundled NER model
+    detect_background_value,  # CT/MRI background detection
 )
 ```
 
@@ -299,7 +328,21 @@ If you use this tool, please cite:
 }
 ```
 
-If you use HD-BET (skull-stripping, Step 2), please also cite:
+If you use CT defacing (TotalSegmentator, Step 2), please also cite:
+
+```bibtex
+@article{Wasserthal2023,
+  author={Wasserthal, Jakob and Breit, Hanns-Christian and Meyer, Manfred T. and Pradella, Maurice and Hinck, Daniel and Sauter, Alexander W. and Heye, Tobias and Boll, Daniel T. and Cyriac, Joshy and Yang, Shan and Bach, Michael and Segeroth, Martin},
+  title={TotalSegmentator: Robust Segmentation of 104 Anatomic Structures in CT Images},
+  journal={Radiology: Artificial Intelligence},
+  volume={5},
+  number={5},
+  year={2023},
+  doi={10.1148/ryai.230024}
+}
+```
+
+If you use HD-BET (MRI skull-stripping, Step 2), please also cite:
 
 ```bibtex
 @article{Isensee2019,
@@ -330,4 +373,4 @@ If you use the text anonymisation (NER + HIPS), please also cite:
 
 ## License
 
-This project is licensed under the Apache License 2.0 -- see the [LICENSE](../LICENSE) file for details.
+This project is licensed under the Apache License 2.0 -- see the [LICENSE](https://github.com/cai4cai/defacing_pipeline/blob/main/LICENSE) file for details.

{caideface-0.3.1 → caideface-0.3.3}/tests/test_reorient.py

@@ -30,7 +30,7 @@ def _make_nifti(shape=(64, 64, 32), orientation="PSR", dirpath=None):
 
 
 class TestReorientSingle:
-    def test_reorients_to_las(self, tmp_path):
+    def test_reorients_to_ras(self, tmp_path):
         input_path = _make_nifti(orientation="PSR", dirpath=str(tmp_path))
         output_path = os.path.join(str(tmp_path), "output", "reoriented.nii.gz")
 
@@ -39,10 +39,10 @@ class TestReorientSingle:
         assert success is True
         assert os.path.exists(output_path)
         img = nib.load(output_path)
-        assert nib.aff2axcodes(img.affine) == ("L", "A", "S")
+        assert nib.aff2axcodes(img.affine) == ("R", "A", "S")
 
-    def test_already_las_is_unchanged(self, tmp_path):
-        input_path = _make_nifti(orientation="LAS", dirpath=str(tmp_path))
+    def test_already_ras_is_unchanged(self, tmp_path):
+        input_path = _make_nifti(orientation="RAS", dirpath=str(tmp_path))
         output_path = os.path.join(str(tmp_path), "output", "reoriented.nii.gz")
 
         success = reorient_single(input_path, output_path)
@@ -86,7 +86,7 @@ class TestReorientSingle:
             success = reorient_single(input_path, output_path)
             assert success is True
             img = nib.load(output_path)
-            assert nib.aff2axcodes(img.affine) == ("L", "A", "S"), f"Failed for {ornt}"
+            assert nib.aff2axcodes(img.affine) == ("R", "A", "S"), f"Failed for {ornt}"
 
     def test_invalid_file_returns_false(self, tmp_path):
         fake_path = os.path.join(str(tmp_path), "nonexistent.nii.gz")