tip

tip — SPM tip methods

Functions

void	(*GwyTipModelFunc) ()
void	(*GwyTipGuessFunc) ()
gint	gwy_tip_model_get_npresets ()
const GwyTipModelPreset *	gwy_tip_model_get_preset ()
const GwyTipModelPreset *	gwy_tip_model_get_preset_by_name ()
gint	gwy_tip_model_get_preset_id ()
const gchar *	gwy_tip_model_get_preset_tip_name ()
const gchar *	gwy_tip_model_get_preset_group_name ()
gint	gwy_tip_model_get_preset_nparams ()
const GwyTipParamType *	gwy_tip_model_get_preset_params ()
void	gwy_tip_model_preset_create ()
void	gwy_tip_model_preset_create_for_zrange ()
GwyDataField *	gwy_tip_dilation ()
GwyDataField *	gwy_tip_erosion ()
GwyDataField *	gwy_tip_cmap ()
GwyDataField *	gwy_tip_estimate_partial ()
GwyDataField *	gwy_tip_estimate_full ()

Types and Values

struct

GwyTipModelPreset

Object Hierarchy

    gpointer
    ╰── GwyTipModelPreset

Includes

#include <libprocess/gwyprocess.h>

Description

Functions

GwyTipModelFunc ()

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

Warning

GwyTipModelFunc is deprecated and should not be used in newly-written code.

GwyTipGuessFunc ()

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

Warning

GwyTipGuessFunc is deprecated and should not be used in newly-written code.

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.

Parameters

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.

Parameters

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.

Parameters

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

Parameters

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

Parameters

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.

Warning

In versions prior to 2.47 the function alwas returned zero and thus was useless. You had to know the what parameters each model had and always pass a maximum-nparams-sized array with only the interesting elements containing your parameters. Since version 2.47 it returns the true number of parameters used in functions such as gwy_tip_model_preset_create() and gwy_tip_model_preset_create_for_zrange(). It does not return the number of parameters the old functions take. They behave exactly as before.

Parameters

preset

Tip model preset.

Returns

Number of parameters.

gwy_tip_model_get_preset_params ()

const GwyTipParamType *
gwy_tip_model_get_preset_params (const GwyTipModelPreset *preset);

Gets the list of parameters of a tip model preset.

All tip models have parameters from a predefined set given by the GwyTipParamType enum.

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

Parameters

preset

Tip model preset.

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.

Since: 2.47

gwy_tip_model_preset_create ()

void
gwy_tip_model_preset_create (const GwyTipModelPreset *preset,
                             GwyDataField *tip,
                             const gdouble *params);

Fills a data field with a preset tip model.

Both pixel and physical dimensions of the tip data field are preserved by this function. Ensure that before using this function the tip data field has the same pixels 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_preset_nparams() and gwy_tip_model_get_preset_params(). And only those parameters are passed in params .

Parameters

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

Since: 2.47

gwy_tip_model_preset_create_for_zrange ()

void
gwy_tip_model_preset_create_for_zrange
                               (const GwyTipModelPreset *preset,
                                GwyDataField *tip,
                                gdouble zrange,
                                gboolean square,
                                const gdouble *params);

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

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

However, its dimensions 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_preset_nparams() and gwy_tip_model_get_preset_params(). And only those parameters are passed in params .

Parameters

preset	Tip model preset.
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.

Since: 2.47

gwy_tip_dilation ()

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

Performs the tip convolution algorithm published by Villarrubia, which is equivalent to morphological dilation operation.

If the operation is aborted the size and contents of result field is undefined.

Parameters

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, which is equivalent to morphological erosion operation.

If the operation is aborted the size and contents of result field is undefined.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Types and Values

struct GwyTipModelPreset

struct GwyTipModelPreset;

Warning

GwyTipModelPreset is deprecated and should not be used in newly-written code.