GwyShapeFitPreset: Gwyddion Library Reference Manual

## GwyShapeFitPreset GwyShapeFitPreset — 3D geometrical shape fitting functions |

## Functions

GwyInventory * | gwy_shape_fit_presets ()
gboolean | gwy_shape_fit_preset_needs_same_units ()
guint | gwy_shape_fit_preset_get_n_params ()
const gchar * | gwy_shape_fit_preset_get_param_name ()
const gchar * | gwy_shape_fit_preset_get_param_description ()
GwyNLFitParamFlags | gwy_shape_fit_preset_get_param_flags ()
GwyUnit * | gwy_shape_fit_preset_get_param_units ()
gint | gwy_shape_fit_preset_get_param_power_xy ()
gint | gwy_shape_fit_preset_get_param_power_z ()
guint | gwy_shape_fit_preset_get_n_secondary ()
const gchar * | gwy_shape_fit_preset_get_secondary_name ()
const gchar * | gwy_shape_fit_preset_get_secondary_description ()
GwyNLFitParamFlags | gwy_shape_fit_preset_get_secondary_flags ()
gdouble | gwy_shape_fit_preset_get_secondary_value ()
gdouble | gwy_shape_fit_preset_get_secondary_error ()
GwyUnit * | gwy_shape_fit_preset_get_secondary_units ()
gint | gwy_shape_fit_preset_get_secondary_power_xy ()
gint | gwy_shape_fit_preset_get_secondary_power_z ()
void | gwy_shape_fit_preset_setup ()
gboolean | gwy_shape_fit_preset_guess ()
gdouble | gwy_shape_fit_preset_get_value ()
void | gwy_shape_fit_preset_calculate_z ()
void | gwy_shape_fit_preset_calculate_xyz ()
GwyNLFitter * | gwy_shape_fit_preset_create_fitter ()
GwyNLFitter * | gwy_shape_fit_preset_fit ()
GwyNLFitter * | gwy_shape_fit_preset_quick_fit ()

## Types and Values

struct | GwyShapeFitPreset
struct | GwyShapeFitPresetClass

## Object Hierarchy

        GObject
        ╰── GwyResource
            ╰── GwyShapeFitPreset

## Includes

    #include <libgwyddion/gwyddion.h>

## Description

Non-linear fitter 3D geometrical shape presets are predefined fitting functions

that can be used to determine the parameters of various features in images and XYZ data.

The defined functions include:

`"Plane"` – tilted plane (linear function)
`"Step (one-sided)"` – one-sided step
`"Step (two-sided)"` – two-sided step (bar or trench)
`"Sphere"` – full-height ball on a plane
`"Half-sphere"` – upper half of a ball sticking out of a plane
`"Cylinder"` – vertical cylinder on a plane
`"Cylinder (lying)"` – infinite cylinder lying on a plane
`"Gaussian"` – Gaussian peak on a plane
`"Lorentzian"` – Lorentzian peak on a plane
`"Exponential"` – exponential peak on a plane
`"Pyramid (diamond)"` – pyramid with base orientation along axes
`"Pyramid (rectangle)"` – pyramid with base orientation along diagonals
`"Pyramid (3-sided)"` – three-sided pyramid (tetrahedron)
`"Parabolic bump"` – parabolic bump on a plane
`"Cone"` – cone on a plane
`"Ring"` – bar or trench in the shape of an annulus
`"Smooth cone"` – cone with parabolically rounded tip
`"Smooth pyramid"` – pyramid with parabolically rounded tip
`"Smooth pyramid (3-sided)"` – tetrahedron with parabolically rounded tip
`"Grating (simple)"` – simple periodic grating
`"Grating (3-level)"` – grating with detailed sidewall parameterisation
`"Holes"` – two-dimensional periodic arrangement of holes (or pillars)
`"Lunette"` – asymmetrical crescent/ring shape

## Functions

### gwy_shape_fit_presets()

    GwyInventory *
    gwy_shape_fit_presets (void);

Gets inventory with all the 3D geometric shape fitting presets.

#### Returns

3D geometric shape fitting preset inventory.

[transfer none]

