## tip

tip — SPM tip methods

## Synopsis

    #include <libprocess/gwyprocess.h>

    gboolean            (*GwySetFractionFunc)               (gdouble fraction);
    gboolean            (*GwySetMessageFunc)                (const gchar *message);
    void                (*GwyTipModelFunc)                  (GwyDataField *tip,
                                                             gdouble height,
                                                             gdouble radius,
                                                             gdouble rotation,
                                                             gdouble *params);
    void                (*GwyTipGuessFunc)                  (GwyDataField *data,
                                                             gdouble height,
                                                             gdouble radius,
                                                             gdouble *params,
                                                             gint *xres,
                                                             gint *yres);
                        GwyTipModelPreset;
    gint                gwy_tip_model_get_npresets          (void);
    const GwyTipModelPreset* gwy_tip_model_get_preset       (gint preset_id);
    const GwyTipModelPreset* gwy_tip_model_get_preset_by_name
                                                            (const gchar *name);
    gint                gwy_tip_model_get_preset_id         (const GwyTipModelPreset *preset);
    const gchar*        gwy_tip_model_get_preset_tip_name   (const GwyTipModelPreset *preset);
    const gchar*        gwy_tip_model_get_preset_group_name (const GwyTipModelPreset *preset);
    gint                gwy_tip_model_get_preset_nparams    (const GwyTipModelPreset *preset);
    GwyDataField*       gwy_tip_dilation                    (GwyDataField *tip,
                                                             GwyDataField *surface,
                                                             GwyDataField *result,
                                                             GwySetFractionFunc set_fraction,
                                                             GwySetMessageFunc set_message);
    GwyDataField*       gwy_tip_erosion                     (GwyDataField *tip,
                                                             GwyDataField *surface,
                                                             GwyDataField *result,
                                                             GwySetFractionFunc set_fraction,
                                                             GwySetMessageFunc set_message);
    GwyDataField*       gwy_tip_cmap                        (GwyDataField *tip,
                                                             GwyDataField *surface,
                                                             GwyDataField *result,
                                                             GwySetFractionFunc set_fraction,
                                                             GwySetMessageFunc set_message);
    GwyDataField*       gwy_tip_estimate_partial            (GwyDataField *tip,
                                                             GwyDataField *surface,
                                                             gdouble threshold,
                                                             gboolean use_edges,
                                                             gint *count,
                                                             GwySetFractionFunc set_fraction,
                                                             GwySetMessageFunc set_message);
    GwyDataField*       gwy_tip_estimate_full               (GwyDataField *tip,
                                                             GwyDataField *surface,
                                                             gdouble threshold,
                                                             gboolean use_edges,
                                                             gint *count,
                                                             GwySetFractionFunc set_fraction,
                                                             GwySetMessageFunc set_message);

## Description

## Details

### GwySetFractionFunc ()

    gboolean            (*GwySetFractionFunc)               (gdouble fraction);

`fraction` : |
Returns : |

### GwySetMessageFunc ()

    gboolean            (*GwySetMessageFunc)                (const gchar *message);

`message` : |
Returns : |

### GwyTipModelFunc ()

    void                (*GwyTipModelFunc)                  (GwyDataField *tip,
                                                             gdouble height,
                                                             gdouble radius,
                                                             gdouble rotation,
                                                             gdouble *params);

`tip` : |
`height` : |
`radius` : |
`rotation` : |
`params` : |

### GwyTipGuessFunc ()

    void                (*GwyTipGuessFunc)                  (GwyDataField *data,
                                                             gdouble height,
                                                             gdouble radius,
                                                             gdouble *params,
                                                             gint *xres,
                                                             gint *yres);

`data` : |
`height` : |
`radius` : |
`params` : |
`xres` : |
`yres` : |

### GwyTipModelPreset

    typedef struct {
        const gchar *tip_name;
        const gchar *group_name;
        GwyTipModelFunc func;
        GwyTipGuessFunc guess;
        gint nparams;
    } GwyTipModelPreset;

### gwy_tip_model_get_npresets ()

    gint                gwy_tip_model_get_npresets          (void);

Find number of actual tip model presets.

Returns : | Number of presets.

### gwy_tip_model_get_preset ()

    const GwyTipModelPreset* gwy_tip_model_get_preset       (gint preset_id);

Get data related to tip preset.

`preset_id` : | Preset identifier.
Returns : | Chosen preset data.

### gwy_tip_model_get_preset_by_name ()

    const GwyTipModelPreset* gwy_tip_model_get_preset_by_name
                                                            (const gchar *name);

Get data related to preset with specified name.

`name` : | Name of tip (e. g. "contact").
Returns : | Chosen preset data.

### gwy_tip_model_get_preset_id ()

    gint                gwy_tip_model_get_preset_id         (const GwyTipModelPreset *preset);

Get preset identifier within all presets.

`preset` : | Tip model preset.
Returns : | Preset id.

### gwy_tip_model_get_preset_tip_name ()

    const gchar*        gwy_tip_model_get_preset_tip_name   (const GwyTipModelPreset *preset);

Get name of the preset (e. g. "contact").

`preset` : | Tip model preset.
Returns : | Preset name.

### gwy_tip_model_get_preset_group_name ()

    const gchar*        gwy_tip_model_get_preset_group_name (const GwyTipModelPreset *preset);

