Roadmap

FreeSurfer’s roadmap

How LARMORX ports FreeSurfer 8.2.0, step by step. Every program recon-all runs, in the order it runs them, the waves the work is done in, where each wave stands, and how each program is checked against FreeSurfer.

Last updated: 2026-11-18. FreeSurfer 8.2.0 is the step under way on the roadmap. Its statuses below change at every merge of its work; the plan behind them is in the repository’s FreeSurfer plan.

What this step delivers

  • Every program recon-all runs, ported twice: a replica in the package larmorx-freesurfer, under FreeSurfer’s licence, and a clean room in larmorx, under Apache-2.0, built for speed (FreeSurfer is the slowest part of fMRIPrep’s preprocessing). Each port is complete: every option, message, exit status and failure case, with the originals’ defects corrected by default and reproduced on request, as for every program on this site (Concepts).
  • Both of recon-all’s streams (below) and recon-all itself, in both ports.
  • The FreeSurfer programs fMRIPrep and sMRIPrep run outside recon-all (the list).
  • The code FreeSurfer borrows from other projects, each piece with a replica in the package of its own licence (GSL’s random-number generators in larmorx-gpl, tkregister2_cmdl as a program of its own in larmorx-nc) and a clean room in larmorx. Washington University’s Talairach tools get a clean room only: their terms do not allow a replica without the university’s written permission.
  • No licence key: FreeSurfer’s key is a check inside FreeSurfer’s own programs, which the ports do not need.
  • FreeSurfer’s data files (atlases, colour tables, the average subject fsaverage, the networks’ weights): those up to 2 MB shipped in larmorx-freesurfer, the larger ones (FreeSurfer’s atlases are about 650 MB) fetched on first use from FreeSurfer’s own public store and checked by their SHA-256, or read from a FreeSurfer installation (FREESURFER_HOME). A list of every file, with its licence, comes with the foundations.

Two streams

recon-all 8.2.0 runs, by default, the v8 stream: the brain mask by SynthStrip, the brain’s labels by SynthSeg and the registration by SynthMorph, three neural networks, with several new correction steps. Its -no-v8 flag gives the classic stream, what fMRIPrep 25’s FreeSurfer 7.3.2 runs: the watershed skull strip, the Talairach registration, the atlas’ subcortical labels. Most programs, every surface step among them, belong to both streams. The work goes in that order: the programs both streams run first, then the classic stream’s own, with the v8 stream’s networks as a track of their own beside them. FreeSurfer 7.3.2 is not ported; the final comparisons with fMRIPrep use it as a reference.

Where it stands

Wave Pieces of work: replica / clean room Replica Clean room
3.0 Preparation – done 2026-11-12 one step for both
3.1 Foundations 52 / 8 done 2026-11-18 in progress 2026-11-13
3.2 Volumes 41 / 30 in progress 2026-11-18 in progress 2026-11-19
3.3 Atlas 17 / 4 planned planned
3.4 First surfaces 33 / 16 planned planned
3.5 Final surfaces and statistics 37 / 29 planned planned
3.6 The classic-only programs 21 / 7 planned planned
N The v8 networks 15 / 14 planned planned
3.7 recon-all 13 / 8 planned planned

In all, 229 pieces of work for the replicas and 129 for the clean rooms (13 of them the clean rooms of the borrowed permissive code, which come after FreeSurfer with the other permissive ports’ clean rooms), about 309,000 lines of FreeSurfer’s functions to follow, 90,000 of them the foundations (upper bounds: every line the programs can reach). The clean rooms follow one wave behind the replicas, written separately from descriptions of the programs’ behaviour and from runs of FreeSurfer, never from its source. “Done” means its part’s tests pass and it is merged; the extensive evidence comes in the final validation phase.

recon-all’s steps, in order

recon-all -all runs three parts: autorecon1, from the T1-weighted image to the brain without the skull; autorecon2, from the atlas registration to the white surface; autorecon3, from the sphere to the parcellations and the statistics. The steps on surfaces run for the left hemisphere, then for the right. Each step is named as recon-all’s log names it where it has a name; a program that a step’s script runs inside it is listed in its wave. Stream: both, or only the v8 or the classic stream. Wave: the wave its port belongs to.

Before the first step

Step Programs What it does Stream Wave
Configuration and checks rca-config, rca-config2csh, fsr-getxopts, fs-check-version, fs-check-os Reads recon-all’s configuration and expert options, checks FreeSurfer’s version and the operating system. both 3.7, 3.5

autorecon1

