Correction: Gwyddion Library Reference Manual

## Correction Correction — Data correction |

## Functions

void | (*GwyCoordTransform2DFunc) ()
const GwyEnum * | gwy_plane_symmetry_get_enum ()
void | gwy_field_laplace_solve ()
void | gwy_field_correct_average ()
void | gwy_field_mark_outliers ()
void | gwy_field_mark_outliers2 ()
void | gwy_field_mark_outliers_iqr ()
void | gwy_field_distort ()
void | gwy_field_sample_distorted ()
void | gwy_field_affine ()
void | gwy_field_affine_prepare ()
gboolean | gwy_field_measure_lattice_acf ()
gboolean | gwy_field_measure_lattice_psdf ()
gboolean | gwy_line_laplace_solve ()
void | gwy_field_mark_scars ()
void | gwy_field_subtract_row_shifts ()
GwyLine * | gwy_field_find_row_shifts_trimmed_mean ()
GwyLine * | gwy_field_find_row_shifts_trimmed_diff ()
void | gwy_field_row_level_poly ()
GwyPlaneSymmetry | gwy_field_unrotate_find_corrections ()
void | gwy_field_distance_blend ()

## Types and Values

enum | GwyPlaneSymmetry
enum | GwyAffineScalingType
enum | GwyLaplaceAll

## Includes

    #include <libgwyddion/gwyddion.h>

## Description

## Functions

### GwyCoordTransform2DFunc()

    void
    (*GwyCoordTransform2DFunc) (gdouble x,
                                gdouble y,
                                gdouble *px,
                                gdouble *py,
                                gpointer user_data);

The type of two-dimensional coordinate transform function.

#### Parameters

x | Old x coordinate. |
y | Old y coordinate. |
px | Location to store new x coordinate. |
py | Location to store new y coordinate. |
user_data | User data passed to the caller function. |

### gwy_plane_symmetry_get_enum()

    const GwyEnum *
    gwy_plane_symmetry_get_enum (void);

Returns GwyEnum for the GwyPlaneSymmetry enum type.

#### Returns

`NULL`-terminated GwyEnum which must not be modified nor freed.

### gwy_field_laplace_solve()

    void
    gwy_field_laplace_solve (GwyField *field,
                             GwyNield *mask,
                             gint grain_id,
                             gdouble qprec);

Replaces masked areas by the solution of Laplace equation.

The boundary conditions on mask boundaries are Dirichlet with values given by pixels on the outer boundary of the masked area. Boundary conditions at field edges are Neumann conditions ∂z/∂n=0 where n denotes the normal to the edge. If entire area of `field` is to be replaced the problem is underspecified, and the minimum-norm solution is used, i.e. `field` will be filled with zeros.

Normally, the grains should be contiguous as produced by `gwy_nield_number_contiguous()` and the function is more efficient in this case. However, it will proceed with non-contiguous and touching grains. The main difference is for the interpolation of a single grain, when other touching grains are not treated differrently from unmarked areas. In particular, the Dirichlet boundary condition is imposed over the contact with other grains, not Neumann.

When `grain_id` is non-positive, the current numbering does not matter. In particular, distinct touching grains behave as a single merged grain for `grain_id` ≤ 0 (they are not interpolated individually in sequence).

For the default value of `qprec` the the result should be good enough for any image processing purposes with the typical local error of order 10⁻⁵ for very large grains and possibly much smaller for small grains. You can lower `qprec` down to about 0.3 or even 0.2 if speed is crucial and some precision can be sacrificed. Below that the result just starts becoming somewhat worse for not much speed increase. Conversely, you may wish to increase `qprec` up to 3 or even 5 if accuracy is important and you can afford the increased computation time.

#### Parameters

field | A two-dimensional data field. |
mask | A two-dimensional data field containing mask defining the areas to interpolate. |
grain_id | The id number of the grain to replace with the solution of Laplace equation, from 1 to the maximum grain number (see `gwy_nield_max()`). Additionally, non-positive values from GwyLaplaceAllType enum can be passed to interpolate all marked or unmarked regions. |
qprec | Speed-accuracy tuning parameter. Pass 1.0 for the default that is fast and sufficiently precise. |

### gwy_field_correct_average()

    void
    gwy_field_correct_average (GwyField *field,
                               GwyNield *mask);

Fills data under mask with the average value of unmasked data.

The function calculates the average value of all unmasked pixels in `field` and then fills all the masked pixels with this average value. It can be useful as the first rough step of replacement of data under the mask since it is much faster than, for example, `gwy_field_laplace_solve()`.

