Skip to content

ChristianGaser/T1Prep

BranchesTags

Repository files navigation

Python 3.9 | 3.10 | 3.11 | 3.12 License: Apache 2.0 Release

Warning

This project is still in development and might contain bugs. If you experience any issues, please let me know!

T1Prep logo

T1Prep: T1 PREProcessing Pipeline (aka PyCAT)

Table of Contents

T1Prep is a pipeline that preprocesses T1-weighted MRI data and supports segmentation and cortical surface reconstruction. It provides a complete set of tools for efficiently processing structural MRI scans.

T1Prep partially integrates DeepMriPrep, which uses deep learning (DL) techniques to mimic CAT12's functionality for processing structural MRIs. For details, see: Lukas Fisch et al., "deepmriprep: Voxel-based Morphometry (VBM) Preprocessing via Deep Neural Networks," available on arXiv at https://doi.org/10.48550/arXiv.2408.10656.

An alternative approach uses DeepMriPrep for bias field correction, lesion detection, and also serves as an initial estimate for the subsequent AMAP segmentation from CAT12.

Cortical surface reconstruction and thickness estimation use the algorithms from CAT-Surface (a core component of the CAT12 toolbox) via the cat-surf Python package, which provides pure Python bindings to the CAT-Surface C library — no platform-specific compiled binaries are required.

It is designed for both single-subject and batch processing, with optional parallelization and flexible output naming conventions. The naming patterns are compatible with both CAT12 folder structures and the BIDS derivatives standard.

Requirements

Python 3.9-3.12 is required, and all necessary libraries are automatically installed the first time T1Prep is run or is called with the flag "--install".

Main Differences to CAT12

  • Implemented entirely in Python, eliminating the need for a Matlab license or platform-specific compiled binaries.
  • Newly developed pipeline to estimate cortical surface and thickness.
  • Skull-stripping, segmentation and non-linear spatial registration uses DeepMriPrep
  • Does not yet support longitudinal pipelines.
  • No quality assessment implemented yet.
  • Only T1 MRI data supported.

Installation

T1Prep is distributed as a pure-Python package on PyPI and can also be installed via a bash bootstrapper that lays down the full source tree. Pick whichever workflow suits you.

pip / PyPI (Recommended for Python users)

If you have Python 3.9–3.12 available, install directly from PyPI:

# Latest release
python3 -m pip install T1Prep

# Pin a specific version (any PEP 440 spec)
python3 -m pip install "T1Prep==0.4.4"

# Optional: pipx keeps T1Prep isolated in its own venv
pipx install T1Prep

Model weights are not bundled with the wheel; they are fetched lazily on the first run into your user cache (or downloaded ahead of time with t1prep-download-models).

Use it from Python:

from t1prep import run_t1prep
run_t1prep("/path/to/sub-01_T1w.nii.gz")

…or as a CLI:

python -m t1prep.t1prep --input sub-01_T1w.nii.gz --out-dir out/

Bash bootstrapper (full source tree)

If you also want the bash orchestrator (scripts/T1Prep) — useful for multi-subject parallelism — install T1Prep with the bundled bootstrapper:

curl -fsSL https://raw.githubusercontent.com/ChristianGaser/T1Prep/refs/heads/main/scripts/install.sh | bash

The installer will interactively prompt you to:

  1. Select a version: Latest release, development (main branch), or choose from available releases
  2. Choose installation directory: Current folder, temporary folder, or custom path

Non-Interactive Installation

Use environment variables to skip the interactive prompts:

# Install latest release to current directory
T1PREP_VERSION=latest T1PREP_INSTALL_DIR="$PWD/T1Prep" \
  curl -fsSL https://raw.githubusercontent.com/ChristianGaser/T1Prep/refs/heads/main/scripts/install.sh | bash

# Install specific version to custom directory
T1PREP_VERSION=v1.0.0 T1PREP_INSTALL_DIR=/opt/T1Prep \
  curl -fsSL https://raw.githubusercontent.com/ChristianGaser/T1Prep/refs/heads/main/scripts/install.sh | bash
Environment Variable Description
T1PREP_VERSION Release tag (e.g., v1.0.0) or latest
T1PREP_INSTALL_DIR Absolute path for installation

Windows Installation via WSL (Recommended)

T1Prep requires a Linux environment to run. On Windows, we recommend using Windows Subsystem for Linux (WSL), which provides a complete Linux environment with full compatibility.

WSL Requirements

Windows Version WSL Support
Windows 11 (all versions) WSL 2 ✓
Windows 10 version 2004+ (Build 19041+) WSL 2 ✓
Windows 10 version 1903-1909 WSL 2 (with manual kernel update)
Windows 10 version 1607-1903 WSL 1 only
Windows Server 2019+ WSL ✓

