Functions
cpl_error_code	clipm_align_correlate (const cpl_image ref_img, const cpl_image test_img, const cpl_matrix ref_locations, const cpl_matrix test_locations, unsigned int area_size, double max_distance, clipm_align_opt align_mode_bitmask, cpl_matrix pixel_transform_matrix, cpl_matrix pixel_transshiftvector, cpl_matrix all_pixelshifts, cpl_matrix all_locationshifts, cpl_matrix all_uncertainties, cpl_array all_error_codes)
	Align two images by correlation of sub-regions. More...

Detailed Description

Alignment of images using the image content.

Synopsis:: #include "clipm_align.h"

*

See Also

Function Documentation

cpl_error_code clipm_align_correlate	(	const cpl_image *	ref_img,
		const cpl_image *	test_img,
		const cpl_matrix *	ref_locations,
		const cpl_matrix *	test_locations,
		unsigned int	area_size,
		double	max_distance,
		clipm_align_opt	align_mode_bitmask,
		cpl_matrix **	pixel_transform_matrix,
		cpl_matrix **	pixel_transshiftvector,
		cpl_matrix **	all_pixelshifts,
		cpl_matrix **	all_locationshifts,
		cpl_matrix **	all_uncertainties,
		cpl_array **	all_error_codes
	)

Align two images by correlation of sub-regions.

Parameters

ref_img	Reference image (FITS convention)
test_img	Test image (FITS convention)
ref_locations	Center coordinates of reference correlation areas as 2 x N matrix
test_locations	Optional center coordinates of correlation areas in test image as 2 x N matrix, can be NULL
area_size	Edge length of correlation areas (>= 5)
max_distance	Maximum search distance, must be <= (area_size - 2)/3
align_mode_bitmask	Alignment mode
pixel_transform_matrix	Output transformation matrix, can be NULL
pixel_transshiftvector	Output transformation shifting vector, can be NULL
all_pixelshifts	Output matrix containing all the respective shift vectors for absolute image pixel coordinates, can be NULL
all_locationshifts	Output matrix containing all the respective shift vectors, that must be added to the test locations, so that they point to the same image content in test_img, as ref_locations in ref_img, can be NULL
all_uncertainties	Output matrix containing all the centroiding uncertainties (see below), and -1 where the centroiding failed, can be NULL
all_error_codes	Output array of type CPL_TYPE_INT containing all the respective correlation and centroiding error codes, can be NULL

Returns: CPL error code

Introduction:: The translation (and evt. minimal transformation) of two images is determined using cross-correlation of sub-regions of these images (see also the algorithm description below). These regions are defined by the locations of their centers and their size area_size. The maximum search range is defined by max_distance. area_size must be at least 3*max_distance+2, and be at least 5. The respective translations are determined by centroiding (gaussian fitting) the peaks in the correlation output matrices. The output parameters are all the respective translations, and the overall image transformation/translation parameters.

This function has a special output behaviour in the case of error, please refer to the section "Error Handling" below.

Important Constraint:: The usage of cross-correlation implies that the main difference between the two input images is a translation.

The computation of transformation parameters to determine relative image distortions makes only sense, if the relative distortions are neglegible inside the correlated sub-regions.

For example, the transformation parameters of an image which is slightly out of focus and therefore globally slightly scaled, can be determined well. But if this is not the case, the distortions (e.g. rotation, shearing...) should be pre-corrected, and this function then be used as an iterative step for fine-tuning.

Input Parameter Details:

The location matrices are expected in the following form (the number of rows is 2 (the number of dimensions), and the number of columns is the number of locations):
$locations = \left( \begin{array}{lllc} x_0 & x_1 & \cdots & x_{N-1} \\ y_0 & y_1 & \cdots & y_{N-1} \end{array} \right)$
The minimum number of locations (columns in ref_locations) for doing the alignment, which must all succeed in cross-correlation and centroiding, is:
- 1, if align_mode_bitmask is CLIPM_ALIGN_SHIFT only (and evt. CLIPM_ALIGN_ROBUST), and
- 3, in any other alignment mode (see also clipm_align_points()).
test_locations is optional, if it is given, the correlations areas in test_img are centered around the test locations, otherwise (if test_locations is NULL) around the reference locations (test_locations must of course then have the same size as ref_locations).
area_size defines the edge length of the square sub-regions. The lower limit is: area_size >= (max_distance * 3) + 2, or 5.
max_distance defines the maximum search range from the given locations of the sub-regions, respectively in x and y.
align_mode_bitmask should be given by a bit-wise combination of the options in Alignment Options.

