.TH "limereg.h" 3 "October 2016" "liblimereg-1.4.1" \" -*- nroff -*-
.ad l
.nh
.SH NAME
limereg.h \- Library for lightweight image registration\&.  

.SH SYNOPSIS
.br
.PP
.SS "Data Structures"

.in +1c
.ti -1c
.RI "struct \fBLimereg_Image\fP"
.br
.RI "Pointer to pixeldata and image dimensions Image buffer with data pointer and image dimensions\&. The buffer consists of one byte per pixel of luminance data (greyscale)\&. "
.ti -1c
.RI "struct \fBLimereg_TrafoParams\fP"
.br
.RI "Parameters for a rigid transformation Parameters for a rigid transformation\&. That is horizontal and vertical shift and a rotation angle\&. The image will retain it's dimensions, it will not be sheared, only shift and rotation are allowed\&. "
.ti -1c
.RI "struct \fBLimereg_AdvancedRegControl\fP"
.br
.RI "Advanced parameters for controlling the image registration This parameters allow the control of advanced parameters\&. Each parameter can be set to 0 for an autodetect or default behavior\&. Also a nullpointer can be passed instead of this struct if for all advanced parameters the autodetect/default value shall be used\&. "
.ti -1c
.RI "struct \fBLimereg_TrafoLimits\fP"
.br
.RI "Result limits for a rigid transformation Maximum allowed result (shift/rotation) for the rigid transformation result of the image registration\&. The algorithm will stay in this boundary, it will not abort\&. "
.in -1c
.SS "Enumerations"

.in +1c
.ti -1c
.RI "enum \fBLimereg_RetCode\fP { \fBLIMEREG_RET_SUCCESS\fP =0, \fBLIMEREG_RET_INTERNAL_ERROR\fP =1, \fBLIMEREG_RET_RCV_NULLPTR\fP =2, \fBLIMEREG_RET_INVALID_PYRAMID_TYPE\fP =3, \fBLIMEREG_RET_IMAGE_TOO_SMALL\fP =100, \fBLIMEREG_RET_MAX_ROT_INVALID\fP =101, \fBLIMEREG_RET_MAX_TRANS_INVALID\fP =102, \fBLIMEREG_RET_STARTPARAM_INVALID\fP =103, \fBLIMEREG_RET_ABORT_MAXITER_EXCEEDED\fP =200, \fBLIMEREG_RET_STENCIL_NOT_IMPL_YET\fP =9997, \fBLIMEREG_RET_IMAGES_MUST_HAVE_SAME_SIZE\fP =9999 }"
.br
.ti -1c
.RI "enum \fBLimereg_Flags\fP { \fBLimereg_Trafo_Rigid\fP =0 }"
.br
.in -1c
.SS "Functions"

