 _ _                               
| (_)_ __ ___   ___ _ __ ___  __ _ 
| | | '_ ` _ \ / _ \ '__/ _ \/ _` |
| | | | | | | |  __/ | |  __/ (_| |
|_|_|_| |_| |_|\___|_|  \___|\__, |
                             |___/ 

Lightweight IMagE REGistration

Open source and commandline based application and/or software development library, that performs a 2D, rigid
image registration on two images and outputs either the transformation parameters or the registered image.

FOR THE IMPATIENT

On a recent Ubuntu Linux, enter the following into a console window:
 sudo apt-get install build-essential libcv-dev libhighgui-dev libopencv-dev libboost-dev libboost-program-options-dev doxygen help2man
 ./configure  CFLAGS="-Ofast" CXXFLAGS="-Ofast"
 make
 sudo make install
 
Then test the installed application:
 limereg --tfile tests/testimg/T_512.bmp --rfile tests/testimg/R_512.bmp

HISTORY

This algorithm for highly efficient Image Registration was taken from fimreg, which is a supplementary software
for our article in the Springer Journal of Realtime Image Processing with the title: "Highly efficient image
registration for embedded systems using a distributed multicore DSP architecture" which is available for purchase
at: http://link.springer.com/article/10.1007/s11554-014-0457-3. There is also a preprint available free of charge
at http://embedded-software-architecture.com/Berg2014Highly_Preprint.pdf

If you want to understand how the algorithm works, chapter three of this paper is the best starting point.
Please be aware that this software is a limited research prototype. If you need industrial quality please
contact one of the authors.

The package builds two binaries:
a) liblimereg: (Mandatory) A library for software developers who need image registration within their application.
b) limereg: (Optional) A commandline utility for image registration, which uses liblimereg.

The optional utility limereg will only be built when libboost-program-options-dev and libopencv-dev are present.
If these prerequisites are not present only the library liblimereg will be built, which has no dependencies to
boost and/or opencv.

PREREQUISITES

Unix/Linux:
- GNU compiler (build-essentials)
- Optional: Doxygen (manpage generation for the library liblimereg)
- Optional: help2man (manpage generation for the command line utility limereg) 
- Optional: OpenCV (only needed when the limereg command line utility shall be built. Not needed for a lib-only version.)
- Optional: BoostCmdLineOptions (only needed when the limereg command line utility shall be built. Not needed for a lib-only version.)
An apt-get commandline for all prerequisites on Debian/Ubuntu would be:
sudo apt-get install build-essential libcv-dev libhighgui-dev libopencv-dev libboost-dev libboost-program-options-dev doxygen help2man

Windows:
Former versions of this library came with a MS Visual Studio project file. If you need MS VSS, just contact me at
rberg@berg.solutions.de and I will add a vss project file again (only if someone needs it). Currently this project
is based on the GNU build system (autotools/configure) and this toolchain is also compatible to Windows by using
compatibility layers like MSYS or Cygwin, just follow the steps below in an MSYS or Cygwin shell.

EXAMPLE RUN BEFORE INSTALLATION

If you want to get an impression of limereg before installing it, do the following (otherwise proceed with the next chapter):

 ./configure  CFLAGS="-Ofast" CXXFLAGS="-Ofast"
 make
 cd exe
 ./limereg --tfile ../tests/testimg/T_512.bmp --rfile ../tests/testimg/R_512.bmp --outfile ../mytest.jpg

You will see that the registered image (../mytest.jpg) has the content of T_512.bmp which has been rigidly aligned to R_512.bmp. 

BUILD AND INSTALLATION

A typical installation is as follows:

 ./configure CFLAGS="-Ofast" CXXFLAGS="-Ofast"
 make
 sudo make install

ATTENTION: ON SOME SYSTEMS (DEBIAN, UBUNTU) IT IS CURRENTLY NECESSARY TO CALL AFTER MAKE INSTALL: sudo ldconfig 
Like in https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=684981

For advanced installation options see file INSTALL. You may also want to execute 'make check' after 'make' for
executing the built-in test automation before installation.

MANUAL

After installation the following command opens the manual of the library:
  man liblimereg
and/or
  man limereg.h
  
To open the manual of the command line utility:
  man limereg

The project's web site has additional documentation:
 http://www.berg-solutions.de/limereg.html

EXAMPLES

Example code can be found in the folder named 'tests'. An example for the command line tool
would be as follows (after 'make install' was executed):

Display registration result on the display screen:
 cd tests/testimg
 limereg --tfile T_512.bmp --rfile R_512.bmp

Without GUI (batch mode):
 cd tests/testimg
 limereg --tfile T_512.bmp --rfile R_512.bmp --nogui --outfile result.jpg

DEBUGGING

For debugging with gcc use:
./configure CFLAGS="-ggdb3 -O0" CXXFLAGS="-ggdb3 -O0" LDFLAGS="-ggdb3"
Then set LD_LIBRARY_PATH to lib/.libs (eclipse: environment tab of the dbg config) and debug the executable exe/.libs/limereg.

TROUBLESHOOTING

Q: What are the current limitations ?
A: The current version supports only equally sized pictures and internally operates in greyscale color space, it
also outputs images as greyscale. Furthermore the stencil functions are unsupported today and only rigid transformations
are possible. This limitations will be eliminated in the future, e.g. allowing also affine transformations (zoom/shear)
Requesting a feature from the author might change priorities and speed up the development of your desired feature.

Q: What if the registration result is rubbish ?
A: Image registration isn't trivial, once the optimization algorithm has 'grip' it will give you awesome results. But
to get this far some work has to be invested. Carefully adjust the max. rotation and max. translation to your particular
image data, to your use-case. When using the limereg executable (standalone or as a development-tool for figuring out
the best settings) this would be the parameters --maxrot and --maxtrans. If you expect less rotation, limit --maxrot to
a few degrees. If you expect much translation, raise --maxtrans, maybe up to 100%.
For best results use light image data centered on a dark background. You may want to invert the image if your background
is light. In the limereg executable this can be done by the --invert switch. Get familiar with all parameters of the
limereg executable and find out what's best for your kind of data.
Feel free to contact the author if you need help, then the documentation will be extended.

BUG REPORTS / CONTRIBUTION

Please report bugs or send source code contributions via github at:
https://github.com/roelofberg/limereg
(This is the base project that is used to create the source code tarball distributions.)

HARDWARE ACCELERATION

Limereg was forked from a software called fimreg that was written for the scientific paper mentioned
above. It utilized an Advantech DSPC-8681 PCIe expansion card that contains four TI C6678 highspeed DSPs.
	http://embedded-software-architecture.com/fimreg.html
If you need hardware acceleration also for limereg, please contact the authors. In our experiments we
offloaded the CPU by a factor 20 by using such a coprocessor expansion card.

OPEN ISSUES

There are some limitations in the current version. But, however, the interface is designed for durability.
This means, the current version can be used for development and an upgrade will lateron remove the following
open issues without a changed interface (limereg.h).

- Currently only equally sized images are supported, the sizes of Reference and Template image must be equal.
- The algorithm internally operates in geyscale only. Also outputted images will be greyscale (this limitation will be removed in V1.5).
- Stencil images aren't supported yet
- Currently manual pyramid generation for searching subimages is ignored internally (but the interface can be used allready)
- One wasting image copy step is made when putting the image data into a matlab array. Elimination will
  speed up the software. (CRegistrator.cpp:98. Just change MatlabArray to reference to existing memory.
 Template: fimreg)
- The image rotation algorithm can be made more efficient (for highest performance use limereg to obtain
  the parameters and perform the rigid transformation yourself)