Installing WSL and T1Prep

  1. Install WSL (run PowerShell as Administrator):

    wsl --install

    This installs WSL 2 with Ubuntu by default. Restart your computer when prompted.

  2. Open Ubuntu from the Start menu and complete the initial setup (create username/password).

  3. Install T1Prep inside WSL (Ubuntu terminal):

    curl -fsSL https://raw.githubusercontent.com/ChristianGaser/T1Prep/main/scripts/install.sh | bash

  4. Access Windows files from WSL at /mnt/c/ (C: drive), /mnt/d/ (D: drive), etc.:

    # Process a file from your Windows Documents folder
T1Prep --out-dir /mnt/c/Users/YourName/T1Prep_output /mnt/c/Users/YourName/Documents/scan.nii.gz

Alternative: Docker on Windows

If you prefer not to install WSL directly, you can use Docker Desktop for Windows (which uses WSL 2 internally):

docker run --rm -it -v C:\path\to\data:/data t1prep:latest --out-dir /data/out /data/file.nii.gz

See the Docker section for build instructions.

Manual Installation

If you do not want pip to manage the environment for you (e.g. for an offline or air-gapped setup), you can install the dependencies yourself.

From PyPI into your own virtualenv:

python3.12 -m venv env
source env/bin/activate
pip install T1Prep

From a source checkout (developers):

git clone https://github.com/ChristianGaser/T1Prep.git
cd T1Prep
python3.12 -m venv env
source env/bin/activate
pip install -e .                    # editable; tracks local edits
# – or –
pip install -r requirements.txt     # dependencies only (no T1Prep itself)

Source ZIP plus bash bootstrapper (kept for parity with older docs):

unzip T1Prep_$version.zip -d your_installation_folder
./scripts/T1Prep --python python3.12 --install

Web UI (Flask)

A minimal browser-based UI is available for local use. It uploads selected NIfTI files, lets you configure General and Save options, and can schedule jobs to start at a specific time.

./scripts/T1Prep_ui

By default the Web UI runs on port 5050. To use a different port:

./scripts/T1Prep_ui 5500

When started, the UI will try to open an app-style window (Chrome if available, otherwise your default browser). You can also open the URL manually in any browser.

Then open http://127.0.0.1:5050 (or the port you selected) in your browser.

To prevent auto-opening a browser window:

./scripts/T1Prep_ui --no-browser

Uploaded files are stored under webui_uploads/ and per-job logs under webui_jobs/.

Docker

A Dockerfile is provided that installs T1Prep from PyPI on top of a slim Python 3.12 base image. No source checkout is needed — the image is a pure-Python distribution with model weights fetched lazily on first run.

Build

Latest release from PyPI:

docker build -t t1prep:latest .

Pinned release:

docker build \
  --build-arg T1PREP_VERSION=0.4.4 \
  -t t1prep:0.4.4 .

The T1PREP_VERSION build-arg accepts any PEP 440 version string (no leading v) and is forwarded to pip install "T1Prep==...". Leave it unset to track the latest release on PyPI.

Run

Mount your data directory into the container (replace /path/to/data with your folder):

docker run --rm -it \
  -v /path/to/data:/data \
  t1prep:latest \
  --out-dir /data/out /data/file.nii.gz

Append --gpus all to docker run to enable GPU acceleration when available.

Memory & performance

Make sure that the container has at least 16-24 GB of RAM available. If you are using Docker Desktop/WSL2, increase the VM memory in the settings. If you receive an error message stating that there is no space left on the device: /tmp/, you can try the following: If you obtain an error that no space is left on device: /tmp/ you can try that:

docker run --rm -it \
  --tmpfs /tmp:rw,exec,nosuid,nodev,size=16g \
  -v /path/to/data:/data \
  t1prep:latest \
  --out-dir /data/out /data/file.nii.gz

Output Folder Structure and Naming Conventions

T1Prep automatically determines output locations based on the input data structure:

  1. BIDS datasets
    If the input NIfTI is located in an anat folder:

<dataset-root>/derivatives/T1Prep-v<version>/<sub-XXX>/<ses-YYY>/anat/

  • Subject (sub-XXX) and session (ses-YYY) are extracted from the path.
  • If --out-dir <DIR> is specified, the BIDS substructure will still be created inside <DIR>.
  1. Non-BIDS datasets
    Results are written to CAT12-style subfolders (mri/, surf/, etc.) in:

<input-folder>/<subfolder>/

or in <DIR> if --out-dir <DIR> is specified.

  1. Naming Conventions
  • Default (CAT12): Uses classic names like mri/brainmask.nii and surf/lh.thickness.
  • With --bids: Uses BIDS derivatives naming, e.g.: 
    sub-01_ses-1_space-T1w_desc-brain_mask.nii.gz