Step Programs What it does Stream Wave
Input mri_convert, mri_info Converts the T1-weighted image into FreeSurfer’s MGZ format. both 3.2
Motion correction (MotionCor) mri_robust_template, mri_convert, mri_add_xform_to_header, lta_convert Averages the T1-weighted images into one when there are several, resamples it to FreeSurfer’s conformed grid (256 × 256 × 256 voxels of 1 mm) and writes the transform between the two. both 3.2
Brain mask by network mri_synthstrip SynthStrip, a neural network, draws the brain mask. v8 N
Labels by network mri_synthseg, csvprint SynthSeg, a neural network, labels the brain’s structures and measures their volumes, the intracranial volume among them. v8 N
Talairach mri_nu_correct.mni, talairach_avi, lta_convert Corrects the intensity bias, then registers the head to the MNI305 atlas with an affine transform. classic 3.2, 3.6
Talairach failure detection talairach_afd, extract_talairach_avi_QA.awk Checks the transform against those of known good registrations. After a failure the registration runs again with another atlas, and after a second one with MINC’s talairach (later). classic 3.6
Talairach, by the v8 stream rca-talairach Registers the head to the MNI305 atlas, from the network’s brain mask. v8 N
Registration by network fs-synthmorph-reg SynthMorph, a neural network, registers the head to the MNI152 template, nonlinearly. v8 N
Intensity correction (Nu Intensity Correction) mri_nu_correct.mni with ITK’s N4 (AntsN4BiasFieldCorrectionFs), mri_add_xform_to_header Removes the slow change of intensity across the image that the scanner’s coils cause (N4) and rescales the image to 8 bits (nu.mgz). both 3.2
Intensity normalization mri_normalize Scales the intensities so that white matter is 110 everywhere (T1.mgz). both 3.2
Dura and venous sinuses mri_mcadura_seg, mri_vsinus_seg Neural networks label parts of the dura (mca-dura.mgz) and the venous sinuses (vsinus.mgz), so that the surfaces later stay out of them. v8 N
Skull stripping, by the v8 stream mri_mask Applies the network’s brain mask to the normalised image (brainmask.mgz). v8 3.2
Skull stripping mri_em_register, mri_watershed Registers the head to an atlas that includes the skull, then strips the skull with the watershed method, guided by that atlas (brainmask.mgz). classic 3.3, 3.6

autorecon2

Step Programs What it does Stream Wave
EM registration mri_em_register Registers the brain to FreeSurfer’s probabilistic atlas of brain structures, with an affine transform. both 3.3
CA normalize mri_ca_normalize Normalises the intensities again, with the intensity the atlas expects of each structure (norm.mgz). both 3.3
CA registration mri_ca_register Registers the brain to the atlas nonlinearly. classic 3.3
Entorhinal white matter mri_entowm_seg A neural network labels the white matter near the entorhinal cortex, which the next steps use to correct the white matter there. v8 N
Subcortical segmentation mri_ca_label Labels the subcortical structures from the atlas and the registration (aseg). classic 3.6
Corpus callosum seg2cc, mri_cc Labels the corpus callosum in the segmentation. both 3.2
Intensity normalization 2 mri_normalize Normalises the intensities once more, with the segmentation (brain.mgz). both 3.2
Mask for the surfaces mri_mask, mri_edit_wm_with_aseg Masks the brain for the surfaces’ placement; in the v8 stream also masks out the dura and the venous sinuses. both 3.2
White-matter segmentation AntsDenoiseImageFs, mri_segment, mri_edit_wm_with_aseg, mri_pretess Denoises the brain (ITK’s non-local means), labels the white matter by its intensity and corrects that label with the segmentation (wm.mgz). both 3.2
Fill mri_fill Separates the two hemispheres and cuts away the brainstem and the cerebellum (filled.mgz). both 3.2
Tessellation mri_pretess, mri_tessellate, mris_extract_main_component Turns each hemisphere’s filled volume into a first surface of triangles, kept to its largest piece. both 3.4
Smoothing, inflation, quick sphere mris_smooth, mris_inflate, mris_sphere Smooths that surface, inflates it and maps it quickly onto a sphere, for the topology fix. both 3.4
Topology fix mris_fix_topology, mris_euler_number, mris_topo_fixer, defect2seg, mris_remesh, mris_remove_intersection Removes the surface’s holes and handles so that it has a sphere’s topology (mris_topo_fixer only where a defect remains), records the defects as a volume, remeshes the surface into regular triangles and removes the places where it crosses itself. both 3.4
Grey and white intensities mris_autodet_gwstats Measures the intensities of grey and white matter near the surface. both 3.5
White surface, first placement mris_place_surface Moves the surface to the boundary between white and grey matter. both 3.5
Cortex label label-cortex, mri_label2label Labels the cortex on the surface, without and with the hippocampus and the amygdala. both 3.5, 3.4
Smoothing, inflation, curvature mris_smooth, mris_inflate, mris_curvature Smooths and inflates the white surface again (with the depth of the sulci) and computes its curvatures. both 3.4, 3.5

autorecon3

