Command-line tool overview

The package contains three Python CLI scripts. Although you are more likely to use the imreg_dft functionality from your own Python programs, you can still have some use to the ird front-end.

There are these main reasons why you would want to use it:

  • Quickly learn whether imreg_dft is relevant for your use case.
  • Quickly tune the advanced image registration settings.
  • Use ird in a script and process batches of images instead of one-by-one. (ird can’t do it, but you can call it in the script, possibly using GNU Paralell.)

Additionally, there are two more scripts — see their documentation in the utilities section.

General considerations

Generally, you call ird with two images, the first one being the template and the second one simply the subject. If you are not sure about other program options, run it with --help or --usage arguments:

[user@linuxbox examples]$ ird -h
usage: ird [-h] [--lowpass LOW_THRESH,HIGH_THRESH]
           [--highpass LOW_THRESH,HIGH_THRESH] [--cut LOW_THRESH,HIGH_THRESH]
           [--resample RESAMPLE] [--iters ITERS] [--extend PIXELS]
           [--order ORDER] [--filter-pcorr FILTER_PCORR] [--print-result]
           [--print-format PRINT_FORMAT] [--tile] [--version]
           [--angle MEAN[,STD]] [--scale MEAN[,STD]] [--tx MEAN[,STD]]
           [--ty MEAN[,STD]] [--output OUTPUT] [--loader {pil,mat,hdr}]
           [--loader-opts LOADER_OPTS] [--help-loader] [--show]
           template subject

...

The notation [foo] means that specifying content of brackets (in this case foo) is optional. For example, let’s look at a part of help [--angle MEAN[,STD]]. The outer square bracket means that specifying --angle is optional. However, if you specify it, you have to include the mean value as an argument, i.e. --angle 30. The inner square brackets then point out that you may also specify a standard deviation, in which case and you separate it from the mean using comma: --angle 30,1.5. There are sanity checks present, so you will be notified if you commit a mistake.

So only the input arguments are obligatory. Typically though, you will want to add arguments to also get the result:

  1. Take an instant look at the registration result — use the --show argument.
  2. Learn the registration parameters: Use the --print-result argument (explained in greater detail below).
  3. Save the transformed subject: Use the --output argument.

The image registration works best if you have images that have features in the middle and their background is mostly uniform. If you have a section of a large image and you want to use registration to identify it, most likely, you will not succeed.

For more exhaustive list of known limitation, see the section Caveats.

Quick reference

  1. Quickly find out whether it works for you, having the results (optionally) shown in a pop-up window and printed out. We assume you stand in the root of imreg_dft cloned from the git repo (or downloaded from the web).

    [user@linuxbox imreg_dft]$ ird resources/examples/sample1.png resources/examples/sample2.png --show --print-result
scale: 1 +-0.003212
angle: 0 +-0.1125
shift (x, y): -19, 79 +-0.25
success: 1

    The output tells you what has to be done with the subject so it looks like the template.

    Warning

    Keep in mind that images have the zero coordinate (i.e. the origin) in their upper left corner!

  2. You can have the results print in a defined way. First of all though, let’s move to the examples directory:

    [user@linuxbox imreg_dft]$ cd resources/examples
[user@linuxbox examples]$ ird sample1.png sample2.png --print-result --print-format 'translation:%(tx)d,%(ty)d\n'
translation:-19,79

    You can get an up-to-date listing of possible values you can print using the help argument. Generally, you can get back the values as well as confidence interval half-widths that have a D prefix. For example there is angle and Dangle; in case that the method doesn’t fail misreably, the true angle will not differ from angle more than over Dangle.

  3. Let’s try something more tricky! The first and third examples are rotated against each other and also have a different scale.

    [user@linuxbox examples]$ ird sample1.png sample3.png --print-result --show
