Quickstart guide

Installation

Before installing imreg_dft, it is good to have dependencies sorted out. numpy and scipy should be installed using package managers on Linux, or downloaded from the web for OSX and Windows.

The easy(_install) way

You can get the package from PyPi, which means that if you have Python setuptools installed, you can install imreg_dft using easy_install. For a user (i.e. not system-wide) install, insert --user between easy_install and imreg_dft. User install does not require administrator priviledges, but you may need to add the installation directories to your system path, otherwise the ird script won’t be visible.

[user@linuxbox ~]$ easy_install imreg_dft

If you have pip installed, you can use it instead of easy_install. pip even allows you to install from the source code repository:

[user@linuxbox ~]$ pip install git+https://github.com/matejak/imreg_dft.git

The source way (also easy)

The other means is to check out the repository and install it locally (or even run imreg_dft without installation). You will need the git version control system to obtain the source code:

[user@linuxbox ~]$ git clone https://github.com/matejak/imreg_dft.git
[user@linuxbox ~]$ cd imreg_dft
[user@linuxbox imreg_dft]$ python setup.py install
...

As with other Python packages, there is a setup.py. To install imreg_dft, run python setup.py install. Add the --user argument after install to perform user (i.e. not system-wide) install. As stated in the previous paragraph, the user install does not require administrator priviledges, but you may need to add the installation directories to your system path, otherwise the ird script won’t be visible.

If you want to try imreg_dft without installing it, feel free to do so. The package is in the src directory.

Quickstart

A succesful installation means that:

• The Python interpreter can import imreg_dft.
• There is the ird script available to you, e.g. running ird --version should not end by errors of any kind.

Note

If you have installed the package using pip or easy_install, you don’t have the example files, images nor test files. To get them, download the source archive from PyPi or release archive from Github and unpack them.

Python examples

The following examples are located in the resources/code directory of the project repository or its source tree as similarity.py and translation.py. You can launch them from their location once you have installed imreg_dft to observe the output.

The full-blown similarity function that returns parameters (and the transormed image):

import os

import scipy as sp
import scipy.misc

import imreg_dft as ird


basedir = os.path.join('..', 'examples')
# the TEMPLATE
im0 = sp.misc.imread(os.path.join(basedir, "sample1.png"), True)
# the image to be transformed
im1 = sp.misc.imread(os.path.join(basedir, "sample3.png"), True)
result = ird.similarity(im0, im1, numiter=3)

assert "timg" in result
# Maybe we don't want to show plots all the time
if os.environ.get("IMSHOW", "yes") == "yes":
    import matplotlib.pyplot as plt
    ird.imshow(im0, im1, result['timg'])
    plt.show()

Or just the translation:

import os

import scipy as sp
import scipy.misc

import imreg_dft as ird


basedir = os.path.join('..', 'examples')
# the TEMPLATE
im0 = sp.misc.imread(os.path.join(basedir, "sample1.png"), True)
# the image to be transformed
im1 = sp.misc.imread(os.path.join(basedir, "sample2.png"), True)
result = ird.translation(im0, im1)
tvec = result["tvec"].round(4)
# the Transformed IMaGe.
timg = ird.transform_img(im1, tvec=tvec)

# Maybe we don't want to show plots all the time
if os.environ.get("IMSHOW", "yes") == "yes":
    import matplotlib.pyplot as plt
    ird.imshow(im0, im1, timg)
    plt.show()

print("Translation is {}, success rate {:.4g}"
      .format(tuple(tvec), result["success"]))

Command-line script examples

Please see the corresponding section that is full of examples.

Do not forget

These steps should go before the Quickstart section, but they come now as this is a quickstart guide.

Tests

If you have downloaded the source files, you can run tests after installation. There are now unit tests and regression tests. You can execute them by going to the tests subdirectory and running

[user@linuxbox imreg_dft]$ cd tests
[user@linuxbox tests]$ make help
make[1]: Entering directory '/home/user/imreg_dft/tests'
Run either 'make check' or 'make check COVERAGE=<coverage command name>'
You may also append 'PYTHON=<python executable>' if you don't use coverage
make[1]: Leaving directory '/home/user/imreg_dft/tests'
[user@linuxbox tests]$ make check
...

If you have the coverage module installed, you also have a coverage (or perhaps coverage2) scripts in your path. You can declare that and therefore have the tests ran with coverage support:

[user@linuxbox tests]$ make check COVERAGE=coverage2
...

In any way, if you see something like

[user@linuxbox tests]$ make check
...
make[1]: Leaving directory '/home/user/imreg_dft/tests'
* * * * * * * * * * * * * * * * * * * * *
 Rejoice, tests have passed successfully!
* * * * * * * * * * * * * * * * * * * * *

it is a clear sign that there indeed was no error encountered during the tests at all.

Documentation

Although you can read the documentation on readthedocs.org (bleeding-edge) and pythonhosted.org (with images), you can generate your own easily. You just have to check out the requirements_docs.txt file at the root of the project and make sure you have all modules that are mentioned there. You also need to have imreg_dft installed prior to documentation generation.

Also be sure to have the source files. In the source tree, go to the doc directory there and run make html or make latexpdf there.