Step Programs What it does Stream Wave
Sphere mris_sphere Maps the inflated surface onto a sphere. both 3.4
Surface registration rca-surfreg, mris_register Registers the sphere to FreeSurfer’s atlas of cortical folding. both 3.5
Jacobian and average curvature mris_jacobian, mrisp_paint Measures how much the registration stretches the surface, and maps the atlas’ average curvature onto it. both 3.5
Cortical parcellation mris_ca_label Divides the cortex into regions from the atlas (Desikan-Killiany). both 3.5
White and pial surfaces mris_place_surface Places the final white surface and the pial surface, the outer boundary of the grey matter. both 3.5
Curvature, area, thickness, volume mris_place_surface, vertexvol, mris_curvature_stats Computes the curvature, area, thickness and volume at every vertex, and the curvatures’ statistics. both 3.5
Cortical ribbon mris_volmask Fills the volume between the white and pial surfaces (ribbon.mgz). both 3.5
Parcellations 2 and 3 mris_ca_label The Destrieux (a2009s) and DKT parcellations. both 3.5
White and grey contrast pctsurfcon Measures the contrast between white and grey matter along the surface. both 3.5
Hypointensities mri_relabel_hypointensities Labels hypointensities of the white matter, with the white surfaces. both 3.5
Segmentations from the surfaces mri_surf2volseg, mri_brainvol_stats Corrects the segmentation with the surfaces (aseg.mgz), labels the cortex and the white matter by region (aparc+aseg.mgz, its two variants and wmparc.mgz) and measures the brain’s volumes. both 3.5
Statistics mri_segstats, mris_anatomical_stats Writes the statistics of every structure and every cortical region (aseg.stats, wmparc.stats, the parcellations’ statistics). both 3.2, 3.5
Brodmann areas mri_label2label, mris_label2annot, mris_anatomical_stats Maps the Brodmann areas and other labels of FreeSurfer’s average subject (fsaverage) onto the subject, with their statistics. both 3.4, 3.5

fMRIPrep’s programs outside recon-all

fMRIPrep and sMRIPrep run these FreeSurfer programs themselves. They belong to no stream and come with the waves their code belongs to, the volume ones early.

Program What fMRIPrep does with it Wave
mri_coreg Registers the BOLD reference to the T1-weighted image: the start of the boundary-based registration. 3.2
mri_robust_template, mri_robust_register Average several T1-weighted images into one, and register two images robustly. 3.2
mri_vol2vol, lta_convert Resample a volume through a transform, and convert transform files between formats. 3.2
bbregister, with mri_segreg and tkregister2_cmdl Registers the BOLD reference to the white surface by the contrast across it (boundary-based registration). 3.5
mri_vol2surf, mri_surf2surf Sample a volume onto a surface, and resample data from one surface to another (fsaverage, fsnative). 3.5
mris_convert, mris_expand Convert surfaces to GIFTI, and make the mid-thickness surface. 3.5

The waves

Each wave delivers its programs complete: the replica first, its clean room one wave behind. A wave’s pieces of work appear below with their own status as they begin.

3.0 Preparation

The map of the work, before any port: every program the two streams and fMRIPrep run, measured on FreeSurfer’s own runs; the order of the waves and the list of their pieces of work; FreeSurfer’s reference runs, every step recorded; the replay tool that tests a port on those recordings; the list of FreeSurfer’s data files and their licences.

Status
done 2026-11-12

3.1 Foundations

FreeSurfer’s shared library, on which every program stands: its file formats, its volume and surface structures, its mathematics, its random numbers and its messages; the 80-bit arithmetic of x86 processors that FreeSurfer’s long-double numbers use; the routines it borrows from other projects; and a build of FreeSurfer’s own library that checks these pieces function by function.