sub-01_ses-1_hemi-L_thickness.shape.gii
  • All filename mappings for both modes are defined in Names.tsv and can be customized.

Usage

./scripts/T1Prep [options] file1.nii.[.gz] file2.nii[.gz] ...

Helper Scripts

In addition to ./scripts/T1Prep, the following wrappers provide convenient entry points for Web UI and CAT-Surface post-processing.

./scripts/T1Prep_ui

Launches the Flask Web UI (same tool described in the Web UI (Flask) section).

./scripts/T1Prep_ui
./scripts/T1Prep_ui 5500
./scripts/T1Prep_ui --no-browser
  • Default port: 5050
  • Optional positional port argument (e.g., 5500)
  • --no-browser disables auto-launching a browser/app window

./scripts/CAT_SurfResampleMulti_ui

Resamples LH/RH surface values to target spheres and writes a combined output per LH input using CAT_SurfResampleMulti.

./scripts/CAT_SurfResampleMulti_ui [options] lh.thickness.subject.gii

Common options:

  • --out <DIR> output directory
  • --res <STR> output surface resolution (32k or 4k)
  • --fwhm <FLOAT> smoothing FWHM
  • --trg-sphere <FILE> target LH sphere
  • --mask <FILE> target LH mask
  • --jobs <N> parallel worker count

Input expectations:

  • Supports lh.* naming and auto-derives RH counterparts
  • BIDS-style *_left* naming is currently not implemented

./scripts/CAT_SurfParameters_ui

Computes surface parameters from mesh files using CAT-Surface binaries (CAT_SurfCurvature, CAT_SurfFractalDimension, CAT_SurfArea, CAT_SurfRatio, CAT_SurfSulcusDepth) bundled in src/t1prep/bin/.

./scripts/CAT_SurfParameters_ui [options] lh.central.gii

Common options:

  • -gy, -mc, -gc, -cv, -si, -sh, -fi, -area, -fd, -sr, -sra
  • -depth, -sqrt-depth, -min-curv, -max-curv, -dp
  • -gifti write GIfTI output
  • -noclobber do not overwrite existing files
  • --jobs <N> / --no-parallel parallel control

Input expectations:

  • Accepts .obj and .gii
  • For lh.* files, matching rh.* is processed automatically when available

./scripts/CAT_Surf2ROIMulti_ui

Extracts ROI-wise values from surface value files using CAT_Surf2ROIMulti. For each LH input, RH files are derived automatically.

./scripts/CAT_Surf2ROIMulti_ui [options] lh.thickness.subject.gii

Common options:

  • --out <DIR> output directory
  • --res <STR> surface/atlas resolution (default 32k)
  • --trg-sphere <FILE> target LH sphere
  • --annot <NAMES> one or multiple atlas names
  • --jobs <N> / --no-parallel parallel control

Atlas names for --annot are resolved as:

  • src/t1prep/data/atlases_surfaces_<res>/lh.<name>.annot
  • src/t1prep/data/atlases_surfaces_<res>/rh.<name>.annot

Multi-atlas examples:

./scripts/CAT_Surf2ROIMulti_ui --annot "'aparc_DK40.freesurfer' 'aparc_a2009s.freesurfer'" lh.thickness.subject.gii
./scripts/CAT_Surf2ROIMulti_ui --annot "aparc_DK40.freesurfer,aparc_a2009s.freesurfer" lh.thickness.subject.gii

Python API

You can also call the full pipeline from Python without shelling out manually:

from t1prep import run_t1prep

# Single file, BIDS naming
run_t1prep("/data/sub-01/ses-1/anat/sub-01_ses-1_T1w.nii.gz", bids=True)

# Multiple files with options and logging
run_t1prep([
  "/data/T1/sub-01.nii.gz",
  "/data/T1/sub-02.nii.gz",
], out_dir="/results", atlas=["neuromorphometrics", "suit"], multi=-1,
   wp=True, p=True, csf=True, lesions=True, gz=True, stream_output=True,
   log_file="/results/T1Prep_run.log")

Options

Simply call T1Prep to see available options

./scripts/T1Prep

Skull-stripping modes:

  • --skullstrip-only: run skull-stripping only and exit after writing a skull-stripped image and brain mask.
  • --no-skullstrip / --skip-skullstrip: skip skull-stripping (assumes input is already skull-stripped).

Longitudinal / advanced flags:

  • --initial-surf <FILE>: use an initial surface estimate for longitudinal processing.
  • --long-data <PATH>: process the volume at <PATH> while keeping output naming/folders based on the provided input file.
  • --no-atlas: disable atlas labeling (overrides any defaults file atlas selection).

Robustness:

  • --no-retry: disable automatic retry of failed processing steps. By default, if segmentation or surface estimation fails for a subject it is retried once before being reported as an error.

Output folders structure