### gwy_shape_fit_preset_needs_same_units()

    gboolean
    gwy_shape_fit_preset_needs_same_units (GwyShapeFitPreset *preset);

Reports if a 3D geometrical shape fitter preset requires the same lateral and value units.

For instance, fitting a sphere is meaningless if the horizontal and vertical radii would be different physical quantities.

#### Parameters

preset | A 3D geometrical shape fitting function. |

#### Returns

`TRUE` if the function requires the same lateral and value units.

### gwy_shape_fit_preset_get_n_params()

    guint
    gwy_shape_fit_preset_get_n_params (GwyShapeFitPreset *preset);

Reports the number of parameters of a 3D geometrical shape fitter preset.

#### Parameters

preset | A 3D geometrical shape fitting function. |

#### Returns

The number of function parameters.

### gwy_shape_fit_preset_get_param_name()

    const gchar *
    gwy_shape_fit_preset_get_param_name (GwyShapeFitPreset *preset,
                                         guint i);

Gets the name of a fitting parameter of a 3D geometrical shape fitter preset.

The name may contain Pango markup.

#### Parameters

preset | A 3D geometrical shape fitting function. |
i | Parameter number. |

#### Returns

The name of the `i` -th parameter.

### gwy_shape_fit_preset_get_param_description()

    const gchar *
    gwy_shape_fit_preset_get_param_description
                                   (GwyShapeFitPreset *preset,
                                    guint i);

Gets the description of a fitting parameter of a 3D geometrical shape fitter preset.

The description may contain Pango markup. It may also be `NULL` if the parameter is currently undescribed.

#### Parameters

preset | A 3D geometrical shape fitting function. |
i | Parameter number. |

#### Returns

The description of the `i` -th parameter, possibly `NULL`.

### gwy_shape_fit_preset_get_param_flags()

    GwyNLFitParamFlags
    gwy_shape_fit_preset_get_param_flags (GwyShapeFitPreset *preset,
                                          guint i);

Gets the properties of a fitting parameter of a 3D geometrical shape fitter preset.

#### Parameters

preset | A 3D geometrical shape fitting function. |
i | Parameter number. |

#### Returns

The flags of the `i` -th parameter.

### gwy_shape_fit_preset_get_param_units()

    GwyUnit *
    gwy_shape_fit_preset_get_param_units (GwyShapeFitPreset *preset,
                                          guint i,
                                          GwyUnit *unit_xy,
                                          GwyUnit *unit_z);

Derives the SI unit of a fitting parameter from the units of abscissa and ordinate.

Note that angle parameters are by default in radians and thus unitless. If you want to convert them to degrees for presentation to the user you must do it explicitly.

#### Parameters

preset | A 3D geometrical shape fitting function. |
i | Parameter number. |
unit_xy | SI unit of lateral coordinates. |
unit_z | SI unit of values. |

#### Returns

A newly created GwyUnit with the units of the `i` -th parameter.

### gwy_shape_fit_preset_get_param_power_xy()

    gint
    gwy_shape_fit_preset_get_param_power_xy
                                   (GwyShapeFitPreset *preset,
                                    guint i);

Gets the power of abscissa units in a shape fitting parameter.

Usually it is easier to let `gwy_shape_fit_preset_get_param_units()` derive the parameter units.

#### Parameters

preset | A 3D geometrical shape fitting function. |
i | Parameter number. |

#### Returns

The power of abscissa in the parameter.

### gwy_shape_fit_preset_get_param_power_z()

    gint
    gwy_shape_fit_preset_get_param_power_z
                                   (GwyShapeFitPreset *preset,
                                    guint i);

Gets the power of ordinate units in a shape fitting parameter.

Usually it is easier to let `gwy_shape_fit_preset_get_param_units()` derive the parameter units.

#### Parameters

preset | A 3D geometrical shape fitting function. |
i | Parameter number. |

#### Returns

The power of ordinate in the parameter.

### gwy_shape_fit_preset_get_n_secondary()

    guint
    gwy_shape_fit_preset_get_n_secondary (GwyShapeFitPreset *preset);

Reports the number of secondary (derived) quantities of a 3D geometrical shape fitter preset.

#### Parameters