Replica
done 2026-11-18 Complete (2026-11-18), but for the pieces that belong to later waves: the B-splines (wave 3.2), DICOM series (wave 3.7) and the surface pieces of wave 3.4 (the realm trees, the parameterisation, the deformation’s integration parameters). One function of the C library, the double arc cosine, stays correctly rounded in both modes, as decided for FSL: it differs from FreeSurfer’s glibc in the last bit for about 0.05 % of arguments.
Clean room
in progress 2026-11-13 The core, the random numbers, the C library’s sort, the cubic spline, the mathematics and the volume structure done; the first seven parts of the volumes (the geometry block, voxel arithmetic, coordinates and orientation, the samplers, the moves, the head’s box, the transform reader, the label tests, the brain-volume cache, resolution, planes, flood fills, whole-factor resampling, changes of type, frame samplers and splatting, derivatives and gradients, linear transforms, resampling onto a template’s grid, value replacement, and since 2026-11-19 the statistics and their print, the type names, the box crop, orientation strings and the voxel-to-world matrices) written from their specification, their cubic B-spline paths through the B-splines’ clean room (wave 3.2): on the open probe’s 13,346 calls (30 groups, the B-splines’ included), no difference from FreeSurfer that a recorded defect does not explain in fix mode; in reproduce mode 2 lines differ, both B-spline transforms given in physical-voxel coordinates, which need a conversion whose specification part is not ready yet (for now they stop with an error saying so); the two values FreeSurfer reads from memory it never wrote (FS-300, FS-325), found the same on every run by the specification’s writer, now count as explained; its trilinear, cubic and nearest-neighbour samplers 1.2 to 1.5 times as fast as FreeSurfer’s (the windowed sinc 0.75 times, for now), its flood fill 2.3 times as fast on 64-voxel cubes, the sixth part’s other functions 0.85 to 1.4 times; the rest of the volumes, the volume files and the surface files follow as their specifications are made ready.
Size
52 pieces of work for the replica, 8 for the clean room
Part What it holds Replica Clean room
FreeSurfer’s library, checked function by function FreeSurfer 8.2.0’s library built as the official release was built (the same compiler, GCC 8.4.0, and the same options), so that each piece of the foundations is compared with FreeSurfer’s own functions. A tool for the checks, not a port. done 2026-11-12 none
Numerical routines from other projects VXL’s and netlib’s routines FreeSurfer calls (minimisers, matrix decompositions), with the not-a-number values of x86-64 processors on every platform; the 80-bit arithmetic of x86 processors. Their clean rooms come with the clean rooms of the permissive ports, after FreeSurfer. done 2026-11-13 planned
Random numbers and the C library’s sort RANLUX with GSL’s distributions, VXL’s generator, drand48 and the C library’s rand and random; the C library’s sort, whose order of equal items FreeSurfer’s results depend on. GSL’s generators as a replica in larmorx-gpl, alone; the C library’s functions as clean rooms only, written from a description of their behaviour (its code is not translated). done 2026-11-13 done 2026-11-13
The cubic spline John Burkardt’s cubic spline (2006), which mri_normalize uses. done 2026-11-13 done 2026-11-13
File formats from other projects GIFTI surfaces, MINC’s .xfm transforms, DICOM’s file probe (CTN’s reader), JSON and zip compression (miniz), NRRD files (NrrdIO’s reader), MINC volumes, zlib’s compression, TIFF and JPEG images. Done: GIFTI surfaces, MINC’s .xfm transforms, the DICOM probe, JSON and zip compression, NRRD files (identical to NrrdIO and to FreeSurfer’s copy of it on 69,500 generated files) and reading MINC volumes (identical to MINC 1.5.1 and to FreeSurfer’s copy on about 37,500 generated files; larmorx also reads the double-precision and compressed MINC files that FreeSurfer 8.2.0 cannot). Writing MINC volumes is done too (identical to MINC 1.5.1 and to FreeSurfer’s copy in 17,433 comparisons; larmorx also writes the 4-D volumes FreeSurfer’s copy cannot), and zlib’s compression as FreeSurfer’s programs load it (byte-identical on 100,300 test streams; larmorx’s MGZ, .nii.gz and GIFTI files now match FreeSurfer’s byte for byte, not only in their contents). JPEG images (IJG libjpeg 6b: identical to it and to FreeSurfer’s copy on 26,526 test files). TIFF images (libtiff 3.6.1, as FreeSurfer builds it): reading identical to it and to FreeSurfer’s copy on 20,000 of 25,000 generated files; of the other 5,000, the original crashed or hung on about 2,050 and gave results that depend on memory contents on about 550 (larmorx names each case), and about 2,400 used five rarer compressions then not yet ported; writing byte-identical on 5,300 files. Those five compressions (CCITT fax, PixarLog, SGILog, ThunderScan, NeXT) are now ported too, so larmorx reads every compression FreeSurfer’s copy reads: on 21,000 further generated files covering all of them, 0 differ, and 1,000 more written files are byte-identical. Two defects found in them change results on valid images (the word alignment of one fax compression, and a size overflow that makes every SGILog image stored without a RowsPerStrip tag fail to read); larmorx corrects both by default and reproduces them on request. CTN’s DICOM element reading is done too (identical to CTN 3.0.6 and to FreeSurfer’s copy on 10,038 generated files). The reads into no buffer behave as libtiff’s do too (27,000 probe reads, 0 differing), which completes the replica of this part. Their clean rooms come with the clean rooms of the permissive ports, after FreeSurfer. done 2026-11-17 planned
The core Messages and diagnostics, the program’s name and environment, version stamps, timers, paths, threads, the licence check’s messages. done 2026-11-13 done 2026-11-13
The mathematics Matrices in single and extended precision, the numerical routines and optimisers, histograms, statistics, probability distributions, random fields. done 2026-11-13 done 2026-11-13
The volume structure FreeSurfer’s volume in memory, its geometry, and the linear transform files (LTA). done 2026-11-13 done 2026-11-13
Volume files Reading and writing volumes (MGH and MGZ, NIfTI, ANALYZE, DICOM and others), FreeSurfer’s tags, the binary colour tables, the detection of a file’s format. Done: MRIread, the entry through which every FreeSurfer program reads a volume, volume reordering (mri_convert’s -r; FreeSurfer crashes on some huge values through a 32-bit overflow, larmorx refuses them with FreeSurfer’s message) (a damaged header asking for an impossible number of frames is refused at once, as FreeSurfer does), the tags, the colour tables, the format detection, the DICOM probe, Siemens mosaics, MATLAB and Bruker files, 2-D images, reading a volume’s header, GIFTI volumes, writing volumes, the MGH/MGZ writer, NIfTI files (.nii, .nii.gz and the .hdr/.img pairs) read and written, ANALYZE, COR, bshort and bfloat, GDF and SDT volumes, GE Genesis and LX (which FreeSurfer 8.2.0 itself cannot read: larmorx reads them, and reproduces the crash on request), GE Signa and XIMG, the old Siemens .ima series, AFNI datasets, curvature and annotation files read as volumes, image files (MATLAB, SGI and HIPS) read and written as volumes, ITK warp files written, NRRD files read as volumes (FreeSurfer misplaces some of them in space: larmorx places them correctly by default and reproduces FreeSurfer’s placement on request), FreeSurfer’s probabilistic atlases (GCA files) read as volumes (identical voxel for voxel to FreeSurfer’s own mri_convert on its four atlases, a little faster and with less memory), MINC files read and written as volumes (FreeSurfer’s writer loses some integer volumes and NaN-led ranges: larmorx writes them correctly by default and reproduces FreeSurfer on request), FreeSurfer’s refusals to write AFNI and NRRD files, FreeSurfer’s way of reading a number cut short at the end of a file, and the atlas warps (.m3z files) read as volumes (the warps of six recorded heads: 108 of 108 volumes identical to FreeSurfer’s) and written (those six warps read and written again: 30 of 30 outputs identical to FreeSurfer’s), warp maps converted between formats when written, and JPEG and TIFF images read and written as volumes (the image readers and writers, TIFF included: identical to FreeSurfer on all 1,744 compared cases of 2,400 generated ones), and FreeSurfer’s autoencoder files (.ae, .sae, .csae) read as volumes. Where FreeSurfer’s readers leave memory it never wrote in a volume (fields of damaged .mgz files, the geometry of a warp read without it), larmorx writes defined values and says so; where that memory is predictable (the .mgz reader keeps the previous number’s bytes), it reproduces FreeSurfer’s values on request. Still to do: DICOM series as volumes, planned with the completeness work (DICOM’s element reading is done). done 2026-11-18 planned
Volumes Voxels and frames, conforming, regions, resampling, transforms (LTA, .xfm, FSL’s matrices), the Talairach helpers, warp fields. Done: the volume geometry, voxel arithmetic, coordinates, samplers, moves and rotations, the head’s bounding box, reading transforms, the CMA labels, resizing and type changes, splatting, derivatives, the linear transforms and their operations (inverse, concatenation, change of type), their writers in every format FreeSurfer writes (.lta, MINC’s .xfm, register.dat, FSL’s matrices), applying them to volumes and points, the rotation and affine-parameter helpers, the voxel lists, resampling to another volume, statistics and orientation, the volume fractions, PCA, the Talairach helpers and volumes, conforming, dilations and set operations, histograms, segmentations mapped onto volumes, segment statistics, crops, and the rest of FreeSurfer’s general volume functions (volume-to-volume filling, the topology-preserving erosion and dilation, the subcortical mass fix, binary morphology), and FreeSurfer’s general transform, a linear transform or an atlas warp (reading, writing, copying, inversion, sampling, composition, concatenation, the voxel and RAS conversions, and resampling a volume through it, linear or an atlas warp, in both directions). FreeSurfer lays every row of a tensor volume over its first row in the functions that walk a volume directly; larmorx gives each row its own place by default and reproduces FreeSurfer’s layout on request. Left for the surface waves: the volume functions that need the surfaces. done 2026-11-18 in progress 2026-11-17
Surface files The surface structure and its files: surfaces, curvatures, patches and overlays, and the measures computed when a surface is read. Done: the surface readers and writers (curvature, patches, STL, triangle and quadrangle files, GIFTI), the curvature files in every format FreeSurfer writes (48 of 48 recorded files identical), value files, patches, normals, vertex positions and annotations read and written (60 of 60 recorded files identical), reading whole surfaces, the surface measures (normals, cortical thickness, curvatures), the quality statistics recon-all prints, and the surface-to-volume functions (a surface’s interior filled into a volume, the cortical ribbon, bounding volumes: identical to FreeSurfer on 24 of 24 volumes of three recorded heads, and faster than FreeSurfer: 38 s against 55 s), surfaces turned into masks and the laminar volume fractions (identical to FreeSurfer on generated surfaces), the Talairach coordinates of surface points, the vertex-to-voxel conversions, the distributions of normals and curvatures and the triangle energy (6 of 6 recorded heads identical), a surface’s values written into a volume and value files, the copies between vertex fields, and the area, distance and mark files (recon-all’s area files of 3 recorded heads written byte for byte, 12 of 12), the surface hash table and the triangle tests that find where a surface crosses itself, and the filling of holes on a surface (56 of 60 runs on recorded surfaces identical to FreeSurfer; on the other 4 FreeSurfer itself crashes, and larmorx finishes), and the surface marks, the value filters (average, median, Gaussian, mode, soap bubble) and the distance sampling the spherical registration uses (no difference from FreeSurfer in 2,000 generated cases), and the rest of the surface values: excluding and restoring regions, growing and shrinking marked regions, the annotation filter and disks of a given radius (78 of 78 runs on recorded heads identical to FreeSurfer in the reproduce mode; by default larmorx also finds the disks beyond about 40 mm that FreeSurfer’s binarize step refuses), the surface’s topology (Euler numbers, edge and neighbour edits, removing excluded vertices, renumbering: the Euler numbers of the six recorded heads as recon-all’s, 24 of 24 recorded runs identical in the reproduce mode) and the soap-bubble smoothings (12 of 12 recorded runs identical in both modes). When FreeSurfer removes excluded vertices it leaves the other vertices’ neighbour lists stale, which happens every time recon-all cuts away what lies outside the cortex label; larmorx corrects it by default and reproduces it on request. Then the closest-vertex and closest-face searches and the sphere, cylinder and ellipsoid projections (6 of 6 recorded runs identical for each, in both modes), projecting a surface onto another and flattening a patch, removing a surface’s self-intersections, and a surface’s distance into a volume (54 of 60 recorded runs identical in both modes; on the other 6 FreeSurfer itself crashes, and larmorx finishes). Also done: reading patches, the sampled energies and the triangle overlaps (6 of 6 recorded runs identical in both modes), and moving a surface through FreeSurfer’s general transform (108 of 108 recorded cases identical in both modes). Left for wave 3.4: the pieces that need its modules (the realm trees, the parameterisation, the deformation’s integration parameters). done 2026-11-18 planned
Labels Colour tables, annotations, labels, register.dat files, control points, point sets. Done: colour tables, registration files, labels, annotations, control points, point sets, the label coordinate conversions, the removal of overlapping labels, and labels on surfaces: marking, area, filling, erosion and dilation, inversion, masks (24 of 24 recorded labels identical), and the removal of holes and islands from surface labels, on FreeSurfer’s surface clusters ported whole (36 of 36 comparisons on recorded heads identical). FreeSurfer’s cluster growth crashes once it nests about 104,000 levels deep; whole recorded hemispheres reach about 87,000, so only denser surfaces would crash. larmorx grows every cluster in full and says so when FreeSurfer would have crashed. Flattening a label and cutting away what lies outside it are done too (24 of 24 recorded runs identical in the reproduce mode). done 2026-11-18 planned
Volume filters Filters and morphology, intensity normalisation, segmentation helpers, flood fill, connected components, fast marching, clusters. Done: the distance maps (fast marching), Gaussian smoothing and convolutions, Sobel filters, the white-matter border classification, connected components, the frame functions, clusters, the non-parametric tissue classification, connected segments, the flood fill of volumes, the bias fields, the intensity normalisation of recon-all’s T1 step (identical to FreeSurfer on three recorded heads, and now faster than FreeSurfer with the same output: 69 s against 126 s for the normalisation’s nine runs on three recorded heads), the high-signal control points of mri_normalize’s -snr option, and the mask from a T2 image and the aparc+aseg segmentation (identical to FreeSurfer on 5 of 6 recorded volumes; on the sixth FreeSurfer itself crashes). More speed work comes with the programs that use these filters. done 2026-11-18 planned