.in +1c
.ti -1c
.RI "const char * \fBLimereg_GetVersion\fP ()"
.br
.RI "Get library version\&. Returns the package version of liblimereg in use by the current application\&. "
.ti -1c
.RI "enum \fBLimereg_RetCode\fP \fBLimereg_RegisterImage\fP (const struct \fBLimereg_Image\fP *referenceImage, const struct \fBLimereg_Image\fP *templateImage, const struct \fBLimereg_TrafoLimits\fP *registrResultLimits, const unsigned int flags, const struct \fBLimereg_AdvancedRegControl\fP *advancedCtrl, struct \fBLimereg_TrafoParams\fP *registrResult, double *distanceMeasure, unsigned int *iterationAmount, unsigned int *iterationsPerLevel)"
.br
.RI "Register two images\&. Find out the horizontal/vertical shift and the rotation for the best possible overlay of both images\&. "
.ti -1c
.RI "enum \fBLimereg_RetCode\fP \fBLimereg_CreatePyramid\fP (const struct \fBLimereg_Image\fP *sourceImage, const struct \fBLimereg_TrafoLimits\fP *registrResultLimits, const unsigned int flags, const struct \fBLimereg_AdvancedRegControl\fP *advancedCtrl, struct \fBLimereg_Image\fP *pyramidImage)"
.br
.RI "Create multilevel pyramid (FOR ADVANCED USE ONLY\&. IF NOT USED, THE PYRAMID IS CREATED AUTOMATICALLY)\&. Create a multilevel pyramid\&. For a usual image registration this function should be AVOIDED\&. In usual cases \fBLimereg_RegisterImage()\fP creates the multilevel pyramid internally, automatically\&. The images of each pyramid level will be bigger than the (scaled) source image, because margins will be added that allow Dirichlet boundary conditions to be used without jumps / pipeline hazards\&. "
.ti -1c
.RI "enum \fBLimereg_RetCode\fP \fBLimereg_DeletePyramid\fP (const struct \fBLimereg_Image\fP *pyramidImage)"
.br
.RI "Delete multilevel pyramid created by \fBLimereg_CreatePyramid()\fP (FOR ADVANCED USE ONLY\&. IF NOT USED, THE PYRAMID IS CREATED AUTOMATICALLY)\&. Delete a multilevel pyramid that was created by \fBLimereg_CreatePyramid()\fP\&. For a usual image registration this function should be AVOIDED\&. In usual cases \fBLimereg_RegisterImage()\fP creates and deletes the multilevel pyramid internally, automatically\&. "
.ti -1c
.RI "enum \fBLimereg_RetCode\fP \fBLimereg_TransformImage\fP (const struct \fBLimereg_Image\fP *sourceImage, const struct \fBLimereg_TrafoParams\fP *trafoParams, struct \fBLimereg_Image\fP *transformedImage)"
.br
.RI "Rigid image transformation\&. Apply shift and rotation obtained by Limereg_RegisterImage to an image\&. "
.ti -1c
.RI "enum \fBLimereg_RetCode\fP \fBLimereg_CalculateDiffImage\fP (const struct \fBLimereg_Image\fP *referenceImage, const struct \fBLimereg_Image\fP *templateImage, struct \fBLimereg_Image\fP *differenceImage)"
.br
.RI "Generate difference image\&. Calculate the difference image between reference and the template image (sum of squared differences)\&. "
.in -1c
.SH "Detailed Description"
.PP 
Library for lightweight image registration\&. 

Software development library, that performs a 2D, rigid image registration on two greyscale images and outputs either the transformation parameters or the registered image\&. 
.PP
.nf
Examples:

In the source distribution at http://embedded-software-architecture.com/limereg.html the following folders contain examples:

tests: C written test automation that can be used as example code.

exe: C++ written commandline utility using liblimereg.

.fi
.PP
.PP
Copyright 2014, Roelof Berg, Licensed under the 3-clause BSD license at http://berg-solutions.de/limereg-license.html\&. Credit goes to Lars Koenig and Jan Ruehaak from Fraunhofer MEVIS in Germany\&. 
.PP
.nf
Sourcecode:
http://embedded-software-architecture.com/limereg.html
.fi
.PP

.SH "Enumeration Type Documentation"
.PP 
.SS "enum \fBLimereg_Flags\fP"
Flags to control the registration algorithm 
.PP
\fBEnumerator\fP
.in +1c
.TP
\fB\fILimereg_Trafo_Rigid \fP\fP
Rigid transformation: Supports horizontal, vertical shift and rotation\&. The size of the image area remains the same\&. 
.SS "enum \fBLimereg_RetCode\fP"