If all data are masked the field is filled with zeroes.

#### Parameters

field | A data field. |
mask | Mask of places to be corrected. |

### gwy_field_mark_outliers()

    void
    gwy_field_mark_outliers (GwyField *field,
                             GwyNield *mask,
                             gdouble thresh);

Creates mask of data that are above or below `thresh` *sigma from average height.

Sigma denotes root-mean square deviation of heights. This criterium corresponds to the usual Gaussian distribution outliers detection if `thresh` is 3.

#### Parameters

field | A data field. |
mask | A data field to be filled with mask. |
thresh | Threshold deviation. |

### gwy_field_mark_outliers2()

    void
    gwy_field_mark_outliers2 (GwyField *field,
                              GwyNield *mask,
                              gdouble thresh_low,
                              gdouble thresh_high);

Creates mask of data that are above or below multiples of rms from average height.

Data that are below `mean` -`thresh_low` *`sigma` or above `mean` +`thresh_high` *`sigma` are marked as outliers, where `sigma` denotes the root-mean square deviation of data values.

See `gwy_field_mark_outliers_iqr()` for a slower but more robust version which uses rank-based statistics. See also `gwy_nield_mark_range()` for marking inside/oustide given range.

#### Parameters

field | A data field. |
mask | A data field to be filled with mask. |
thresh_low | Lower threshold deviation. |
thresh_high | Upper threshold deviation. |

### gwy_field_mark_outliers_iqr()

    void
    gwy_field_mark_outliers_iqr (GwyField *field,
                                 GwyNield *mask,
                                 gdouble thresh_low,
                                 gdouble thresh_high);

Creates mask of data that are above or below multiples of the inter-quartile range.

Data that are below `quartile_25` -`thresh_low` *`iqr` or above `quartile_75` +`thresh_high` *`iqr` are marked as outliers, where `iqr` denotes the inter-quartile range of data values. Note that zero thresholds already remove everything outside the IQR.

See `gwy_field_mark_outliers2()` for a faster but less robust version which uses mean and standard deviation. See also `gwy_nield_mark_range()` for marking inside/oustide given range.

#### Parameters

field | A data field. |
mask | A data field to be filled with mask. |
thresh_low | Lower threshold deviation. |
thresh_high | Upper threshold deviation. |

### gwy_field_distort()

    void
    gwy_field_distort (GwyField *source,
                       GwyField *dest,
                       GwyCoordTransform2DFunc invtrans,
                       gpointer user_data,
                       GwyInterpolationType interp,
                       GwyExteriorType exterior,
                       gdouble fill_value);

Distorts a data field in the horizontal plane.

Note the transform function `invtrans` is the inverse transform, in other words it calculates the old coordinates from the new coordinates (the transform would not be uniquely defined the other way round).

The `GWY_EXTERIOR_LAPLACE` exterior type cannot be used with this function.

#### Parameters

source | Source data field. |
dest | Destination data field. |
invtrans | Inverse transform function, that is the transformation from new coordinates to old coordinates. It gets (`j` +0.5, `i` +0.5), where `i` and `j` are the new row and column indices, passed as the input coordinates. The output coordinates should follow the same convention. Unless a special exterior handling is required, the transform function does not need to concern itself with coordinates being outside of the data. | [scope call]
user_data | Pointer passed as `user_data` to `invtrans` . |
interp | Interpolation type to use. |
exterior | Exterior pixels handling. |
fill_value | The value to use with `GWY_EXTERIOR_FIXED_VALUE` . |

### gwy_field_sample_distorted()

    void
    gwy_field_sample_distorted (GwyField *source,
                                GwyField *dest,
                                const GwyXY *coords,
                                GwyInterpolationType interp,
                                GwyExteriorType exterior,
                                gdouble fill_value);

Resamples a data field in an arbitrarily distorted manner.

Each item in `coords` corresponds to one pixel in `dest` and gives the coordinates in `source` defining the value to set in this pixel.

The `GWY_EXTERIOR_LAPLACE` exterior type cannot be used with this function.

#### Parameters

source | Source data field. |
dest | Destination data field. |
coords | Array of `source` coordinates with the same number of items as `dest` , ordered as data field data. See `gwy_field_distort()` for coordinate convention discussion. |
interp | Interpolation type to use. |
exterior | Exterior pixels handling. |
fill_value | The value to use with `GWY_EXTERIOR_FIXED_VALUE` . |

