Registration page
Contents |
Software Modules for 3-D Image Registration & Large-scale Montage (Mosaic) Synthesis
The FARSIGHT registration module is a 3D extension of the Generalized Dual-Bootstrap Algorithm - one of the most robust available. The registration 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. The mosaic synthesis executable can generate the montage for a given channel, or one montage containing all channels in grayscale.
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. The required inputs are the two image names, including the path. The output is an XML file containing the pairwise transformation data for the pair of images. Too see the usage, 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 also
be downloaded at http://www.vision.cs.rpi.edu/gdbicp
-slices integer Number of slices to register. Needed when registering large image stacks on PC.
If not set, all slices are taken [100]
-scaling bool Substantial scaling is expected. [not set]
-prior bool xml file containing the initial transformation []
-? bool Print this message
Examples:
1. To register two lsm images, image1.lsm to image2.lsm, using all channels do (on Windows):
register_pair.exe image1.lsm image2.lsm
2. To register two lsm images, image1.lsm and image2.lsm, using channel 0 do (on Windows):
register_pair.exe image1.lsm image2.lsm -channel 0
register_joint
This executable is for registering a set of images jointly with global consistency. A file containing the names of xml files, each containing a pairwise transformation generated using register_pair, should be provided as the input to the executable. The default output file is joint_transforms.xml, which contains mutually consistent transformations for all image pairs in the set. Too see the usage, 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_pair, 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_. mosaic_images.exe is designed to output only grayscale images. For multi-channel images, the user may choose to generate a montage including all channels fused or a montage of a specific channel if the "channel" switch is set. 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. To montage a set of images using only channel 0 with transformations stored in joint_transforms.xml and image1.lsm as the anchor (reference) image, do
mosaic_images joint_transforms.xml image1.lsm -channel 0
3. -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_roi
This executable generates a region of interest of the montage using a set of transformations stored in an xml file, which is either generated by register_pair, or register_joint. The outputs of the operation are a xml file, a 2D projection of the region of interest, and a directory containing 2D image slices of the 3D region of interest, 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_. mosaic_roi.exe is designed to output only grayscale images. For multi-channel images, the user may choose to generate a region of a montage including all channels fused or a montage of a specific channel if the "channel" switch is set. To see the usage, type "-?". Mosaic_roi will create multiple sets of images. After the mosaic_roi is started it will prompt the user for a postscript that will be added to the output file names. Then it will prompt for the x y and z coordinates in the anchor space for the the origin of the region of interest. It will then prompt for the x y and z sizes for the region. This process will repeat until a "q" is entered for the postscript.
Usage:
mosaic_roi.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] - No effect Not yet implemented!
-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_roi 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. To montage a set of images using only channel 0 with transformations stored in joint_transforms.xml and image1.lsm as the anchor (reference) image, do
mosaic_images joint_transforms.xml image1.lsm -channel 0
3. -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
4. The region of interest origin and size are set in the montage image space specified by the anchor location. The origin can be a negative number.
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 transforms 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 reference_image_name are found in the xml file containing the 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 The file containing a list of (from_image_name feature_file_name) pairs,
one line per pair.
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 as well if its features are part of the global space. All points are first transformed to the reference space and shifted so that all coordinates have positive values.
Utility Programs for Montaging
To generate a color montage to better differentiate information in different channels, the user may run our utility programs multi_channels_2D.exe and multi_channels_3D.exe. Both the utility programs take a file that lists, one per line, the montage files for single channels and their RGB components and, the name for the output file:
multi_channels_2D.exe montage_color_list 2D_output_image
For example, to combine grayscale montages of 3 channels: channel0_montage.tiff, channel1_montage.tiff, and channel2_montage.tiff, with the first channel in red, second channel in blue and the third channel in green. The montage_color_list should contain the following:
channel0_montage.tiff 1 0 0 channel1_montage.tiff 0 0 1 channel2_montage.tiff 0 1 0
In this text file, the first column contains the montage file names, the second column is for the intensity value of the red color channel in the range of [0,1], the third column for the green color channel, and the fourth column for the blue color channel.
Scripts for Batch Processing
For montage synthesis of a large dataset, it is recommended that the user runs a python script to batch process the entire image set. Several python scripts are made available.
register_pairs
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 pairs of image names, one pair per line. The image path should not be part of a image name in pair_list_file, but given as image_dir input to the script instead. The script runs register_pair on the given pairs, register_joint using the generated pairwise transformations, and mosaic_images using the first image as the anchor. 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
register_list
If the spatial positions of images can be inferred from the image names, register_list can be used instead to save computation. To generate a montage given a set of image names in an input file do:
register_list image_dir image_list_file filename_pattern [channel_color_file]
Different from register_pairs, 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 channel_color_file is provided, a color montage of montages of individual channels will be generated in the same fashion as register_pairs.
register_all_pairs
If it is time-consuming to compile a list of image pairs or it is impossible to infer the adjacency information from the file names, register_all_pairs can be applied in this situation. This script runs register_pair on every image pair in the given set. The syntax is the same as register_list
register_all_pairs image_dir image_list_file [channel_color_file]
Piping console output from Windows to file
To pipe the output from stdout and stderr to a file, you need to do this
<command> > debug.txt > 2>&1
