Photo Reconstruction Documentation

Citation

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

• Gazula, H., Tregidgo, H.F., Billot, B., Balbastre, Y., Williams Ramirez, J., Herisse, R., Deden-Binder, L.J., Casamitjana, A., Melief, E.J., Latimer, C.S. and Kilgore, M.D., 2024. Machine learning of dissection photographs and surface scanning for quantitative 3D neuropathology. Elife, 12, p.RP91398. doi

Click here for a video with an overview of the method

Purpose

This manual provides an end-to-end guide for using the tools available on 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 like an MRI, a post-mortem surface scan, or an atlas. The guide touches on aquisition of surface scans prior to slabbing, preparing tissue slabs for gross photography, and how to preprocess photographs using the dissection_photo graphical user interface.

Requirements

• The latest FreeSurfer development version sourced in your terminal.

• Model files (downloaded once):

  • the reconstruction model downloaded, into $FREESURFER_HOME/models

• A CUDA enabled graphics card is optional: segmentation and reconstruction are much faster with one.

Part 1: Acquisition

Surface scanning

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

Preparing Slab Data

The following guidelines should be followed when preparing slab images for optimal results.

Guidelines for Brain Slab Image Acquisition

There are some important requirements for the photographic setup of the brain slabs to ensure the best results.

Use a high-contrast background that stands out in uniform contrast to the brain slabs, such as a solid black background. This will make slabs are easier to segment downstream. Using a complex background with color similar to your brain slabs, will lead to a more manual intervention such as having to manually trace contours, which is not only time-consuming but also non-reproducible.

Additionally, all tissue block faces must be facing the same direction. All slices should be either from an anterior or a posterior view. Note if slabs are from the posterior view, an extra flag,

--photos_of_posterior_side must be used for the final reconstruction.

When a single slice produces multiple tissue blocks, they should be placed as similar to the original anatomy as possible. For example, after acquiring slices from the frontal pole, the initial blocks corresponding to the temporal lobe will often be detached from the main block. The following figure shows a) Proper anatomical placement of tissue and, b) Tissue placed too far apart, which is not anatomically accurate.

Tissue slab placement a) Properly placed tissue b) Tissue placed in a non-anatomical manner.

Another example of difficult tissue placement can be the corpus callosum. In the following figure, we see a good example setup with high contrast for the background and good lighting. However, the placement of the corpus callosum on the rightmost slab is incorrect, which will negatively affect volumetric estimates of the third ventricle.

Markers for pixel and perspective corrections

To calibrate pixel size, we will need landmarks with known distances in between them to be provided by the user. The minimum requirement is a ruler, which provides us with two discrete landmarks. This enables rough This method is preferable for legacy images that only have a ruler for reference.

Tip: It is better to use landmarks that are as far apart as possible, as the relative error when manually setting the reference in pixels per millimeter decreases with greater distances.

A more effective setup involves four landmarks placed the corners of a rectangle of known dimensions. This enables us to correct for both pixel size and perspective. In the example below, we can easily tell that the 4 points marked on the grid define a rectangle of dimensions 170x200 mm.

The optimal scenario is to have 4 points defined by fiducial markers with highly salient features. This enables our software to automatically recognize the fiducials, which minimizes human interaction, reducing time and maximizing reproducibility. We strongly recommend that you print these set fiducials and place them on the corners of the board.

Tip: For best results, affix these fiducials to a small piece of rubber/wood/plastic that lifts them X mm above the board, where X is the thickness of your typical brain slice. Lifting the fiducial minimizes error due to the surface of the brain slice not being at the same distance as the plane of the board surface, but rather a few millimeters above it.

The fiducial form the four corners of our corrected image; hence all tissue should be within the rectangle created from the four fiducial corners. The following image shows slab photos where the fiducials were not placed sufficiently apart.

By drawing a rectangle with all fiducial markers, it is clear that much of the tissue lies outside of the pixel-corrected region.

In summary, here is an example of what an optimal photographic setup would look like, including the uniform, high-contrast background and provided fiducials located at known distances, and consistent lighting on all slabs.

Tip: It does not matter if slabs are not presented on a grid, as long as the distance between the fiducials is known. The software will draw digital rulers for your images later pixel-correction.

Recommended Directory Structure

We recommend the following directory structure for data and case organization. Each case should have its own directory, and within each case directory, create the following seven subdirectories to store the respective outputs:

1. photos – Brain slab images (.JPG, .PNG).
2. deformed - Pixel-corrected images.
3. point_clouds – Files from the project collected from the surface scanner.
4. mesh – Watertight mesh processed from point clouds on the scanner (.stl).
5. masked – Binarized masks created from pixel-corrected photos.
6. connected_components - .npz files showing the connected components for each image.
7. recon - Final reconstructed volumes, and segmentations.

Note that during the image preprocessing GUI files under deformed, masked, and connected_components will be automatically generated. After each step, ensure that your data is saved to the appropriate subdirectory. Below is an example of how files should be organized in the recommended structure:

Photo Preprocessing

The following guide will walk through the steps to preprocessing the brain slab images. This includes pixel correction, binarizing images, and selecting connected components. Make sure Freesurfer is properly sourced, and you have downloaded the model weights before continuing with the tutorial.

Pixel Correction Using Fiducials

Using the provided fiducial markers, we can correct for non-uniformities in pixel size across the images. If not available this step can be skipped retrospective correction modes can be used in the dissection_photo_gui covered in the next section. For images with fiducials, a calibration is required for pixel correction. For best results, use an image of the setup without tissue.

To start the fiducial calibration use command fiducials_calibration

After loading the image, start the calibration process.

Pan and zoom can be used to have a precise selection in these GUIs. First, select the center of one of the fiducials, followed by selecting the outer ring.

After selecting all the points, set the width and height between the fiducial markers. Next, click “Perform calibration,” to save a calibration '.npz' file. This calibration file will be used for automating pixel correction in subsequent steps, as long as the fiducial markers are not moved.

Dissection Photo GUI

The dissection photo GUI performs all preprocessing tasks, including pixel correction, binarizing images, and selecting connected components. To run the GUI, source Freesurfer and use command dissection_photo_gui. The first time the GUI is run it will display instructions on setup of model weights for the segmentation step.

Pixel Correction

In the first menu of the dissection_photo_gui select the input directory with the unprocessed gross photographs. Photographs should be set in the order such that tissue slabs are seen in the order they were cut. Additionally select the output directory where the pixel-corrected images will be saved. Here we have the option to load an optimal calibration file if available to automate pixel correction. Select Go! when you have defined the required directories.

If a calibration file was used the next widow will display the pixel-corrected images for quality assurance purposes. Click Next to proceed assuring the images were corrected.

If no calibration file is provided the next window will be for the Retrospective Correction mode. Select the type of calibration, 2-point, 3-point, or 4-point, and its relevant dimensions in millimeters. The 2-point calibration is used when there is a single axis of ground truth measurement, which enables rough pixel size correction (e.g., one ruler in the image). The 3-point calibration is used when there are three points on the corners of a rectangle – but the fourth point is not available (e.g., there are two orthogonal rulers). The 4-point version should be chosen if the four corners of a rectangle can be identified; this is the default model when the automatic mode with calibration file is used. The 3- and 4-point versions enable perspective correction (approximate with 3 points; exact with 4). We can pan and zoom to make precise selections on the image.

After pixel correcting all images, click Proceed to Segmentation to continue to the next step.

Tissue Segmentation

After selecting an output directory for the masked images, our automatic segmentation tool will immediately start predicting a binary mask per each photograph. If a GPU is available all five folds of the model will be run which will slightly increase segmentation accuracy. After the first photograph is segmented by the model, the user can start cleaning the predicted binary masks. Here the user can pan and zoom like before, but can additionally use a brush tool to remove or add any pixels. Remove any non-slice tissue and the background. The opacity of the predicted mask can also be changed using the provided slider, or toggled using Ctrl+Z.

IMPORTANT: The cortical surface should not be part of the masks, so the first (if photographed from the anterior side) or last slice (if photographed from the posterior side) should NOT be considered. You can either leave it out of the mask or ignore it when processing with the GUI.

Once we are satisfied with the mask, click Next to proceed to the next image. After all images have been segmented and cleaned, click Proceed to CC to continue to the connected components step.

Connected Components

Like previous steps, select an output directory for the connected components masks. The connected components section of the GUI will display the masked and pixel-corrected photographs. Here the user will draw boxes around the tissue slabs in each photograph. The GUI will then save the connected components as .npy files.

For each image select slices in order, either anterior-posterior or posterior-anterior. Remain consistent of slice order on all photographs. Connected components are selected by clicking and dragging to draw a box in a region of each individual slab in the photograph. After a box has been drawn in each individual slab, click Next to save the output .npy file and move to the next image.

Tip: Make sure no boxes are overlapping.

Once a box is drawn over the tissue, the slab will be colored to show what is being included as one slice.

Above is an example of how to correctly draw the boxes within the brain slabs themselves. These boxes inform the GUI that the pixels connected to these slabs are all part of the same tissue slice. Note the box covers tissue from the temporal lobe as it can sometimes be disjoint from the rest of the slab.

Below is an example of how NOT to draw boxes for this GUI. Notice the occurrence of overlap between boxes and the inclusion of an abundance of black space. Try to keep the boxes drawn to small regions within the brain slabs themselves as to not include any background pixels.

Photo Reconstruction

Please see our separate page on the command mri_3d_photo_recon

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.

Example for running SynthSeg on a Left Hemisphere

• mri_synthseg \
• --i ./recon/photo_recon.mgz \
• --o ./recon/photo_recon_synthseg.mgz \
• --photo left \
• --parc