Differences between revisions 77 and 103 (spanning 26 versions)

Photo Reconstruction Documentation

Contents

Photo Reconstruction Documentation
Part 1: Acquisition
Part 2: Preprocessing Photographs with the Dissection Photo App
Part 3: Downstream Tasks
1. Photo-Synthseg Segmentation

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

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

Crespo-Aguirre, M., Williams-Ramirez, J., Zemlyanker, D., Hu, X., Deden-Binder, L.J., Herisse, R., Montine, M., Connors, T.R., Mount, C., MacDonald, C.L., Keene, C.D., Latimer, C.S., Oakley, D.H., Hyman, B.T., Lawry-Aguila, A. and Iglesias, J.E., 2026. Improving neuropathological reconstruction fidelity via AI slice imputation. Acta Neuropathologica Communications. doi

Automatic segmentation model trained using nnUNet:

Williams Ramirez, J., Zemlyanker, D., Deden-Binder, L., Herisse, R., Garcia Pallares, E., Gopinath, K., Gazula, H., Mount, C., Kozanno, L.N., Marshall, M.S., Connors, T.R., Frosch, M.P., Montine, M., Oakley, D.H., Mac Donald, C.L., Keene, C.D., Hyman, B.T., Fischl, B. and Iglesias, J.E., 2026. A public generalizable AI tool for automated segmentation of coronal brain tissue slabs for 3D neuropathology. PLOS One, 21(8), p.e0355740. doi
Isensee, F., Jaeger, P.F., Kohl, S.A., Petersen, J. and Maier-Hein, K.H., 2021. nnU-Net: a self-configuring method for deep learning-based biomedical image segmentation. Nature methods, 18(2), pp.203-211.

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 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, preparing tissue slabs for gross photography, and preprocessing 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.

Overview

Acquire a 3D reference: either a surface scan or an MRI. Without one, slabs are registered to an atlas.
Photograph the tissue slabs
Preprocess the photos in the dissection photo GUI
Reconstruct the 3D volume
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:

The cerebellum removed: it is not on the slabs, so including it in the scan leads to an incorrect reconstruction.
The sides of the specimen captured.
A watertight mesh, saved as .stl. Small holes in the initial point cloud due to deep sulci are fine; these will be covered by the meshing process.

Preparing Slabs

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 the slabs easier to segment downstream. Using a complex background with a color similar to your brain slabs will lead to more manual intervention, such as having to manually trace contours, which is not only time-consuming but also non-reproducible.


Low-contrast background: difficult to segment.	High-contrast background: easy to segment.

Additionally, all tissue block faces must face the same direction: all slices should be photographed either from the anterior or from the posterior view. Note that if slabs are photographed from the posterior view, the extra flag --photos_of_posterior_side must be used in the final reconstruction command.

When a single slice produces multiple tissue blocks, they should be placed as close 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 is the corpus callosum. The following figure shows a good setup, with a high-contrast 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, the user needs to provide landmarks with known distances between them. The minimum requirement is a ruler, which provides two discrete landmarks. This enables rough pixel size correction. 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 uses four landmarks placed at 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 170 x 200 mm.

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

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

The fiducials form the four corners of the corrected image; hence, all tissue should be within the rectangle formed by the four fiducials. The following image shows slab photos where the fiducials were not placed far enough apart.

Drawing a rectangle through the four fiducial markers makes it clear that much of the tissue lies outside of the pixel-corrected region.

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

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

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.

Projects Home screen.

To start processing a new batch of dissection photographs click on New Project.
Open a project to continue where you left off or backtrack to any completed steps.

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

Drag and drop a folder containing dissection photographs, or click Upload Images.
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.
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.
Click Get started.

Add photos, before any photographs are chosen.

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 in this wiki page.

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.
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.
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.
Upload the photograph of the empty dissection table with just the markers present, and enter the width and height of the fiducial box.
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.
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.

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

Zoomed in on one marker, before clicking.

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)

Every photo is corrected automatically as soon as Correction opens. The markers are found in each photo separately, so it does not matter if the camera moved between photos.
Check each photo: Original shows the photo as taken, with the marker centres that were found; Corrected shows the result. A green tick in the strip at the bottom marks each corrected photo.
If the markers cannot be found in a photo, the app says which ones. On each of them, click the centres of the four markers on the Original view and click Correct this photo.

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

Ctrl + left click places a point; once all are placed, Ctrl + click moves the nearest one. Clear points starts again.
Click Correct this photo (Ctrl + W also moves on to the next photo). Place points on the Original view; the Corrected view is for checking.

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

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.

The automatic mask (green) shown over the slabs.

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

Brush (Q) adds to the mask, Eraser (W) removes from it, and Fill (E) fills an area. Apply the tool with Ctrl + left drag; set the sizes with the sliders.
Mask opacity changes how see-through the mask is; Show mask (Ctrl + T) hides and shows it. Undo and redo with Ctrl + Z and Ctrl + Shift + Z.
Leave out everything that is not slab tissue: the background, labels, and fragments that do not belong to a slab.
IMPORTANT: the cortical surface should not be part of the masks, so the first slab (if photographed from the anterior side) or the last slab (if photographed from the posterior side) should NOT be included.
You need to look at every photo's mask before Continue to Connected Components becomes available; a note at the top says which ones are left.