preset | A 3D geometrical shape fitting function. |

#### Returns

The number of secondary quantities.

### gwy_shape_fit_preset_get_secondary_name()

    const gchar *
    gwy_shape_fit_preset_get_secondary_name
                                   (GwyShapeFitPreset *preset,
                                    guint i);

Gets the name of a secondary (derived) quantity of a 3D geometrical shape fitter preset.

The name may contain Pango markup.

#### Parameters

preset | A 3D geometrical shape fitting function. |
i | Secondary quantity number. |

#### Returns

The name of the `i` -th secondary quantity.

### gwy_shape_fit_preset_get_secondary_description()

    const gchar *
    gwy_shape_fit_preset_get_secondary_description
                                   (GwyShapeFitPreset *preset,
                                    guint i);

Gets the description of a secondary quantity of a 3D geometrical shape fitter preset.

The description may contain Pango markup. It may also be `NULL` if the quantity is currently undescribed.

#### Parameters

preset | A 3D geometrical shape fitting function. |
i | Secondary quantity number. |

#### Returns

The description of the `i` -th secondary quantity, possibly `NULL`.

### gwy_shape_fit_preset_get_secondary_flags()

    GwyNLFitParamFlags
    gwy_shape_fit_preset_get_secondary_flags
                                   (GwyShapeFitPreset *preset,
                                    guint i);

Gets the properties of a secondary (derived) quantity of a 3D geometrical shape fitter preset.

#### Parameters

preset | A 3D geometrical shape fitting function. |
i | Secondary quantity number. |

#### Returns

The flags of the `i` -th secondary quantity.

### gwy_shape_fit_preset_get_secondary_value()

    gdouble
    gwy_shape_fit_preset_get_secondary_value
                                   (GwyShapeFitPreset *preset,
                                    guint i,
                                    const gdouble *param);

Calculates the value of a secondary (derived) quantity of a 3D geometrical shape fitter preset.

#### Parameters

preset | A 3D geometrical shape fitting function. |
i | Secondary quantity number. |
param | Values of fitting parameters for function `preset` . |

#### Returns

The value of the `i` -th secondary quantity.

### gwy_shape_fit_preset_get_secondary_error()

    gdouble
    gwy_shape_fit_preset_get_secondary_error
                                   (GwyShapeFitPreset *preset,
                                    guint i,
                                    const gdouble *param,
                                    const gdouble *error,
                                    const gdouble *correl);

Calculates the error of a secondary (derived) quantity of a 3D geometrical shape fitter preset.

The error is calculated by numerical differentiation of the function and applying the law of error propagation.

#### Parameters

preset | A 3D geometrical shape fitting function. |
i | Secondary quantity number. |
param | Values of fitting parameters for function `preset` . |
error | Values of errors of fitting parameters for function `preset` . |
correl | Parameter correlation matrix for function `preset` (passed as lower triangular matrix). |

#### Returns

The error of the `i` -th secondary quantity.

### gwy_shape_fit_preset_get_secondary_units()

    GwyUnit *
    gwy_shape_fit_preset_get_secondary_units
                                   (GwyShapeFitPreset *preset,
                                    guint i,
                                    GwyUnit *unit_xy,
                                    GwyUnit *unit_z);

Derives the SI unit of a secondary (derived) quantity from the units of abscissa and ordinate.

Note that angle parameters are by default in radians and thus unitless. If you want to convert them to degrees for presentation to the user you must do it explicitly.

#### Parameters

preset | A 3D geometrical shape fitting function. |
i | Secondary quantity number. |
unit_xy | SI unit of lateral coordinates. |
unit_z | SI unit of values. |

#### Returns

A newly created GwyUnit with the units of the `i` -th secondary quantity.

### gwy_shape_fit_preset_get_secondary_power_xy()

    gint
    gwy_shape_fit_preset_get_secondary_power_xy
                                   (GwyShapeFitPreset *preset,
                                    guint i);

Gets the power of abscissa units in a shape fitting secondary (derived) quantity.

Usually it is easier to let `gwy_shape_fit_preset_get_secondary_units()` derive the quantity units.

#### Parameters

