---
name: "limereg.h"
section: "3"
platform: "linux"
package: "liblimereg-dev"
version: "1.4.1-4+b1"
release: "Debian 10 (Buster)"
platforms: ["linux"]
url: "https://new.carta.tech/limereg.h"
---

# limereg.h(3)

Library for lightweight image registration.

## NAME

limereg.h - Library for lightweight image registration.

## SYNOPSIS

### Data Structures

struct **Limereg\_Image**\
 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).  struct **Limereg\_TrafoParams**\
 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.  struct **Limereg\_AdvancedRegControl**\
 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.  struct **Limereg\_TrafoLimits**\
 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.

### Enumerations

enum **Limereg\_RetCode** { **LIMEREG\_RET\_SUCCESS** =0, **LIMEREG\_RET\_INTERNAL\_ERROR** =1, **LIMEREG\_RET\_RCV\_NULLPTR** =2, **LIMEREG\_RET\_INVALID\_PYRAMID\_TYPE** =3, **LIMEREG\_RET\_IMAGE\_TOO\_SMALL** =100, **LIMEREG\_RET\_MAX\_ROT\_INVALID** =101, **LIMEREG\_RET\_MAX\_TRANS\_INVALID** =102, **LIMEREG\_RET\_STARTPARAM\_INVALID** =103, **LIMEREG\_RET\_ABORT\_MAXITER\_EXCEEDED** =200, **LIMEREG\_RET\_STENCIL\_NOT\_IMPL\_YET** =9997, **LIMEREG\_RET\_IMAGES\_MUST\_HAVE\_SAME\_SIZE** =9999 }\
 enum **Limereg\_Flags** { **Limereg\_Trafo\_Rigid** =0 }\

### Functions

const char \* **Limereg\_GetVersion** ()\
 Get library version. Returns the package version of liblimereg in use by the current application.  enum **Limereg\_RetCode** **Limereg\_RegisterImage** (const struct **Limereg\_Image** \*referenceImage, const struct **Limereg\_Image** \*templateImage, const struct **Limereg\_TrafoLimits** \*registrResultLimits, const unsigned int flags, const struct **Limereg\_AdvancedRegControl** \*advancedCtrl, struct **Limereg\_TrafoParams** \*registrResult, double \*distanceMeasure, unsigned int \*iterationAmount, unsigned int \*iterationsPerLevel)\
 Register two images. Find out the horizontal/vertical shift and the rotation for the best possible overlay of both images.  enum **Limereg\_RetCode** **Limereg\_CreatePyramid** (const struct **Limereg\_Image** \*sourceImage, const struct **Limereg\_TrafoLimits** \*registrResultLimits, const unsigned int flags, const struct **Limereg\_AdvancedRegControl** \*advancedCtrl, struct **Limereg\_Image** \*pyramidImage)\
 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 **Limereg\_RegisterImage()** 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.  enum **Limereg\_RetCode** **Limereg\_DeletePyramid** (const struct **Limereg\_Image** \*pyramidImage)\
 Delete multilevel pyramid created by **Limereg\_CreatePyramid()** (FOR ADVANCED USE ONLY. IF NOT USED, THE PYRAMID IS CREATED AUTOMATICALLY). Delete a multilevel pyramid that was created by **Limereg\_CreatePyramid()**. For a usual image registration this function should be AVOIDED. In usual cases **Limereg\_RegisterImage()** creates and deletes the multilevel pyramid internally, automatically.  enum **Limereg\_RetCode** **Limereg\_TransformImage** (const struct **Limereg\_Image** \*sourceImage, const struct **Limereg\_TrafoParams** \*trafoParams, struct **Limereg\_Image** \*transformedImage)\
 Rigid image transformation. Apply shift and rotation obtained by Limereg\_RegisterImage to an image.  enum **Limereg\_RetCode** **Limereg\_CalculateDiffImage** (const struct **Limereg\_Image** \*referenceImage, const struct **Limereg\_Image** \*templateImage, struct **Limereg\_Image** \*differenceImage)\
 Generate difference image. Calculate the difference image between reference and the template image (sum of squared differences).

## Detailed Description

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.

```
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.
```

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.

```
Sourcecode:
http://embedded-software-architecture.com/limereg.html
```

## Enumeration Type Documentation

### enum Limereg\_Flags

Flags to control the registration algorithm

**Enumerator**

- *Limereg\_Trafo\_Rigid*

  *Rigid transformation: Supports horizontal, vertical shift and rotation. The size of the image area remains the same.*

### enum Limereg\_RetCode

**Enumerator**

- *LIMEREG\_RET\_SUCCESS*

  *No error.*

- *LIMEREG\_RET\_INTERNAL\_ERROR*

  *Unexpected internal error.*

- *LIMEREG\_RET\_RCV\_NULLPTR*

  *An unexpected nullpointer was passed as an argument.*

- *LIMEREG\_RET\_INVALID\_PYRAMID\_TYPE*

  *The enum value of PyramidImage is invalid in the current context.*

- *LIMEREG\_RET\_IMAGE\_TOO\_SMALL*

  *xDimension or yDimension smaller than alloweg (e.g. 0)*

- *LIMEREG\_RET\_MAX\_ROT\_INVALID*

  *The rotation in registrResultLimits is invalid (too big or small)*

- *LIMEREG\_RET\_MAX\_TRANS\_INVALID*

  *The shift in registrResultLimits is invalid (too big)*

