Gwyddion – Free SPM (AFM, SNOM/NSOM, STM, MFM, …) data analysis software

correlation

correlation — Correlation and crosscorrelation

Functions

gdouble gwy_data_field_get_correlation_score ()
gdouble gwy_data_field_get_weighted_correlation_score ()
void gwy_data_field_crosscorrelate ()
GwyComputationState * gwy_data_field_crosscorrelate_init ()
void gwy_data_field_crosscorrelate_set_weights ()
void gwy_data_field_crosscorrelate_iteration ()
void gwy_data_field_crosscorrelate_finalize ()
void gwy_data_field_correlate ()
GwyComputationState * gwy_data_field_correlate_init ()
void gwy_data_field_correlate_iteration ()
void gwy_data_field_correlate_finalize ()
void gwy_data_field_correlation_search ()

Includes

#include <libprocess/gwyprocess.h>

Description

Functions

gwy_data_field_get_correlation_score ()

gdouble
gwy_data_field_get_correlation_score (GwyDataField *data_field,
                                      GwyDataField *kernel_field,
                                      gint col,
                                      gint row,
                                      gint kernel_col,
                                      gint kernel_row,
                                      gint kernel_width,
                                      gint kernel_height);

Calculates a correlation score in one point.

Correlation window size is given by kernel_col , kernel_row , kernel_width , kernel_height , postion of the correlation window on data is given by col , row .

If anything fails (data too close to boundary, etc.), function returns -1.0 (none correlation)..

Parameters

data_field

A data field.

 

kernel_field

Kernel to correlate data field with.

 

col

Upper-left column position in the data field.

 

row

Upper-left row position in the data field.

 

kernel_col

Upper-left column position in kernel field.

 

kernel_row

Upper-left row position in kernel field.

 

kernel_width

Width of kernel field area.

 

kernel_height

Heigh of kernel field area.

 

Returns

Correlation score (between -1.0 and 1.0). Value 1.0 denotes maximum correlation, -1.0 none correlation.

gwy_data_field_get_weighted_correlation_score ()

gdouble
gwy_data_field_get_weighted_correlation_score
                               (GwyDataField *data_field,
                                GwyDataField *kernel_field,
                                GwyDataField *weight_field,
                                gint col,
                                gint row,
                                gint kernel_col,
                                gint kernel_row,
                                gint kernel_width,
                                gint kernel_height);

Calculates a correlation score in one point using weights to center the used information to the center of kernel.

Correlation window size is given by kernel_col , kernel_row , kernel_width , kernel_height , postion of the correlation window on data is given by col , row .

If anything fails (data too close to boundary, etc.), function returns -1.0 (none correlation)..

Parameters

data_field

A data field.

 

kernel_field

Kernel to correlate data field with.

 

weight_field

data field of same size as kernel window size

 

col

Upper-left column position in the data field.

 

row

Upper-left row position in the data field.

 

kernel_col

Upper-left column position in kernel field.

 

kernel_row

Upper-left row position in kernel field.

 

kernel_width

Width of kernel field area.

 

kernel_height

Heigh of kernel field area.

 

Returns

Correlation score (between -1.0 and 1.0). Value 1.0 denotes maximum correlation, -1.0 none correlation.

gwy_data_field_crosscorrelate ()

void
gwy_data_field_crosscorrelate (GwyDataField *data_field1,
                               GwyDataField *data_field2,
                               GwyDataField *x_dist,
                               GwyDataField *y_dist,
                               GwyDataField *score,
                               gint search_width,
                               gint search_height,
                               gint window_width,
                               gint window_height);

Algorithm for matching two different images of the same object under changes.

It does not use any special features for matching. It simply searches for all points (with their neighbourhood) of data_field1 within data_field2 . Parameters search_width and search_height determine maimum area where to search for points. The area is cenetered in the data_field2 at former position of points at data_field1 .

Parameters

data_field1

A data field.

 

data_field2

A data field.

 

x_dist

A data field to store x-distances to.

 

y_dist

A data field to store y-distances to.

 

score

Data field to store correlation scores to.

 

search_width

Search area width.

 

search_height

Search area height.

 

window_width

Correlation window width. This parameter is not actually used. Pass zero.

 

window_height

Correlation window height. This parameter is not actually used. Pass zero.

 

gwy_data_field_crosscorrelate_init ()

GwyComputationState *
gwy_data_field_crosscorrelate_init (GwyDataField *data_field1,
                                    GwyDataField *data_field2,
                                    GwyDataField *x_dist,
                                    GwyDataField *y_dist,
                                    GwyDataField *score,
                                    gint search_width,
                                    gint search_height,
                                    gint window_width,
                                    gint window_height);

Initializes a cross-correlation iterator.

This iterator reports its state as GwyComputationStateType.

Parameters

data_field1

A data field.

 

data_field2

A data field.

 

x_dist

A data field to store x-distances to, or NULL.

 

y_dist

A data field to store y-distances to, or NULL.

 

score

Data field to store correlation scores to, or NULL.

 

search_width

Search area width.

 

search_height

Search area height.

 

window_width

Correlation window width.

 

window_height

Correlation window height.

 

Returns

A new cross-correlation iterator.

gwy_data_field_crosscorrelate_set_weights ()

void
gwy_data_field_crosscorrelate_set_weights
                               (GwyComputationState *state,
                                GwyWindowingType type);

Sets the weight function to be used within iterative cross-correlation algorithm. By default (not setting it), rectangular windowing is used. This function should be called before running first iteration to get consistent results.

Parameters

state

Cross-correlation iterator.

 

type