Get group name of preset (e. g. "analytical".)

`preset` : | Tip model preset.
Returns : | Preset group name.

### gwy_tip_model_get_preset_nparams ()

    gint                gwy_tip_model_get_preset_nparams    (const GwyTipModelPreset *preset);

Get number of tip preset parameters.

`preset` : | Tip model preset.
Returns : | Number of parameters.

### gwy_tip_dilation ()

    GwyDataField*       gwy_tip_dilation                    (GwyDataField *tip,
                                                             GwyDataField *surface,
                                                             GwyDataField *result,
                                                             GwySetFractionFunc set_fraction,
                                                             GwySetMessageFunc set_message);

Performs tip convolution (dilation) algorithm published by Villarrubia. This function converts all fields into form requested by "morph_lib.c" library, that is almost identical with original Villarubia's library.

`tip` : | Tip data.
`surface` : | Surface data.
`result` : | Data field where to store dilated surface to.
`set_fraction` : | Function that sets fraction to output (or `NULL`).
`set_message` : | Function that sets message to output (or `NULL`).
Returns : | Dilated surface data, i.e. `result`, on success. May return `NULL` if aborted.

### gwy_tip_erosion ()

    GwyDataField*       gwy_tip_erosion                     (GwyDataField *tip,
                                                             GwyDataField *surface,
                                                             GwyDataField *result,
                                                             GwySetFractionFunc set_fraction,
                                                             GwySetMessageFunc set_message);

Performs surface reconstruction (erosion) algorithm published by Villarrubia. This function converts all fields into form requested by "morph_lib.c" library, that is almost identical with original Villarubia's library.

`tip` : | Tip data.
`surface` : | Surface to be eroded.
`result` : | Data field where to store dilated surface to.
`set_fraction` : | Function that sets fraction to output (or `NULL`).
`set_message` : | Function that sets message to output (or `NULL`).
Returns : | Reconstructed (eroded) surface, i.e. `result`, on success. May return `NULL` if aborted.

### gwy_tip_cmap ()

    GwyDataField*       gwy_tip_cmap                        (GwyDataField *tip,
                                                             GwyDataField *surface,
                                                             GwyDataField *result,
                                                             GwySetFractionFunc set_fraction,
                                                             GwySetMessageFunc set_message);

Performs certainty map algorithm published by Villarrubia. This function converts all fields into form requested by "morph_lib.c" library, that is almost identical with original Villarubia's library. Result certainty map can be used as a mask of points where tip did not directly touch the surface.

`tip` : | Tip data.
`surface` : | Surface data.
`result` : | Data field to store ceratainty map data to.
`set_fraction` : | Function that sets fraction to output (or `NULL`).
`set_message` : | Function that sets message to output (of `NULL`).
Returns : | Certainty map, i.e. `result`, on success. May return `NULL` if aborted.

### gwy_tip_estimate_partial ()

    GwyDataField*       gwy_tip_estimate_partial            (GwyDataField *tip,
                                                             GwyDataField *surface,
                                                             gdouble threshold,
                                                             gboolean use_edges,
                                                             gint *count,
                                                             GwySetFractionFunc set_fraction,
                                                             GwySetMessageFunc set_message);

Performs partial blind estimation algorithm published by Villarrubia. This function converts all fields into form requested by "morph_lib.c" library, that is almost identical with original Villarubia's library. Note that the threshold value must be chosen sufficently high value to supress small fluctulations due to noise (that would lead to very sharp tip) but sufficiently low value to put algorithm at work. A value similar to 1/10000 of surface range can be good. Otherwise we recommend to start with zero threshold and increase it slowly to observe changes and choose right value.

`tip` : | Tip data to be refined (allocated).
`surface` : | Surface data.
`threshold` : | Threshold for noise supression.
`use_edges` : | Whether use also edges of image.
`count` : | Where to store the number of places that produced refinements to.
`set_fraction` : | Function that sets fraction to output (or `NULL`).
`set_message` : | Function that sets message to output (or `NULL`).
Returns : | Estimated tip. May return `NULL` if aborted.

### gwy_tip_estimate_full ()

    GwyDataField*       gwy_tip_estimate_full               (GwyDataField *tip,
                                                             GwyDataField *surface,
                                                             gdouble threshold,
                                                             gboolean use_edges,
                                                             gint *count,
                                                             GwySetFractionFunc set_fraction,
                                                             GwySetMessageFunc set_message);

Performs full blind estimation algorithm published by Villarrubia. This function converts all fields into form requested by "morph_lib.c" library, that is almost identical with original Villarubia's library. Note that the threshold value must be chosen sufficently high value to supress small fluctulations due to noise (that would lead to very sharp tip) but sufficiently low value to put algorithm at work. A value similar to 1/10000 of surface range can be good. Otherwise we recommend to start with zero threshold and increase it slowly to observe changes and choose right value.

`tip` : | Tip data to be refined (allocated).
`surface` : | Surface data.
`threshold` : | Threshold for noise supression.
`use_edges` : | Whether use also edges of image.
`count` : | Where to store the number of places that produced refinements to.
`set_fraction` : | Function that sets fraction to output (or `NULL`).
`set_message` : | Function that sets message to output (or `NULL`).
Returns : | Estimated tip. May return `NULL` if aborted.