### gwy_field_affine()

    void
    gwy_field_affine (GwyField *source,
                      GwyField *dest,
                      const gdouble *invtrans,
                      GwyInterpolationType interp,
                      GwyExteriorType exterior,
                      gdouble fill_value);

Performs an affine transformation of a data field in the horizontal plane.

Note the transform `invtrans` is the inverse transform, in other words it calculates the old coordinates from the new coordinates. This way even degenerate (non-invertible) transforms can be meaningfully used. Also note that the (column, row) coordinate system is left-handed.

The `GWY_EXTERIOR_LAPLACE` exterior type cannot be used with this function.

#### Parameters

source | Source data field. |
dest | Destination data field. |
invtrans | Inverse transform, that is the transformation from new pixel coordinates to old pixel coordinates, represented as (`j` +0.5, `i` +0.5), where `i` and `j` are the row and column indices. It is represented as a six-element array [`axx` , `axy` , `ayx` , `ayy` , `bx` , `by` ] where `axy` is the coefficient from `x` to `y` . | [array fixed-size=6]
interp | Interpolation type to use. |
exterior | Exterior pixels handling. |
fill_value | The value to use with `GWY_EXTERIOR_FIXED_VALUE` . |

### gwy_field_affine_prepare()

    void
    gwy_field_affine_prepare (GwyField *source,
                              GwyField *dest,
                              const gdouble *a1a2,
                              gdouble *a1a2_corr,
                              gdouble *invtrans,
                              GwyAffineScalingType scaling,
                              gboolean prevent_rotation,
                              gdouble oversampling);

Resolves an affine transformation of a data field in the horizontal plane.

This function calculates suitable arguments for `gwy_field_affine()` from given images and lattice vectors (in real coordinates).

Data field `dest` will be resized and its real dimensions and units set in anticipation of `gwy_field_affine()`. Its contents will be destroyed.

Note that `a1a2_corr` is an input-output parameter. In general, the vectors will be modified according to `scaling` and `prevent_rotation` to the actual vectors in `dest` after the transformation. Only if `prevent_rotation` is `FALSE` and `scaling` is `GWY_AFFINE_SCALING_AS_GIVEN` the vectors are preserved.

#### Parameters

source | Source data field. |
dest | Destination data field. |
a1a2 | Lattice vectors (or generally base vectors) in `source` , as an array of four components: `x1` , `y1` , `x2` and `y2` . | [array fixed-size=4]
a1a2_corr | Correct lattice vectors (or generally base vectors) `dest` should have after the affine transform, in the same form as `a1a2` . | [inout][array fixed-size=4]
invtrans | Inverse transform as an array of six values to be filled according to `gwy_field_affine()` specification. | [array fixed-size=6]
scaling | How (or if) to scale the correct lattice vectors. |
prevent_rotation | `TRUE` to prevent rotation of the data by rotating `a1a2_corr` as a whole to a direction preserving the data orientation. `FALSE` to take `a1a2_corr` as given. |
oversampling | Oversampling factor. Values larger than 1 mean smaller pixels (and more of them) in `dest` , values smaller than 1 the opposite. Pass 1.0 for the default pixel size choice. |

### gwy_field_measure_lattice_acf()

    gboolean
    gwy_field_measure_lattice_acf (GwyField *acf2d,
                                   gdouble *a1a2);

Estimates or improves estimate of lattice vectors from a 2D ACF field.

Note that the 2D ACF of a data field has to be passed, not the data field itself. The correlation function can be for instance calculated by `gwy_field_acf_2d()`. However, you can calculate and/or process the correlation function in any way you see fit.

When the vectors in `a1a2` are zero the function attempts to estimate the lattice from scratch. But if `a1a2` contains two non-zero vectors it takes them as approximate lattice vectors to improve.

If the function return `FALSE` the array `a1a2` is filled with useless values and must be ignored.

#### Parameters

acf2d | Data field containing two-dimensional autocorrelation function. |
a1a2 | Lattice vectors as an array of four components: `x1` , `y1` , `x2` and `y2` (in real coordinates). | [array fixed-size=4]

#### Returns

`TRUE` if good lattice vectors were found, `FALSE` on failure.

### gwy_field_measure_lattice_psdf()

    gboolean
    gwy_field_measure_lattice_psdf (GwyField *psdf2d,
                                    gdouble *a1a2);

Estimates or improves estimate of lattice vectors from a 2D PSDF field.

