ifw-odp  2.0.0-alpha
•All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Modules | Functions
Correlation
Mathematics: Analysis

Modules

 Coverage Modes
 Coverage modes for cross-signal operations.
 

Functions

cpl_size clipm_math_get_coverage_size_1d (cpl_size size1, cpl_size size2, cpl_size custom_xy_outsize, clipm_coverage_mode cov)
 Predict the output size of a signal-cross-operation using a certain coverage mode. More...
 
cpl_error_code clipm_math_get_coverage_size (const cpl_size *size1, const cpl_size *size2, const cpl_size *custom_xy_outsize, cpl_size *out_size, int ndims, clipm_coverage_mode cov)
 Predict the output size of a multi-dimensional signal-cross-operation using a certain coverage mode. More...
 
cpl_matrix * clipm_math_xcorr_image (const cpl_image *image1, const cpl_image *image2, const cpl_size *window1, const cpl_size *window2, clipm_coverage_mode cov, const cpl_size *custom_xy_outsize, cpl_matrix **overlap_map)
 Cross-correlate 2 images or image windows. More...
 
cpl_matrix * clipm_math_xcorr_matrix (const cpl_matrix *m1, const cpl_matrix *m2, clipm_coverage_mode cov, const cpl_size *custom_xy_outsize, cpl_matrix **overlap_map)
 Cross-correlate 2 matrices. More...
 
cpl_matrix * clipm_math_normxcorr_image (const cpl_image *image1, const cpl_image *image2, const cpl_size *window1, const cpl_size *window2, clipm_coverage_mode cov, const cpl_size *custom_xy_outsize)
 Normalized cross-correlation of 2 images or image windows. More...
 
cpl_matrix * clipm_math_normxcorr_matrix (const cpl_matrix *m1, const cpl_matrix *m2, clipm_coverage_mode cov, const cpl_size *custom_xy_outsize)
 Normalized cross-correlation of 2 matrices. More...
 
cpl_image * clipm_math_conv_image_matrix (const cpl_image *image, const cpl_matrix *kernelmat, const cpl_size *im_window, clipm_coverage_mode cov, const cpl_size *custom_xy_outsize, int norm_to_kernel, cpl_matrix **overlap_map)
 Convolve an image with a matrix kernel. More...
 

Detailed Description

This module provides functions for signal correlations.

Synopsis:
#include "clipm_math_correlation.h"
*

Function Documentation

cpl_image* clipm_math_conv_image_matrix ( const cpl_image *  image,
const cpl_matrix *  kernelmat,
const cpl_size *  im_window,
clipm_coverage_mode  cov,
const cpl_size *  custom_xy_outsize,
int  norm_to_kernel,
cpl_matrix **  overlap_map 
)

Convolve an image with a matrix kernel.

Parameters
imageInput image (FITS convention)
kernelmatKernel matrix
im_windowCoordinate buffer of the form {x1a, x1b, y1a, y1b}, can be NULL, minimum/maximum order is irrelevant
covCoverage mode
custom_xy_outsizeCustom output size buffer for cov == CLIPM_COVERAGE_CUSTOM, otherwise ignored and can be NULL
norm_to_kernelFlag whether to normalise to the overlapping kernel weight
overlap_mapOptional output weighting map for normalising the output matrix, can be NULL
Returns
Convolved image, NULL on error
Algorithm:
  • The convolution of an image with a kernel matrix is performed.
  • The kernel matrix is internally vertically flipped due to the different internal array organisations (images upwards, matrices downwards).
  • An upshift of kernelmat means an upper row in the output image, and a rightshift means a column to the right in the ouput.
  • If window? is not NULL, then the respective region of the image is used as input.
  • If given, overlap_map will contain the local amount of the overlapping pixels. This can be of interest if the coverage mode is not CLIPM_COVERAGE_VALID.
  • This function does not regard bad pixels, since the impact on the processing time would be high and there are different philosophies to handle them (like setting to zero and parallel-processing of weighting maps, or interpolation, or masking whole affected ranges after a cross-signal operation).
