## correlation

correlation — Correlation and crosscorrelation

## Synopsis

    #include <libprocess/gwyprocess.h>

    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);
    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);
    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);
    void                gwy_data_field_crosscorrelate_iteration
                                                            (GwyComputationState *state);
    void                gwy_data_field_crosscorrelate_finalize
                                                            (GwyComputationState *state);
    void                gwy_data_field_correlate            (GwyDataField *data_field,
                                                             GwyDataField *kernel_field,
                                                             GwyDataField *score,
                                                             GwyCorrelationType method);
    GwyComputationState* gwy_data_field_correlate_init      (GwyDataField *data_field,
                                                             GwyDataField *kernel_field,
                                                             GwyDataField *score);
    void                gwy_data_field_correlate_iteration  (GwyComputationState *state);
    void                gwy_data_field_correlate_finalize   (GwyComputationState *state);

## Description

## Details

### 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)..

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

`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.
`window_height` : | Correlation window height.

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

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

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

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

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

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

`state` : | Correlation iterator.

### gwy_data_field_correlate_finalize ()

    void                gwy_data_field_correlate_finalize   (GwyComputationState *state);

Destroys a correlation iterator, freeing all resources.

`state` : | Correlation iterator.