Photo Reconstruction Documentation



Citation

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

The machine learning slice imputation in the reconstruction is described in:

Automatic segmentation model trained using nnUNet:

Click here for a video with an overview of the method
video_screenshot.png

Purpose

This manual provides an end-to-end guide for using the tools available in FreeSurfer to reconstruct dissection photographs of brain slabs into a 3D reconstruction for quantitative analysis. Reconstructions are done by registering photographs to a 3D reference such as an MRI, a post-mortem surface scan, or an atlas. The guide covers acquiring surface scans prior to slabbing, photographing tissue slabs, and preprocessing photographs using the dissection_photo graphical user interface.

Requirements

Overview

  1. Acquire a 3D reference: either a surface scan or an MRI. Without one, slabs are registered to an atlas.

  2. Photograph the tissue slabs

  3. Preprocess the photos in the dissection photo GUI

  4. Reconstruct the 3D volume

  5. Downstream analysis of photographs

Part 1: Acquisition

Surface scanning

A surface scan of the specimen is taken after the cerebellum has been sectioned off and before the specimen is slabbed. The full scanning protocol is available on its own page: Surface Scanning Protocol.

Summary of the key requirements of a reference mesh:


Photographing the slabs

The slab photography protocol (background, tissue placement, lighting, and the markers used for pixel and perspective correction) is on its own page: Slab Photography Protocol.

Summary of the key requirements of a slab photograph:


Part 2: Preprocessing Photographs with the Dissection Photo App

The dissection photo app has five principal windows for each subject: Add photos, Correction, Segmentation, Connected components and Reconstruction. The step bar at the top of the window shows which step is being done. Users can backtrack by clicking any of the previous steps at any time, or click the house icon to return to the Projects screen with a summary of all reconstructions done or in process. For each project, work is saved as you go, so the app can be closed at any time and you can pick up later where you left off.

Before continuing, make sure the development version of FreeSurfer is properly sourced, you have downloaded the model weights, and have set NNUNET_MODEL_DIR as an environment variable pointing to the segmentation model. To start the application, use the command dissection_photo_2.

Projects Page

Each specimen corresponds to a project: a folder which will be populated with the outputs from all steps. The project home contains a summary of all projects and their progress.

ds2_00_projects.png
Projects Home screen.

Tip: For advanced users, the gear icon can be used to change which resources are used by the automatic segmentation model, covered in automatic segmentation settings.

After naming a project you will be prompted to save a folder of the same name. It is in this folder that the outputs of all steps will be stored.

Directory Structure

For each project the following directory structure will be populated with all outputs.

Folder / file

Contents

photos/

Copy of the original photographs

deformed/

Pixel-corrected photos

mask/

Binary tissue masks

connected_components/

Label maps per slab

recon/

The 3D-photo reconstruction

Step 1. Add photographs

  1. Drag and drop a folder containing dissection photographs, or click Upload Images.

  2. Select the photographs that should be used for the reconstruction. This can be used to omit repeat photographs, dissection photographs of cerebellar tissue, or gross photographs done prior to slabbing. Double click on any image in the grid for a larger preview.
  3. If you have or would like to create a calibration file to automate pixel correction, click on + Add a calibration file (optional) and follow the steps in Making a Calibration File and then Prospective Correction.

  4. Click Get started.

ds2_01_add_photos_empty.png
Add photos, before any photographs are chosen.

ds2_02_add_photos_populated.png
Photographs added, with the calibration file box expanded.

Optional: Making a calibration file

This step only needs to be done once, as long as the markers are not moved. For more information on proper usage refer to the Markers for pixel and perspective corrections section of the slab photography page.

  1. On the Add photos menu, click + Add a calibration file (optional) to expand the calibration file box, and click on Create one under the Upload Calibration button.

  2. On the next menu, if you have not printed out the fiducial markers, they can be downloaded for printing by clicking the Download Marker Printout button.

  3. Next, place markers at a known distance in a rectangle formation on the photography table. Be sure that opposite sides of the rectangle created by the fiducial markers are parallel; inaccurate marker placement can lead to incorrect perspective correction.
  4. Upload the photograph of the empty dissection table with just the markers present, and enter the width and height of the fiducial box.
  5. For each of the markers, click its centre and outer circle. Options to zoom, pan, and redo/undo can help fix mistakes and make the best calibration possible.
  6. Click Save Calibration and save your calibration file in an easy-to-access location.