3.2 Volumes

The volume programs both streams run, from the input image to the white-matter volume, with ITK’s N4 bias correction and denoising as FreeSurfer builds them; and fMRIPrep’s own volume programs early (mri_coreg, mri_robust_template, mri_robust_register), with EPFL’s B-splines and the robust-registration library as pieces of their own; the freesurfer family of the larmorx command and lx.freesurfer in Python.

Replica
in progress 2026-11-18 Started 2026-11-18, one program or library piece at a time: first EPFL’s B-splines, which many of the wave’s programs use; next the intensity normalisation (mri_normalize, complete 2026-11-19), the format converter (mri_convert) and the robust-registration library.
Clean room
in progress 2026-11-19 Started 2026-11-19 with EPFL’s B-splines, written from their specification alone; the programs follow as their specifications are made ready.
Size
41 pieces of work for the replica, 30 for the clean room
Programs
mri_convert, mri_info, mri_add_xform_to_header, lta_convert, mri_robust_template, mri_normalize, mri_mask, mri_cc, mri_edit_wm_with_aseg, AntsDenoiseImageFs, AntsN4BiasFieldCorrectionFs, mri_segment, mri_pretess, mri_fill, mri_binarize, mri_segstats, mris_calc, mri_make_uchar, mri_vol2vol, mri_concat, mri_label2vol, mri_robust_register, mri_coreg, fs_temp_file, mri_nu_correct.mni, seg2cc, mergeseg, getfullpath
Part What it holds Replica Clean room
EPFL’s B-splines Cubic and higher-degree B-spline coefficients, sampling, transforms and the halving and doubling pyramids that FreeSurfer’s resampling and robust registration use. Every degree from 2 to 9. Checked against FreeSurfer’s own library build with the volume probe’s 28,600 random calls (every volume function, the B-splines’ new calls included) in reproduce mode: 26,580 identical, 0 different, the other 2,020 not comparable (calls on which FreeSurfer crashes or never returns). Computing the coefficients of a 256-voxel cube takes 0.54 s against FreeSurfer’s 0.52 s with 2 to 3 % less memory; transforming a 128-voxel cube is still slower (0.49 s against 0.35 s), for a later speed step. Four new defects of FreeSurfer recorded (FS-962 to FS-965). Its clean room (2026-11-19), written from the specification alone: the coefficients, sampling at every degree, the three transforms and both pyramids; on the open probe’s B-spline calls no difference that a recorded defect does not explain in fix mode, and in reproduce mode 2 lines still open (transforms given in physical-voxel coordinates, whose conversion is not yet specified); as fast as FreeSurfer’s or up to 1.4 times faster (a 128-voxel cube’s coefficients in 0.052 s against 0.063 to 0.067 s, at one thread). done 2026-11-18 in progress 2026-11-19
mri_normalize The intensity normalisation of recon-all’s T1 and brain steps: white matter scaled to 110, with control points, a brain mask from the atlas, and the white-matter outliers near the segmentation removed. Complete. recon-all’s 24 recorded steps in 12 runs (six subjects, the classic and v8 streams) replayed: outputs identical to the recorded ones in both modes (24 of 24). The whole program against FreeSurfer’s official program on 82 command lines covering every option and failure, two seeds: 0 different in reproduce mode (58 and 59 identical; the others counted apart: not comparable, where FreeSurfer crashes or reads memory it does not own, or differing only in FreeSurfer’s error text after a failed file open, a known difference not yet modelled). Its parts were checked earlier against FreeSurfer’s own code built as a library (900 random calls, no difference). Peak memory 566 MiB against FreeSurfer’s 570 MiB on the T1 step and 1,173 MiB on the brain step. Still slower: 79 s against FreeSurfer’s 66 s on three recorded subjects’ 12 steps; the time goes to per-voxel reads and writes, for a later speed step. One new defect of FreeSurfer (FS-1017: it crashes when a step gives it no volume; larmorx stops with a clear error). done 2026-11-19 planned
mri_convert The format converter both streams start with: reading and writing every volume format, conforming to 256 cubed, changing type, resampling and reorienting, and its statistics tables. Parts 1 and 2 (of 4) done: the statistics tables, every option’s parsing and checks, and the whole conversion (reading, header changes, transforms, type changes, reslicing, reorienting, cropping and writing); it runs as the larmorx-freesurfer program mri_convert. Checked against FreeSurfer’s program built with print hooks, in reproduce mode: the options, every setting compared, on 1,000 random command lines: 947 identical, 0 different, 53 not comparable (FreeSurfer crashes or reads memory it does not own); whole conversions, every written file compared, on 1,200 random command lines of two seeds: 1,137 identical, 0 different, 63 not comparable, and the 8 conformed conversions identical (a third seed’s 1,000: 3 differ, all where FreeSurfer crashes or runs past the probe’s time and memory limits). Eleven new defects of FreeSurfer recorded (FS-1043 to FS-1053); none changes a result of recon-all’s or fMRIPrep’s calls (one is a line their logs print, which larmorx prints with a defined value). The outline reader (.otl files) follows, then the replay of its 24 recorded steps and fMRIPrep’s calls. in progress 2026-11-18 planned
The robust-registration library Reuter’s robust registration, shared by mri_robust_register and mri_robust_template (both run by fMRIPrep): image scaling, subsampling, blurring and gradients, principal axes, matrix decompositions and transform distances, then the registration itself. Part 1 of 2 done (2026-11-20): the helpers both programs reach, with the matrix square root, which the default symmetric registration takes at every step. Checked against FreeSurfer’s own files built with its flags: 16,100 random calls, 15,737 identical, 0 different, 363 not comparable (FreeSurfer crashes, hangs or reads memory it does not own); the square root and its complex Schur form (reference LAPACK’s, as FreeSurfer’s build links it) on 10,200 random matrices: 10,061 identical in reproduce mode, its error messages byte for byte, 0 different, 139 not yet ported (matrices holding a NaN or an infinity, which a registration never makes), and 2.7 times as fast as FreeSurfer’s (200,000 square roots of 4-by-4 transforms in 0.27 s against 0.73 s). Inside it the complex absolute value and square root take the correctly rounded hypotenuse in both modes, as decided for the confounds; whether FreeSurfer’s own last bits would change a registration is measured at the programs’ replays. After a fix of the foundations’ filter (2026-11-19) the gradients are faster than FreeSurfer’s (0.58 s against 0.81 s on a 256-voxel cube) and the blur 1.7 times slower (0.66 s against 0.39 s), both with slightly less memory than FreeSurfer’s; the blur’s remaining time is a frame copy in the volume library, for a later speed step. Five new defects of FreeSurfer recorded (FS-966 to FS-970). Part 2, the registration itself, follows. in progress 2026-11-18 planned