Automatic Segmentation Settings

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

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.

In each photo, draw a box inside each slab (Ctrl + left drag), always in the same order: anterior to posterior, or posterior to anterior. The slab is colored as soon as its box is drawn.
Keep boxes small and inside the tissue, and do not let them overlap. If a slab is in several pieces (e.g. a detached temporal lobe), make sure its box touches every piece.
Click Save components (Ctrl + W also moves on to the next photo); moving to another photo saves it too. A green tick marks saved photos. If you change a saved photo, its tick goes away until you save it again.
Undo and redo with Ctrl + Z and Ctrl + Shift + Z. Slab overlay changes how strongly the slabs are colored.

Before any boxes are drawn.

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

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.

Output folder: the folder inside the project for the results (default recon).
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.
Reference: none (the MNI atlas), a surface mesh (.stl), an MRI scan, or both. See Which reference should I use?
Optionally: the number of threads, a graphics card, and the advanced settings. Empty expert weights use the command's own defaults, shown in grey.
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.

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.

Example for running SynthSeg on a Left Hemisphere

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

-  ⇤ ← Revision 77 as of 2023-07-26 16:30:33 → 
  Size: 27540
  Editor: JonWilliamsRamirez
  Comment:
+   ← Revision 103 as of 2026-10-28 18:50:43 → ⇥
  Size: 21300
  Editor: JonWilliamsRamirez
  Comment:
-Deletions are marked like this.
+Additions are marked like this.
 Line 2:
-== Table of Contents ==
<<TableOfContents>>
+<<TableOfContents>><<BR>><<BR>>

