FastSurfer v2.5.4

This hot fix release fixes an issue in the Corpus Callosum Module: In some cases the midline was computed in reverse order. This flipping affected the sub-segmentation of the CC (only two components were created). When performing analysis on individual CC segments, we highly recommend upgrading to this version!

What's Changed

• CC subsegment ordering by @ClePol in #836
• Minor CI quicktests version bumps and updates (unrelated to the main pipeline)

Full Changelog: v2.5.3...v2.5.4

FastSurfer v2.5.3

What's Changed

• Docker Images would not run unless USER was explicitly passed, this is fixed now
• minor fixes in CC module for contour visualization
• speedup (bincount instead of mode)
• replicability (remove randomness from lapy call)
• minor fixes

The full test pipeline was re-run on this. There should be no changes in the output stats etc (except for the general randomness noise)

Full Changelog: v2.5.2...v2.5.3

FastSurfer v2.5.2

What's Changed

• Due to changes in the parameters of conform.py, FastSurfer was failing when a T2 image is passed (for HypVINN). This is not part of our test pipeline yet and remained unnoticed. This hot fix release patches that. #821
• It also improves the Mac build: upx not needed #819
• Finally, we also fix a numpy 2 incompatibility inside a rare if block #821

Full Changelog: v2.5.1...v2.5.2

FastSurfer v2.5.1

Updates

This hot-fix release does not change the pipeline, it only adds:

• a fix for automatically generating the Mac build on GitHub in #817
• removes requirements.cpu.txt as it is not needed any longer, pinned requirements of the release can be found in requirements.txt

Note

• For Dockerhub we are building versions with different cuda versions. The tag latest points to the version with Cuda 12.8 to support more modern GPUs including Blackwell (50**). For support of old CUDA drivers or hardware, download the cu118 (CUDA11.8) tag.

Full Changelog: v2.5.0...v2.5.1

FastSurfer v2.5.0

Main Updates

1. Integration of the new and very much improved Corpus Callosum Segmentation, including CC thickness, curvature analysis, see https://deep-mi.org/FastSurfer/dev/overview/modules/CC.html and our paper, published in Imaging Neuroscience https://doi.org/10.1162/IMAG.a.1221 , pdf also here: https://arxiv.org/abs/2511.16471
2. Native Image: Experimental, with the --keepgeom or --native_image flag we now allow to perform the segmentation (--seg_only !!) in the native image space. For this the image should be close to isotropic voxel sizes.
3. Our Lesion Inpainting Tool neuroLIT is now experimentally integrated into FastSurfer to permit processing images with a lesion mask or resection and generating surface models etc. https://doi.org/10.1162/imag_a_00446 https://deep-mi.org/FastSurfer/dev/overview/modules/LIT.html
4. Improved eTIV stability. Still based on the FreeSurfer-like registration approach, but with a more stable pre-alignment to avoid mis-registrations and incorrect eTIV values, e.g. in HCP data. Addressing, e.g. #800 . Also watch out for our own superior segmentation based eTIV tools in future releases.
5. Added a MacOS build packaging
6. Various minor fixes and improvement (see below).

Note

• For Dockerhub we are building versions with different cuda versions. The tag latest points to the version with Cuda 12.8 to support more modern GPUs including Blackwell (50**). For support of old CUDA drivers or hardware, download the cu118 (CUDA11.8) tag.

What's Changed