Note that the 2D PSDF of a data field has to be passed, not the data field itself. The spectral density can be for instance calculated by `gwy_field_fft_2d()` and summing the squares of real and imaginary parts However, you can calculate and/or process the spectral density in any way you see fit.

When the vectors in `a1a2` are zero the function attempts to estimate the lattice from scratch. But if `a1a2` contains two non-zero vectors it takes them as approximate lattice vectors to improve.

If the function return `FALSE` the array `a1a2` is filled with useless values and must be ignored.

#### Parameters

psdf2d | Data field containing two-dimensional power spectrum density function (or alternatively Fourier coefficient modulus). |
a1a2 | Lattice vectors as an array of four components: `x1` , `y1` , `x2` and `y2` (in real coordinates). | [array fixed-size=4]

#### Returns

`TRUE` if good lattice vectors were found, `FALSE` on failure.

### gwy_line_laplace_solve()

    gboolean
    gwy_line_laplace_solve (GwyLine *line,
                            GwyLine *mask_line);

Fills missing values in a data line using Laplace interpolation.

Both data lines must have the same number of values.

For one-dimensional data the missing data interpolation is explicit. Interior missing segments are filled with linear dependence between the edge points. Missing segments with one end open are filled with the edge value.

#### Parameters

line | A data line. |
mask_line | Mask of places to be corrected. |

#### Returns

`TRUE` if the line contained any data at all. If there are no data the `FALSE` is returned and `line` is filled with zeros.

### gwy_field_mark_scars()

    void
    gwy_field_mark_scars (GwyField *field,
                          GwyNield *result,
                          gdouble threshold_high,
                          gdouble threshold_low,
                          gdouble min_scar_len,
                          gdouble max_scar_width,
                          GwySignFlags sign);

Find and marks scars in a data field.

Scars are linear horizontal defects, consisting of shifted values. Zero or negative values in `result` siginify normal data, positive values siginify samples that are part of a scar.

The function operates on rows. Use `gwy_field_transpose()` if you need a column-wise marking.

#### Parameters

field | A data field to find scars in. |
result | A number field to store the result to (it is resized to match `field` ). |
threshold_high | Miminum relative step for scar marking, must be positive. |
threshold_low | Definite relative step for scar marking, must be at least equal to `threshold_high` . |
min_scar_len | Minimum length of a scar, shorter ones are discarded (must be at least one). |
max_scar_width | Maximum width of a scar, must be at least one. |
sign | Sign(s) of features to mark. |

### gwy_field_subtract_row_shifts()

    void
    gwy_field_subtract_row_shifts (GwyField *field,
                                   GwyLine *shifts);

Shifts entire data field rows as specified by given data line.

Data line `shifts` must have resolution corresponding to the number of `field` rows. Its values are subtracted from individual field rows.

#### Parameters

field | A data field. |
shifts | Data line containing the row shifts. |

### gwy_field_find_row_shifts_trimmed_mean()

    GwyLine *
    gwy_field_find_row_shifts_trimmed_mean
                                   (GwyField *field,
                                    GwyNield *mask,
                                    GwyMaskingType masking,
                                    gdouble trimfrac,
                                    gint mincount);

Finds row shifts to misaligned row correction using trimmed row means.

For zero `trimfrac` the function calculates row means. For `trimfrac` of 1/2 or larger it calculates row medians. Values between correspond to trimmed means.

#### Parameters

field | A data field. |
mask | Mask of values to take values into account/exclude, or `NULL` for full `field` . | [nullable]
masking | Masking mode to use. See the introduction for description of masking modes. |
trimfrac | Fraction of lowest values and highest values to discard when trimming. |
mincount | Minimum number of values in a row necessary for per-row calculation. Rows which are essentially completely masked are not shifted with respect to a global value. Pass a non-positive number to use an automatic minimum count. |

#### Returns

A newly created data line containing the row shifts, for instance row means, medians or trimmed means.

[transfer full]

### gwy_field_find_row_shifts_trimmed_diff()

    GwyLine *
    gwy_field_find_row_shifts_trimmed_diff
                                   (GwyField *field,
                                    GwyNield *mask,
                                    GwyMaskingType masking,
                                    gdouble trimfrac,
                                    gint mincount);

Finds row shifts to misaligned row correction using trimmed means of row differences.

For zero `trimfrac` the function calculates row means. For `trimfrac` of 1/2 or larger it calculates row medians. Values between correspond to trimmed means.