== 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. [[https://doi.org/10.7554/eLife.91398.4|doi]]

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

 * Crespo-Aguirre, M., Williams-Ramirez, J., Zemlyanker, D., Hu, X., Deden-Binder, L.J., Herisse, R., Montine, M., Connors, T.R., Mount, C., !MacDonald, C.L., Keene, C.D., Latimer, C.S., Oakley, D.H., Hyman, B.T., Lawry-Aguila, A. and Iglesias, J.E., 2026. Improving neuropathological reconstruction fidelity via AI slice imputation. Acta Neuropathologica Communications. [[https://doi.org/10.1186/s40478-026-02451-3|doi]]

Automatic segmentation model trained using nnUNet:

 * Williams Ramirez, J., Zemlyanker, D., Deden-Binder, L., Herisse, R., Garcia Pallares, E., Gopinath, K., Gazula, H., Mount, C., Kozanno, L.N., Marshall, M.S., Connors, T.R., Frosch, M.P., Montine, M., Oakley, D.H., Mac Donald, C.L., Keene, C.D., Hyman, B.T., Fischl, B. and Iglesias, J.E., 2026. A public generalizable AI tool for automated segmentation of coronal brain tissue slabs for 3D neuropathology. PLOS One, 21(8), p.e0355740. [[https://doi.org/10.1371/journal.pone.0355740|doi]]
 * Isensee, F., Jaeger, P.F., Kohl, S.A., Petersen, J. and Maier-Hein, K.H., 2021. nnU-Net: a self-configuring method for deep learning-based biomedical image segmentation. Nature methods, 18(2), pp.203-211.

[[https://www.youtube.com/watch?v=wo5meYRaGUY|Click here for a video with an overview of the method]]<<BR>> {{attachment:video_screenshot.png||width="666"}}  <<BR>><<BR>>

== 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, preparing tissue slabs for gross photography, and preprocessing photographs using the dissection_photo graphical user interface.<<BR>><<BR>>

== Requirements ==
 * The latest FreeSurfer development version sourced in your terminal.
 * Model files (downloaded once):
  * the [[https://ftp.nmr.mgh.harvard.edu/pub/dist/lcnpublic/dist/dissection_photo_model/photo_imputation_unet.pth|reconstruction model]], downloaded into `$FREESURFER_HOME/models`
 * A CUDA-enabled graphics card is optional: segmentation and reconstruction are much faster with one.

== Overview ==
 1. '''Acquire a 3D reference''': either a surface scan or an MRI. Without one, slabs are registered to an atlas.
 1. '''Photograph the tissue slabs'''
 1. '''Preprocess the photos in the dissection photo GUI'''
 1. '''Reconstruct the 3D volume'''
 1. '''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: '''[[PhotoTools Surface Scanning|Surface Scanning Protocol]]'''.

Summary of the key requirements of a reference mesh:

 * The cerebellum removed: it is not on the slabs, so including it in the scan leads to an incorrect reconstruction.
 * The sides of the specimen captured.
 * A watertight mesh, saved as `.stl`. Small holes in the initial point cloud due to deep sulci are fine; these will be covered by the meshing process.
-Line 6:
+Line 47:
+== Preparing Slabs ==
The following guidelines should be followed when preparing slab images for optimal results. <<BR>>

== 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 the slabs easier to segment downstream. Using a complex background with a color similar to your brain slabs will lead to more manual intervention, such as having to manually trace contours, which is not only time-consuming but also non-reproducible.<<BR>>
|| {{attachment:17_low_constrast.png||height="266"}} || {{attachment:18_high_contrast.png||height="266"}} ||
||Low-contrast background: difficult to segment. ||High-contrast background: easy to segment. ||

Additionally, all tissue block faces must face the same direction: all slices should be photographed either from the anterior or from the posterior view. Note that if slabs are photographed from the posterior view, the extra flag '''--photos_of_posterior_side''' must be used in the final reconstruction command.

When a single slice produces multiple tissue blocks, they should be placed as close 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.

{{attachment:19_slab_placement.png||height="483",width="667"}} <<BR>>''Tissue slab placement: a) properly placed tissue; b) tissue placed in a non-anatomical manner.''<<BR>>

Another example of difficult tissue placement is the corpus callosum. The following figure shows a good setup, with a high-contrast 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.

{{attachment:20_incorrect_tissue_placement.png||height="333",width="659"}} <<BR>> <<BR>>

== Markers for pixel and perspective corrections ==
To calibrate pixel size, the user needs to provide landmarks with known distances between them. The minimum requirement is a ruler, which provides two discrete landmarks. This enables rough pixel size correction. This method is preferable for legacy images that only have a ruler for reference.

{{attachment:21_twoPoint.jpeg||height="382",width="664"}} <<BR>>

'''''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 uses four landmarks placed at 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 170 x 200 mm.

{{attachment:22_fourPoint.png||height="561",width="659"}} <<BR>>

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

{{attachment:23_fiducials.png||height="439",width="416"}} <<BR>>

'''''Tip''''': For best results, affix the fiducials to a small piece of rubber, wood or plastic that lifts them X mm above the board, where X is the thickness of your typical brain slice. Lifting the fiducials minimizes the error caused by the surface of the brain slice not being in the same plane as the board, but a few millimeters above it.

{{attachment:24_fiducialTissue.png||height="460",width="674"}} <<BR>>

The fiducials form the four corners of the corrected image; hence, all tissue should be within the rectangle formed by the four fiducials. The following image shows slab photos where the fiducials were not placed far enough apart.

{{attachment:25_tissueSpace.png||height="404",width="685"}} <<BR>>

Drawing a rectangle through the four fiducial markers makes it clear that much of the tissue lies outside of the pixel-corrected region.

{{attachment:26_tissueBox.png||height="403",width="683"}} <<BR>>

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

{{attachment:27_goodContrast.png||height="478",width="676"}} <<BR>>

'''''Tip''''': It does not matter if the slabs are not placed on a grid, as long as the distance between the fiducials is known. The software will draw digital rulers on your images during pixel correction.<<BR>><<BR>>

= 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'''. <<BR>>

== 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.

{{attachment:ds2_00_projects.png||width="560"}} <<BR>> ''Projects Home screen.''

 * To start processing a new batch of dissection photographs click on '''New Project'''.
 * Open a project to continue where you left off or backtrack to any completed steps.

'''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|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'''.
 1. 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.
 1. 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 [[#Optional:_Making_a_calibration_file|Making a Calibration File]] and then [[#Prospective_Correction_.28Using_fiducial_markers_and_calibration_file.29|Prospective Correction]].
 1. Click '''Get started'''.

||<:> {{attachment:ds2_01_add_photos_empty.png||width="420"}} <<BR>> ''Add photos, before any photographs are chosen.'' ||<:> {{attachment:ds2_02_add_photos_populated.png||width="420"}} <<BR>> ''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|Markers for pixel and perspective corrections]] section in this wiki 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.
 1. 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.
 1. 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.
 1. Upload the photograph of the empty dissection table with just the markers present, and enter the width and height of the fiducial box.
 1. 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.
 1. 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.

{{attachment:ds2_03_calibration_photo.png||width="640"}} <<BR>> ''The photograph of the empty table with the four markers, uploaded.''

||<:> {{attachment:ds2_04_calibration_zoomed.png||width="420"}} <<BR>> ''Zoomed in on one marker, before clicking.'' ||<:> {{attachment:ds2_05_calibration_clicks.png||width="420"}} <<BR>> ''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) ===
 * Every photo is corrected automatically as soon as Correction opens. The markers are found in each photo separately, so it does not matter if the camera moved between photos.
 * Check each photo: '''Original''' shows the photo as taken, with the marker centres that were found; '''Corrected''' shows the result. A green tick in the strip at the bottom marks each corrected photo.
 * If the markers cannot be found in a photo, the app says which ones. On each of them, click the centres of the four markers on the Original view and click '''Correct this photo'''.

=== 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||
 * Ctrl + left click places a point; once all are placed, Ctrl + click moves the nearest one. '''Clear points''' starts again.
 * Click '''Correct this photo''' (Ctrl + W also moves on to the next photo). Place points on the Original view; the Corrected view is for checking.

||<:> {{attachment:ds2_06_correction_ruler.png||width="420"}} <<BR>> ''2 Point mode: two points placed along a 150 mm ruler (Original).'' ||<:> {{attachment:ds2_07_correction_done.png||width="420"}} <<BR>> ''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.

||<:> {{attachment:ds2_08_segmentation_mask_on.png||width="440"}} <<BR>> ''The automatic mask (green) shown over the slabs.'' ||<:> {{attachment:ds2_09_segmentation_mask_off.png||width="346"}} <<BR>> ''The mask hidden ('''Show mask''' off); the note at the top lists the masks not yet previewed.'' ||

 * '''Brush''' (Q) adds to the mask, '''Eraser''' (W) removes from it, and '''Fill''' (E) fills an area. Apply the tool with Ctrl + left drag; set the sizes with the sliders.
 * '''Mask opacity''' changes how see-through the mask is; '''Show mask''' (Ctrl + T) hides and shows it. Undo and redo with Ctrl + Z and Ctrl + Shift + Z.
 * Leave out everything that is not slab tissue: the background, labels, and fragments that do not belong to a slab.
 * '''IMPORTANT''': the cortical surface should not be part of the masks, so the first slab (if photographed from the anterior side) or the last slab (if photographed from the posterior side) should '''NOT''' be included.
 * You need to look at every photo's mask before '''Continue to Connected Components''' becomes available; a note at the top says which ones are left.

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

{{attachment:ds2_10_seg_settings.png||width="480"}} <<BR>> ''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.
 * In each photo, draw a box inside each slab (Ctrl + left drag), always in the same order: anterior to posterior, or posterior to anterior. The slab is colored as soon as its box is drawn.
 * Keep boxes small and inside the tissue, and do not let them overlap. If a slab is in several pieces (e.g. a detached temporal lobe), make sure its box touches every piece.
 * Click '''Save components''' (Ctrl + W also moves on to the next photo); moving to another photo saves it too. A green tick marks saved photos. If you change a saved photo, its tick goes away until you save it again.
 * Undo and redo with Ctrl + Z and Ctrl + Shift + Z. '''Slab overlay''' changes how strongly the slabs are colored.

{{attachment:ds2_11_components_empty.png||width="420"}} <<BR>> ''Before any boxes are drawn.''

||<:> {{attachment:ds2_12_components_good.png||width="420"}} <<BR>> ''One small box inside each slab; each slab is colored and the photo is saved.'' ||<:> {{attachment:ds2_13_components_bad.png||width="420"}} <<BR>> ''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`).
 1. '''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.
 1. '''Reference''': none (the MNI atlas), a surface mesh (`.stl`), an MRI scan, or both. See [[#Which_reference_should_I_use.3F|Which reference should I use?]]
 1. Optionally: the number of threads, a graphics card, and the advanced settings. Empty expert weights use the command's own defaults, shown in grey.
 1. 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.

{{attachment:ds2_14_reconstruction.png||width="640"}} <<BR>> ''A reconstruction running, with the command and its log.''
-Line 8:
+Line 221:
-If you use these tools in your analysis, please cite:
 
* [[https://doi.org/10.1101/2023.06.08.544050|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, JE Iglesias. Under revision.)

[[https://www.youtube.com/watch?v=wo5meYRaGUY|Click here for a video with an overview of the method]]
<<BR>>
{{attachment:video_screenshot.png||width="666"}} 

<<BR>>
<<BR>>


== Purpose ==
This manual will provide step-by-step instructions on utilizing the Einscan Pro HD scanner, recommended preparation of tissue slabs after scanning, and outline the data processing pipeline to finalize a 3D reconstruction of brain slab images using a reference surface. <<BR>><<BR>><<BR>>

= 1. Einscan Turntable Protocol =
This section will cover our standard operating procedure for scanning fixed tissue samples in the Massachusetts General Hospital (MGH).  In the setup, we use an EinScan Pro HD scanner with the ‘industrial pack,’ which includes an additional turntable and tripod. A good surface scan is critical for accurately reconstructing the tissue slabs, as it is used as the reference to which the slabs are registered and deformed into. Later sections will cover surface mesh quality assessment and what to look for in a scan. <<BR>>

== Scanner Setup ==
To set up the turntable and scanner, we adjust the tripod closely to the tissue while maintaining a clear view of the full turntable plate. Having the scanner not too far from the tissue will yield the best results. When using ‘Handheld’ mode, SHINING3D software will guide the user on the scanner distance. On the table, the scanner is adjusted to approximately 45˚, 8-10 inches from the turntable. Both the scanner and turntable are connected to the computer via USB and external power.

{{attachment:01_ScannerSetup.png||width="439",height="310"}}  <<BR>>''Scanner setup for turntable scan.''<<BR>>

Next, we launch the most up-to-date Shining3D software for the Einscan Pro HD. Software for all EinsScan 3D scanners can be found at [[https://www.einscan.com/support/download/|einscan.com/support/download/]]. Next, a menu will prompt a selection for the type of scan, fixed scan (using the turntable), handheld HD scan, or handheld rapid scan. We select “fixed scan” to use the turntable add-on and create a new “Non-texture Scan” project.

{{attachment:02_TextureSettings.png||width="439",height="310"}} <<BR>>''Texture settings prompt when creating a new project.''<<BR>>

At this point, the main scan menu should be on the screen, where we can customize different parameters for scan acquisition. On the left-hand side of the screen, there is a preview of the scanner’s field of view.

{{attachment:03_MainScanMenu.jpg||width="670",height="349"}} <<BR>>''Main scan menu.''<<BR>>

In the Scan Setting menu, ensure the “with Turntable” box is checked and the align mode is set to Features. The alignment mode “Turntable Coded Targets” is not used because tissue can slide as the turntable changes orientation. Sliding can be especially present when scanning the medial wall and can be helped by gently patting the tissue with a linen towel to remove some excess fixative on the tissue. When using the handheld mode, we highly recommend using markers which can vastly improve scanning speed and user experience.

Turntable steps determine how many scans will be acquired and stitched for this session. Higher numbers can lead to more accurate data but can increase scan time. We set turntable steps to 48, which we consider a good balance between acquisition time and scan quality.

For handheld scans, we use the parameters:

 * Texture: Non-texture scan
 * Mode of alignment: hybrid
 * Operation mode: classic (scanning speed: 15 fps)
 * Resolution: high (0.5mm)

<<BR>>

== Sample Setup ==
We place a glass sheet atop to protect the turntable and ease cleanup. The glass sheet contains markers that can aid tracking in handheld scans but will not be used with the feature alignment mode. The sample is placed in the middle of the turntable so that the scanner gets the best view of the sample as it rotates. Occluding the turntable markers will also affect the stitching of scans if the scan is set to “Turntable Coded Targets.” When doing a handheld scan, make sure the sample is not covering the placed markers on the glass sheet. Note the sample does not include the cerebellum.

{{attachment:05_SamplePlacement.png||width="435",height="445"}} <<BR>>''Sample placement on the turntable with sample lateral side down.''<<BR>>

Two scan projects are created for all samples on opposite sides. For hemispheres, we first acquire a scan with the sample medial side down. Next, the hemisphere is flipped to be lateral side down, and the tissue is more likely to shift when the turntable steps. To reduce sample movement, we wipe down excess fixative on the sheet of glass to improve traction. Whole Brains are scanned upright (brain stem down) and upside down. Although these types of samples do not tend to move during the scan, they can deform between being upright versus upside down, which can lead to issues aligning the two sets of point clouds.

'''''Tip''''': Samples should have the cerebellum removed before acquisition. The cerebellum is not considered in the reconstruction, including it present in the scan will lead to incorrect slice reconstruction.

{{attachment:06_ScanIncorrect.png||width="435",height="380"}} <<BR>>''Scan incorrectly including the cerebellum.''<<BR>> <<BR>>

== Handheld Scanning ==
Handheld mode is also an option, particularly for fresh tissue, due to the tissue being unable to maintain its shape. It cannot be flipped for two-sided scans. In this mode, a transparent surface can be used to scan both sides of the sample without having to shift the easily deformable tissue.

{{attachment:07_ExampleHandheld.png||width="435",height="404"}} <<BR>>''Example of a handheld scan setup.''<<BR>> <<BR>>

== Running the Scan ==
In the scan workspace, the preview window is used to center the tissue sample in the camera view. Set the red crosshairs to the middle of the sample for full coverage of the tissue as the turntable moves.

{{attachment:10_expsure_good.png||width="288",height="250"}} <<BR>>''Scanner preview.''<<BR>>

The camera exposure has a large effect on scan quality. Incorrect exposure can lead to noisier surfaces in the resulting scan point clouds. Exposure is adjusted in the main scan menu on the slider under the camera preview screen.

{{attachment:09_ScannerExp.png||height="72"}} <<BR>>''Scanner exposure slider.''<<BR>>

To determine if the sample is not exposed appropriately, the preview window will show bright regions with red. The slider is set to an exposure where there are some but not many red regions. To avoid any issues with exposure, sometimes we use HDR mode, which can be set in the Scan Settings menu for fixed turntable scans.
|| {{attachment:11_exposure_over.png||width="245",height="221"}} || {{attachment:12_exposure_under.png||width="237",height="215"}} || {{attachment:10_expsure_good.png||width="246",height="212"}} ||
||''Overexposed (red filter on sample + bright image)'' ||''Underexposed (black filter on sample + dark image)'' ||''Sufficient exposure (can see sample, markers, decent contrast)'' ||




<<BR>>

== HDR Mode ==
HDR mode is used for samples with dark features like bruising or veins. The scanner can have a hard time picking up darker features on the sample. HDR mode will take three images at each turntable step at different exposures to capture darker and deeper structures in the tissue (e.g., sometimes this mode is good if point clouds aren’t generated near medial structures, including 3^rd^ventricle, septum pellucidum, corpus callosum, parahippocampal gyrus, occipitotemporal gyrus, and any optic structures – nerve, chiasm)

{{attachment:13_dark_veins.png||width="432",height="463"}} <<BR>>''Sample with dark veins.''<<BR>> <<BR>>

== Editing and Saving Data ==
=== Removing Excess Elements ===
 1. Remove excess data or turntable markers using the deleting tool in case the scanner picks up other neighboring geometry that’s not brain – though this is not likely on a fixed scan.
 1. Select extra elements by holding the shift key + left click.
 1. Delete these points by clicking the “Delete Selected Data” button or the delete key.
 1. Press the “Complete Editing” check-mark icon once all necessary edits are done.
 1. Note: Editing point clouds is easier than editing meshes on the software.

{{attachment:14_UI_guide.png||width="667",height="394"}} <<BR>>''Performing the second run after removing excess elements from the first set of  point clouds.''<<BR>>

 1. When finished editing, an optimized point cloud will be generated, which should have saved automatically as “Project 1.”
 1. Briefly QA scan data, looking at noise or holes in the surface of the scan. Some gaps in the point clouds are normal. Any scan can be redone to get better results at any time.

<<BR>>

=== Aligning both runs ===
 1. If you have two scanning sessions, you can align the cloud points using three reference regions.
 1. Click the alignment icon and drag and drop both scanning sessions to the float and fixed windows.
 1. Hold the shift key and left click to select three collinear points on each scan session. Ideally, we would want to place one point on the anterior, superior, and posterior sides of the brain.
 1. Click Complete when finished with the alignment.

<<BR>>

=== Creating a Mesh ===
 1. Click on the mesh icon to generate a mesh model from your generated point clouds.
 1. Select watertight.
 1. Choose the “high-detail” option for the best mesh resolution.
 1. This reconstruction should take approximately 20+ minutes, depending on the equipment.
 1. Save your mesh when reconstruction has finished. Your mesh should be saved as a .stl file automatically, but it is also recommended to save your point clouds (.asc files).

<<BR>>

=== Addressing mesh quality ===
When acquiring the mesh, the sides of the sample are critical for a good point cloud alignment. A bad alignment between scans can cause a lot of issues, leading to scans that are not representative of the tissue. The following example shows a handheld scan where the sides of the tissue were not acquired. This can lead to a seemingly flatter sample and will affect the quality of the final reconstruction.

{{attachment:15_bad_mesh.png||width="436",height="330"}} <<BR>>''Mesh missing sides of the top scan.''<<BR>>

Ideally, we want the sides of the mesh to be filled like in the following example. When acquiring a handheld scan, it can be difficult to acquire the sides of the sample without acquiring other surfaces. These additional surfaces can be edited and deleted in the same way as markers are deleted.

{{attachment:16_good_mesh.png||width="438",height="329"}} <<BR>>''Mesh correctly including the sides of the tissue.''<<BR>>

Note that the previous surface has some holes due to deep sulci, which should not be an issue with the reconstruction. Watertight meshing should be able to handle small holes. <<BR>><<BR>><<BR>>

= 2. Preparing Slab Data =
=== Preparing Slab Image Data ===
The following guide should be applied for the preparation of the slab images. This step should be completed prior to any GUI usage.

== Guidelines for Brain Slab Image Acquisition ==
Before processing slice segmentation and volume reconstruction, there are some important requirements for the photographic setup of the brain slabs.

Use a high-contrast background that stands out in uniform contrast to the brain slabs, like a solid black background, so slabs are easier to segment downstream with a simple threshold. Using a complex background with color similar to your brain slabs, will lead to a more manual intervention like having to manually trace contours, which is not only time-consuming but also non-reproducible.
|| {{attachment:17_low_constrast.png||height="266"}} || {{attachment:18_high_contrast.png||height="266"}} ||
||Difficult to segment low contrast background. ||Easy to segment high contrast background. ||




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 tissue block. The following figure a) shows a good tissue placement consistent with the anatomy while b) shows too much distance between the blocks of tissue that is not anatomically accurate.

{{attachment:19_slab_placement.png||width="667",height="483"}} <<BR>>''Tissue slab placement a) Properly placed tissue b) Tissue placed in a non-anatomical manner.''<<BR>>

Another example of difficult tissue placement can be the corpus callosum. In the following figure, we show a great example slab image with a critical flaw. Fiducials are clearly shown, and there is high contrast for the background and great lighting. However, there is an issue with tissue placement. Note the rightmost slab has an incorrect placement of the corpus callosum, which will affect estimates of the medial vessel.

{{attachment:20_incorrect_tissue_placement.png||width="659",height="333"}} <<BR>> <<BR>>

== 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.

{{attachment:21_twoPoint.jpeg||width="664",height="382"}} <<BR>>

'''''Tip''''': It is preferable to use two points that are as far apart as possible. This is because the relative error in pixels/mm is minimized by choosing two points with a greater distance between them.

A better photographic setup is to have four landmarks in the corners of a rectangle of known dimensions. This enables us to correct for both pixel size and perspective. For example, in the picture below, we can easily tell that the 4 points marked on the grid define a rectangle of dimensions 17x20 cm.

{{attachment:22_fourPoint.png||width="659",height="561"}} <<BR>>

The most optimal scenario is to have 4 points defined by highly salient fiducial markers. 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.

{{attachment:23_fiducials.png||width="416",height="439"}} <<BR>>

'''''Tip''''': For the greatest benefit, these fiducials should be attached 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.

{{attachment:24_fiducialTissue.png||width="674",height="460"}} <<BR>>

The fiducial markers serve as 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.

{{attachment:25_tissueSpace.png||width="685",height="404"}} <<BR>>

Additionally, by drawing a rectangle with all fiducial corners, it is clear that much of the tissue is outside of the pixel-corrected region.

{{attachment:26_tissueBox.png||width="683",height="403"}} <<BR>>

In sum, 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.

{{attachment:27_goodContrast.png||width="676",height="478"}} <<BR>>

'''''Tip''''': It does not matter that these slabs are not presented on a grid. As long as you know the distance in millimeters between the fiducials, our software will draw digital rulers for your images later.

'''Cloning The Freesurfer Development Git Repo'''

Additionally, download the development version of Freesurfer by cloning the dev branch here:

https://github.com/freesurfer/freesurfer

'''Creating a Directory Structure'''

We recommend the following directory structure for data and case organization. Each case should have a directory. Inside your case directory, create seven additional directories to store the following outputs.

 1. photos – Brain slab images (.JPG, .PNG).
 1. deformed - Pixel-corrected images.
 1. point_clouds – Files from the project collected from the surface scanner.
 1. mesh – Watertight mesh processed from point clouds on the scanner (.stl).
 1. masked – Binarized masks created from pixel-corrected photos.
 1. connected_components - The outputs from the connected components GUI.
 1. recon - The final reconstructed image volumes.

After each step, ensure that you are uploading your data back to your subject’s main directory. See below how files are divided between each of the sub-directories.
|| {{attachment:28_demoDirectory.png||height="555"}} || {{attachment:29_demoDirectory.png||height="180"}} <<BR>> {{attachment:29.2_demoDirectory.png||height="203"}} ||




<<BR>>

= 3. Image Correction =
The following guide should be applied for pixel correction of the brain slab image data. These GUIs will use images of raw brain slab photographs as input and creates deformed, pixel-corrected images. By selecting fiducials of known distance from each other, we can correct for non-uniformities in pixel size across the image.

== Correction with fiducials ==
For images with fiducials, a calibration will be made before pixel correcting the images. To generate a calibration, a tissue-free image must be used.

 1. Source the dev version of Freesurfer.
 1. Run the fiducial calibration with the command “calibration_with_fiducials.”

{{attachment:30_fiducialCalibIntro.png||width="550",height="275"}} <<BR>>

After loading the image, we can start the calibration process.

{{attachment:31_fiducialCalibWindow.png||width="548",height="440"}} <<BR>>

We can use pan and zoom to have a precise selection in these GUIs. First, select the center of one of the fiducials, followed by selecting the outer ring.
|| {{attachment:32_fiducialCenter.png||height="237"}} || {{attachment:33_fiducialDiameter.png||height="237"}} ||
||The first selection at the fiducial center. ||The second selection at the outer circle of the fiducial. ||




After selecting all the points, the width and height between the fiducial markers. After clicking “Perform calibration,” a ‘.npz’ calibration file is saved.

Next, run the command “fiducial_correction” and add the relevant directories to correct all images automatically.

{{attachment:34_fiducialCalibDirectory.png||height="298"}} <<BR>>

== Retrospective Registration ==
Although less preferable, for images that do not have fiducials, we can still pixel-correct images using other references in the image, like a ruler, for each of the images.

 1. Source the dev version of Freesurfer.
 1. Organize your directory structure.
 1. Run the retrospective registration command “retrospective_correction.”

Select “Click to Start” on the first dialogue box.

{{attachment:35_retrospectiveIntro.png||width="630",height="210"}} <<BR>>

Select mode and indicate file paths. A new dialogue box (pictured below) will appear.

Follow the directions as such:

 1. Select the directory with the input images (the untouched sectioned brain images) by clicking the Choose Folder option.
 1. Select the directory for the output images to be saved. As stated, this directory must already be created.
 1. Select the mode that will be used for pixel correction. Select a mode that is compatible with your image setup. 2 points should be chosen if there is a single axis of ground truth measurement (i.e., One ruler in the image), and four should be chosen if there are two axes.

{{attachment:36_retrospectiveDirectory.png||width="557",height="303"}} <<BR>> <<BR>> {{attachment:37_retrospectiveTissue.png||width="568",height="445"}} <<BR>>

A new interactive window with your brain slabs and a “Ruler Length” option will be displayed. Click visible markers that provide ground truth measurement. Use these as the basis for your ruler Length, which should be entered in millimeters. Then, click register and complete the remaining images. The pixel-corrected images will then populate your output directory. Finally, save your subject’s registered images to your subject’s ‘deformed’ subdirectory. <<BR>><<BR>><<BR>>

= 4. Binarizing Images =
Binary masks are created to only include the tissue slice and not include any cortex. Image editing software like GIMP can be used to create these binary masks. A combination of the thresholding and lasso tool is used to remove any non-slice tissue and the background. <<BR>><<BR>><<BR>>

= 5. Connected Components =
This section covers how to use the connected components GUI to select brain slices.

 1. Source the dev version of Freesurfer.
 1. Run the fiducial calibration with the command “connected_components.”

Following these directions, select the directory with the input images (the pixel-corrected deformed images).

 1. Select the directory with the input masks created through GIMP.
 1. Select the directory where you want the output masks saved.

By clicking '''Click to Start''', you will land on the following interactive module. Input the directory destinations here.

{{attachment:38_ccIntro.png||width="517",height="287"}} <<BR>>

{{attachment:39_ccDirectory.png||width="560",height="328"}} <<BR>>

By clicking '''Start Processing''', you will open a new interactive window displaying the deformed brain slab photographs. For each image, select slices in order 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 '''Process Image '''to save the output .npy files. Make sure no boxes are overlapping.

{{attachment:40_ccMain.png||width="575",height="453"}} <<BR>>

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

{{attachment:41_ccBox.png||width="582",height="458"}} <<BR>>

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 related. It is important that there is a disconnection between these slabs with some empty/black space between them so the GUI does not count two separate slabs as a single connected component. Additionally, note that the slabs are selected in the order they were cut.

{{attachment:42_ccBoxLarge.png||width="579",height="457"}} <<BR>>

Above 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.

'''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 unknown GUI. <<BR>><<BR>><<BR>>

== 6. Photo Reconstruction ==
This is a guide to submitting the final outputs from the photo-calibration aspect of the processing pipeline for reconstruction and surface estimation.

To begin, make sure to have the dev version of Freesurfer installed.

Next, we can call the scrips to perform the slice reconstruction. Use the following command for help with any flag for the script:

mri_3d_photo_recon -h
||--input_photo_dir ||Directory   with input pixel-corrected photos. ||
||--input_segmentation_dir ||Directory   with input slab masks/segmentations ||
||--ref_mask ||When   using a binary volume as a reference. ||
||--ref_surface ||Using   a 3D surface scan as a reference. ||
||--ref_soft_mask ||Using   the provided average atlas. Best for using retrospective processing on data   without a better reference. ||
||--mesh_reorient_with_indices ||Vertex   indices of the frontal pole, occipital pole, and top of the central sulcus,   separated with commas, for mesh alignment. ||
||--photos_of_posterior_side ||Use   when photos are taken of the posterior side of slabs (default is anterior   side). ||
||--order_posterior_to_anterior ||Use   when photos are ordered from posterior to anterior (default is anterior to   posterior). ||
||--allow_z_stretch ||Use   to adjust the slice thickness to best match the reference. You should   probably '''*never*''' use this with soft references (ref_soft_mask). ||
||--rigid_only_for_photos ||Switch   on if you want photos to deform only rigidly (not affine). ||
||--slice_thickness ||Slice   thickness in mm. ||
||--photo_resolution ||Resolution   of the photos in mm. ||
||--output_directory ||Output   directory with reconstructed photo volume and reference ||




In the bottom Freeview menu, we can find the number corresponding to each of the vertices of each of these areas.
|| {{attachment:43_vertexFP.png||width="304",height="254"}} || {{attachment:44_vertexOP.png||width="297",height="249"}} || {{attachment:45_vertexCS.png||width="302",height="253"}} ||
||Frontal Pole ||Occipital Pole ||Top of the central sulcus ||




These are used for the --mesh_reorient_with_indices flag, where indices are comma-separated in the order of frontal pole, occipital pole, and top of central sulcus. When using this flag, it will look something like:

 . –mesh_reorient_with_indices 999999,999999,999999

'''Example for running reconstruction''' <<BR>> mri_3d_photo_recon \

 . --input_photo_dir ./deformed \
 . --input_segmentation_dir ./connected_components \
 . --ref_surface ./mesh/case.stl \
 . --mesh_reorient_with_indices 999,1010,333333 \
 . --photos_of_posterior_side \ --allow_z_stretch \
 . --slice_thickness 8 \
 . --photo_resolution 0.1

<<BR>><<BR>><<BR>>

== 7. Photo-Synthseg Segmentation ==
+= Part 3: Downstream Tasks =
== Photo-Synthseg Segmentation ==
-Line 356:
+Line 224:
+|| {{attachment:43_synthseg_photo.jpg||height="400"}} || {{attachment:44_synthseg_parc.jpg||height="400"}} ||




'''Example for running SynthSeg on a Left Hemisphere''' <<BR>>

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