preset | A 3D geometrical shape fitting function. |
i | Secondary quantity number. |

#### Returns

The power of abscissa in the secondary quantity.

### gwy_shape_fit_preset_get_secondary_power_z()

    gint
    gwy_shape_fit_preset_get_secondary_power_z
                                   (GwyShapeFitPreset *preset,
                                    guint i);

Gets the power of ordinate units in a shape fitting secondary (derived) quantity.

Usually it is easier to let `gwy_shape_fit_preset_get_secondary_units()` derive the quantity units.

#### Parameters

preset | A 3D geometrical shape fitting function. |
i | Secondary quantity number. |

#### Returns

The power of ordinate in the secondary quantity.

### gwy_shape_fit_preset_setup()

    void
    gwy_shape_fit_preset_setup (GwyShapeFitPreset *preset,
                                const GwyXYZ *points,
                                gsize n,
                                gdouble *params);

Initialises parameter values of a 3D geometrical shape fitter preset.

The parameters are quickly set to reasonable values that roughly correspond to the ranges of the data points. They may serve as starting values for manual experimentation but often will not be good enough as initial parameter estimates for the fit. See also `gwy_shape_fit_preset_guess()`.

#### Parameters

preset | A 3D geometrical shape fitting function. |
points | Array of XYZ data to fit. |
n | Number of data points. |
params | The array to fill with initialised parameter values. |

### gwy_shape_fit_preset_guess()

    gboolean
    gwy_shape_fit_preset_guess (GwyShapeFitPreset *preset,
                                const GwyXYZ *points,
                                gsize n,
                                gdouble *params);

Estimates parameter values of a 3D geometrical shape fitter preset.

This function tries to find initial parameter estimates that are good enough for the fit the converge. Of course, it is not guaranteed it always succeeds. For some shapes it can be noticeably slower than `gwy_shape_fit_preset_setup()`.

The estimate may not be deterministic. For large point sets some estimates are carried out using a randomly selected subset of points.

If the function cannot find how the data points could correspond to the preset geometrical shape it return `FALSE`. Parameter values are still set. However, in this case they may be no better than from `gwy_shape_fit_preset_setup()`.

#### Parameters

preset | A 3D geometrical shape fitting function. |
points | Array of XYZ data to fit. |
n | Number of data points. |
params | The array to fill with initialised parameter values. |

#### Returns

`TRUE` if the estimation succeeded, `FALSE` if it failed.

### gwy_shape_fit_preset_get_value()

    gdouble
    gwy_shape_fit_preset_get_value (GwyShapeFitPreset *preset,
                                    gdouble x,
                                    gdouble y,
                                    const gdouble *params);

Calculates the value of a 3D geometrical shape fitter preset in a single point.

If you want multiple values you should use either `gwy_shape_fit_preset_calculate_z()` or `gwy_shape_fit_preset_calculate_xyz()` instead of calling this function in a cycle.

#### Parameters

preset | A 3D geometrical shape fitting function. |
x | X-coordinate. |
y | Y-coordinate. |
params | Fitting parameter values. |

#### Returns

The calculated function value in (`x` ,`y` ).

### gwy_shape_fit_preset_calculate_z()

    void
    gwy_shape_fit_preset_calculate_z (GwyShapeFitPreset *preset,
                                      const GwyXYZ *points,
                                      gdouble *z,
                                      gsize n,
                                      const gdouble *params);

Calculates values of a 3D geometrical shape fitter preset in an array of points.

The z-coordinates in `points` are ignored. Only the lateral coordinates are used.

See also `gwy_shape_fit_preset_calculate_xyz()`.

#### Parameters

preset | A 3D geometrical shape fitting function. |
points | Array of `n` XYZ data defining the lateral coordinates. |
z | Array length `n` to fill with calculated values. |
n | Number of items in `points` and `z` . |
params | Fitting parameter values. |

### gwy_shape_fit_preset_calculate_xyz()

    void
    gwy_shape_fit_preset_calculate_xyz (GwyShapeFitPreset *preset,
                                        GwyXYZ *points,
                                        gsize n,
                                        const gdouble *params);

Calculates values of a 3D geometrical shape fitter preset in an array of points.