• Update LONG.md by @m-reuter in #665
• Prevent division by zero by @santiestrada32 in #667
• Fix smaller issues in srun_fastsurfer.sh by @dkuegler in #671
• Fix regmode none for hypvinn by @dkuegler in #675
• Move existing surfaces check into run_fastsurfer by @dkuegler in #677
• Mac compatibility: Avoid PCRE grep in recon-surf, stat formatting and mapfile by @dkuegler in #672
• Read the voxel size from image with python instead of from log by @dkuegler in #683
• quicktest update & merge CerebNet.utils.metrics into FastSurferCNN.utils.metrics by @taha-abdullah in #590
• Update doc for Docker in the rootless mode by @plu-project in #684
• Add additional stats/aseg.VINN.stats file by @dkuegler in #678
• Update matplotlib by @santiestrada32 in #687
• Fix links to actions in quicktest workflow by @dkuegler in #686
• Add documentation to build the docker image releases by @dkuegler in #689
• Fix how devices were parsed in brun_fastsurfer by @dkuegler in #690
• Add segmentation of images in "native image space" by @dkuegler in #691
• Some formatting changes that have accumulated over time by @dkuegler in #692
• Fixes to the anisotropic segmentation of FastSurfer by @dkuegler in #695
• Bump setuptools from 75.8.0 to 78.1.1 by @dependabot[bot] in #696
• Fixes so de-selecting views for processing for run_prediction is possible by @dkuegler in #697
• Data documentation by @kdiers in #419
• Bump tornado from 6.4.2 to 6.5.1 by @dependabot[bot] in #698
• Add information about FastSurfer course by @kdiers in #711
• Fix conform.py losing tr value during conversion by @OtabekRintaro in #714
• Fix ruff error suppression of typing.Optional by @OtabekRintaro in #713
• Fix import in brun_fastsurfer by @dkuegler in #715
• Bump urllib3 from 2.3.0 to 2.5.0 by @dependabot[bot] in #710
• Bump requests from 2.32.3 to 2.32.4 by @dependabot[bot] in #706
• Bump protobuf from 5.28.3 to 5.29.5 by @dependabot[bot] in #707
• Bump torch from 2.6.0+cpu to 2.7.1+cpu by @dependabot[bot] in #708
• Add workaround for SSL certificate mismatch error with mamba/conda at DZNE by @dkuegler in #718
• Bugfixes before release by @dkuegler in #700
• Fix inconsistent file and folder permissions by @dkuegler in #719
• Github workflow changes by @dkuegler in #720
• Add Docker command and revise longitudinal notes by @m-reuter in #725
• Change "base" to person-specific template by @m-reuter in #726
• Fix typos in LONG.md by @christianewert in #729
• Add the longitudinal outputs compatibility script by @dkuegler in #722
• Avoid ' without termination in help text by @m-reuter in #731
• Fix ROCm installation link for AMD GPU support by @cbrnr in #735
• Fix srun_fastsurfer termination on files inspection by @dkuegler in #741
• Fix quicktest outputs if FastSurfer fails by @dkuegler in #742
• Fix and update spherical project by @dkuegler in #743
• Add MacOS build packaging tool by @OtabekRintaro in #734
• Fix subshells exiting not leading to script ending by @dkuegler in #749
• Updates in preparation for FastSurferCC by @dkuegler in #750
• Minor fixes to the documentation, formatting and literal strings. by @dkuegler in #751
• Add a template pre-commit hook script and speed up sphinx build by @dkuegler in #755
• Maintenance update for FastSurfer (coming from FastSurferCC integration) by @dkuegler in #757
• Documentation better linking of symbols to files and cleanup by @dkuegler in #760
• Add FastSurfer-CC to the FastSurfer repository by @ClePol in #727
• FastSurfer-CC bugfixes by @ClePol in #762
• CC documentation & final testing by @ClePol in #763
• Quick fix to address warning in run_prediction.py by @dkuegler in #768
• Change error message to warning in link_fs.sh by @m-reuter in #771
• Exclude WarmupCosineLR.step from doc validation by @m-reuter in #772
• Various updates and changes to the documentation by @dkuegler in #765
• Add citation for FastSurfer-CC by @ClePol in #773
• Add timeout to version.py execution by @m-reuter in #774
• bump python packages, use UV instead of conda, update docker build by @dkuegler in #766
• Fix version info by @dkuegler in #776
• Internal benchmarking/execution time for segmentation pipeline by @dkuegler in #777
• Modify the macOS release script to remove the link_fs.sh duplicate file by @dkuegler in #775
• Fixes to the docker build process by @dkuegler in #781
• Quickfix: Fix typo in functions.sh by @dkuegler in #783
• Fix voxel radius calculation in sample_parc.py by @m-reuter in #784
• add stages to long_fastsurfer.sh by @m-reuter in #786
• Change and harmonize 0 or 1 as boolean values to "true"/"false" in bash scripts by @dkuegler in #785
• Remove corpus callosum processing from surface pipeline by @dkuegler in #787
• Fix bug in spherically project wrapper by @dkuegler in #788
• Add missing files to the documentation by @dkuegler in #792
• CC module bugfix and robustness by @ClePol in #791
• Add missing '[@]' to function RunBatchJobs by @dkuegler in #793
• Fix: Correct FastSurfer-CC error code handling and documentation formatting by @dkuegler in #794
• Update pre-commit script and GitHub workflows to use uv by @dkuegler in #796
• Fix the matplotlib backend for qc plotting by @dkuegler in #797
• Upgrade WhipperSnapPy from 1.3 to 2....