- *LIMEREG\_RET\_STARTPARAM\_INVALID*

  *The content of startParameters in* **Limereg\_RegisterImage()** *is invalid. Check if the content is plausible and within the bounds of registrResultLimits.*

- *LIMEREG\_RET\_ABORT\_MAXITER\_EXCEEDED*

  *The registration algorithm took more iterations than allowed by maxIterations and was aborted.*

- *LIMEREG\_RET\_STENCIL\_NOT\_IMPL\_YET*

  *Currently stencil images are unsupported and the pointer named stencilImage has to be set to 0.*

- *LIMEREG\_RET\_IMAGES\_MUST\_HAVE\_SAME\_SIZE*

  *Currently the images to be registered must both have the same size (this limitation will be removed soon)*

## Function Documentation

### enum Limereg\_RetCode Limereg\_CalculateDiffImage (const struct Limereg\_Image \* referenceImage, const struct Limereg\_Image \* templateImage, struct Limereg\_Image \* differenceImage)

*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.*

**Parameters:**

*referenceImage Reference image (image to be matched against)* \
 *templateImage Template image (image to be shifted/rotated until it matches to the reference image)* \
 *differenceImage Result: Output image will be written to here. The passed width and height fields have to match the buffer space (width\*heigth bytes).*

**Returns:**

*return code*

### enum Limereg\_RetCode Limereg\_CreatePyramid (const struct Limereg\_Image \* sourceImage, const struct Limereg\_TrafoLimits \* registrResultLimits, const unsigned int flags, const struct Limereg\_AdvancedRegControl \* advancedCtrl, struct Limereg\_Image \* pyramidImage)

*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* **Limereg\_RegisterImage()** *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* **Limereg\_Image.PyramidImage** *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* **Limereg\_DeletePyramid()** *to free this memory again lateron.*

*Important: The parameters registrResultLimits, flags and pyramidLevelCount have to be equal to the later calls to* **Limereg\_RegisterImage()** *and have to stay equal for every call to* **Limereg\_RegisterImage()***.*

**Parameters:**

*sourceImage Image data for the finest level of the multilevel pyramid.* \
 *registrResultLimits Maximum shift and rotation allowed/expected. The algorithm will stay inside this boundaries.* \
 *flags Variations in the mathematical approach (0=default)* \
 *advancedCtrl Advanced parameters for fine tuning the algorithm (NULLPOINTER = Autodetect best settings, maxIterations, stopSensitivity and startParameters are ignored here)* \
 *pyramidImage Buffer of subsequent pyramid images, starting with the finest, proceeding up to the coarsest level*

**Returns:**

*return code*

### enum Limereg\_RetCode Limereg\_DeletePyramid (const struct Limereg\_Image \* pyramidImage)

*Delete multilevel pyramid created by* **Limereg\_CreatePyramid()** *(FOR ADVANCED USE ONLY. IF NOT USED, THE PYRAMID IS CREATED AUTOMATICALLY). Delete a multilevel pyramid that was created by* **Limereg\_CreatePyramid()***. For a usual image registration this function should be AVOIDED. In usual cases* **Limereg\_RegisterImage()** *creates and deletes the multilevel pyramid internally, automatically. The member* **Limereg\_Image.PyramidImage** *of the output buffer is expected to have the value Pyramidized.*

**Returns:**

*return code*

### const char\* Limereg\_GetVersion ()

*Get library version. Returns the package version of liblimereg in use by the current application.*

**Returns:**

*Pointer to a null terminated char array containing the version string.*

### enum Limereg\_RetCode Limereg\_RegisterImage (const struct Limereg\_Image \* referenceImage, const struct Limereg\_Image \* templateImage, const struct Limereg\_TrafoLimits \* registrResultLimits, const unsigned int flags, const struct Limereg\_AdvancedRegControl \* advancedCtrl, struct Limereg\_TrafoParams \* registrResult, double \* distanceMeasure, unsigned int \* iterationAmount, unsigned int \* iterationsPerLevel)

*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.*

**Parameters:**

*referenceImage Reference image R (image to be matched against)* \
 *templateImage Template image T (image to be shifted/rotated until it matches to the reference image)* \
 *registrResultLimits Maximum shift and rotation allowed/expected. The algorithm will stay inside this boundaries.* \
 *flags Variations in the mathematical approach (0=default)* \
 *advancedCtrl Advanced parameters for fine tuning the algorithm (NULLPOINTER = Autodetect best settings)* \
 *registrResult Registration result: Shift and rotation for the best detected image alignment (NULL = ignored)* \
 *distanceMeasure 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)* \
 *iterationAmount Total amount of algorithm iterations passed (NULL = ignored)* \
 *iterationsPerLevel 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)*

**Returns:**

*return code*

### enum Limereg\_RetCode Limereg\_TransformImage (const struct Limereg\_Image \* sourceImage, const struct Limereg\_TrafoParams \* trafoParams, struct Limereg\_Image \* transformedImage)

*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.*

**Parameters:**

*sourceImage Source image to be shifted/rotated* \
 *trafoParams Shift and rotation to be applied* \
 *transformedImage Result: Output image will be written to here (same image dimensions as the sourceImage).*

**Returns:**

*return code*

## Author

*Generated automatically by Doxygen for liblimereg-1.4.1 from the source code.*