See also `gwy_shape_fit_preset_calculate_z()`.

#### Parameters

preset | A 3D geometrical shape fitting function. |
points | Array of `n` XYZ data defining the lateral coordinates. The z-coordinates will be filled with the calculated values. |
n | Number of items in `points` . |
params | Fitting parameter values. |

### gwy_shape_fit_preset_create_fitter()

    GwyNLFitter *
    gwy_shape_fit_preset_create_fitter (GwyShapeFitPreset *preset);

Creates a non-linear least-squares fitter for a 3D geometrical shape.

The created fitter will be of the opaque indexed data type, as created with `gwy_nl_fitter_new_idx()`.

If you do not need to modify the fitter settings you can use `gwy_shape_fit_preset_fit()` directly with `NULL` fitter.

#### Parameters

preset | A 3D geometrical shape fitting function. |

#### Returns

A newly created fitter for `preset` .

### gwy_shape_fit_preset_fit()

    GwyNLFitter *
    gwy_shape_fit_preset_fit (GwyShapeFitPreset *preset,
                              GwyNLFitter *fitter,
                              const GwyXYZ *points,
                              gsize n,
                              gdouble *params,
                              const gboolean *fixed_param,
                              gdouble *rss);

Performs a non-linear least-squares fit with a 3D geometrical shape fitter.

If you pass `NULL` `fitter` the function creates one for you and immediately performs the fit. If you want to modify the fitter settings beforehand or set callback functions create it using `gwy_shape_fit_preset_create_fitter()` and pass to this function. The fitter must be created for the same preset.

Additional quantities such as parameter errors or the correlation matrix can be obtained from the fitter. See `gwy_nl_fitter_fit_full()` for details.

#### Parameters

preset | A 3D geometrical shape fitting function. |
fitter | A Marquardt-Levenberg nonlinear fitter already initialized for `preset` 's function, or `NULL`. |
points | Array of `n` XYZ data defining the lateral coordinates and values to fit. |
n | Number of items in `points` . |
params | Fitting parameters filled with initial estimates (the fitting starts from the provided values). |
fixed_param | Which parameters should be treated as fixed (set corresponding element to `TRUE` for them). May be `NULL` if all parameters are free. |
rss | Location to store the residual sum of squares, as returned by `gwy_nl_fitter_fit_idx()`, may be `NULL`. |

#### Returns

Either `fitter` itself, or a newly created fitter if it was `NULL`.

### gwy_shape_fit_preset_quick_fit()

    GwyNLFitter *
    gwy_shape_fit_preset_quick_fit (GwyShapeFitPreset *preset,
                                    GwyNLFitter *fitter,
                                    const GwyXYZ *points,
                                    gsize n,
                                    gdouble *params,
                                    const gboolean *fixed_param,
                                    gdouble *rss);

Performs a rough non-linear least-squares fit with a 3D geometrical shape fitter.

See `gwy_shape_fit_preset_fit()` for discussion. This functions differs by using a reduced number of points to perform the fit (unless the input set is small) and may also set fitter parameters to make the least squares method terminate faster. The input points are reduced the same way as in `gwy_scatter_reduce_points()`.

#### Parameters

preset | A 3D geometrical shape fitting function. |
fitter | A Marquardt-Levenberg nonlinear fitter already initialized for `preset` 's function, or `NULL`. |
points | Array of `n` XYZ data defining the lateral coordinates and values to fit. |
n | Number of items in `points` . |
params | Fitting parameters filled with initial estimates (the fitting starts from the provided values). |
fixed_param | Which parameters should be treated as fixed (set corresponding element to `TRUE` for them). May be `NULL` if all parameters are free. |
rss | Location to store the residual sum of squares, as returned by `gwy_nl_fitter_fit_idx()`, may be `NULL`. |

#### Returns

Either `fitter` itself, or a newly created fitter if it was `NULL`.

## Types and Values

### struct GwyShapeFitPreset

    struct GwyShapeFitPreset;

### struct GwyShapeFitPresetClass

    struct GwyShapeFitPresetClass {
        GwyResourceClass parent_class;
    };

## See Also

GwyNLFitter