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

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 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 >= V3.1 (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 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. The parameter --stopsens has an impact on
the tradeoff between speed and quality. The higher this parameter is, the faster the registration will be, but the lower the
quality (the probability for an adequate result) will become. Values above 0.5 are very agressive, but can do. Values around
0.1 are the conservative choice and will lead to good results usually. Values around 0.01 and lower are maybe too paranoid,
but depending on the problem, will lead to highest quality. Get familiar with all parameters of the limereg executable and
find out what's best for your kind of data.
By the way, when you're using liblimereg, it's a good starting point to use the limereg executable on some example images
to find out the best parameters for your special registration task. Feel free to contact the author if you need help, then the
documentation will be extended.

Q: How can I speed up the execution ?
A: Your can try to set the parameter --stopsens to higher values (like 0.5 or 0.7). Furthermore the parameter --maxlevels
can lead to a speedup (the otherwise automatically taken amount is written to the console, set this lower/higher +- one
or two and try out). Sometimes some noise elimination (like a gauss) can also help. Also read the section 'HARDWARE
ACCELERATION' below.

Q: Why is the image only shifted/rotated and not for example stretched (affine transformation) ?
A: It would be very easy for the author to extend limereg to affine transformations. In fact the rigid transformation is a
special case of the affine way. Which means that we hat to do extra work to turn the originally affine form into a rigid form.
If you need it, contact the author and you will get it in about one or two months.

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.
There's currently no GPU port planned. If you need such, contact the author, I know a student who tried the given
algorithm on a GPU and maybe we can port his results into limereg - if there's demand.

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)