Constraints:
The input image must be of the type CPL_TYPE_FLOAT or CPL_TYPE_DOUBLE.
Signal Shift:
The output image size depends on the coverage mode (see also clipm_coverage_mode), as following:
  • CLIPM_COVERAGE_VALID: the output image size will be [abs(xsize1-xsize2)+1,abs(ysize1-ysize2)+1].
  • CLIPM_COVERAGE_SAME: the output image size will be the same as of image 1. The size of kernelmat should be odd. If the size of kernelmat is even (either horizontally or vertically), then the overhang of kernelmat with respect to image will be greater by 1 to the left or bottom (lower indices) than to the right or top (higher indices).
  • CLIPM_COVERAGE_FULL: the output image size will be [xsize1+xsize2-1,ysize1+ysize2-1].
  • CLIPM_COVERAGE_CUSTOM: the output image will have the size as stored in custom_xy_outsize, the central value of the output image corresponds to kernelmat centered over image.
Note
  • The resulting image has to be deleted using cpl_image_delete().
  • The optional overlap_map has to be deleted using cpl_matrix_delete().
Error Handling:
The following codes are set in the case of error:
  • CPL_ERROR_NULL_INPUT:
    • image and/or kernelmat is NULL, or
    • custom_xy_outsize is NULL but required
  • CPL_ERROR_ACCESS_OUT_OF_RANGE:
    • window coordinates are outside the image, or
    • custom_xy_outsize has entries bigger than possible (bigger than with the mode CLIPM_COVERAGE_FULL) or less than 1
  • CPL_ERROR_INVALID_TYPE: the passed image type is not supported
  • CPL_ERROR_ILLEGAL_INPUT: if cov is CLIPM_COVERAGE_VALID and one of image and kernelmat is not the biggest in ALL dimensions (cp. clipm_math_get_coverage_size())
  • CPL_ERROR_UNSUPPORTED_MODE: the coverage mode is not supported
See Also
cpl_error_code clipm_math_get_coverage_size ( const cpl_size *  size1,
const cpl_size *  size2,
const cpl_size *  custom_xy_outsize,
cpl_size *  out_size,
int  ndims,
clipm_coverage_mode  cov 
)

Predict the output size of a multi-dimensional signal-cross-operation using a certain coverage mode.

Parameters
size1Size of input signal 1 as [x, y] buffer
size2Size of input signal 2 as [x, y] buffer
custom_xy_outsizeCustom output size buffer for cov == CLIPM_COVERAGE_CUSTOM, otherwise ignored and can be NULL
out_sizeOutput size buffer
ndimsNumber of dimensions
covCoverage mode
Returns
The resulting size
Principle:
When concolving or correlating for example an image with another image, then this function determines the output size.
Constraints:
  • size1, size2 and out_size are not checked for NULL, passing NULL or buffers smaller than ndims will crash the application!.
  • size1 and size2 are not checked for being greater or equal than 1. Providing such values will result in unreasonable output values.
Error Handling:
In the case of error, one of the following error codes is set, and out_size is left untouched.
  • CPL_ERROR_ILLEGAL_INPUT: Using the mode CLIPM_COVERAGE_VALID in a higher dimensional operation might not be possible. This happens if one object is not the biggest in ALL dimensions, for example for two images of size 10x20 and 20x10.
  • CPL_ERROR_UNSUPPORTED_MODE: cov is not supported
  • CPL_ERROR_ACCESS_OUT_OF_RANGE:
    • an entry of size1 or size2 < 1, or
    • cov == CLIPM_COVERAGE_CUSTOM and an entry of custom_xy_outsize < 1 or greater than possible (i.e. greater than the mode CLIPM_COVERAGE_FULL would return)
  • CPL_ERROR_NULL_INPUT:
    • cov == CLIPM_COVERAGE_CUSTOM and custom_xy_outsize == NULL
