Use as a Python module

The following is the public API of imreg_dft.

See the Python examples section to see how to use it.

imreg module

FFT based image registration. — main functions

imreg_dft.imreg.imshow(im0, im1, im2, cmap=None, fig=None, **kwargs)

Plot images using matplotlib. Opens a new figure with four subplots:

+----------------------+---------------------+
|                      |                     |
|   <template image>   |   <subject image>   |
|                      |                     |
+----------------------+---------------------+
| <difference between  |                     |
|  template and the    |<transformed subject>|
| transformed subject> |                     |
+----------------------+---------------------+
Parameters:
  • im0 (np.ndarray) – The template image
  • im1 (np.ndarray) – The subject image
  • im2 – The transformed subject — it is supposed to match the template
  • cmap (optional) – colormap
  • fig (optional) – The figure you would like to have this plotted on
Returns:

The figure with subplots
Return type:

matplotlib figure
imreg_dft.imreg.similarity(im0, im1, numiter=1, order=3, constraints=None, filter_pcorr=0, exponent='inf', reports=None)

Return similarity transformed image im1 and transformation parameters. Transformation parameters are: isotropic scale factor, rotation angle (in degrees), and translation vector.

A similarity transformation is an affine transformation with isotropic scale and without shear.

Parameters:
  • im0 (2D numpy array) – The first (template) image
  • im1 (2D numpy array) – The second (subject) image
  • numiter (int) – How many times to iterate when determining scale and rotation
  • order (int) – Order of approximation (when doing transformations). 1 = linear, 3 = cubic etc.
  • filter_pcorr (int) – Radius of a spectrum filter for translation detection
  • exponent (float or 'inf') – The exponent value used during processing. Refer to the docs for a thorough explanation. Generally, pass “inf” when feeling conservative. Otherwise, experiment, values below 5 are not even supposed to work.
  • constraints (dict or None) –

    Specify preference of seeked values. Pass None (default) for no constraints, otherwise pass a dict with keys angle, scale, tx and/or ty (i.e. you can pass all, some of them or none of them, all is fine). The value of a key is supposed to be a mutable 2-tuple (e.g. a list), where the first value is related to the constraint center and the second one to softness of the constraint (the higher is the number, the more soft a constraint is).

    More specifically, constraints may be regarded as weights in form of a shifted Gaussian curve. However, for precise meaning of keys and values, see the documentation section Using constraints. Names of dictionary keys map to names of command-line arguments.
Returns:

Contains following keys: scale, angle, tvec (Y, X), success and timg (the transformed subject image)
Return type:

dict

Note

There are limitations

  • Scale change must be less than 2.
  • No subpixel precision (but you can use resampling to get around this).
imreg_dft.imreg.similarity_matrix(scale, angle, vector)

Return homogeneous transformation matrix from similarity parameters.

Transformation parameters are: isotropic scale factor, rotation angle (in degrees), and translation vector (of size 2).

The order of transformations is: scale, rotate, translate.

imreg_dft.imreg.transform_img(img, scale=1.0, angle=0.0, tvec=(0, 0), mode='constant', bgval=None, order=1)

Return translation vector to register images.

Parameters:
  • img (2D or 3D numpy array) – What will be transformed. If a 3D array is passed, it is treated in a manner in which RGB images are supposed to be handled - i.e. assume that coordinates are (Y, X, channels).
  • scale (float) – The scale factor (scale > 1.0 means zooming in)
  • angle (float) – Degrees of rotation (clock-wise)
  • tvec (2-tuple) – Pixel translation vector, Y and X component.
  • mode (string) – The transformation mode (refer to e.g. scipy.ndimage.shift() and its kwarg mode).
  • bgval (float) – Shade of the background (filling during transformations) If None is passed, imreg_dft.utils.get_borderval() with radius of 5 is used to get it.
  • order (int) – Order of approximation (when doing transformations). 1 = linear, 3 = cubic etc. Linear works surprisingly well.
Returns:

The transformed img, may have another i.e. (bigger) shape than the source.
Return type:

np.ndarray
imreg_dft.imreg.transform_img_dict(img, tdict, bgval=None, order=1, invert=False)

Wrapper of transform_img(), works well with the similarity() output.

Parameters:
  • img –
  • tdict (dictionary) – Transformation dictionary — supposed to contain keys “scale”, “angle” and “tvec”
  • bgval –
  • order –
  • invert (bool) – Whether to perform inverse transformation — doesn’t work very well with the translation.
Returns:

See also

transform_img()
Return type:

np.ndarray
imreg_dft.imreg.translation(im0, im1, filter_pcorr=0, odds=1, constraints=None, reports=None)

Return translation vector to register images. It tells how to translate the im1 to get im0.

Parameters:
  • im0 (2D numpy array) – The first (template) image
  • im1 (2D numpy array) – The second (subject) image
  • filter_pcorr (int) – Radius of the minimum spectrum filter for translation detection, use the filter when detection fails. Values > 3 are likely not useful.
  • constraints (dict or None) – Specify preference of seeked values. For more detailed documentation, refer to similarity(). The only difference is that here, only keys tx and/or ty (i.e. both or any of them or none of them) are used.
  • odds (float) – The greater the odds are, the higher is the preferrence of the angle + 180 over the original angle. Odds of -1 are the same as inifinity. The value 1 is neutral, the converse of 2 is 1 / 2 etc.
Returns:

Contains following keys: angle, tvec (Y, X),

and success.
Return type:

dict