Registration page
Contents |
Software Modules for 3-D Image Registration & Large-scale Montage (Mosaic) Synthesis
The FARSIGHT registration modules are based on a 3-D Generalized Dual-Bootstrap Algorithm - one of the most robust available. The mosaic synthesis methods are capable of registering image tiles jointly enabling them to be utilized on a large scale.
There are two executables for registration, one is to register an image pair and one is to jointly register a bunch of images given the pairwise transformations.
How to Download
The executables described in this page can be downloaded from:
- Select "individual modules" from "Type of download".
- Then you will find the executables if you click on "File to download"
Alternatively you can visit the farsight contents page:
register_pair
This executable is for registering a pair of images. Too see the useage, type "-?"
Usage:
register_pair.exe [string] [string] [-channel integer] [-bg float] [-smooth float] [-gdbicp string]
[-slices integer] [-remove_2d bool] [-scaling bool]
REQUIRED:
string From image file
string To image file
Optional:
Switch Type Help [default value]
-channel integer The color channel (0-red, 1-green, 2-blue), or the image channel if the original image is a
lsm image. [0]
-bg float threshold value for the background [30]
-smooth float If smoothing is performed [0.5]
-gdbicp string The path where the gdbicp exe can be found. The executable of gdbicp can be found at
http://www.vision.cs.rpi.edu/gdbicp
-slices integer Number of slices to register. Needed when registering large i mage stacks on PC. [100]
-scaling bool Substantial scaling is expected. [not set]
-? bool Print this message
Examples:
1. To register two lsm images, image1.lsm and image2.lsm, using all channels do (on Windows):
regiser_pairs.exe image1.lsm image1.lsm
2. To register two lsm images, image1.lsm and image2.lsm, using channel 0 do (on Windows):
regiser_pairs.exe image1.lsm image1.lsm -channel 0
register_joint
This executable is for registering a set of images jointly with global consistency. A list of xml files, each containing a pairwise transformation generated using regiser_pair, should be provided as the input to the executable. Too see the useage, type "-?"
Usage:
register_joint.exe [string] [-output string] [-multiplier float] [-error_bound float] [-quick bool] [-roi string]
REQUIRED:
string A file containing filenames of xml files, each containing a pairwise transformation.
Optional:
Switch Type Help [default value]
-output string Output xml filename ['joint_transforms.xml']
-multiplier float The multiplier for the error scale. 4 is a good value. It is better to tune the error_bound
using this parameter. [0]
-error_bound float The upper bound for the accepted error in the range of [-1,0]. When set to 0, all pairs are
accepted [0]
-quick bool No mutual consistency is imposed [not set]
-roi string Text file containing the list of image names in the ROI []
-? bool Print this message
If -multiplier is set, pairwise transformations with higher errors are excluded in the computation.
Executables for Montaging
There are two executables for generating image montages from existing transformations, one GUI executable for navigating the montage, and one executable for transforming segmentation results to a common reference space.
mosaic_images
This executable generate the montage using a set of transformations stored in an xml file, which is either generated by register_pairwise, or register_joint. The outputs of the operation are a xml file, a 2D projection of the image montage, and a directory containing 2D image slices of the 3D image, which can also be generated upon request. All outputs have the same filename (but different extensions). If the filename not specified, it is the filename of the anchor image prefixed with montage_. To see the usage, type "-?"
Usage:
mosaic_images.exe [string] [string] [-channel integer] [-path string] [-old_str string] [-new_str string]
[-output string] [-in_anchor bool] [-overlap_only bool] [-nn bool] [-blending integer]
[-denoise bool]
REQUIRED:
string A xml file containing transformations
string Anchor image name
Optional:
Switch Type Help [default value]
-channel integer The color channel (0-red, 1-green, 2-blue), or the image channel if the original image is
lsm image. [0]
-path string The path of the image files. ['.']
-old_str string The old substr in the image names to be replaced []
-new_str string The new substr in the image names []
-3d bool Generate a 3D image as well [not set]
-output string The name of the output []
-in_anchor bool The final space is set to the anchor image [not set]
-overlap_only bool Only consider images that overlap the anchor image [not set]
-nn bool Use Nearest-Neighbor interpolation [not set]
-blending integer 0: max (default), 1: even weighted, 2: photopleaching weighted (the fanciest). [0]
-denoise bool Making an attempt to remove noise of high frequencies [not set]
-? bool Print this message
Examples:
1. To montage a set of images in the parent directory with transformations stored in joint_transforms.xml and image1.lsm as the anchor (reference) image, do
mosaic_images joint_transforms.xml image1.lsm -path ../
If -output not specified, the montage is stored in the directory named montage_image1 and the xml file is montage_image1.xml. A 2D maximum projection is also generated and is named montage_image1_2d_proj.png in this example.
2. -old_str and -new_str can be used to change the image names recorded in the xml files. The string following -old_str is what to be replaced, and the string following -new_str is what to be replaced with. For example, if the image names in the xml file is *.lsm and the images for montaging are *.tiff, the previous example becomes
mosaic_images joint_transforms.xml image1.tiff -path ../ -old_str .lsm -new_str .tiff
mosaic_image_pair
This executable generates a color montage for inspection of the quality of registration. The transformation can be from either pairwise or joint registration stored in an xml file. One image is displayed in green and one in red. The region of overlap should be in yellow for good alignment. The result of the operation is an xml file, a 3D image, a 2D projection, and a directory containing 2D image slices of the 3D image. All outputs have the same filename (different extensions). If the output filename not specified, it is the filename of the to_image prefixed with pairwise_montage_ . To see the usage, type "-?"
Usage:
mosaic_image_pair.exe [ string] [ string] [ string] [-channel integer] [-path string] [-old_str string]
[-new_str string] [-output string] [-in_anchor bool]
REQUIRED:
string xml file for transforms []
string From_image name []
string To_image name []
Optional:
Switch Type Help [default value]
-channel integer The color channel (0-red, 1-green, 2-blue), or the image channel if the original image is
lsm image. [0]
-path string The path of the image files. ['.']
-old_str string The old substr in the image names to be replaced []
-new_str string The new substr in the image names []
-output string The name of the outuput image []
-in_anchor bool The output image is the size of the anchor image [not set]
-? bool Print this message
To navigate the montage, load the xml of the montage generated by mosaic_images. The user can click on the montage to see the coordinates of a point in the original images. To generate cropped regions, the user has to provide the image directory which contains the montage to be cropped from. The reason for having to choose a directory when saving a cropped region is to make it possible to pick a montage directory of another channel of the same image set for cropping.
transform_segmentation_results
This executable transform all point locations in one image to a given image as the reference frame. To handle transformation of a variety of segmented objects, the segmentation results are stored in a plain text file (feature_file) in the following format:
image_name_for_segmentation ID x y z feature1 feature2 ... ID x y z feature1 feature2 ... ...
Each feature_file starts with the name of the image for segmentation as the first line. Following the image name are the features for segmented objects, one line per object. Only the first 4 fields are essential and only the coordinates are transformed. Other features are transferred directly to the output file. The output file contains the following information:
image_name_for_segmentation FROM from_image_name TO reference_image_name ID xformed_x xformed_y xformed_z feature1 feature2 ... ID xformed_x xformed_y xformed_z feature1 feature2 ... ...
Both from_image_name and regerence_image_name are found in the xml file for transformations. To run the executable:
Usage: transform_segmentation_results.exe [ string] [ string] [ string] [-output_prefix string]
REQUIRED:
string The xml file containing transformations. []
string The reference image name in the transformation file. []
string List of (from_image_name feature_file_name) pairs. []
Optional:
Switch Type Help [default value]
-output_prefix string The prefix for the output file. If not given, the default is transformed_ ['transformed_']
-? bool Print this message
Please note, The pair for the reference image should be included if its features are part of the global space too. All points are first transformed to the reference space and shifted so that all coordinates have positive values.
Scripts for Batch Processing
To generate a montage given image names in pairs in an input file do:
register_pairs image_dir pair_list_file [channel_color_file]
The pair_list_file contains a pair of image names per line. The script runs register_pairwse on the given pairs, register_joint using the generated pairwise transformations, and mosaic_images using the first image an the anchor. If only one image pair is provided in the input file, a pairwise montage is generated using mosaic_image_pair, which displays the two images with two different colors. Image pairs that fail to register are stored in file pair_list_file.failed_pairs.
channel_color_file is optional. If provided for multi-channel images, such as lsm, the montages of individual channels are generated and a 2D-projected, superimposed montage is produced using colors specified in channel_color_file, which contains the RGB ratios of one data channel per line. For example, if the lsm image contains two channels: channel 0 in green and channel 1 in blue. The channel_color_file contains
0 1 0 0 0 1
To generate a montage given a set of image names in an input file do:
regiser_list image_dir image_list_file filename_pattern [channel_color_file]
Different from register_pairs, this register_list first figures out the adjacent image pairs based on the filename_pattern. Both 1D and 2D adjacency is allowed. The filename_pattern should be double-quoted. Examples for filename_pattern specification:
Example1: For a 1D image series containing mcnor_5-8-06_arc_bk2_26_ca3_2_7.lsm and
mcnor_5-8-06_arc_bk2_26_ca3_2_10.lsm, the filename_pattern is
"mcnor_5-8-06_arc_bk2_26_ca3_2_([0-9]*).lsm"
Example2: For a 2D image series containing Slide61Lbox003F_ChS1-T2.tiff and Slide61Lbox001A_ChS1-T2.tiff,
the filename_pattern is "Slide61Lbox00([0-9])([A-Z])_ChS1-T2.tiff"
If the image_list_file contains only two images, a pairwise, color montage is generated as for register_pairs.
