register

PURPOSE

register takes pairs of images, and finds a non-linear mapping that registers the first image of the pair (the source image) to the second (the target image).  If the images differ substantially in content or have obvious distortions or artifacts, it is recommended that the output maps from register are checked with inspector.  If errors are found, one can use inspector to add correspondence points and rerun register with the -cpts option.

 

TYPICAL USAGE

register -pairs pairs.lst  \
            -images images/  \
            -masks masks/  \
            -output_level 6  \
            -depth 6  \
            -quality 0.5 \
            -output maps/
            

COMMAND LINE OPTIONS

-affine

When correspondence points are provided, use the best affine transformation derived from these correspondence points as the initial map.

-all_maps

If specified, this option causes all intermediate maps to be written out, not just the one at final resolution.  (mostly for debugging)

-constraining float_weight

This options controls how much deviations from a constraining map are weighted when searching for a registration.  If no constraining_map option is given, this option has no effect.

-constraining_confidence_threshold float_threshold

If this option is given, then only consider map elements in the constraining map that have a confidence value greater than the given threshold.  If no constraining_map option is given, this option has no effect.

-constraining_map directory/

If specified, use a constraining map to restrict the search for a registration.  A constraining map is used as a hint for where the correct solution should lie.    When evaluating a map the search algorithm will check if the distance between points projected using the map being evaluated and points projected using the constraining map.  If their distance is greater than the constraining_threshold, then a penalty term is added onto the evaluation.

-constraining_threshold float_distance_in_pixels

The constraining threshold represents the geometrical uncertainty (expressed in pixel distances in the original images) of the constraining map.  Larger values mean the constraining map is more uncertain, and a 0 value means that any variation from the constraining map will be penalized (not terribly useful).   The default value is 0, so one should include this option if one is using constraining maps.

-correlation_half_width int_distance_in_pixels

This sets the half width of the kernel used for computing localized image correlation.   The localized image correlation is only used for output (in determining the confidences of the map elements), and is not used in actually performing the registration.  Defaults to 31.

-correspondence float_weight

This option controls how much deviations from the correspondence points are weighted when searching for a registration.  If no correspondence points are available for the image pair, this option has no effect.  The default value is 1.

-correspondence_threshold float_distance_in_pixels

If this option is given, then do not penalize maps that project the correspondence points to within this distance of each other.  This is useful when there is some uncertainty in marking up the correspondence points, or even just to compensate for slight mouse movement that happened when the used was clicking the mouse to mark the correspondence points.  The default value is 0.

-cpts directory/

use the correspondence points found in the given directory.  The name of the correspondence points file is generated by appending ".cpts" to the image pair name.  The correspondence points file is usually automatically generated by the inspect program, but can also be manually generated and edited.  The format of the correspondence points file is a list of correspondence point pairs:

 img_x img_y ref_x ref_y

 where img_x iand img_y are the x and y coordinates of a point in the image, and ref_x and ref_y are the coordinates of the corresponding point in the reference image.

-depth int_depth_exponent

sets the ratio between the map resolution and image resolution as the program registers the images.  For example, if this is set to 6, then when computing the 16x16 map, the images at resolution 1024x1024 will be used when computing the correlation (since 16 * 2^6 = 1024).  This same ratio will be used as the map resolution is progressively increased, until the native image resolution is reached. This parameter defaults to 6.

-distortion float_weight

This option controls how much map distortion (i.e., the deviation of each element from a perfect square) is weighted when searching for a registration.  This parameter defaults to 1.  Set it lower to tolerate more distortion, and set it higher to tolerate less distortion.

-images directory/

specifies the directory where the images will be read from.

-initial_map directory/

specifies the directory where the initial maps will be read from.

 -logs directory/

specifies the directory where log files are written to; if this option is omitted, no log files will be written.

-masks directory/

specifies the directory where the masks will be read from.

-min_overlap float_percentage

specifies the minimum percentage overlap between the images.  This avoids the problem of finding a "perfect registration" by overlapping a single corner pixel in one image with another corner pixel in the other image that happens to have the same value.  The default value for this parameter is 20.

-min_res int_resolution_in_pixels

specifies that images should not be reduced to a size smaller than the given number pixels in either x or y.   This is to prevent excessive reduction that would blur out details important for registration.  The default value is 1, which allows for arbitrary reduction.

-output directory/

specifies the output directory where maps are to be written.

-output_correlation directory/

specifies the directory where correlation images should be written to.  The correlation image is white where the correlations are highest and black where they are lowest.  The correlation image is congruent with the first image of the image pair.  If this option is omitted, no correlation images will be output.

-output_level int_level

