Version: 1.0.0.1
Author: aspolverato
Email: [email protected]
Affiliation: NILab (CIMeC and FBK)

Neucav is a comprehensive deep learning tool designed to automatically generate post-surgery cavity masks from post-operative T1-weighted contrast-enhanced (T1-w-CE) MRI images. The tool leverages state-of-the-art neural networks (nnUNet) and provides detailed analysis including overlap calculations with anatomical regions of interest (ROIs).

• Multi-format Input Support: Accepts NIfTI files (.nii, .nii.gz), DICOM folders, or ZIP archives containing DICOM files
• Automated Preprocessing Pipeline: Includes DICOM conversion, resampling, reorientation, skull stripping, and MNI registration
• Quality Control Options: Two quality levels (0: low/fast, 1: high/slow) for different use cases
• ROI Analysis: Calculates overlap with white matter and gray matter regions of interest
• Visualization: Generates radar plots for anatomical importance analysis
• Flexible Output: Supports both NIfTI and DICOM output formats

• ANTs (Advanced Normalization Tools)
• FSL (FMRIB Software Library)
• FreeSurfer (for SynthStrip skull stripping)
• nnUNet (Neural network framework)
• dcm2niix (DICOM to NIfTI conversion)
• Python 3 with required libraries

• IMAGINGlib
• REGlib
• FILESlib
• CPUslib

• CPU/GPU support (GPU recommended for faster processing)
• Sufficient RAM for processing medical images
• Storage space for intermediate processing files

1. Install the required software dependencies:

   # Install FSL, ANTs, FreeSurfer following their respective installation guides
   # Install dcm2niix
   # Install nnUNet following: https://github.com/MIC-DKFZ/nnUNet

2. Set up the nnUNet environment variables:

   export nnUNet_raw="/path/to/nnUNet_raw"
   export nnUNet_preprocessed="/path/to/nnUNet_preprocessed"
   export nnUNet_results="/path/to/nnUNet_results"

3. Make the script executable:

   chmod +x Neucav.sh

./Neucav.sh [-h] -i <input_file> -o <output_directory> [-q <quality>] [-e <extension>] [-z] [--gpu]

• -i, --input=<filename>: Input post-operative T1-w-CE image (NIfTI file, DICOM folder, or ZIP containing DICOMs)
• -o, --output=<directory>: Output directory for results

• -q, --quality=<quality>: Quality of the output mask (default: 1)
  • 0: Low quality (faster processing, CPU-optimized)
  • 1: High quality (slower processing, better accuracy)
• -e, --output_extension=<extension>: Output file extension
  • n: NIfTI format (.nii.gz) [default]
  • d: DICOM format
• -z, --zip: Create compressed output (useful for DICOM format)
• --gpu: Use GPU acceleration (if available)
• -h, --help: Show help message

./Neucav.sh -i sub_001_T1w_CE.nii.gz -o ./results -q 1

./Neucav.sh -i /path/to/dicom_folder/ -o ./results -q 0

./Neucav.sh -i patient_dicoms.zip -o ./results -q 1 --gpu

The tool executes the following automated pipeline:

1. Input Validation and Format Detection

   • Detects file format (NIfTI, DICOM folder, or ZIP)
   • Extracts ZIP archives if needed

2. DICOM to NIfTI Conversion (if applicable)

   • Converts DICOM files to NIfTI format using dcm2niix
   • Handles multiple series and selects appropriate T1-w images

3. Image Preprocessing

   • Resampling: Converts to isotropic 1×1×1mm resolution
   • Reorientation: Standardizes to RAS (Right-Anterior-Superior) orientation
   • Skull Stripping: Removes non-brain tissue using SynthStrip
   • MNI Registration: Registers to MNI152 standard space using FLIRT

4. Neural Network Prediction

   • Applies pre-trained nnUNet model (Dataset 950) for cavity segmentation
   • Uses 3D full-resolution configuration with custom training

5. Post-processing

   • Transforms predicted mask back to original image space
   • Restores original orientation and resolution
   • Ensures geometric consistency with input image

6. ROI Analysis

   • Calculates overlap with white matter tracts
   • Computes overlap with gray matter regions
   • Generates importance scores for different anatomical areas

7. Visualization and Output

   • Creates radar plots showing anatomical importance
   • Packages final results in standardized format

The tool generates a comprehensive set of outputs in the specified directory:

• res_cavity.nii.gz: Final cavity mask in native image space
• res_cavity_MNI.nii.gz: Cavity mask in MNI standard space
• flirt_to_mni.mat: Affine transformation matrix to MNI space

• GM_importance.csv: Gray matter region overlap analysis
• WM_importance.csv: White matter tract overlap analysis
• Radar plots: Visual representation of anatomical importance (PNG/PDF/SVG)

• Resampled, reoriented, and skull-stripped images
• Registration matrices and intermediate transformations
• Volume statistics and processing logs

The tool includes several quality control measures:

• Volume Validation: Checks if predicted mask has non-zero volume
• Geometric Consistency: Ensures proper alignment between mask and original image
• Processing Logs: Detailed logging of each processing step
• Intermediate File Preservation: Allows inspection of processing pipeline

1. Empty mask warning: If the predicted mask has zero volume, check:

   • Input image quality and contrast
   • Presence of actual surgical cavity
   • Image orientation and preprocessing success

2. Memory issues: For large images:

   • Use quality level 0 for reduced memory usage
   • Ensure sufficient system RAM
   • Consider processing on a machine with more resources

3. Registration failures: If MNI registration fails:

   • Check FSL installation and FSLDIR environment variable
   • Verify input image has proper brain anatomy
   • Ensure skull stripping was successful

Check the console output for detailed processing information and error messages. The tool provides verbose logging for each processing step.

If you use Neucav in your research, please cite the appropriate publications related to the underlying methods (nnUNet, FSL, ANTs, FreeSurfer).

Please refer to the individual software licenses for the components used (nnUNet, FSL, ANTs, FreeSurfer).

For issues, questions, or contributions, please contact:

• Author: aspolverato
• Email: [email protected]
• Affiliation: NILab (CIMeC and FBK)

• v1.0.0.1: Initial release with full pipeline implementation