cpl_size clipm_math_get_coverage_size_1d ( cpl_size  size1,
cpl_size  size2,
cpl_size  custom_xy_outsize,
clipm_coverage_mode  cov 
)

Predict the output size of a signal-cross-operation using a certain coverage mode.

Parameters
size1Size of input signal 1
size2Size of input signal 2
custom_xy_outsizeCustom output size
covCoverage mode
Returns
The resulting size, 0 on error
Principle:
When concolving or correlating a vector with another vector, then this function determines the output size.
Error Handling:
In the case of error, one of the following error codes is set, and 0 is returned:
  • CPL_ERROR_UNSUPPORTED_MODE: cov is not supported
  • CPL_ERROR_ACCESS_OUT_OF_RANGE:
    • size1 < 1 or size2 < 1, or
    • cov = CLIPM_COVERAGE_CUSTOM and custom_xy_outsize < 1
cpl_matrix* clipm_math_normxcorr_image ( const cpl_image *  image1,
const cpl_image *  image2,
const cpl_size *  window1,
const cpl_size *  window2,
clipm_coverage_mode  cov,
const cpl_size *  custom_xy_outsize 
)

Normalized cross-correlation of 2 images or image windows.

Parameters
image1First image (FITS convention)
image2Second image (FITS convention)
window1Coordinate buffer of the form {x1a, x1b, y1a, y1b}, can be NULL, minimum/maximum order is irrelevant
window2Coordinate buffer of the form {x2a, x2b, y2a, y2b}, can be NULL, minimum/maximum order is irrelevant
covCoverage mode
custom_xy_outsizeCustom output size buffer for cov == CLIPM_COVERAGE_CUSTOM, otherwise ignored and can be NULL
Returns
Correlation matrix, NULL on error
Algorithm:
The normalized correlation of two images is performed in the following way:
  1. The means of the whole images (or image windows) are subtracted (i.e. the constant component is removed):

    \[ I_1'(x,y) = I_1(x,y) - \frac{1}{N}\sum_{x,y} I_1(x,y), \quad I_2'(x,y) = I_2(x,y) - \frac{1}{N}\sum_{x,y} I_2(x,y) \]

  2. The cross-correlation is computed and normalized to the geometric mean of the energies of the respective overlapping signals:

    \[ C(h, v) = \frac { \sum_{x,y} I_1'(x, y) \cdot I_2'(x-h, y-v) } { \sqrt{ \sum_{x,y} I_1'(x, y)^2 \cdot \sum_{x,y} I_2'(x-h, y-v)^2 } } \]

  3. An upshift of image2 means an upper row in the output matrix, and a rightshift means a column to the right in the ouput. Due to the FITS convention and the vertically flipped indexing, the internal computation is made using $ M_{output}(row, column) = C(column-offset_x, offset_y-row) $ (where the indexing offsets adapt for the regarded overlap of the images requested by cov).
  • If window? is not NULL, then the respective region of the image is used as input.
  • This function does not regard bad pixels, since the impact on the processing time would be high and there are different philosophies to handle them (like setting to zero and parallel-processing of weighting maps, or interpolation, or masking whole affected ranges after a cross-signal operation).
Constraints:
The input images must be of the same type, and this be CPL_TYPE_INT, CPL_TYPE_FLOAT or CPL_TYPE_DOUBLE
Signal Shift:
The output matrix size depends on the coverage mode (see also clipm_coverage_mode), as following:
  • CLIPM_COVERAGE_VALID: the output matrix size will be [abs(xsize1-xsize2)+1,abs(ysize1-ysize2)+1].
  • CLIPM_COVERAGE_SAME: the output matrix size will be the same as of image 1. The size of image2 should be odd. If the size of image2 is even (either horizontally or vertically), then the overhang of image2 with respect to image1 will be greater by 1 to the left or bottom (lower indices) than to the right or top (higher indices).
  • CLIPM_COVERAGE_FULL: the output matrix size will be [xsize1+xsize2-1,ysize1+ysize2-1].
  • CLIPM_COVERAGE_CUSTOM: the output matrix will have the size as stored in custom_xy_outsize, the central value of the output matrix corresponds to image2 centered over image1.