Tip: Because of slight lens distortion, the overlaid labels for the outer circle of the markers might not always align throughout the whole circumference. This is not an issue.

ds2_03_calibration_photo.png
The photograph of the empty table with the four markers, uploaded.

ds2_04_calibration_zoomed.png
Zoomed in on one marker, before clicking.

ds2_05_calibration_clicks.png
The marker's centre and outer circle clicked.

Step 2: Pixel Correction

This step corrects all photographs to be at the same pixel size. Additionally, it can correct for perspective when using a calibration file, or when doing manual correction in 4-point mode.

Prospective Correction (Using fiducial markers and calibration file)

Retrospective Correction (Using a spatial reference within the photographs)

Choose how many points you can mark, enter the real distances, and place the points on each photo:

Mode

You need

Corrects

2 Point

One ruler or other known distance (entered as Ruler width (mm))

Pixel size only

3 Point

Three corners of a rectangle, e.g. two rulers at right angles

Pixel size, approximate perspective

4 Point

Four corners of a rectangle

Pixel size and perspective

ds2_06_correction_ruler.png
2 Point mode: two points placed along a 150 mm ruler (Original).

ds2_07_correction_done.png
The corrected photo, with rulers (Corrected).

When every photo is corrected, make sure to click Continue to Segmentation.

Step 3: Binary Segmentation

While you were correcting, the app was already finding the tissue in each corrected photo. Here you check each mask and fix it.

ds2_08_segmentation_mask_on.png
The automatic mask (green) shown over the slabs.

ds2_09_segmentation_mask_off.png
The mask hidden (Show mask off); the note at the top lists the masks not yet previewed.

Automatic Segmentation Settings

Open them from the gear on the Projects screen. Changes apply the next time photos are segmented.

ds2_10_seg_settings.png
Automatic segmentation settings.

Setting

What it does

Automatic segmentation (On / Off)

Off: every mask is drawn by hand from scratch. Only turn it off if the automatic segmentation fails on your photos.

Model folds

Automatic: 5 folds on a GPU, 1 on the CPU. Five folds are steadier but 4-5x slower.

Run on

Automatic uses the GPU if there is one; or choose GPU or CPU.

Maximum threads

The most processor threads segmentation may use. If the computer has fewer, it uses all it has.

Model folder

The folder of the segmentation model (nnUNetTrainer__nnUNetPlans__2d).

Step 4: Slab Connected Components

Here you tell the app which pieces of tissue belong to which slab.

ds2_11_components_empty.png
Before any boxes are drawn.

ds2_12_components_good.png
One small box inside each slab; each slab is colored and the photo is saved.

ds2_13_components_bad.png
How NOT to draw boxes: they overlap each other and cover background.

Step 5: Photo Reconstruction

Please see our separate page on the command mri_3d_photo_recon. The last step runs mri_3d_photo_recon on the images of the project. While the reconstruction is running in the background the user can continue processing images of other cases.

  1. Output folder: the folder inside the project for the results (default recon).

  2. Slabs: the hemisphere, the slab thickness in mm, which face of the slabs was photographed (anterior or posterior), the order the photos were taken in, and whether the tissue is fixed or fresh.

  3. Reference: none (the MNI atlas), a surface mesh (.stl), an MRI scan, or both. See Which reference should I use?

  4. Optionally: the number of threads, a graphics card, and the advanced settings. Empty expert weights use the command's own defaults, shown in grey.
  5. Click Run Reconstruction.

The command being run is shown on the right (Copy command copies it, for example to run it on another computer), and its output appears in the log below it. The reconstruction keeps running if you switch to another project; the Projects screen shows its progress.

ds2_14_reconstruction.png
A reconstruction running, with the command and its log.


Part 3: Downstream Tasks

Photo-Synthseg Segmentation

The 3D reconstructed stacks can be segmented with SynthSeg using the flag --photo. Please see the wiki page for SynthSeg for further information.

43_synthseg_photo.jpg

44_synthseg_parc.jpg

Example for running SynthSeg on a Left Hemisphere

PhotoTools (last edited 2026-11-03 14:05:11 by JonWilliamsRamirez)