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/orty
(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 2tuple (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 commandline arguments.
Returns: Contains following keys:
scale
,angle
,tvec
(Y, X),success
andtimg
(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 (clockwise)
 tvec (2tuple) – Pixel translation vector, Y and X component.
 mode (string) – The transformation mode (refer to e.g.
scipy.ndimage.shift()
and its kwargmode
).  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 thesimilarity()
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
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 keystx
and/orty
(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