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-allruns, ported twice: a replica in the packagelarmorx-freesurfer, under FreeSurfer’s licence, and a clean room inlarmorx, 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) andrecon-allitself, 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_cmdlas a program of its own inlarmorx-nc) and a clean room inlarmorx. 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 inlarmorx-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
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, whichrecon-allruns 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-allagain. 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 |