GwyTipModel: Gwyddion Library Reference Manual

## GwyTipModel GwyTipModel — SPM tip modelling |

## Functions

GwyInventory * | gwy_tip_models ()
const gchar * | gwy_tip_model_get_group_name ()
gint | gwy_tip_model_get_n_params ()
const GwyTipParamType * | gwy_tip_model_get_params ()
void | gwy_tip_model_fill_param ()
void | gwy_tip_model_create ()
void | gwy_tip_model_create_for_zrange ()

## Types and Values

enum | GwyTipParamType
struct | GwyTipModel
struct | GwyTipModelClass

## Object Hierarchy

        GObject
        ╰── GwyResource
            ╰── GwyTipModel

## Includes

    #include <libgwyddion/gwyddion.h>

## Description

The follwing tip shapes are defined:

`"Pyramid"` – general pyramid with an arbitrary number of sides
`"Contact"` – four-sided pyramid with atan(√2) side slope
`"Non-contact"` – three-sided pyramid with 70° side slope
`"Delta function"` – single pixel tip
`"Parabola"` – parabolic tip
`"Cone"` – conical tip
`"Elliptical parabola"` – asymmetrical parabolic typ
`"Ball on stick"` – spherical tip at the end of almost-cyliner

The delta-function tip is a single pixel, but usually in a 3×3 or even larger tip image. Therefore, it may or may behave as infinitely sharp, depending on the height.

## Functions

### gwy_tip_models()

    GwyInventory *
    gwy_tip_models (void);

Gets inventory with all the predefined tip models.

#### Returns

tip model inventory.

[transfer none]

### gwy_tip_model_get_group_name()

    const gchar *
    gwy_tip_model_get_group_name (GwyTipModel *model);

Gets group name of of a tip model.

Model names, such as "Analytical" or "Pyramid", are informative.

#### Parameters

model | Tip model. |

#### Returns

Group name.

### gwy_tip_model_get_n_params()

    gint
    gwy_tip_model_get_n_params (GwyTipModel *model);

Get number of tip model parameters.

The parameters are from a predefined set enumerated in GwyTipParamType. Use `gwy_tip_model_get_params()` to get the parameter list.

#### Parameters

model | Tip model. |

#### Returns

Number of model parameters.

### gwy_tip_model_get_params()

    const GwyTipParamType *
    gwy_tip_model_get_params (GwyTipModel *model);

Gets the list of parameters of a tip model.

All tip models have parameters from a predefined set given by the GwyTipParamType enum. Use `gwy_tip_model_get_n_params()` to get the number of parameters.

Note that further items may be in principle added to the enum in the future so you may want to avoid tip models that have parameters with an unknown (higher than known) id.

#### Parameters

model | Tip model. |

#### Returns

List of all tip model parameter ids in ascending order. The array is owned by the library and must not be modified nor freed.

### gwy_tip_model_fill_param()

    void
    gwy_tip_model_fill_param (GwyTipModel *model,
                              gdouble *params,
                              GwyTipParamType type,
                              gdouble value);

Fills one value in an array of tip model parameters.

This helper function simplifies the lookup when setting the values of specific parameters. Instead of getting the list of parameters using `gwy_tip_model_get_params()` and searching for the position of each parameter, you can do

    1
    2
    3
    gdouble *params = g_new(gdouble, gwy_tip_model_get_n_params(model));
    gwy_tip_model_fill_param(model, params, GWY_TIP_PARAM_RADIUS, 6e-9);
    gwy_tip_model_fill_param(model, params, GWY_TIP_PARAM_ROTATION, gwy_deg2rad(60));

provided you know that the model has parameters `GWY_TIP_PARAM_RADIUS` and `GWY_TIP_PARAM_ROTATION`. It is an error to try to set a non-existent parameter.

#### Parameters

model | Tip model. |
params | Array of parameters of `model` where to fill one specific value. The number of elements must be at least the number returned by `gwy_tip_model_get_n_params()`. |
type | The parameter to fill. |
value | Value to set the parameter to. |

### gwy_tip_model_create()

    void
    gwy_tip_model_create (GwyTipModel *model,
                          GwyField *tip,
                          const gdouble *params);

Fills a data field with a model tip model.

Both pixel and physical dimensions of `tip` are preserved by this function. Ensure that before using this function `tip` has the same physical pixel size as target data field you want to use the tip model with.

The number of parameters is the true full number of parameters as reported by `gwy_tip_model_get_n_params()` and `gwy_tip_model_get_params()`. Exacly these parameters are passed in `params` , in the reported order.

#### Parameters

model | Tip model. |
tip | Data field to fill with the tip model. |
params | Parameters of the tip model. |

### gwy_tip_model_create_for_zrange()

    void
    gwy_tip_model_create_for_zrange (GwyTipModel *model,
                                     GwyField *tip,
                                     gdouble zrange,
                                     gboolean square,
                                     const gdouble *params);

Fills a data field with a model tip model, resizing it to make it suitable for the given value range.

The physical dimensions of a pixel in `tip` is preserved by this function. Ensure that before using this function the `tip` data field has the same pixel size as target data field you want to use the tip model with.

However, its dimensions (`xres` and `yres` ) will generally be changed to ensure it is optimal for `zrange` . This means it is guaranteed the height difference between the apex and any border pixel in `tip` is at least `zrange` , while simultaneously the smallest such difference is not much larger than `zrange` .

The number of parameters is the true full number of parameters as reported by `gwy_tip_model_get_n_params()` and `gwy_tip_model_get_params()`. Exacly these parameters are passed in `params` , in the reported order.

#### Parameters

model | Tip model. |
tip | Data field to fill with the tip model. |
zrange | Range of height values in the data determining the required height of the tip model. |
square | `TRUE` to enforce a square data field (with `xres` and `yres` equal). |
params | Parameters of the tip model. |

## Types and Values

### enum GwyTipParamType

Type of tip model parameter.

This enum is used with the new tip model functions `gwy_tip_model_get_params()`, `gwy_tip_model_create()`, `gwy_tip_model_create_for_zrange()`.

#### Members

GWY_TIP_PARAM_HEIGHT | Total tip height. This is used only in the delta function tip; for all others it is implied. |
GWY_TIP_PARAM_RADIUS | Radius of curvature of the tip apex. |
GWY_TIP_PARAM_ROTATION | Rotation angle (in radians). |
GWY_TIP_PARAM_NSIDES | The number of sides for pyramidal tips (an integer ≥ 3, even though it is passed as a double). |
GWY_TIP_PARAM_SLOPE | Half-angle of the apex (complement of the side slope for straight sides), in radians. A small slope angle means a sharp tip. |
GWY_TIP_PARAM_ANISOTROPY | Ratio between larger and smaller tip width in two orthotonal directions. |

### struct GwyTipModel

    struct GwyTipModel;

### struct GwyTipModelClass

    struct GwyTipModelClass {
        GwyResourceClass parent_class;
    };