scale: 1.2475 +-0.004006
angle: -30.0493 +-0.1125
shift (x, y): 34.7935, 72.159 +-0.25
success: 0.9034

  4. And now something even more tricky - when a part of the subject is cut out. The difference between the fourth and third image is their mutual translation which also causes that the feature we are matching against is cut out from the fourth one.

    Generally, we have to address the this The --extend option here serves exactly this purpose. It extends the image by a given amount of pixels (on each side) and it tries to blur the cut-out image beyond its original border. Although the blurring might not look very impressive, it makes a huge difference for the image’s spectrum which is used for the registration. So let’s try:

    [user@linuxbox examples]$ ird sample1.png sample4.png --extend 20 --show --print-result --iter 4
scale: 1.2474 +-0.00373
angle: -30.0789 +-0.10227
shift (x, y): 158.79, 94.9163 +-0.25
success: 0.6112

    As we can see, the result is correct.

    Extension can occur on-demand when the scale change or rotation operations result in image size growth. However, whether this will occur or not is not obvious, so it is advisable to specify the argument manually. In this example (and possibly in the majority of other examples) specifying the option manually is not needed.

    Warning

    If the image extension by blurring is very different from how the image really looks like, the image registration will fail. Don’t use this option until you become sure that it improves the registration quality.

  5. Buy what do we actually get on output? You may wonder what those numbers mean. The output tells you what has to be done with the image so it looks like the template. The scale and angle information is quite clear, but the translation depends on the center of scaling and the center of rotation...

    So the idea is as follows — let’s assume you have an image, an imreg_dft print output and all you want is to perform the image transformation yourself. The output describes what operations to perform on the image so it is close to the template. All transformations are performed using scipy.ndimage.interpolate package and you need to do the following:

    1. Call the zoom function with the provided scale. The center of the zoom is the center of the subject.
    2. Then, rotate the subject using the rotate function, specifying the given angle. The center of the rotation is again the center of the subject.
    3. Finally, translate the subject using the shift function. Remember that the y axis is the first one and x the second one.
    4. That’s it, the subject should now look like the template.

  6. Speaking of which, you can have the output saved to a file. This is handy for example if you record the same thing with different means (e.g. a cell recorded with multiple microscopes) and you want to examine the difference between them on a pixel-by-pixel basis. In order to be able to exploit this feature to its limits, read about loaders, but you can simply try this example:

    [user@linuxbox examples]$ ird sample1.png sample3c.jpg --iter 3 --print-result --output color.jpg
scale: 1.2493 +-0.004012
angle: -30.0184 +-0.1125
shift (x, y): 34.9015, 72.786 +-0.25
success: 0.6842

    To sum it up, the registration is a process performed with images somehow converted to grayscale (for example as the average across all color chanels). However, as soon as the transformation is known, an RGB image can be transformed to match the template and saved in full color.

Loaders

ird can support a wide variety of input formats. It uses an abstract means of how to load and save an image.

To cut the long story short — you probably want to autodetection of how to load an image based on the file extension. The list of available loaders is obtained by passing the --help-loader. To inquire about meaning of individual options, also specify a loader on the same command-line, e.g. pass --loader pil.

To pass an option to change loader properties pass a --loader-opts argument. It accepts comma-separated option name=value pairs, so for example the mat loader understands --loader-opts in=imgdata,out=timgdata. Note that all loaders have access to passed options.

The loaders concept functionality is limited by now, but it can be extended easily by writing code. See the developer documentation to learn the background. If you miss some functionality, you are kindly invited to create a pull request!

Caveats

There are known weak points of ird. Although they are explained in other places in the text, we sum them up here:

Extending images.
Due to the fact that the spatial frequencies spectrum is used, the border of images are become important. We address it here by extending the image, but it often doesn’t work well.
Sub-pixel resolution.
This is a tricky matter. Since the frequency spectrum is used, neither linear or cubic interpolation guarantee an improvement. However, the log-polar transform is used with linear interpolation, since it has been observed that it has a positive impact on the result. For a more correct approach, you can try the resampling feature, but beware — you have to have correctly sampled (i.e. not undersampled) input for it to work.
Big template.
If the template presents a wider field of view than the image, you may or may not be successful when using the --tile option. The current implementation is flaky.
Success value.
The Success that is reported has an unclear meaning. And its behavior is also quite dodgy.