Synthseg ======== synthseg - Neural Network-Based Brain MRI Segmentation Part of the micaflow processing pipeline for neuroimaging data. This module provides an interface to SynthSeg, a deep learning-based tool for automated brain MRI segmentation that works across different MRI contrasts without retraining. SynthSeg segments brain anatomical structures in T1w, T2w, FLAIR, and other MR contrasts, providing both whole-brain segmentation and optional cortical parcellation. What is SynthSeg? ---------------- SynthSeg is a contrast-agnostic segmentation tool that: - Segments brain MRI scans regardless of acquisition contrast - Works with T1w, T2w, FLAIR, PD, and other MRI modalities - Provides robust segmentation across different scanners and protocols How It Works: 1. Load input MRI (any contrast) 2. Optional preprocessing (cropping, resampling) 3. Run 3D U-Net inference 4. Optional postprocessing (CRF, largest component) 5. Output segmentation labels 6. Optional: Compute volumes and QC scores Segmentation Labels: ------------------- Standard mode (37 labels): - Cortical gray matter (left/right) - White matter (left/right) - Lateral ventricles (left/right) - Cerebellum (left/right) - Thalamus (left/right) - Caudate (left/right) - Putamen (left/right) - Pallidum (left/right) - Hippocampus (left/right) - Amygdala (left/right) - Brainstem - ... and more subcortical structures Parcellation mode (up to 132 labels): - All standard labels - Cortical parcellation (FreeSurfer-style) - Frontal, parietal, temporal, occipital regions - Gyral and sulcal subdivisions Features: -------- - Contrast-agnostic: Works with T1w, T2w, FLAIR, PD, etc. - Whole-brain segmentation: 37 anatomical structures - Cortical parcellation: Optional FreeSurfer-style parcellation - Batch processing: Process multiple subjects efficiently - Multi-threading: CPU parallelization support Command-Line Usage: ------------------ # Basic segmentation micaflow synthseg \ --i \ --o # With cortical parcellation (detailed) micaflow synthseg \ --i \ --o \ --parc # Robust mode for highest quality micaflow synthseg \ --i \ --o \ --robust # Fast mode for quick processing micaflow synthseg \ --i \ --o \ --fast # With volume measurements micaflow synthseg \ --i \ --o \ --vol # With quality control scores micaflow synthseg \ --i \ --o \ --qc # Batch processing with all outputs micaflow synthseg \ --i \ --o \ --parc \ --vol \ --qc \ --post \ --threads 8 # CPU-only execution micaflow synthseg \ --i \ --o \ --cpu \ --threads 8 # CT scan segmentation micaflow synthseg \ --i \ --o \ --ct Python API Usage: ---------------- >>> from micaflow.scripts.synthseg import main >>> import sys >>> >>> # Basic usage >>> sys.argv = [ ... 'synthseg', ... '--i', 'T1w.nii.gz', ... '--o', 'segmentation.nii.gz' ... ] >>> main() >>> >>> # With options (alternative approach) >>> main({ ... 'i': 'T1w.nii.gz', ... 'o': 'segmentation.nii.gz', ... 'parc': True, ... 'robust': True, ... 'vol': 'volumes.csv', ... 'qc': 'qc_scores.csv', ... 'threads': 8, ... 'cpu': False ... }) Pipeline Integration: -------------------- SynthSeg is typically used early in the processing pipeline for: 1. Quality control of acquisitions 2. Brain masking 3. Registration targets 4. Volume-based analysis Structural MRI Pipeline: 1. Segmentation (synthseg) 2. Surface reconstruction (optional) 3. Registration to template 4. Morphometric analysis Multimodal Pipeline: 1. Structural segmentation (synthseg) 2. Functional/diffusion preprocessing 3. Coregistration to anatomical 4. ROI-based analysis using segmentation Exit Codes: ---------- 0 : Success - segmentation completed 1 : Error - invalid inputs, file not found, or processing failure Limitations: ----------- - Optimized for adult brain anatomy - May struggle with severe pathology See Also: -------- - coregister : Register segmentation to functional data - apply_warp : Apply transformations to segmentation - extract_rois : Extract ROI time series using segmentation References: ---------- 1. Billot B, Greve DN, Puonti O, et al. SynthSeg: Segmentation of brain MRI scans of any contrast and resolution without retraining. Med Image Anal. 2023;86:102789. doi:10.1016/j.media.2023.102789 Command Line Usage ----------------- .. code-block:: bash micaflow synthseg [options] Source Code ----------- View the source code: `GitHub Repository `_ Description ----------- ║ Contrast-Agnostic Brain Segmentation ║ This script runs the SynthSeg neural network for automated brain MRI segmentation. It works across different MRI contrasts (T1w, T2w, FLAIR, etc.) without retraining, providing robust anatomical segmentation. Full Help --------- .. code-block:: text ╔════════════════════════════════════════════════════════════════╗ ║ SYNTHSEG ║ ║ Contrast-Agnostic Brain Segmentation ║ ╚════════════════════════════════════════════════════════════════╝ This script runs the SynthSeg neural network for automated brain MRI segmentation. It works across different MRI contrasts (T1w, T2w, FLAIR, etc.) without retraining, providing robust anatomical segmentation. ────────────────────────── USAGE ────────────────────────── micaflow synthseg [options] ─────────────────── REQUIRED ARGUMENTS ─────────────────── --i PATH : Input image(s) to segment (file or folder) --o PATH : Output segmentation file(s) or folder ─────────────────── OPTIONAL ARGUMENTS ─────────────────── --parc : Enable cortical parcellation (132 labels vs 37) --robust : Use robust mode (higher quality, ~5x slower) --fast : Faster processing (minimal postprocessing) --threads N : Number of CPU threads (default: 1) --cpu : Force CPU processing (instead of GPU) --vol PATH : Output CSV file with region volumes --qc PATH : Output CSV file with quality control scores --post PATH : Output posterior probability maps --resample PATH: Output resampled images --crop N [N ...]: Size of 3D patches (default: 192) --ct : Clip intensities [0,80] for CT scans --v1 : Use SynthSeg 1.0 (legacy version) ────────────────── EXAMPLE USAGE ──────────────────────── # Example 1: Basic segmentation micaflow synthseg \ --i T1w.nii.gz \ --o segmentation.nii.gz # Example 2: With cortical parcellation micaflow synthseg \ --i T1w.nii.gz \ --o segmentation.nii.gz \ --parc # Example 3: Robust mode for research micaflow synthseg \ --i T1w.nii.gz \ --o segmentation.nii.gz \ --parc \ --robust # Example 4: Batch processing with volumes micaflow synthseg \ --i input_folder/ \ --o output_folder/ \ --vol volumes.csv \ --qc qc_scores.csv \ --threads 8 # Example 5: Fast mode for exploration micaflow synthseg \ --i T2w.nii.gz \ --o segmentation.nii.gz \ --fast # Example 6: CPU-only with all outputs micaflow synthseg \ --i FLAIR.nii.gz \ --o segmentation.nii.gz \ --parc \ --vol volumes.csv \ --qc qc_scores.csv \ --post posteriors.nii.gz \ --cpu \ --threads 8 ───────────────── COMMON ISSUES ───────────────────────── Issue: Poor segmentation quality Solution: Try --robust mode, check image quality, verify contrast Issue: Out of memory error Solution: Use --crop for smaller patches, or --cpu mode Issue: Very slow processing Solution: Use GPU if available, or --fast mode for quick results Issue: Missing structures in segmentation Solution: Check QC scores, use --robust mode, verify input quality