3.3 Atlas

The programs that register a head to FreeSurfer’s probabilistic atlas and normalise its intensities with it, which both streams run.

Replica
planned
Clean room
planned
Size
17 pieces of work for the replica, 4 for the clean room
Programs
mri_em_register, mri_ca_normalize, mri_ca_register

3.4 First surfaces

From the filled white-matter volume to the first surface of each hemisphere with a sphere’s topology: tessellation, smoothing, inflation, the quick sphere, the topology fix, remeshing.

Replica
planned
Clean room
planned
Size
33 pieces of work for the replica, 16 for the clean room
Programs
mri_label2label, mri_tessellate, mris_extract_main_component, mris_smooth, mris_inflate, mris_sphere, mris_fix_topology, mris_euler_number, mris_topo_fixer, mris_remesh, mris_remove_intersection, mris_defects_pointset, defect2seg

3.5 Final surfaces and statistics

The white and pial surfaces, the surface registration to the folding atlas, the parcellations, the segmentations made from the surfaces and every statistics file; fMRIPrep’s surface programs and bbregister, with tkregister2_cmdl (its replica in larmorx-nc, as a program of its own).

Replica
planned
Clean room
planned
Size
37 pieces of work for the replica, 29 for the clean room
Programs
mri_relabel_hypointensities, mri_surf2volseg, mri_brainvol_stats, mri_vol2surf, mri_cor2label, mris_autodet_gwstats, mris_place_surface, mris_curvature, mris_register, mris_jacobian, mrisp_paint, mris_ca_label, mris_curvature_stats, mris_volmask, mris_anatomical_stats, mris_label2annot, mris_convert, mri_surf2surf, mris_expand, mri_segreg, tkregister2_cmdl, label-cortex, fscalc, mri_mergelabels, rca-surfreg, vertexvol, pctsurfcon, bbregister, fsr-getxopts

