Registration page

Latest revision as of 17:25, 15 November 2011

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:

• http://www.farsight-toolkit.org/wiki/Special:FarsightDownloads

• 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:

• http://www.farsight-toolkit.org/wiki/Table_of_Contents

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

MontageNavigator

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