specifies the level of resolution of the output maps.  This is expressed as the base-2 logarithm of the pixel distance between map points (in both x and y diimensions).  For example, a value of 6 would indicate that the maps should have a grid point every 64 pixels in x and y.  Typical values for this range from 6 to 10.  The default value is 6.

-output_mask directory/

specifies where optional output masks are located.  Note that the output mask is an input to the register program.  If this option is present, the output mask will determine which map elements get filled in by the register program; only those map elements necessary to cover the unmasked pixels will get filled in.  The masks in the output_mask directory should have the same width and height as the first component of the image pair.

-output_pairs outpairs.lst

If this option is present, then the pairs that were actually updated will be written to the specified list file.  Use this in conjunction with the -update option.

-output_pairwise_mask directory/

This option is very similar in function to the -output_mask option.  The difference is that with -output_pairwise_mask , the image pair name is used to construct the name of the output mask file that will be read in, whereas with -output_mask only the name of the first image of the pair is used to construct the name of the output mask file.

-output_sorted_pairs outpairs.lst

If this option is present, then the pairs that were actuall updated will be sorted according to registration score (lowest first) and then written to the specified list.  The registration score is better for those pairs for which the program is more confident of a good match.  Thus, this enables the user to go through suspect pairs first until reaching pairs whose registration is likely correct.  Both this option and the -output_pairs option may be used together.

-output_warped directory/

If this option is present, then the second member of the image pair (the reference image) will be warped to match the first image, and the resultant image will be written to the specified directory as a .pgm file.   The output resolution will match that of the first image.  Note that the apply_map program offers this capability as well, but with many more options.

-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 specirfied, then ignore pairs for which some of the necessary files (image files or mask files) are missing.  By default, an error will be generated if files are found to be missing, and program execution will terminate.

-quadratic

When correspondence points are provided, use the best quadratic transformation derived from these correspondence points as the initial map.

-quality float_quality

The option specifies how much search is to be performed to look for the best registration.  The number of iterations (and hence run time) correlates roughly linearly with the quality parameter.  Typical values are in the 0.1-10.0 range.  A too small value for this parameter will generate a solution quickly, but its quality will be poor.  On the other hand, choosing too large a value will take a large amount of processing time, with no guarantee of a correct solution.   If the images differ greatly, or are noisy, or contain repeated subimages, or have incorrect initial maps, then the program may generate incorrect results even with a high quality parameter.  The default value is 1.0.

-rigid

When correspondence points are provided, use the best rigid transformation derived from these correspondence points as the initial map.

-start_level int_level

Specifies the starting level of resolution for map generation.  By default, the program will determine this from the resolution of the images to be registered.  However, if there is a lack of low-frequency content in the images, it is possible that starting at too high a level (= low image resolution) will cause the images to be excessively downsized and not contain registerable content.  This option can be used to force the program to start at a specific map level.  For instance, if this is set to 10, then the first maps to be computed will have each map element corresponding to a 1024x1024 pixel subregion in the first image.  The image resolution level where correlation is performed will be -depth (q.v.) levels below this, so if the depth is 6, then the images will be downsampled to level 4, i.e., by a factor of 16 from the originals.

-strict_masking

If this option is specified, then map elements will only be computed for image regions where every pixel is unmasked.  Normally, map elements will be computed for image regions where any pixel is unmasked.

-summary summary_file.out

If this option is given, then write out a summary of each pair's registration scores to the specified file.

-tif

If this option is specified along with the -output_warped option, then warped images will be written out as .tif files; otherwise they will be written as .pgm files.

-translation

When correspondence points are provided, use the best translation transformation (no rotation or scaling) derived from these correspondence points as the initial map.

-trim_map_source_threshold float_percentage

If this option is given, then remove map elements where the percentage of valid source (a.k.a. image0) pixels underneath the map element  is less than the specified percentage.  This can be used to remove map elements around the periphery of an image that have a minimal number of pixels inside them, and thus may not be the most reliably positioned.  This option is only applied after map computations are complete, in contrast to the -strict_masking option which is applied while map computations are being done.

-trim_map_target_threshold float_percentage

If this option is given, then remove map elements where the percentage of valid target (a.k.a image1 or reference) pixels underneath the map element is less than the specified percentage.  This can be used to remove map elements around the periphery of an image that have a minimal number of pixels inside them, and thus may not be the most reliably positioned.

-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, correspondence points, etc.).  This option is especially useful when correspondence points are being added or modified to correct poor registrations.

-vis

This option causes the program, when used in an X windows environment, to graphically display the map refinement as the algorithm proceeds.  This has a significant impact on performance, so is probably best used for debugging.