Note
  • The correlation matrix has to be deleted using cpl_matrix_delete().
  • Cross-correlation is not commutative.
Error Handling:
The following codes are set in the case of error:
  • CPL_ERROR_NULL_INPUT:
    • image1 and/or image2 is NULL, or
    • custom_xy_outsize is NULL but required
  • CPL_ERROR_ACCESS_OUT_OF_RANGE:
    • window coordinates are outside the image, or
    • custom_xy_outsize has entries bigger than possible (bigger than with the mode CLIPM_COVERAGE_FULL) or less than 1
  • CPL_ERROR_TYPE_MISMATCH: the two images have different types
  • CPL_ERROR_INVALID_TYPE: the passed image type is not supported
  • CPL_ERROR_ILLEGAL_INPUT: if cov is CLIPM_COVERAGE_VALID and one of the two images is not the biggest in ALL dimensions (cp. clipm_math_get_coverage_size())
  • CPL_ERROR_UNSUPPORTED_MODE: the coverage mode is not supported
See Also
cpl_matrix* clipm_math_normxcorr_matrix ( const cpl_matrix *  m1,
const cpl_matrix *  m2,
clipm_coverage_mode  cov,
const cpl_size *  custom_xy_outsize 
)

Normalized cross-correlation of 2 matrices.

Parameters
m1First matrix
m2Second matrix
covCoverage mode
custom_xy_outsizeCustom output size buffer (of size 2, containing {x, y}) for cov == CLIPM_COVERAGE_CUSTOM, otherwise ignored and can be NULL
Returns
Correlation matrix, NULL on error
Algorithm:
The normalized correlation of two matrices is performed in the following way:
  1. The means of the whole matrices are subtracted (i.e. the constant component is removed):

    \[ M_1'(x,y) = M_1(x,y) - \frac{1}{N}\sum_{x,y} M_1(x,y), \quad M_2'(x,y) = M_2(x,y) - \frac{1}{N}\sum_{x,y} M_2(x,y) \]

  2. The cross-correlation is computed and normalized to the geometric mean of the energies of the respective overlapping signals:

    \[ C(h, v) = \frac { \sum_{x,y} M_1'(x, y) \cdot M_2'(x-h, y-v) } { \sqrt{ \sum_{x,y} M_1'(x, y)^2 \cdot \sum_{x,y} M_2'(x-h, y-v)^2 } } \]

  3. An upshift of m2 means an upper row in the output matrix, and a rightshift means a column to the right in the ouput.
Signal Shift:
The output matrix size depends on the coverage mode (see also clipm_coverage_mode), as following:
  • CLIPM_COVERAGE_VALID: the output matrix size will be [abs(xsize1-xsize2)+1,abs(ysize1-ysize2)+1].
  • CLIPM_COVERAGE_SAME: the output matrix size will be the same as of matrix 1. The size of m2 should be odd. If the size of m2 is even (either horizontally or vertically), then the overhang of m2 with respect to m1 will be greater by 1 to the left or bottom (lower indices) than to the right or top (higher indices).
  • CLIPM_COVERAGE_FULL: the output matrix size will be [xsize1+xsize2-1,ysize1+ysize2-1].
  • CLIPM_COVERAGE_CUSTOM: the output matrix will have the size as stored in custom_xy_outsize, the central value of the output matrix corresponds to m2 centered over m1.
Note
  • The correlation matrix has to be deleted using cpl_matrix_delete().
  • Cross-correlation is not commutative.