Output Parameter Details:

Any output parameter can be NULL.
pixel_transform_matrix and pixel_transshiftvector return the transformation coefficients that are necessary to transform test_img for matching with ref_img. See also clipm_priv_matrix_transform_points().
If both, pixel_transform_matrix and pixel_transshiftvector, are NULL, then the alignment process is skipped, only the other output parameters are calculated, and align_mode_bitmask is ignored.
all_pixelshifts returns the determined pixel offsets of the correlation areas. This refers to real pixel p Aerrorlist = NULL; ositions and not to the input location vectors. In other words, all_pixelshifts contains translation vectors that would be necessary to add to the pixel indices of the respective correlation areas in test_img for them to match with the ones in ref_img.
all_locationshifts returns the determined image content offsets relative to the input locations, this means: adding all_locationshifts to test_locations would make them point to the same objects in test_img, as ref_locations do in ref_img. This parameter seems somewhat similar to all_pixelshifts, but is relative to both: the positioning of the image content, and the input location vectors.
all_uncertainties returns all 1-sigma-values of the uncertainties of the centroiding process, for every correlation location and in x and y, and -1 where the centroiding failed.
all_error_codes is returned as type CPL_TYPE_INT with the size equal to the number of locations, and returns all CPL error codes of the respective correlation and centroiding processes. The following value is hard-defined: 0 (zero) in the case of success.

Supported Alignment Modes:

Not all alignment mode combinations are supported. Have a look at Alignment Options.

Algorithm:: For every position in ref_locations (and test_locations), the sub-regions in ref_img and test_img are defined by the location as the center and by the size area_size. The sub-regions are being cross-correlated. The peaks in the outputs of the cross-correlations are fitted in a max_distance of the centers, and allow the computation of the respective translations for output (in all_pixelshifts and all_locationshifts).

max_distance is interpreted like its name, as a maximum search distance. To ensure high quality results within this range, the correlation translation limits are internally higher by a factor of 1.5 (to be precise: max(2, 1.5*max_distance) ).

All successful results (peak fittings might fail if there is bad signal) are selected and used as input for an object alignment step. This can be for example just the computation of the median translation (see below) or even the determination of the mentioned full geometrical transformation parameters, with the also mentioned constraint.

$\arraycolsep1pt \begin{array}{cccccccl} & & ref\_img & & test\_img & & & \\ & & \downarrow & & \downarrow & & & \\ ref\_locations & \rightarrow & \fbox{Select Area} & & \fbox{Select Area} & \leftarrow & test\_locations & \\ \mid & & \hfill \downarrow \quad & & \quad \downarrow \hfill & & \mid & \\ \mid & & \multicolumn{3}{c}{\fbox{\begin{tabular}[t]{c}\mbox{Normalized} \\ \mbox{Cross-Correlation}\end{tabular}}} & & \mid & \\ \mid & & & \downarrow & & & \mid & \\ \mid & & \multicolumn{3}{c}{\fbox{\begin{tabular}[t]{c}Centroiding \\ (Gaussian Fit)\end{tabular}}} & & \mid & \mbox{\begin{tabular}[t]{l}$\Rightarrow$ Centroiding Error $(all\_error\_codes)$ \\ $\Rightarrow (all\_uncertainties)$\end{tabular}} \\ \downarrow & & & \downarrow & & & \downarrow & \\ \multicolumn{5}{c}{\fbox{\qquad\qquad\qquad\qquad Shifting\qquad\qquad\qquad\qquad}\hfill} & \leftarrow & test\_locations & \mbox{\begin{tabular}[t]{l}$\Rightarrow$ $(all\_pixel\_shifts)$\end{tabular}}\\ & & & \mid & & & \mid & \mbox{\begin{tabular}[t]{l}$\Rightarrow$ $(all\_location\_shifts)$\end{tabular}} \\ & & & \downarrow & & & \downarrow & \\ & & \multicolumn{3}{c}{\qquad \fbox{\qquad Selection\qquad}\Longleftarrow} & \multicolumn{2}{l}{\fbox{\qquad Selection\qquad}\hfill} & \Leftarrow \mbox{Centroiding Error}\\ & & & \downarrow & & & \downarrow & \\ & & \multicolumn{5}{c}{\hfill \fbox{\qquad\qquad\qquad\qquad Aligning\qquad\qquad\qquad\qquad}} & \mbox{\begin{tabular}[t]{l}$\Rightarrow$ $(pixel\_transform\_matrix)$ \\ $\Rightarrow$ ($pixel\_transshiftvector$)\end{tabular}} \\ \end{array}$