.PP
\fBEnumerator\fP
.in +1c
.TP
\fB\fILIMEREG_RET_SUCCESS \fP\fP
No error\&. 
.TP
\fB\fILIMEREG_RET_INTERNAL_ERROR \fP\fP
Unexpected internal error\&. 
.TP
\fB\fILIMEREG_RET_RCV_NULLPTR \fP\fP
An unexpected nullpointer was passed as an argument\&. 
.TP
\fB\fILIMEREG_RET_INVALID_PYRAMID_TYPE \fP\fP
The enum value of PyramidImage is invalid in the current context\&. 
.TP
\fB\fILIMEREG_RET_IMAGE_TOO_SMALL \fP\fP
xDimension or yDimension smaller than alloweg (e\&.g\&. 0) 
.TP
\fB\fILIMEREG_RET_MAX_ROT_INVALID \fP\fP
The rotation in registrResultLimits is invalid (too big or small) 
.TP
\fB\fILIMEREG_RET_MAX_TRANS_INVALID \fP\fP
The shift in registrResultLimits is invalid (too big) 
.TP
\fB\fILIMEREG_RET_STARTPARAM_INVALID \fP\fP
The content of startParameters in \fBLimereg_RegisterImage()\fP is invalid\&. Check if the content is plausible and within the bounds of registrResultLimits\&. 
.TP
\fB\fILIMEREG_RET_ABORT_MAXITER_EXCEEDED \fP\fP
The registration algorithm took more iterations than allowed by maxIterations and was aborted\&. 
.TP
\fB\fILIMEREG_RET_STENCIL_NOT_IMPL_YET \fP\fP
Currently stencil images are unsupported and the pointer named stencilImage has to be set to 0\&. 
.TP
\fB\fILIMEREG_RET_IMAGES_MUST_HAVE_SAME_SIZE \fP\fP
Currently the images to be registered must both have the same size (this limitation will be removed soon) 
.SH "Function Documentation"
.PP 
.SS "enum \fBLimereg_RetCode\fP Limereg_CalculateDiffImage (const struct \fBLimereg_Image\fP * referenceImage, const struct \fBLimereg_Image\fP * templateImage, struct \fBLimereg_Image\fP * differenceImage)"

.PP
Generate difference image\&. Calculate the difference image between reference and the template image (sum of squared differences)\&. The images are treated as byte array where one byte matches the luminance (grey-value) of one pixel\&.
.PP
\fBParameters:\fP
.RS 4
\fIreferenceImage\fP Reference image (image to be matched against) 
.br
\fItemplateImage\fP Template image (image to be shifted/rotated until it matches to the reference image) 
.br
\fIdifferenceImage\fP Result: Output image will be written to here\&. The passed width and height fields have to match the buffer space (width*heigth bytes)\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
return code 
.RE
.PP

.SS "enum \fBLimereg_RetCode\fP Limereg_CreatePyramid (const struct \fBLimereg_Image\fP * sourceImage, const struct \fBLimereg_TrafoLimits\fP * registrResultLimits, const unsigned int flags, const struct \fBLimereg_AdvancedRegControl\fP * advancedCtrl, struct \fBLimereg_Image\fP * pyramidImage)"

.PP
Create multilevel pyramid (FOR ADVANCED USE ONLY\&. IF NOT USED, THE PYRAMID IS CREATED AUTOMATICALLY)\&. Create a multilevel pyramid\&. For a usual image registration this function should be AVOIDED\&. In usual cases \fBLimereg_RegisterImage()\fP creates the multilevel pyramid internally, automatically\&. The images of each pyramid level will be bigger than the (scaled) source image, because margins will be added that allow Dirichlet boundary conditions to be used without jumps / pipeline hazards\&. The member \fBLimereg_Image\&.PyramidImage\fP of the output buffer will be set to Pyramidized and the data pointer will point to the pyramid image data\&. The memory for the image data will be created on the heap by this function, use \fBLimereg_DeletePyramid()\fP to free this memory again lateron\&.
.PP
Important: The parameters registrResultLimits, flags and pyramidLevelCount have to be equal to the later calls to \fBLimereg_RegisterImage()\fP and have to stay equal for every call to \fBLimereg_RegisterImage()\fP\&.
.PP
\fBParameters:\fP
.RS 4
\fIsourceImage\fP Image data for the finest level of the multilevel pyramid\&. 
.br
\fIregistrResultLimits\fP Maximum shift and rotation allowed/expected\&. The algorithm will stay inside this boundaries\&. 
.br
\fIflags\fP Variations in the mathematical approach (0=default) 
.br
\fIadvancedCtrl\fP Advanced parameters for fine tuning the algorithm (NULLPOINTER = Autodetect best settings, maxIterations, stopSensitivity and startParameters are ignored here) 
.br
\fIpyramidImage\fP Buffer of subsequent pyramid images, starting with the finest, proceeding up to the coarsest level
.RE
.PP
\fBReturns:\fP
.RS 4
return code 
.RE
.PP