Error Handling:
The following codes are set in the case of error:
  • CPL_ERROR_NULL_INPUT:
    • m1 and/or m2 is NULL, or
    • custom_xy_outsize is NULL but required
  • CPL_ERROR_ACCESS_OUT_OF_RANGE: custom_xy_outsize has entries bigger than possible (bigger than with the mode CLIPM_COVERAGE_FULL) or less than 1
  • CPL_ERROR_ILLEGAL_INPUT: if cov is CLIPM_COVERAGE_VALID and one of the two images is not the biggest in ALL dimensions (cp. clipm_math_get_coverage_size())
  • CPL_ERROR_UNSUPPORTED_MODE: the coverage mode is not supported
See Also
cpl_matrix* clipm_math_xcorr_image ( const cpl_image *  image1,
const cpl_image *  image2,
const cpl_size *  window1,
const cpl_size *  window2,
clipm_coverage_mode  cov,
const cpl_size *  custom_xy_outsize,
cpl_matrix **  overlap_map 
)

Cross-correlate 2 images or image windows.

Parameters
image1First image (FITS convention)
image2Second image (FITS convention)
window1Coordinate buffer of the form {x1a, x1b, y1a, y1b}, can be NULL, minimum/maximum order is irrelevant
window2Coordinate buffer of the form {x2a, x2b, y2a, y2b}, can be NULL, minimum/maximum order is irrelevant
covCoverage mode
custom_xy_outsizeCustom output size buffer for cov == CLIPM_COVERAGE_CUSTOM, otherwise ignored and can be NULL
overlap_mapOptional output weighting map for normalising the output matrix, can be NULL
Returns
Correlation matrix, NULL on error
Algorithm:
  • The cross-correlation of two images is computed:

    \[ C(h, v) = \sum_{x,y} I_1(x, y) \cdot I_2(x-h, y-v) \]

    No normalization is performed.
  • An upshift of image2 means an upper row in the output matrix, and a rightshift means a column to the right in the ouput. Due to the FITS convention and the vertically flipped indexing, the internal computation is made using $ M_{output}(row, column) = C(column-offset_x, offset_y-row) $ (where the indexing offsets adapt for the regarded overlap of the images requested by cov).
  • If window? is not NULL, then the respective region of the image is used as input.
  • If given, overlap_map will contain the local amount of the signal overlap. This can be of interest if the coverage mode is not CLIPM_COVERAGE_VALID.
  • This function does not regard bad pixels, since the impact on the processing time would be high and there are different philosophies to handle them (like setting to zero and parallel-processing of weighting maps, or interpolation, or masking whole affected ranges after a cross-signal operation).
Constraints:
  • The input images must be of the same type, and this be CPL_TYPE_INT, CPL_TYPE_FLOAT or CPL_TYPE_DOUBLE
Signal Shift:
The output matrix size depends on the coverage mode (see also clipm_coverage_mode), as following:
  • CLIPM_COVERAGE_VALID: the output matrix size will be [abs(xsize1-xsize2)+1,abs(ysize1-ysize2)+1].
  • CLIPM_COVERAGE_SAME: the output matrix size will be the same as of image 1. The size of image2 should be odd. If the size of image2 is even (either horizontally or vertically), then the overhang of image2 with respect to image1 will be greater by 1 to the left or bottom (lower indices) than to the right or top (higher indices).
  • CLIPM_COVERAGE_FULL: the output matrix size will be [xsize1+xsize2-1,ysize1+ysize2-1].
  • CLIPM_COVERAGE_CUSTOM: the output matrix will have the size as stored in custom_xy_outsize, the central value of the output matrix corresponds to image2 centered over image1.
Note
  • The correlation matrix, and the eventual overlap_map, have to be deleted using cpl_matrix_delete().
  • Cross-correlation is not commutative.
  • If overlap_map is not NULL, then the overlap weight is put out. The correlation matrix can then be normalised by the weighting map. This can be of interest if the coverage mode is not CLIPM_COVERAGE_VALID (but is not the same as a normalized cross-correlation, cp. clipm_math_normxcorr_matrix()).