v2.4.2

FastSurfer v2.4.2

Changes affect only longitudinal processing of a single time point case inside docker:

• Our docker images were missing the script make_upright which is needed for the processing of a single time point case in the longitudinal stream. This is now added.

Background: Single time point cases can be used in a longitudinal study. For example, linear mixed effects models make use of this data to estimate cross-subject variance. In order to include single time point cases in a longitudinal analysis, they need to be processed through the same steps as other cases, to be comparable. The longitudinal pipeline permits doing so.

What's Changed

• LONG: add make_upright to docker by @m-reuter in #664

Full Changelog: v2.4.1...v2.4.2

v2.4.1

FastSurfer v2.4.1

This hot fix release contains several fixes (the default pipeline is not affected):

• --allow_root was broken in run_fastsurfer and long_fastsurfer and now is fixed.
• the new longitudinal stream stopped when image geometries were not perfectly identical across time points (this usually indicates changes in the image acquisition or the pre-processing and can be a source of bias - i.e. measuring changes when there are none). It now gives a warning as intended and then continues. Please take the warning seriously and check why your image resolutions differ across time, even if the difference is small.
• adding a T2 for the hippothalamus segmentation did not work correctly and is fixed now. Also note, that we perform a registration to the T1 and for that currently you need to pass a freesurfer licenses even in the segmentation block (only when passing a T2 in addition to a T1).
• Further fixes in srun_fastsurfer and brun_fastsurfer.

What's Changed

• Fix allow_root in run_fastsurfer and long_fastsurfer by @dkuegler in #658
• run diff command in if statement to catch error by @m-reuter in #657
• Fixes additional flags in srun_fastsurfer and T2 processing by @dkuegler in #656

Full Changelog: v2.4.0...v2.4.1

v2.4.0

FastSurfer v2.4.0

This version is a big one and introduces some really exciting new functionality! We almost made it a major release, but since it should not really break any compatibility, we will keep some more really cool things in stock for you for v3. Hard to believe we can do even more than what we have in this release:

• Longitudinal Stream
  You have waited long for the longitudinal pipeline in FastSurfer and now it is finally here. In our tests we see increased reliability and sensitivity of this new stream, but not only with respect to FastSurfer's independent processing, but even with respect to our older FreeSurfer longitudinal pipeline. We are really excited about this new stream. There is no reason to wait, try for yourself and see Long-Documentation to get started.

• Edits
  We have added a few ways to interact with FastSurfer and introduce manual edits, such as white matter and pial surface edits. These should rarely be necessary, but if you want to intervene, now you can. Find all the details in our Edits-Documentation.

• Parallel

  • We have cleaned up the many ways that things run in parallel. This makes the interface much simpler for run_fastsurfer.sh: you only need to use --threads to select a target number of cores now (or --threads_seg and --threads_surf for more control over the threads in each block). The --parallel argument is deprecated and run_fastsurfer.sh will automatically process both hemispheres in parallel, if you use more than 1 thread (1 is currently still the default). Note, we no longer double the number of threads used during parallel surface processing. So for threads=2, each hemisphere gets one thread, the rest of the code uses 2 threads.
  • Furthermore, we added flags to brun_fastsurfer.sh to allow specifying the number of parallel cases in the segmentation block and the surface block separately, for a more fine grained control (--parallel_seg and --parallel_surf), e.g. of GPU usage (in seg) vs. CPU (in surf) and even using multipe GPUs.
  • Our new long_fastsurfer.sh now can make use of this functionality when you want to run multiple time points in parallel, try --parallel_surf there.