3.6 The classic-only programs

What only the classic stream runs, fMRIPrep’s FreeSurfer: the watershed skull strip, the Talairach registration and its check, the atlas’ subcortical labels. Washington University’s Talairach tools (talairach_avi with mpr2mni305 and the four 4dfp programs) get a clean room only, their atlas fetched from FreeSurfer on first use.

Replica
planned
Clean room
planned
Size
21 pieces of work for the replica, 7 for the clean room
Programs
mri_watershed, mri_ca_label, talairach_afd, mri_matrix_multiply, fs_temp_dir, analyzeto4dfp, gauss_4dfp, imgreg_4dfp, compute_vox2vox, talairach_avi, mpr2mni305, avi2talxfm, extract_talairach_avi_QA.awk

N The v8 networks

The neural networks of the v8 stream, run in Rust with FreeSurfer’s own trained weights: the inference core, SynthStrip, SynthSeg, SynthMorph and the limbic segmentation (three models), the scripts around them and the programs only those scripts run. A track of its own, beside waves 3.2 to 3.5; its scripts wait for 3.3.

Replica
planned
Clean room
planned
Size
15 pieces of work for the replica, 14 for the clean room
Programs
mri_synthstrip, mri_synthseg, mri_synthmorph, mri_sclimbic_seg, rca-talairach, fs-synthmorph-reg, mri_mcadura_seg, mri_vsinus_seg, mri_entowm_seg, csvprint, mri_concatenate_lta, mri_warp_convert, mri_diff, mri_compute_seg_overlap

