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

correct (HEAD)

correct — Data correction

Functions

void (*GwyCoordTransform2DFunc) ()
void gwy_data_field_laplace_solve ()
void gwy_data_field_correct_laplace_iteration ()
void gwy_data_field_correct_average ()
void gwy_data_field_correct_average_unmasked ()
void gwy_data_field_mask_outliers ()
void gwy_data_field_mask_outliers2 ()
void gwy_data_field_distort ()
void gwy_data_field_sample_distorted ()
void gwy_data_field_affine ()
void gwy_data_field_affine_prepare ()
gboolean gwy_data_field_measure_lattice_acf ()
gboolean gwy_data_field_measure_lattice_psdf ()
gboolean gwy_data_line_correct_laplace ()
void gwy_data_field_mark_scars ()
void gwy_data_field_subtract_row_shifts ()
GwyDataLine * gwy_data_field_find_row_shifts_trimmed_mean ()
GwyDataLine * gwy_data_field_find_row_shifts_trimmed_diff ()
void gwy_data_field_row_level_poly ()
GwyPlaneSymmetry gwy_data_field_unrotate_find_corrections ()

Includes

#include <libprocess/gwyprocess.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.

 

Since: 2.5

gwy_data_field_laplace_solve ()

void
gwy_data_field_laplace_solve (GwyDataField *field,
                              GwyDataField *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; field will be filled with zeros.

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 ngrains (see gwy_data_field_grain_numbers()). Passing 0 means to replace the entire empty space outside grains while passing a negative value means to replace the entire masked area.

 

qprec

Speed-accuracy tuning parameter. Pass 1.0 for the default that is fast and sufficiently precise.

 

Since: 2.47

gwy_data_field_correct_laplace_iteration ()

void
gwy_data_field_correct_laplace_iteration
                               (GwyDataField *data_field,
                                GwyDataField *mask_field,
                                GwyDataField *buffer_field,
                                gdouble corrfactor,
                                gdouble *error);

Performs one interation of Laplace data correction.

Tries to remove all the points in mask off the data by using iterative method similar to solving heat flux equation.

Use this function repeatedly until reasonable error is reached.

Warning

For almost all purposes this function was superseded by non-iterative gwy_data_field_laplace_solve() which is simultaneously much faster and more accurate.

Parameters

data_field

Data field to be corrected.

 

mask_field

Mask of places to be corrected.

 

buffer_field

Initialized to same size as mask and data.

 

error

Maximum change within last step.

 

corrfactor

Correction factor within step.

 

gwy_data_field_correct_average ()

void
gwy_data_field_correct_average (GwyDataField *data_field,
                                GwyDataField *mask_field);

Fills data under mask with the average value.

This function simply puts average value of all the data_field values (both masked and unmasked) into points in data_field lying under points where mask_field values are nonzero.

In most cases you probably want to use gwy_data_field_correct_average_unmasked() instead.

Parameters

data_field

A data field.

 

mask_field

Mask of places to be corrected.

 

gwy_data_field_correct_average_unmasked ()

void
gwy_data_field_correct_average_unmasked
                               (GwyDataField *data_field,
                                GwyDataField *mask_field);

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

This function calculates the average value of all unmasked pixels in data_field and then fills all the masked pixels with this average value. It is useful as the first rough step of correction of data under the mask.

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

Parameters

data_field

A data field.

 

mask_field

Mask of places to be corrected.

 

Since: 2.44

gwy_data_field_mask_outliers ()

void
gwy_data_field_mask_outliers (GwyDataField *data_field,
                              GwyDataField *mask_field,
                              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

data_field

A data field.

 

mask_field

A data field to be filled with mask.

 

thresh

Threshold value.

 

gwy_data_field_mask_outliers2 ()

void
gwy_data_field_mask_outliers2 (GwyDataField *data_field,
                               GwyDataField *mask_field,
                               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 heights.

Parameters

data_field

A data field.

 

mask_field

A data field to be filled with mask.

 

thresh_low

Lower threshold value.

 

thresh_high

Upper threshold value.

 

Since: 2.26

gwy_data_field_distort ()

void
gwy_data_field_distort (GwyDataField *source,
                        GwyDataField *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.

 

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 .

 

Since: 2.5

gwy_data_field_sample_distorted ()

void
gwy_data_field_sample_distorted (GwyDataField *source,
                                 GwyDataField *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_data_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 .

 

Since: 2.45

gwy_data_field_affine ()

void
gwy_data_field_affine (GwyDataField *source,
                       GwyDataField *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 .

 

interp

Interpolation type to use.

 

exterior

Exterior pixels handling.

 

fill_value

The value to use with GWY_EXTERIOR_FIXED_VALUE .

 

Since: 2.34

gwy_data_field_affine_prepare ()

void
gwy_data_field_affine_prepare (GwyDataField *source,
                               GwyDataField *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_data_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_data_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 .

 

a1a2_corr

Correct lattice vectors (or generally base vectors) dest should have after the affine transform, in the same form as a1a2 .

 

invtrans

Inverse transform as an array of six values to be filled according to gwy_data_field_affine() specification.

 

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.

 

Since: 2.49

gwy_data_field_measure_lattice_acf ()

gboolean
gwy_data_field_measure_lattice_acf (GwyDataField *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_data_field_2dacf(). 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).

 

Returns

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

Since: 2.49

gwy_data_field_measure_lattice_psdf ()

gboolean
gwy_data_field_measure_lattice_psdf (GwyDataField *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_data_field_2dfft() 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).

 

Returns

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

Since: 2.49

gwy_data_line_correct_laplace ()

gboolean
gwy_data_line_correct_laplace (GwyDataLine *data_line,
                               GwyDataLine *mask_line);

Fills missing values in a data line using Laplace data correction.

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

data_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 data_line is filled with zeros.

Since: 2.45

gwy_data_field_mark_scars ()

void
gwy_data_field_mark_scars (GwyDataField *data_field,
                           GwyDataField *result,
                           gdouble threshold_high,
                           gdouble threshold_low,
                           gdouble min_scar_len,
                           gdouble max_scar_width,
                           gboolean negative);

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.

Parameters

data_field

A data field to find scars in.

 

result

A data field to store the result to (it is resized to match data_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.

 

negative

TRUE to detect negative scars, FALSE to positive.

 

Since: 2.46

gwy_data_field_subtract_row_shifts ()

void
gwy_data_field_subtract_row_shifts (GwyDataField *data_field,
                                    GwyDataLine *shifts);

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

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

Parameters

data_field

A data field.

 

shifts

Data line containing the row shifts.

 

Since: 2.52

gwy_data_field_find_row_shifts_trimmed_mean ()

GwyDataLine *
gwy_data_field_find_row_shifts_trimmed_mean
                               (GwyDataField *data_field,
                                GwyDataField *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

data_field

A data field.

 

mask

Mask of values to take values into account/exclude, or NULL for full data_field .

 

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.

Since: 2.52

gwy_data_field_find_row_shifts_trimmed_diff ()

GwyDataLine *
gwy_data_field_find_row_shifts_trimmed_diff
                               (GwyDataField *data_field,
                                GwyDataField *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

data_field

A data field.

 

mask

Mask of values to take values into account/exclude, or NULL for full data_field .

 

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.

Since: 2.52

gwy_data_field_row_level_poly ()

void
gwy_data_field_row_level_poly (GwyDataField *field,
                               GwyDataField *mask,
                               GwyMaskingType masking,
                               gint degree,
                               GwyDataLine *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 data_field .

 

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.

 

Since: 2.67

gwy_data_field_unrotate_find_corrections ()

GwyPlaneSymmetry
gwy_data_field_unrotate_find_corrections
                               (GwyDataLine *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_data_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.

© 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