Note

pixel_transform_matrix, pixel_transshiftvector, all_pixelshifts, all_locationshifts, and all_uncertainties must be deleted using cpl_matrix_delete().
all_error_codes must be deleted usind cpl_array_delete().

Error Handling:

The error handling is divided into two sections, the return value of this function, and the returned centroiding error states in all_error_codes. Before listing the error codes, another fact has to be mentioned:

Attention: This function has a special output behaviour in the case of error:
- if an error happens before the alignment step, all output pointers will be set to NULL, but
- if an error happens during the alignment step, the pointers
  - all_pixelshifts,
  - all_locationhifts,
  - all_uncertainties, and
  - all_error_codes
  will contain the result values of the correlation and centroiding steps. This is to allow individual analysis of the correlation results, e.g. to see why the alignment step failes (if it does).
Therefore, a) these pointers must not be used to check whether the function succeeds, and b) it is safer programming to always delete all returned object pointers, even in the case of error.

The following error codes are set and returned by this function:
- CPL_ERROR_NULL_INPUT: ref_img, test_img, or ref_locations are NULL
- CPL_ERROR_INVALID_TYPE: ref_img and test_img are not of type CPL_TYPE_INT, CPL_TYPE_FLOAT or CPL_TYPE_DOUBLE
- CPL_ERROR_ILLEGAL_INPUT:
  - the number of rows in ref_locations or test_locations is not 2
  - area_size is not >= (max_distance * 3) + 2
  - area_size < 5
- CPL_ERROR_INCOMPATIBLE_INPUT: the number of columns in ref_locations and test_locations (if provided) are not equal
- CPL_ERROR_TYPE_MISMATCH: ref_img and test_img do not have the same type
- CPL_ERROR_UNSUPPORTED_MODE: the alignment mode is not supported
- CPL_ERROR_ILLEGAL_OUTPUT:
  - the number of successful correlations and centroidings is not enough to perform a successful alignment (see also clipm_align_points()), which might also imply that there were not enough input locations
- CPL_ERROR_SINGULAR_MATRIX:
  - the choice of locations does not facilitate the computation of an alignment solution
These error codes are stored in all_error_codes if either the cross-correlation or horizontal or vertical centroiding failed:
- 0: success
- CPL_ERROR_ACCESS_OUT_OF_RANGE: the specified sub_region exceeds the boundaries of the respective image
- CPL_ERROR_ILLEGAL_OUTPUT: the determined cross-correlation translation exceeds max_distance
- CPL_ERROR_CONTINUE: the centroiding of the cross-correlation output failed
- -1: this value just catches potential library version conflicts

Examples:: Compute the free image transformation coefficients that are necessary to transform and map an image over another, and do transform it:
clipm_align_correlate( ref_img,

test_img,

ref_locations,

test_locations,

area_size,

max_distance,

CLIPM_ALIGN_FREE,

&transform_matrix,

&transform_shift,

NULL,

NULL,

NULL,

NULL);

clipm_image_transform_matrix(

test_img,

transform_matrix,

transform_shift,

CLIPM_INTERPOLATION_LINEAR,

0,

NULL,

NULL);

*

Compute the median image shift:
clipm_align_correlate( ref_img,

test_img,

ref_locations,

test_locations,

area_size,

max_distance,

CLIPM_ALIGN_SHIFT |

CLIPM_ALIGN_ROBUST,

NULL,

&transform_shift,

NULL,

NULL,

NULL,

NULL);

*

Compute all successful correlation area shifts (in pixel units):
clipm_align_correlate( ref_img,

test_img,

ref_locations,

test_locations,

area_size,

max_distance,

0, // alignment mode not used

NULL,

NULL,

&pixelshifts,

NULL,

NULL,

&error_codes);

good_shifts = clipm_priv_matrix_select_cols(

pixelshifts,

cpl_array_get_data_int(

error_codes),

0);

*

Functions

Detailed Description

Function Documentation