3.7 recon-all

recon-all itself: its steps, flags, checks and logs, and the way it resumes a subject that sMRIPrep relies on.

Replica
planned
Clean room
planned
Size
13 pieces of work for the replica, 8 for the clean room
Programs
recon-all, rca-config, rca-config2csh, UpdateNeeded, fs-check-version, fs-check-os, fsr-checkxopts, mri_seg_diff

Later

Programs that no default path of either stream runs, ported after the waves:

  • nu_correct: MNI’s N3 bias correction, which recon-all runs only with -no-ants-n4.
  • talairach: MINC’s Talairach registration, which the classic stream runs only after its Talairach check has failed twice.

How each program is validated

Each program, replica and clean room, is checked in its own part, with the same depth as every port since 2026-10-28 (levels of testing):

  • The replay on every recorded head. For each step of FreeSurfer’s reference runs, a replay tool rebuilds the subject’s folder as it was before that step, runs the port there and compares what it writes with what FreeSurfer wrote, and with FreeSurfer’s same step run again at one thread. Its comparisons understand FreeSurfer’s files: MGZ volumes, surfaces, labels, annotations, transforms and the text files. So each program is tested on real heads without running recon-all again. The tool was proved on 68 recorded steps of both streams before any port.
  • The foundations, function by function, against FreeSurfer’s own library, built from 8.2.0 as the official release was.
  • Synthetic cases for every option, message and failure case.
  • Golden cases, so that the six platforms give the same results as Linux: volumes of at most 32 × 32 × 32 voxels, small synthetic surfaces.
  • The defects of FreeSurfer found on the way, each decided by the four rules (Concepts) and recorded in the repository’s register.
  • Its record, its memory near FreeSurfer’s (at most 10 % and 8 MiB more) and its pages on this site: a reference page and an evidence page.

The extensive evidence, the whole data panel, long random-testing runs and the comparisons with fMRIPrep, comes in the final validation phase.

The reference runs

FreeSurfer 8.2.0’s own package, run without changes on six heads of the data panel chosen for their variety: a healthy adult at 3 T (ds000005), an older adult at 1.5 T (ds002422), a child of 3.5 years (ds000228), a 7 T MP2RAGE image (ds005454), a glioma (ds005003) and an older adult with head motion (ds004173). Each is run in both streams with recon-all -all, its steps one after the other, and every step is recorded: its command line, its times and threads, its exit status, and every file it reads, writes and deletes, kept once by its SHA-256.

Runs What they are Status
Both streams at four threads The six heads, each in the v8 stream and in the classic stream (12 runs), at four threads, every step recorded: the files each port is compared with. done 2026-11-12
The classic stream at one thread The six heads again at one thread (6 runs): FreeSurfer’s own variation between thread counts. done 2026-11-13
The v8 stream at one thread, and the rest of the data panel On the lab’s server: complementary runs (the v8 stream at one thread, the other heads of the data panel, repeated runs), which no port waits for. in progress 2026-11-13