Output folder structure depends on the input dataset type:

  • BIDS datasets (if the upper-level folder of the input files is 'anat'): Results are placed in a BIDS-compatible derivatives folder: inside <DIR> Subject ('sub-XXX') and session ('ses-YYY') are auto-detected.
  • Non-BIDS datasets: Results are placed in subfolders similar to CAT12 output (e.g., 'mri/', 'surf/', 'report/', 'label') inside the specified output directory.

If '--bids' is set, the BIDS derivatives substructure will always be used inside <DIR>.

Naming behaviour

  • CAT12 style (default): Uses legacy folder and file names (e.g., 'mri/mwp1sub-01.nii', 'surf/lh.thickness.sub-01').
  • BIDS style: Uses standardized derivatives names, including subject/session identifiers, modality, and processing steps.

The complete mapping between internal outputs and both naming conventions is stored in 'Names.tsv' and can be customized.

Examples: Input: /data/study/sub-01/ses-1/anat/sub-01_ses-1_T1w.nii.gz Default output (no --out-dir): /data/study/derivatives/T1Prep-v${version}/sub-01/ses-1/anat/ With --out-dir /results: /results/derivatives/T1Prep-v${version}/sub-01/ses-1/anat/

Input: /data/T1_images/subject01.nii.gz Default output (no --out-dir): /data/T1_images/mri/ With --out-dir /results: /results/mri/

Examples

  ./scripts/T1Prep --out-dir test_folder sTRIO*.nii

Process all files matching the pattern 'sTRIO*.nii'. Generate segmentation and surface maps, saving the results in the 'test_folder' directory.

  ./scripts/T1Prep --no-surf sTRIO*.nii

Process all files matching the pattern 'sTRIO*.nii', but skip surface creation. Only segmentation maps are generated and saved in the same directory as the input files.

  ./scripts/T1Prep --python python3.9 --no-overwrite "surf/lh.thickness." sTRIO*.nii

Process all files matching the pattern 'sTRIO*.nii' and use python3.9. Skip processing for files where 'surf/lh.thickness.*' already exists, and save new results in the same directory as the input files.

  ./scripts/T1Prep --lesion --no-sphere sTRIO*.nii

Process all files matching the pattern 'sTRIO*.nii'. Skip processing of spherical registration, but additionally save lesion map (named p7sTRIO*.nii) in native space.

  ./scripts/T1Prep --amap sTRIO*.nii

Process all files matching the pattern 'sTRIO*.nii' and enable AMAP segmentation.

  ./scripts/T1Prep --multi 8 --p --csf sTRIO*.nii
  ./scripts/T1Prep --skullstrip-only --out-dir test_folder sTRIO*.nii

Only run skull-stripping and write the skull-stripped image and brain mask.

  ./scripts/T1Prep --skip-skullstrip --out-dir test_folder sTRIO*_brain.nii

Skip skull-stripping for already skull-stripped inputs. Process all files matching the pattern 'sTRIO*.nii'. Additionally save segmentations in native space, including CSF segmentation. The processing pipeline involves two stages of parallelization:

  1. Segmentation (Python-based): Runs best with about 16-24GB of memory per process. The number of processes is automatically estimated based on available memory to optimize resource usage.

  2. Surface Extraction: This stage does not require significant memory and is fully distributed across all available processorsor limited to the defined number of processes using the "--multi" flag.

If "--multi" is set to a specific number (e.g., 8), the system still estimates memory-based constraints for segmentation parallelization. However, the specified number of processes (e.g., 8) will be used for surface extraction, ensuring efficient parallelization across the two stages. The default setting is -1, which automatically estimates the number of available processors.

Longitudinal realignment (experimental)

For rigid realignment of a series of NIfTI volumes, use the realignment helper:

./scripts/realign_longitudinal.sh --help

New tuning flags in the Python realigner:

  • --max-fwhm-mm <FLOAT>: maximum smoothing (FWHM, mm) for coarse alignment.
  • --no-intensity-scale: disable SPM-like global intensity scaling.
  • --overlap-penalty-weight <FLOAT>: penalize samples that fall outside the moving FOV.
  • --sample-strategy {grid,gradient}: choose deterministic grid or edge-biased gradient sampling.
  • --grad-quantile <FLOAT>: threshold for selecting high-gradient samples.

Input

T1-weighted MRI images in NIfTI format (extension nii/nii.gz).

Support

For issues and inquiries, contact me.

License

T1Prep is distributed under the terms of the Apache License as published by the Apache Software Foundation.

About

T1Prep: T1 PREProcessing pipeline (aka PyCat)

Resources

Readme

License

Apache-2.0 license
Activity

Stars

9 stars

Watchers

1 watching

Forks

2 forks
Report repository

Releases 21

v0.4.5 Latest
May 18, 2026
+ 20 releases

Packages

 
 
 

Contributors

Languages