• Other Changes

  • We cleaned up the code and introduced code style checks.
  • Documentation has been updated https://deep-mi.org/FastSurfer/dev/index.html
  • Improved logging
  • Bug fix to HypVINN for large images and other minor fixes
  • Bumped versions of dependencies

Notice

All the amazing functionality of FastSurfer is brought to you for free. You can help us, by making sure you cite our papers in you publications, not only the initial FastSurfer paper or the VINN for high-res support, but also the papers describing the individual modules that you use (Cerebnet, Hypvinn, or our older papers on Longitudinal Processing in FreeSurfer which are the basis for the new longitudinal pipeline).

Future Highlights

Our roadmap includes many things, some of them are listed here:

• Lesion Inpainting to process cases with lesions, tumor, resection cavities or other pathologies (this already works with our Lesion Inpainting Tool
• Improved Corpus Callosum and Fornix segmentation, including AC and PC
• Improved eTIV estimation via segmentation
• Addition of more labels, e.g. for WM sub-segmentation, skull and bone segmentation
• FastPlex for the accurate Choroid Plexus segmentation
• T2 / Flair segmentation

Detailed Changes (selection)

• Add code style via ruff by @m-reuter in #573
• Restore CerebNet checkpoint functions by @dkuegler in #575
• Subject directory should default to environment SUBJECTS_DIR variable by @dkuegler in #576
• bugfix rotate_sphere.py by @m-reuter in #577
• Fixes a bug in srun_fastsurfer that processed the partition argument wrong by @dkuegler in #581
• Longitudinal processing by @m-reuter in #588
• Formatting updates in shell scripts by @dkuegler in #585
• Helper functions: run_it and check_allow_root by @neginshirvani in #592
• Feature/tal reg long edits by @neginshirvani in #593
• apply hotfix 2.3.1 to dev by @m-reuter in #599
• Dev hotfix2.3.2 by @m-reuter in #601
• Bug fixes by @m-reuter in #602
• Fix arguments to version.py by @dkuegler in #608
• Fix parallel longitudinal processing by @dkuegler in #606
• Bump versions to those in docker container by @dkuegler in #610
• Create a dedicated BUILD.info file for docker images by @dkuegler in #612
• Make separate run_fastsurfer.sh invocations more clear in log by @dkuegler in #616
• Edit and establish the workflow "quicktest" on github actions servers by @dkuegler in #619
• Base/long fix -fsaparc by @m-reuter in #621
• Support for edits by @dkuegler in #591
• Update the docker build defaults by @dkuegler in #627
• Update Documentation by @m-reuter in #633
• add LONG description by @m-reuter in #635
• Fix HypVINN issues with image bigger than 320 by @santiestrada32 in #637
• add quickstart example by @m-reuter in #639
• Improvements to brun_fastsurfer.sh by @dkuegler in #640
• Extension: Enable seg=N and surf=N in long_fastsurfer by @dkuegler in #641
• Update versions of python packages by @dkuegler in #642
• Update the recon-surf docs by @dkuegler in #645
• Edit the output of long_fastsurfer.sh (message explaining delayed output) by @dkuegler in #646
• Unify and change of segmentation/surface syntax by @dkuegler in #644

Full Changelog: v2.3.3...v2.4.0

v2.3.3

What's Changed

• BUG: in brun_fastsurfer, positional arguments get converted to lowercase by @dkuegler in #603
• Update default time for segmentation in srun_fastsurfer by @dkuegler in #604
• Bump versions to those in docker container (stable) by @dkuegler in #611

Full Changelog: v2.3.2...v2.3.3

v2.3.2

What's Changed

• Hotfix2.3.2 by @m-reuter in #600

This fixes two things:

1. Fix bug when --fsaparc was used (aseg.stats were missing, causing the pipeline to stop later)
2. Fix bug that caused wmparc.DKTatlas.mapped.statsto contain a lot of lines with zero volume for unrelated structures. These are now omitted.

Full Changelog: v2.3.1...v2.3.2