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 <path/to/image.nii.gz> –o <path/to/segmentation.nii.gz>

# With cortical parcellation (detailed) micaflow synthseg

–i <path/to/image.nii.gz> –o <path/to/segmentation.nii.gz> –parc

# Robust mode for highest quality micaflow synthseg

–i <path/to/image.nii.gz> –o <path/to/segmentation.nii.gz> –robust

# Fast mode for quick processing micaflow synthseg

–i <path/to/image.nii.gz> –o <path/to/segmentation.nii.gz> –fast

# With volume measurements micaflow synthseg

–i <path/to/image.nii.gz> –o <path/to/segmentation.nii.gz> –vol <path/to/volumes.csv>

# With quality control scores micaflow synthseg

–i <path/to/image.nii.gz> –o <path/to/segmentation.nii.gz> –qc <path/to/qc_scores.csv>

# Batch processing with all outputs micaflow synthseg

–i <path/to/input_folder/> –o <path/to/output_folder/> –parc –vol <path/to/volumes.csv> –qc <path/to/qc_scores.csv> –post <path/to/posteriors/> –threads 8

# CPU-only execution micaflow synthseg

–i <path/to/image.nii.gz> –o <path/to/segmentation.nii.gz> –cpu –threads 8

# CT scan segmentation micaflow synthseg

–i <path/to/ct_scan.nii.gz> –o <path/to/segmentation.nii.gz> –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

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

╔════════════════════════════════════════════════════════════════╗
║                         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