#### Parameters

field | A data field. |
mask | Mask of values to take values into account/exclude, or `NULL` for full `field` . | [nullable]
masking | Masking mode to use. See the introduction for description of masking modes. |
trimfrac | Fraction of lowest values and highest values to discard when trimming. |
mincount | Minimum number of values in a row necessary for per-row calculation. Rows which are essentially completely masked are not shifted with respect to a global value. Pass a non-positive number to use an automatic minimum count. |

#### Returns

A newly created data line containing the row shifts, for instance row means, medians or trimmed means.

[transfer full]

### gwy_field_row_level_poly()

    void
    gwy_field_row_level_poly (GwyField *field,
                              GwyNield *mask,
                              GwyMaskingType masking,
                              gint degree,
                              GwyLine *shifts);

Levels misaligned rows of a data field by fitting and subtracting polynomials.

This function does both the fitting and subtraction in one step.

#### Parameters

field | A data field. |
mask | Mask of values to take values into account/exclude, or `NULL` for full `field` . | [nullable]
masking | Masking mode to use. See the introduction for description of masking modes. |
degree | Polynomial degree (0 is mean value, 1 is tilt, 2 is bow, etc.). |
shifts | Data line where to store the subtracted mean values (constant terms of the polynomials), or `NULL`. It will be resized to match the field vertical dimension. | [nullable]

### gwy_field_unrotate_find_corrections()

    GwyPlaneSymmetry
    gwy_field_unrotate_find_corrections (GwyLine *derdist,
                                         gdouble *correction);

Finds rotation corrections.

Rotation correction is computed for for all symmetry types. In addition an estimate is made about the prevalent one.

#### Parameters

derdist | Angular derivation distribution (normally obrained from `gwy_field_slope_distribution()`). |
correction | Corrections for particular symmetry types will be stored here (indexed by GwyPlaneSymmetry). `correction` [0] contains the most probable correction. All angles are in radians. |

#### Returns

The estimate type of prevalent symmetry.

### gwy_field_distance_blend()

    void
    gwy_field_distance_blend (GwyField *field,
                              GwyField *operand,
                              GwyField *distances,
                              gint col,
                              gint row);

Blends one data field into another using distances.

The blending preserves `field` values everywhere where the distance is non-positive. For positive distances, the larger they are, the more weight `operand` gets. Sufficiently far, the contents of `field` is effectively replaced with `operand` .

The distance scaling is pixel-wise. Thereforre, the distance field is usually created for a masked area by `gwy_nield_distance_transform()`.

Either `operand` and/or `distances` can be of the same size of `field` , or only covering a part of `field` (with top left corner given by `col` and `row` ). When both are smaller than `field` , they must be of the same size.

#### Parameters

field | A data field. |
operand | Another data field to blend into `field` . |
distances | Distances determining the blending. |
col | Area left column. |
row | Area top row. |

## Types and Values

### enum GwyPlaneSymmetry

Plane symmetry types for rotation correction.

#### Members

GWY_SYMMETRY_AUTO | Automatic symmetry selection. |
GWY_SYMMETRY_PARALLEL | Parallel symmetry, there is one prevalent direction (bilateral). |
GWY_SYMMETRY_TRIANGULAR | Triangular symmetry, there are three prevalent directions (unilateral) by 120 degrees. |
GWY_SYMMETRY_SQUARE | Square symmetry, two prevalent directions (bilateral) oriented approximately along image sides. |
GWY_SYMMETRY_RHOMBIC | Rhombic symmetry, two prevalent directions (bilateral) oriented approximately along diagonals. |
GWY_SYMMETRY_HEXAGONAL | Hexagonal symmetry, three prevalent directions (bilateral) by 120 degrees. |
GWY_SYMMETRY_LAST | The number of symmetries. |

### enum GwyAffineScalingType

Type of lattice vector scaling in affine transform preparation.

#### Members

GWY_AFFINE_SCALING_AS_GIVEN | Correct lattice vectors lengths are taken as given. |
GWY_AFFINE_SCALING_PRESERVE_AREA | Correct lattice vectors are scaled to make the transformation area-preserving. |
GWY_AFFINE_SCALING_PRESERVE_X | Correct lattice vectors are scaled to preserve the scale along `x` -axis. |

### enum GwyLaplaceAll

#### Members

GWY_LAPLACE_UNMASKED |  |
GWY_LAPLACE_MASKED |  |
GWY_LAPLACE_ALL_GRAINS |  |