Deep-MI/FastSurfer v2.6.0

on GitHub

Hey,

we are happy to announce the new 2.6.0 release of FastSurfer with lots of improvements and fixes, related to
easy install, faster processing, replicability, and much more.

A lot of work has gone into native Mac M-chip support for FastSurfer 2.6:
On Apple silicon it now installs from a single package installer with everything included, so no download of
dependencies at install or run time. Because we build on FreeSurfer 8.2 binaries we can now offer full ARM
support also for the surface module on the Mac, making processing faster. Also the bump to PyTorch 2.14 which
implements all functions natively for MPS speeds things up.

Lots of other new features, see for yourself...

Highlights

FastSurfer on the Mac

• Double-click a .pkg on an Apple silicon Mac (macOS 14 or later). It bundles Python, every dependency, the
  network checkpoints and a pruned FreeSurfer (about 571 MB instead of 10 GB). No internet connection is needed
  during the install, and your shell profile is left alone.
• The FastSurfer app opens a Terminal console with everything on the PATH.
• No Rosetta 2 needed: the bundled FreeSurfer is the native arm64 build of FreeSurfer 8.2.
• Per-command timing now works on the Mac too, also inside recon-all (FastSurfer's own Python fs_time).
• Intel Macs are supported by Docker images, as PyTorch does not ship wheels for them any longer.

FreeSurfer 8.2, PyTorch 2.14, CUDA 13 and Python 3.14

• FreeSurfer 8.2 replaces 7.4.1, binaries replaced only, so the processing is the same and Linux results are
  identical (#926).
• PyTorch 2.14, with Docker images for CUDA 12.6 and 13.2 (the default), ROCm 7.2 and Intel XPU (#919).
  The CUDA 13 images need a recent driver and no longer support Maxwell, Pascal and Volta GPUs; use the CUDA 12.6
  image for those. Images for CUDA 11.8, CUDA 12.8 and ROCm 6.3 are no longer built, and only the latest and
  cpu-latest aliases are published.
• Python 3.12 or newer is required for native installations; the images and the macOS package ship Python 3.14
  (#930).
• A GPU FastSurfer cannot use is explained: an architecture the image does not support, a driver too old for its
  CUDA, or a container started without --gpus all/--nv is named with what to use instead, and the run continues
  on the CPU with a clear warning (#916, #921, #924).

Reproducible results and threads

• Same machine, same --threads: identical results. The topology correction now always runs single threaded, and
  the spherical projection pins its numerical kernels, which were the two sources of run to run differences.
• On CPU, results can be made identical across machines, Intel and AMD, with the environment described in the new
  Reproducibility page of the documentation. It is not the default because it slows down the segmentation. GPU runs
  are not covered.
• --threads is one budget that reaches every library (numpy's BLAS, MKL, ITK, OpenMP), and the default is now
  auto instead of one thread: the CPUs of a container or scheduler allocation, otherwise the physical cores less one
  (all performance cores on Apple silicon), within limits where more threads stop helping. --threads max works on
  macOS and in docker --cpus, and batch and longitudinal runs share the machine between parallel cases (#920).
• Every log records the machine it ran on: CPU, usable cores, torch build, thread limits and a numerical
  fingerprint, so comparing two runs starts with a diff.

New features

• BIDS input: bids_fastsurfer.py, a BIDS-App style entry point that runs a whole dataset locally or on Slurm
  (experimental). Contributed by Karl Koschutnig (#909).
• Longitudinal T2 support: long_fastsurfer.sh --t2s, one T2 per time point, for the hypothalamus module (#910).
  The longitudinal documentation now explains each --stage.
• Lesion inpainting in minutes: neurolit 0.7.0 inpaints a lesion in a few minutes instead of 30 to 60, and
  --lesion_mask is no longer experimental (#869). Its machine-readable summary is now
  stats/lesion_impact_summary.json (previously .yaml).
• Faster cortical ribbon: built with a winding number instead of mris_volmask, minutes become seconds.
• eTIV for already processed subjects: --tal_reg can be added in a later run.
• tools/compare_subjects.py compares two subject directories by content (voxels, vertices, transforms,
  statistics) and reports how large each difference is.
• --extra_slurm_options for srun_fastsurfer.sh (#853).
• Better logs: warnings and tracebacks now reach the log file, not only the terminal.
• Documentation: an installation guide with one page per system, the macOS package first (#935); a page for
  every module, with what it computes, needs and outputs; a command reference sorted into running modules,
  utilities and training, now including recon-surfreg.sh, conform.py and compare_subjects.py (#939, #940);
  consistent, copyable examples with Docker tags that exist and native installation with uv (#918); and Colab
  tutorials that install cleanly again (#922).

Changes that affect results

Compared with 2.5.4, expect small differences from:

• PyTorch 2.14 and, on GPU, CUDA 13 (#919); on Apple silicon also because max_unpool2d, the one operation PyTorch
  2.7 ran on the CPU, now runs on the GPU too;
• the new cortical ribbon: a few hundred voxels near the medial wall lie inside both hemispheres, and instead of
  giving all of them to the left like mris_volmask, FastSurfer gives each to the hemisphere it lies deeper inside.
  This avoid bias and changes a few voxels at the midline in ribbon.mgz and the aseg family and the statistics by at
  most 0.02%; surfaces are unchanged (touch/cortical_ribbon.touch is no longer written);
• CerebNet using the current released model (#876), with its statistics measured on the segmentation grid (#898);
• the WM filling no longer running its MTL path step, matching FreeSurfer (#889);
• the pinned spherical projection, to avoid small shifts in the surfaces;
• the CorpusCallosum networks now honouring --threads;
• a new default thread count (auto) to better use existing hardware if nothing is specified;
• consistent data types (aseg uchar, probabilities float) and the fov header field being set;
• the volumes made from the bias corrected image keeping the exact centre of orig.mgz (a header shift of about
  3e-6 mm, #927);
• on macOS, the native arm64 FreeSurfer, by floating-point noise (#926);
• BrainSegVol-to-eTIV in the withCC statistics being computed from the recomputed BrainSeg (#897);
• the StdDev of the merged labels in cerebellum.CerebNet.stats, which left out the spread between the merged labels
  and was too small (#934);
• lesion inpainting with neurolit 0.7.0, which uses a faster sampler inside the lesion (#869).

Bug fixes

• A failed step no longer reports success, and 14 error messages in run_fastsurfer.sh that could never print now
  do.
• srun_fastsurfer.sh completes a run on a cluster: it uses the GPU Slurm assigned and works with Slurm 22.05 and
  later (#911), and --cpu_only runs get a time limit sized for the cpu (#915), both by Karl Koschutnig.
• Freeview no longer warns that the volume info of the surfaces and the talairach transform is inconsistent
  (#927, reported in #855).
• docker run --user with a user the image does not know no longer fails when a Python dependency asks for the
  user name (#931).
• segstats.py: --robust works again (it kept at most one voxel), and merged labels get the correct mean and
  StdDev; mri_segstats.py --robust now trims like FreeSurfer's mri_segstats (#934).
• --surf_only on a subject processed with --lesion_mask is refused again, also with neurolit 0.7.0 (#932).
• long_fastsurfer.sh checks for the FreeSurfer license before the template preparation instead of failing after
  the segmentation of every time point (#937).
• --hypo_segfile and --hypo_statsfile now take effect; --tal_reg works together with --no_biasfield.
• long_fastsurfer.sh no longer lowercases the arguments it passes on, explains a missing base registration, and
  points --seg_only/--surf_only users to the stages.
• A checkpoint download race on the first run is fixed (#844), and voxel sizes within float noise of 1mm are accepted.
• The version information in scripts/BUILD.log is no longer empty on systems with many Python packages, such as
  Colab (#923).
• Smaller fixes: silent logging in quick_qc, the callosum module and two data preparation scripts; the CC statistics
  written to the wrong file; VERSION=unknown from recon-surfreg.sh; brun_fastsurfer.sh losing options such as
  --py; and more.

Build and packaging

• UPX packing removed: some endpoint security software killed the packed binaries at launch, which looked like an
  out of memory error (#882, #883, #887).
• Updated dependencies, among them PyTorch 2.14, numpy 2.5, scipy 1.18, matplotlib 3.11 and neuroreg 0.12.
  requirements.txt is now generated from pyproject.toml for Linux and macOS in one step, and a Docker build whose
  dependency resolution fails now fails.
• The macOS app is a small AppleScript applet, with a proper icon and a single Terminal window (#912).

Testing and CI

The former quicktest is now pipelinetest: it runs the full pipeline on two subjects, grades each run green, yellow
or red against the reference, and pins the CPU instruction set so runs are comparable. Tests are grouped by what they
need, and bash 3.2 (macOS) is now covered. The Linux test and documentation jobs install the CPU build of PyTorch
(#935, #936), and the optional pre-commit hook runs the lint and unit tests in parallel (#929).

Furthermore as always, our full validation pipeline on multiple datasets with DICE, test-retest, significance testing is run
to make sure this version continues to works on real data and settings - like the ones you will be running it on.

Thanks to everyone for their contributions.

Full Changelog: https://github.com/Deep-MI/FastSurfer/compare/v2.5.34..v2.6.0