Co-registration of dissection photographs of coronal slabs into a 3D volume

For FreeSurfer 8.0 or development versions downloaded before May 2025, please see https://surfer.nmr.mgh.harvard.edu/fswiki/mri_3d_photo_recon_2024.

If you use this tools in your analysis, please cite:

* Machine learning of dissection photographs and surface scanning for quantitative 3D neuropathology. H Gazula, H Tregidgo, B Billot, Y Balbastre, J Williams Ramirez, R Herisse, LJ Deden-Binder, A Casamitjana, EJ Melief, CS Latimer, MD Kilgore, M Montine, E Robinson, E Blackburn, MS Marshall, TR Connors, DH Oakley, MP Frosh, SI Young, K Van Leemput, AV Dalca, B Fischl, CL Mac Donald, CD Keene, B Hyman, and JE Iglesias. Under revision.)

This is a newer version of our older tool with several key improvements:

The main options are (required arguments in bold):

mri_3d_photo_recon

--input_photo_dir [DIR]

Directory with input pixel-corrected photos.

--input_segmentation_dir [DIR]

Directory with input slab masks/segmentations.

--hemisphere [HEMI]

Must be left, right, or both

--slice_thickness [THICKNESS]

Slice thickness in mm (will be finetured if possible); if unsure, give conservative (thinner) estimate.

--photo_resolution [RESO]

Resolution of the photos in mm; if using PhotoToools this would be 0.1.

--output_directory [DIR]

Output directory with reconstructed photo volume and reference.

--photos_of_posterior_side

Use this flag if photos are taken of posterior side of slabs (default is anterior side)

--order_posterior_to_anterior

Use this flag if photos are ordered from posterior to anterior (default is anterior to posterior)

--ref_mesh [FILE]

Reference surface mesh (if available)

--mesh_reorient_with_indices [INDICES]

triplet of vertex indices to reorient mesh; format is just i,j,k (see details below)

--ref_mri [FILE]

Reference MRI scan (if available)

--ref_mri_synthseg [FILE]

SynthSeg of reference MRI scan (will be computed if scan provided and SynthSeg does not exist)

--ref_mri_synthsr [FILE]

SynthSR of reference MRI; only needed if MRI is provided and is not a 1mm T1 (will be computed if it does not exist)

--low_field_synthsr [FILE]

Use low-field version of SynthSR (eg for Hyperfine scans)

--threads [THREADS]

Number of cores to be used. Default is 1. You can use -1 to use all available cores

--gpu [INDEX]

Index of GPU to use (default is None, i.e., CPU mode)

Some additional niche options:

--fresh_tissue

This flag makes the regularizers more lenient to accommodate fresh tissue (typically more deformed)

--initial_stretch_factor_lr [FACTOR]

Initialize stretch of photos in left-right direction by this factor (useful with squashed specimens)

--weights [FILE]

CSV file with slab weights (follows order of photos). Format is just: weight1,weight2,...,weightN

--thickness_cap [MAXIMUM]

when using weights, limit the maximum estimated thickness to this value (in mm). More details below.

--equalize_images

This flag activates histogram equalization of images (useful if they have low contrast, but can hurt the machine learning imputation)

--skip_bfgs

Flag to skip BFGS finetuning (i.e., do only Adam)

--deform_recon_dir [DIR]

Directory with FS dir of reference MRI scan, to deform surfaces etc (expects to find deform_recon_dir/surf)

--input_roi_dir [DIR]

Directory with ROI masks (typically in MNI space) to deform to photo reconstruction

There are also advanced options to control the exact control point spacing and regularization (run command with help flag -h), but these are self configured depending on the type of reference and the --fresh_tissue flag so in principle you should not need to modify them.


Vertex indices for reorienting reference meshes (--mesh_reorient_with_indices)

These are the vertex indices of the frontal pole, occipital pole, and top of the central sulcus, separated with commas (e.g., -–mesh_reorient_with_indices 1000,3000,2000). You can find these indices with Freeview.

43_vertexFP.png

44_vertexOP.png

45_vertexCS.png

Frontal Pole

Occipital Pole

Top of the central sulcus


Slab weights

If you cut slabs of uneven thickness, then the --thickness option expects the average thickness. However, you can also put the slabs on a scale, record the weights, and pass the to the code with the --weights option. The weights must be in a CSV file (comma separated values), following the order of photos. The format is just: weight1,weight2,...,weightN (in grams). The thicknesses get then estimated from the weights and the surface areas.

Now: the thickness estimation can sometimes be unrealistic due to funny combinations of weights and surface areas. The code tries to detect these situations automatically. If this happens, it will prompt you to use the --thickness_cap option, which limits the maximum thickness that a slab can have in this variable thickness mode. In principle, you should not need to use --thickness_cap unless you are proompted to do so.


Machine learning imputation

The new code uses machine learning to impute / interpolate slices every 1mm (see example below).

imputation.png


Example