find_rst
PURPOSE
find_rst takes pairs of images and attempts to find the rotation, scale, and translation that best maps the first image (a.k.a. the source image) into the second image (a.k.a. the target image). If the images differ appreciably in content or have signifcant distortions, this program may not be able to find the correct map, so a downstream inspector step is recommended in those situations.
TYPICAL USAGE
find_rst -pairs pairs.lst -input images/ -output initial_maps/
COMMAND LINE OPTIONS
-candidates max_number_of_candidates
specifies the maximum number of (rotation,scale,translation) candidates that should be printed out; however, only the best candidate will be used for the output map file. Default value for this is 1.
-distortion float_distortion_factor
specifies a guess at how distorted the images are, as a percentage of the overall image width or height; this measures how far a pixel must be displaced to match up with its corresponding pixel in the other image when the images are rigidly aligned. The default for this is 1%.
-feature min_feature_size_in_pixels[-max_feature_size_in_pixels]
specifies the range of features sizes that should be considered most important when doing the registration. The default for this is a minimum of 1 pixel to a maximum of halt the smallest dimension (width or height) of either image.
-frac_res float_fr1[,float_fr2[,float_fr3]]
specifies resolution parameters for doing the fractional Fourier transform. These should be in the range of 0 to 1.0. Generally, it is OK to go with the defaults of 1.0, 0.6, and 0.2. For more details, see the paper by Pan et al.
-images directory/
specifies the directory where the input images are stored
-margin margin_in_pixels
specifies the margin to be applied to the images to reduce edge-effects. By default this is 20% of the smallest dimension of the input image. If the images have very little overlap, it may be necessary to reduce this value so that the periphery has greater weight.
-mask directory/
specifies the directory where the input image masks are stored
-max_res maximum_FFT_resolution_in_pixels
specifies the resolution at which the FFTs will be performed. This will default to the smallest power of 2 that will accommodate both of the images. However, this can be exceedingly time-consuming and memory-intensive for large images, so a reasonable value for this option might be 2048.
-output directory/
specifies the directory into which the output maps will be written.
-output_images
if this option is given, then the intermediate images used in doing the registration will be saved in the output directory. This is useful for debugging purposes.
-pairs pairs.lst
specifies the list of image pairs that are to be registered. This list consists of lines of the following form:
image0_name [ image0_minX image0_maxX image0_minY image0_maxY ] image1_name [ image1_minX image1_maxX image1_minY image1_maxY ] pair_name
If the optional minX, maxX, minY, and maxY components are specified, they designate a subregion of the image to register. This is useful for instance when one is matching up the right side of one image with the left side of an overlapping image. To use the entire image, the minX, maxX, minY, and maxY compoments may be omitted, or they may all be set to -1. The pair_name is the name given to the image pair. Often, it will just consist of the individual image names concatenated together, perhaps with an intervening underscore or hyphen. Occasionally,as when many images are being registered to a single reference image, it would make sense for the pair name to just be the same as the image0_name.
-partial
if this option is given, ignore any image pairs that are missing, and do not report an error.
-reference directory/
specifies the directory where the reference images are stored; this may be the same as the -input directory
-reference_mask directory/
specifies the directory where the reference image masks are stored
-rotation min_theta_in_degrees[-max_theta_in_degrees]
specifies the range of rotations that the program will consider when registering the images; if the range of rotation can a priori be known to lie in some range, then this can be helpful in preventing spurious matches from being investigated that lie outside that range, thus speeding the program up. The rotation should be in the range 0 to 360 degrees, and represents how much the input image has to be turned clockwise [check this] to make it match up with the reference image. The default for this is 0-360 degrees.
-rs_candidates max_number_of_rotation_and_scale_candidates
specifies the maximum number of (rotation,scale) candidates that will be retained for further consideration; because the strongest (rotation, scale) candidate may not necessrily turn out to be the best candidate once translation is taken in account, it is beneficial (though slower) to consider how translation would affect more (rotation, scale) candidates. The default value for this is 4.
-scale min_scale_factor[-max_scale_factor]
specifies the range of scale adjustment that the program will consider when registering the images; if the scale range can a priori be known to lie in some range, then this can be helpful in preventing spurious matches from being investigated that lie outside that range, thus speeding the program up. The scale should be in the 0.1 to 10.0, and represents how much the input image has to be scaled up to make it match the reference image. The default for this is 0.5 to 2.0.
-summary summary.out
If this option is given, then write out a summary of each pair's registration scores to the specified file.
-trans_feature min_trans_feature_size_in_pixels[-max_trans_feature_size_in_pixels]
specifies the range of feature sizes to use when computing the image translation; by default, all features sizes will be used.
-tx min_x_translation_percentage[-max_x_translation_percentage]
specifies the range of possible x translations that the program will consider when reigstering the images; if the translation can a priori be known to lie in some range, then this can be helpful in preventing spurious matches from being investigated that lie outside that range, thus speeding the program up. This translation should be expressed a signed percentage of the image width; a negative percentage indicates a translation to the left; a positive percentage a translation to the right.
-ty min_y_translation_percentage[-max_y_translation_percentage]
specifies the range of possible y translations that the program will consider when reigstering the images; if the translation can a priori be known to lie in some range, then this can be helpful in preventing spurious matches from being investigated that lie outside that range, thus speeding the program up. This translation should be expressed a signed percentage of the image height; a negative percentage indicates a translation upward; a positive percentage a translation downward.
-update
If this option is specified, then only perform the registration for image pairs where the output map is non-existent or older than the input files (images, masks, etc.).