Serial Section Alignment Toolkit
Author: Tao Ju
Last Updated: April 14th, 2008 

-----------------------------
Introduction
-----------------------------

The toolkit is designed for aligning serially sectioned tissues, preferably Nissl-stained histology sections, with the direction of sectioning is vertical. Serial sectioning typically induces global (e.g., shifting and rotation) as well as local (e.g., stretching, compacting, folding, image artifacts, etc.) distortions, which makes direct 3D reconstruction difficult. This toolkit helps to correct both global and local distortions so that a smooth volume can be reconstructed with minimum human input. 

-----------------------------
Components
-----------------------------

The toolkit consists of two parts:

1. Rigid-body alignment (\rigidAligner)

2. Elastic alignment (\elasticAligner)

-----------------------------
Sample data
-----------------------------

A small stack of sample data can be found at:

http://www.cse.wustl.edu/~taoju/code/samples.zip  (original stack)
http://www.cse.wustl.edu/~taoju/code/samples_warped.zip (after elastic warp)

The data for the JNM paper can be found at:

http://www.cse.wustl.edu/~taoju/code/histology.zip (The original stack of 350 Nissl-stained coronal sections of the mouse brain)
http://www.cse.wustl.edu/~taoju/code/histology_equalnorm.zip (The stack after rigid body alignment, size/color equalization and histogram normalization)
http://www.cse.wustl.edu/~taoju/code/histology_warped.zip (The stack after elastic warp filtering using default parameters coming with this toolkit)

-----------------------------
System Requirements
-----------------------------

1. At least 256MB available memory

2. Windows 2000 or higher

3. Java 1.4 or 1.5 (compatibility with 1.6 has not be verified)


-----------------------------
Usage
-----------------------------

1. To use the toolkit, the source images must be placed under a single folder, and should be:
- JPEG format in RGB mode
- white background and dark forground


2. First, align the sections rigidly (if they are not already aligned). In \rigidAligner folder, type in the command prompt (src_folder contains the jpegs, des_folder contains the output jpegs):

java -Xmx256m -Xms256m ImageProcessor  <src_folder> <des_folder>

   (a) Press "Pre-process" for automatic translational alignment. It identifies the "object" in each image and translate the object so that its center of mass is at the image center. Note that it does not perform any rotational correction.
   (b) Press "Inspect" to verify alignment. This will open a new window where you can both inspect and repair the alignement (both translational and rotational)
       - Press UpArrow or DownArrow keys to go to next or previous image
       - Press "f" to fix an incorrectly aligned image. This will open a third window (see description below). 
       - When done, close the window.
   (c) Press "Commit changes" to repair fixed images
   (d) Repeat (b-c) as needed.
   (e) When done, close the dialog box (ignore the "3D Align" button).

The third window allows manual image alignment, and has two main features:
   (a) Locating object of interest. The center of the located object will be used to automatically translate the image. To pick an object, choose a threshold in the panel on the right. The thresholded tissue pieces will be colored blue. Note that only big pieces are shown. You may change the minimal size of a piece by adjusting the "cluster size" in the panel. You may click on each piece and select/de-select them by left/right mouse button. The selected pieces are shown in red. You can also select all or none using the controls. 
   (b) Locate the center line of the tissue. The located line will be used to translate and rotate the tissue so that the line coincides with the vertical center line of the image. Click on "Manual" under "Symmetry". Your cursor will turn to a cross shape. You can create a line by 2 mouse clicks.
   (c) When done, go "File"->"Save parameters" (or press "x" key) and close the window.
	

3. Next, warp all sections elastically. In \elasticAligner folder, type in the command prompt:

java ImageAligner

Before warping:

   (a) Load source image folder (if you just ran rigidAligner, this would be the <des_folder>). You can use UpArrow/DownArrow keys to browse through the images.
   (b) IMPORTANT: If the images are not the same size or is a colored image, use "3D -> Equalizer" option to unify images. This will bring up a separate dialog box, where you can specify the desination folder of the equalized images, the R/G/B channel to perform color->gray conversion, and the desired size of each output image.
   (c) If the images have widely ranging graylevels, use "3D -> view histogram" to find a median grayscale, and use "3D -> normalize" to normalize every image to that histogram.

Warping proceeds in two steps:

   Step 1: Use "3D -> Compute pairwise warps" to compute warps between successive images. The warps are stored in a user-specified folder. 
       - Content variability: the maximal allowed distance (on the image plane) from a pixel on one image to its corresponding pixels in the neighboring image (as a ratio over the height/width of the image)
       - Deformation constraint: how rigid the warps should be (higher value means more rigid and less flexible)
       - Press "OK" (ignore the "Test parameters..." button). This step typically takes 1-3 minutes per pair of successive images, depending on the image resolution (you can observe the progress by checking the ".dat" files in the output folder). 
   
   Step 2: Use "3D -> Reconstruct volume" to smoothly align all images based on the pairwise warps. It needs the folder where the pairwise warps are stored ("Warp file folder"), and outputs the aligned images in a different user-specified folder ("Desitnation folder").
       - Range of smoothing: size of neighborhood to use in smoothing (i.e., each image M in the original stack will be deformed to align with n images before M and the n images after M in the stack, where n is the number you pick). The higher the number, the smoother the volume. This smoothing does not change pixel values on each image, but deforms the image.
       - Range of filter: the higher the number, the less image noise (and blurrier the images). Unlike smoothing, this filter does not deform the image, but alters the pixel values to get rid of outliers (such as image noise).

After warping, you can view synthetic cuts through the middle of the reconstructed stack using the Visualization menu button.