.SS "enum \fBLimereg_RetCode\fP Limereg_DeletePyramid (const struct \fBLimereg_Image\fP * pyramidImage)"

.PP
Delete multilevel pyramid created by \fBLimereg_CreatePyramid()\fP (FOR ADVANCED USE ONLY\&. IF NOT USED, THE PYRAMID IS CREATED AUTOMATICALLY)\&. Delete a multilevel pyramid that was created by \fBLimereg_CreatePyramid()\fP\&. For a usual image registration this function should be AVOIDED\&. In usual cases \fBLimereg_RegisterImage()\fP creates and deletes the multilevel pyramid internally, automatically\&. The member \fBLimereg_Image\&.PyramidImage\fP of the output buffer is expected to have the value Pyramidized\&.
.PP
\fBReturns:\fP
.RS 4
return code 
.RE
.PP

.SS "const char* Limereg_GetVersion ()"

.PP
Get library version\&. Returns the package version of liblimereg in use by the current application\&. 
.PP
\fBReturns:\fP
.RS 4
Pointer to a null terminated char array containing the version string\&. 
.RE
.PP

.SS "enum \fBLimereg_RetCode\fP Limereg_RegisterImage (const struct \fBLimereg_Image\fP * referenceImage, const struct \fBLimereg_Image\fP * templateImage, const struct \fBLimereg_TrafoLimits\fP * registrResultLimits, const unsigned int flags, const struct \fBLimereg_AdvancedRegControl\fP * advancedCtrl, struct \fBLimereg_TrafoParams\fP * registrResult, double * distanceMeasure, unsigned int * iterationAmount, unsigned int * iterationsPerLevel)"

.PP
Register two images\&. Find out the horizontal/vertical shift and the rotation for the best possible overlay of both images\&. The images are treated as byte array where one byte matches the luminance (grey-value) of one pixel\&.
.PP
\fBParameters:\fP
.RS 4
\fIreferenceImage\fP Reference image R (image to be matched against) 
.br
\fItemplateImage\fP Template image T (image to be shifted/rotated until it matches to the reference image) 
.br
\fIregistrResultLimits\fP Maximum shift and rotation allowed/expected\&. The algorithm will stay inside this boundaries\&. 
.br
\fIflags\fP Variations in the mathematical approach (0=default) 
.br
\fIadvancedCtrl\fP Advanced parameters for fine tuning the algorithm (NULLPOINTER = Autodetect best settings) 
.br
\fIregistrResult\fP Registration result: Shift and rotation for the best detected image alignment (NULL = ignored) 
.br
\fIdistanceMeasure\fP For informational purposes\&. The distance measure of the final result (the lower, the better the images are aligned, not comparable between images of different size) (NULL = ignored) 
.br
\fIiterationAmount\fP Total amount of algorithm iterations passed (NULL = ignored) 
.br
\fIiterationsPerLevel\fP NULL = ignored / or a pointer to an array with levelCount (see above) elements that will be filled with the iterations needed on each level (beginning with the coarsest one) 
.RE
.PP
\fBReturns:\fP
.RS 4
return code 
.RE
.PP

.SS "enum \fBLimereg_RetCode\fP Limereg_TransformImage (const struct \fBLimereg_Image\fP * sourceImage, const struct \fBLimereg_TrafoParams\fP * trafoParams, struct \fBLimereg_Image\fP * transformedImage)"

.PP
Rigid image transformation\&. Apply shift and rotation obtained by Limereg_RegisterImage to an image\&. The images are treated as byte array where one byte matches the luminance (grey-value) of one pixel\&.
.PP
\fBParameters:\fP
.RS 4
\fIsourceImage\fP Source image to be shifted/rotated 
.br
\fItrafoParams\fP Shift and rotation to be applied 
.br
\fItransformedImage\fP Result: Output image will be written to here (same image dimensions as the sourceImage)\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
return code 
.RE
.PP

.SH "Author"
.PP 
Generated automatically by Doxygen for liblimereg-1\&.4\&.1 from the source code\&.