Error Handling:
The following codes are set in the case of error:
  • CPL_ERROR_NULL_INPUT:
    • image1 and/or image2 is NULL, or
    • custom_xy_outsize is NULL but required
  • CPL_ERROR_ACCESS_OUT_OF_RANGE:
    • window coordinates are outside the image, or
    • custom_xy_outsize has entries bigger than possible (bigger than with the mode CLIPM_COVERAGE_FULL) or less than 1
  • CPL_ERROR_TYPE_MISMATCH: the two images have different types
  • CPL_ERROR_INVALID_TYPE: the passed image type is not supported
  • CPL_ERROR_ILLEGAL_INPUT: if cov is CLIPM_COVERAGE_VALID and one of the two images is not the biggest in ALL dimensions (cp. clipm_math_get_coverage_size())
  • CPL_ERROR_UNSUPPORTED_MODE: the coverage mode is not supported
See Also
cpl_matrix* clipm_math_xcorr_matrix ( const cpl_matrix *  m1,
const cpl_matrix *  m2,
clipm_coverage_mode  cov,
const cpl_size *  custom_xy_outsize,
cpl_matrix **  overlap_map 
)

Cross-correlate 2 matrices.

Parameters
m1First matrix
m2Second matrix
covCoverage mode
custom_xy_outsizeCustom output size buffer for cov == CLIPM_COVERAGE_CUSTOM, otherwise ignored and can be NULL
overlap_mapOptional output weighting map for normalising the output matrix
Returns
Correlation matrix, NULL on error
Algorithm:
  • The cross-correlation of two matrices is computed:

    \[ C(h, v) = \sum_{x,y} M_1(x, y) \cdot M_2(x-h, y-v) \]

    No normalization is performed.
  • An upshift of image2 means an upper row in the output matrix, and a rightshift means a column to the right in the ouput.
  • If given, overlap_map will contain the local amount of the signal overlap. This can be of interest if the coverage mode is not CLIPM_COVERAGE_VALID.
Signal Shift:
The output matrix size depends on the coverage mode (see also clipm_coverage_mode), as following:
  • CLIPM_COVERAGE_VALID: the output matrix size will be [abs(xsize1-xsize2)+1,abs(ysize1-ysize2)+1].
  • CLIPM_COVERAGE_SAME: the output matrix size will be the same as of m1. The size of m2 should be odd. If the size of m2 is even (either horizontally or vertically), then the overhang of m2 with respect to m1 will be greater by 1 to the left or top (lower indices) than to the right or bottom (higher indices).
  • CLIPM_COVERAGE_FULL: the output matrix size will be [xsize1+xsize2-1,ysize1+ysize2-1].
  • CLIPM_COVERAGE_CUSTOM: the output matrix will have the size as stored in custom_xy_outsize, the central value of the output matrix corresponds to m2 centered over m1.
Note
  • The correlation matrix, and the eventual overlap_map, have to be deleted using cpl_matrix_delete().
  • Cross-correlation is not commutative.
  • If overlap_map is not NULL, then the overlap weight is put out. The correlation matrix can then be normalised by the weighting map. This can be of interest if the coverage mode is not CLIPM_COVERAGE_VALID (but is not the same as a normalized cross-correlation, cp. clipm_math_normxcorr_matrix()).
Error Handling:
The following codes are set in the case of error:
  • CPL_ERROR_NULL_INPUT:
    • m1 and/or m2 is NULL, or
    • custom_xy_outsize is NULL but required
  • CPL_ERROR_ACCESS_OUT_OF_RANGE: custom_xy_outsize has entries bigger than possible (bigger than with the mode CLIPM_COVERAGE_FULL) or less than 1
  • CPL_ERROR_ILLEGAL_INPUT: if cov is CLIPM_COVERAGE_VALID and one of the two images is not the biggest in ALL dimensions (cp. clipm_math_get_coverage_size())
  • CPL_ERROR_UNSUPPORTED_MODE: the coverage mode is not supported
See Also
Generated by   doxygen 1.8.5