Alignment of Patterns

Modules
	Alignment Options
	Available transformation options. These options can be combined bit-wise to allow respective transformation options.

Functions
cpl_error_code	clipm_align_points (const cpl_matrix *ref_points, const cpl_matrix *in_points, const cpl_matrix *ref_variances, const cpl_matrix *in_variances, clipm_align_opt align_mode_bitmask, cpl_matrix **transform_matrix, cpl_matrix **shift, cpl_matrix **residuals)
	The linear transformation between two sets of point coordinates is determined. More...

Detailed Description

This module provides functions for the alignment of objects.

Synopsis:

#include "clipm_align.h"
 * 

Function Documentation

cpl_error_code clipm_align_points	(	const cpl_matrix *	ref_points,
		const cpl_matrix *	in_points,
		const cpl_matrix *	ref_variances,
		const cpl_matrix *	in_variances,
		clipm_align_opt	align_mode_bitmask,
		cpl_matrix **	transform_matrix,
		cpl_matrix **	shift,
		cpl_matrix **	residuals
	)

The linear transformation between two sets of point coordinates is determined.

Parameters

ref_points	Reference point coordinates (column-based)
in_points	Input point coordinates (column-based)
ref_variances	Optional reference point (co-)variances, can be NULL, read below!
in_variances	Optional input point (co-)variances, can be NULL, read below!
align_mode_bitmask	Alignment mode
transform_matrix	Output transformation matrix, can be NULL
shift	Output shifting coordinate, can be NULL
residuals	Output residual coordinates, can be NULL

Returns

CPL error code

Transformation:

This function determines the transformation parameters for two sets of point coordinates as following:

• The point matrices are expected in the following form (the number of rows is the number of dimensions, and the number of columns is the number of points):

  

• Considering an output transformation matrix M and an output shift vector s, an input point coordinate p_n (one column of a coordinate matrix) is transformed by

  

• align_mode_bitmask should be given by a bit-wise combination of the options in Alignment Options.
• The alignment is done by minimizing the mean square error between the transformed input p_n' and the reference coordinates r_n. If CLIPM_ALIGN_ROBUST is given, then a median is used.
• The minimum number of points (columns in ref_points) is:
  • 1, if align_mode_bitmask is CLIPM_ALIGN_SHIFT only (and evt. CLIPM_ALIGN_ROBUST), and
  • N_dims+1, in any other alignment mode, where N_dims is the number of dimensions (i.e. the number of rows in ref_points).
• M is returned as a square matrix with one row/column per dimension, and shift is returned as a one-column matrix with one row per dimension.
• If out_residual_coords is not NULL, then the residuals d are put out (with the same size as ref_points), defined by

  

• ref_points and in_points must contain the same number of columns, i.e. the same number of coordinates.
• The coordinates in ref_points and in_points must be matched, this means that the same columns describe different positions of the same object. If this is not the case, do a point matching like with clipm_match_points_by_name().

Supported Alignment Modes:

The supported alignment modes and the compatibility to alignments of other software is documented centrally in Alignment Options.

Variances:

In future, variances for the reference/input points will be supported. For each variance matrix, 3 different cases are planned:

1. NULL: no variances are given, all input points are weighted the same.
2. variance matrix has same size as point matrix: each point coordinate has an assigned variance value, and equations in the transformation solver will be weighted inversely to the product of the variances of all respectively contained point locations.
3. variance matrix is square with an edge length equal to the number of all entries in the point matrix: the variance matrix is interpreted as a full co-variance matrix, containing in the diagonal all x values, then all y values, then z etc. Variance matrices are not yet supported, and specifying a non-NULL pointer will result an error (see below).

Note

• Any output parameter may be given or not (NULL pointer). If the alignment mode is CLIPM_ALIGN_SHIFT only, transform_matrix will be the identity matrix.
• transform_matrix, shift and residuals must be deleted using cpl_matrix_delete().

Error Handling:

The following error codes are set and put out in the respective case:

• CPL_ERROR_NULL_INPUT: ref_points and/or in_points are NULL
• CPL_ERROR_INCOMPATIBLE_INPUT: ref_points and in_points have different sizes
• CPL_ERROR_UNSUPPORTED_MODE:
  • the alignment mode combination is none of the above list, or
  • CLIPM_ALIGN_ROTATE is used with not 2-dimensional input (if not overridden by CLIPM_ALIGN_FREE)
  • a (co-)variance matrix is specified for one of the above conditions, but the condition is not supported yet.
• CPL_ERROR_SINGULAR_MATRIX:
  • the point coordinates do not facilitate the computation of a solution
• CPL_ERROR_ILLEGAL_INPUT:
  • the number of given points is not enough (see above)
  • a (co-)variance matrix has not one of the sizes described above

Example:

#include <cpl.h>
#include <clipm.h>
#include <stdio.h>

void my_alignment(          double  *ref_positions,
                            double  *in_positions,
                            int     npoints,
                            int     ndims)
{
    cpl_matrix  *Mref,
                *Min,
                *Mtrans,
                *Mshift;
    Mref = cpl_matrix_wrap(ndims, npoints, ref_positions);
    Min = cpl_matrix_wrap(ndims, npoints, in_positions);
    
    if (Mref != NULL && Min != NULL)
        clipm_align_points( Mref,
                            Min,
                            CLIPM_ALIGN_FREE,
                            &Mtrans,
                            &Mshift,
                            NULL);

    if (cpl_error_get_code() != CPL_ERROR_NONE)
        cpl_msg_error(__func__, cpl_error_get_message());
    else
    {
        cpl_msg_info(__func__, "Transformation matrix:");
        cpl_matrix_dump(Mtrans, stdout);
        cpl_msg_info(__func__, "Shifting vector:");
        cpl_matrix_dump(Mshift, stdout);
        
        cpl_matrix_delete(Mtrans);
        cpl_matrix_delete(Mshift);
    }
    
    cpl_matrix_unwrap(Mref);
    cpl_matrix_unwrap(Min);
}

Todo:

• API change to accept uncertainties of points