Set windowing type to be set as correlation weight, see GwyWindowingType for details.

 

gwy_data_field_crosscorrelate_iteration ()

void
gwy_data_field_crosscorrelate_iteration
                               (GwyComputationState *state);

Performs one iteration of cross-correlation.

Cross-correlation matches two different images of the same object under changes.

It does not use any special features for matching. It simply searches for all points (with their neighbourhood) of data_field1 within data_field2 . Parameters search_width and search_height determine maimum area where to search for points. The area is cenetered in the data_field2 at former position of points at data_field1 .

A cross-correlation iterator can be created with gwy_data_field_crosscorrelate_init(). When iteration ends, either by finishing or being aborted, gwy_data_field_crosscorrelate_finalize() must be called to release allocated resources.

Parameters

state

Cross-correlation iterator.

 

gwy_data_field_crosscorrelate_finalize ()

void
gwy_data_field_crosscorrelate_finalize
                               (GwyComputationState *state);

Destroys a cross-correlation iterator, freeing all resources.

Parameters

state

Cross-correlation iterator.

 

gwy_data_field_correlate ()

void
gwy_data_field_correlate (GwyDataField *data_field,
                          GwyDataField *kernel_field,
                          GwyDataField *score,
                          GwyCorrelationType method);

Computes correlation score for all positions in a data field.

Correlation score is compute for all points in data field data_field and full size of correlation kernel kernel_field .

The points in score correspond to centers of kernel. More precisely, the point ((kxres -1)/2, (kyres -1)/2) in score corresponds to kernel field top left corner coincident with data field top left corner. Points outside the area where the kernel field fits into the data field completely are set to -1 for GWY_CORRELATION_NORMAL.

This function is mostly made obsolete by gwy_data_field_correlation_search() which offers, beside the plain FFT-based correlation, a method equivalent to GWY_CORRELATION_NORMAL as well as several others, all computed efficiently using FFT.

Parameters

data_field

A data field.

 

kernel_field

Correlation kernel.

 

score

Data field to store correlation scores to.

 

method

Correlation score calculation method.

 

gwy_data_field_correlate_init ()

GwyComputationState *
gwy_data_field_correlate_init (GwyDataField *data_field,
                               GwyDataField *kernel_field,
                               GwyDataField *score);

Creates a new correlation iterator.

This iterator reports its state as GwyComputationStateType.

This function is mostly made obsolete by gwy_data_field_correlation_search() which offers, beside the plain FFT-based correlation, a method equivalent to GWY_CORRELATION_NORMAL as well as several others, all computed efficiently using FFT.

Parameters

data_field

A data field.

 

kernel_field

Kernel to correlate data field with.

 

score

Data field to store correlation scores to.

 

Returns

A new correlation iterator.

gwy_data_field_correlate_iteration ()

void
gwy_data_field_correlate_iteration (GwyComputationState *state);

Performs one iteration of correlation.

An iterator can be created with gwy_data_field_correlate_init(). When iteration ends, either by finishing or being aborted, gwy_data_field_correlate_finalize() must be called to release allocated resources.

Parameters

state

Correlation iterator.

 

gwy_data_field_correlate_finalize ()

void
gwy_data_field_correlate_finalize (GwyComputationState *state);

Destroys a correlation iterator, freeing all resources.

Parameters

state

Correlation iterator.

 

gwy_data_field_correlation_search ()

void
gwy_data_field_correlation_search (GwyDataField *dfield,
                                   GwyDataField *kernel,
                                   GwyDataField *kernel_weight,
                                   GwyDataField *target,
                                   GwyCorrSearchType method,
                                   gdouble regcoeff,
                                   GwyExteriorType exterior,
                                   gdouble fill_value);

Performs correlation search of a detail in a larger data field.

There are two basic classes of methods: Covariance (products of kernel and data values are summed) and height difference (squared differences between kernel and data values are summed). For the second class, the sign of the output is inverted. So in both cases higher values mean better match. All methods are implemented efficiently using FFT.

Usually you want to use GWY_CORR_SEARCH_COVARIANCE or GWY_CORR_SEARCH_HEIGHT_DIFF, in which the absolute data offsets play no role (only the differences).

If the detail can also occur with different height scales, use GWY_CORR_SEARCH_COVARIANCE_SCORE or GWY_CORR_SEARCH_HEIGHT_DIFF_SCORE in which the local data variance is normalised. In this case dfield regions with very small (or zero) variance can lead to odd results and spurious maxima. Use regcoeff to suppress them: Score of image details is suppressed if their variance is regcoeff times the mean local variance.

If kernel_weight is non-NULL is allows specify masking/weighting of kernel. The simplest use is masking when searching for a non-rectangular detail. Fill kernel_weight with 1s for important kernel pixels and with 0s for irrelevant pixels. However, you can use arbitrary non-negative weights.

Parameters

dfield

A data field to search.

 

kernel

Detail to find (kernel).

 

kernel_weight

Kernel weight, or NULL. If given, its dimensions must match kernel .

 

target

Data field to fill with the score. It will be resampled to match dfield .

 

method

Method, determining the type of output to put into target .

 

regcoeff

Regularisation coefficient, any positive number. Pass something like 0.1 if unsure. You can also pass zero, it means the same as G_MINDOUBLE.

 

exterior

Exterior pixels handling.

 

fill_value

The value to use with GWY_EXTERIOR_FIXED_VALUE exterior.

 

Since: 2.50

Types and Values

© David Nečas and Petr Klapetek

Home Download News Features Screenshots Documentation Communicate Participate Resources Publications Applications Site Map

Valid XHTML 1.0 Valid CSS