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

GwyShapeFitPreset

GwyShapeFitPreset — 3D geometrical shape fitting functions

Functions

gboolean	gwy_shape_fit_preset_needs_same_units ()
guint	gwy_shape_fit_preset_get_nparams ()
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 ()
GwySIUnit *	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_nsecondary ()
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 ()
GwySIUnit *	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 ()
GwyInventory *	gwy_shape_fit_presets ()

Types and Values

struct	GwyShapeFitPreset
struct	GwyShapeFitPresetClass

Object Hierarchy

    GObject
    ╰── GwyResource
        ╰── GwyShapeFitPreset

Includes

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

As of version 2.47 the defined functions include:

"Grating (simple)"

"Grating (3-level)"

"Holes"

"Sphere"

"Cylinder (lying)"

"Gaussian"

"Lorentzian"

"Pyramid (diamond)"

"Parabolic bump"

"Ring"

Since version 2.53 they also include:

"Cone"

"Plane"

"Pyramid (3-sided)"

"Step (one-sided)"

"Step (two-sided)"

Since version 2.54 they also include:

"Cylinder"

Since version 2.56 they also include:

"Half-sphere"

Since version 2.57 they also include:

"Smooth cone"

"Smooth pyramid"

"Smooth pyramid (3-sided)"

Since version 2.59 they also include:

"Exponential"

"Lunette"

Since version 2.61 they also include:

"Pyramid (rectangle)"

Functions

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.

Since: 2.47

gwy_shape_fit_preset_get_nparams ()

guint
gwy_shape_fit_preset_get_nparams (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.

Since: 2.47

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.

Since: 2.47

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.

Since: 2.61

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.

Since: 2.47

gwy_shape_fit_preset_get_param_units ()

GwySIUnit *
gwy_shape_fit_preset_get_param_units (GwyShapeFitPreset *preset,
                                      guint i,
                                      GwySIUnit *siunit_xy,
                                      GwySIUnit *siunit_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.
siunit_xy	SI unit of lateral coordinates.
siunit_z	SI unit of values.

Returns

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

Since: 2.47

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.

Since: 2.50

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.

Since: 2.50

gwy_shape_fit_preset_get_nsecondary ()

guint
gwy_shape_fit_preset_get_nsecondary (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.

Since: 2.47

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.

Since: 2.47

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.

Since: 2.61

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.

Since: 2.47

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.

Since: 2.47

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.

Since: 2.47

gwy_shape_fit_preset_get_secondary_units ()

GwySIUnit *
gwy_shape_fit_preset_get_secondary_units
                               (GwyShapeFitPreset *preset,
                                guint i,
                                GwySIUnit *siunit_xy,
                                GwySIUnit *siunit_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.
siunit_xy	SI unit of lateral coordinates.
siunit_z	SI unit of values.

Returns

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

Since: 2.47

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.

Since: 2.50

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.

Since: 2.50

gwy_shape_fit_preset_setup ()

void
gwy_shape_fit_preset_setup (GwyShapeFitPreset *preset,
                            const GwyXYZ *points,
                            guint 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.

Since: 2.47

gwy_shape_fit_preset_guess ()

gboolean
gwy_shape_fit_preset_guess (GwyShapeFitPreset *preset,
                            const GwyXYZ *points,
                            guint 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.

Since: 2.47

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

Since: 2.47

gwy_shape_fit_preset_calculate_z ()

void
gwy_shape_fit_preset_calculate_z (GwyShapeFitPreset *preset,
                                  const GwyXYZ *points,
                                  gdouble *z,
                                  guint 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.

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.

Since: 2.47

gwy_shape_fit_preset_calculate_xyz ()

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

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

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.

Since: 2.47

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

Since: 2.47

gwy_shape_fit_preset_fit ()

GwyNLFitter *
gwy_shape_fit_preset_fit (GwyShapeFitPreset *preset,
                          GwyNLFitter *fitter,
                          const GwyXYZ *points,
                          guint 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_math_nlfit_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_math_nlfit_fit_idx()`, may be `NULL`.

Returns

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

Since: 2.47

gwy_shape_fit_preset_quick_fit ()

GwyNLFitter *
gwy_shape_fit_preset_quick_fit (GwyShapeFitPreset *preset,
                                GwyNLFitter *fitter,
                                const GwyXYZ *points,
                                guint 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_surface_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_math_nlfit_fit_idx()`, may be `NULL`.

Returns

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

Since: 2.48

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.

Since: 2.47

Types and Values

struct GwyShapeFitPreset

struct GwyShapeFitPreset;

struct GwyShapeFitPresetClass

struct GwyShapeFitPresetClass {
    GwyResourceClass parent_class;
};