Tip: Gwyddion Library Reference Manual

Tip

Tip — SPM tip morphological operations

Functions

gboolean	gwy_field_tip_dilation ()
gboolean	gwy_field_tip_erosion ()
gboolean	gwy_field_tip_certainty_map ()
gint	gwy_field_tip_estimate_partial ()
gint	gwy_field_tip_estimate_full ()

Includes

#include <libgwyddion/gwyddion.h>

Description

The functions implement the algorithms published by Villarrubia: convolution, reconstruction, certainty map and blind tip shape estimations.

In tip data fields, the sign convention is that the tip points upwards in Z. In other words, the apex corresponds to the largest value. This does not mean it is the shape you would see when looking at the probe from the apex, for example in a SEM micrograph. It is mirrored. The actual shape would be obtained by changing the sign of Z (making the tip image look like a pit instead of peak) and rotating it in 3D in some way to look from the apex.

The parity of symmetries in 3D space does not allow to simultaneously (a) have the apex pointing up (positive Z), (b) avoid mirroring the tip and (c) avoid choosing a preferred direction in the XY plane (for the rotation to look at the tip from the other side). Gwyddion chose to sacrifice (b) and all the operations work consistently with this choice.

Functions

gwy_field_tip_dilation()

gboolean
gwy_field_tip_dilation (GwyField *field,
                        GwyField *tip,
                        GwyField *result,
                        gboolean max_is_zero,
                        GwySetFractionFunc set_fraction,
                        GwySetMessageFunc set_message);

Performs the tip convolution (dilation) with a data field.

The function is equivalent to morphological dilation. Passing max_is_zero as TRUE ensures the absolute surface height does not shift, which is usually convenient for SPM tip operations. If you use the function to carry out general morphological dilation, you may want to pass FALSE.

If the operation is cancelled the size and contents of result field are undefined. Cancellation can only occur if non-NULL set_fraction or set_message is passed.

Parameters

field	A data field with surface topography.
tip	Tip data field. Its pixel size must match `field` pixel size.
result	Data field where to store dilated surface to.
max_is_zero	`TRUE` to behave as if `tip` maximum was zero, `FALSE` to use `tip` as given.
set_fraction	Function that sets fraction to output (or `NULL`).	[scope call][nullable]
set_message	Function that sets message to output (or `NULL`).	[scope call][nullable]

Returns

TRUE if the operation finished, FALSE if it was cancelled.

gwy_field_tip_erosion()

gboolean
gwy_field_tip_erosion (GwyField *field,
                       GwyField *tip,
                       GwyField *result,
                       gboolean max_is_zero,
                       GwySetFractionFunc set_fraction,
                       GwySetMessageFunc set_message);

Performs the surface reconstruction (erosion) with a data field.

The function is equivalent to the morphological erosion operation. Passing max_is_zero as TRUE ensures the absolute surface height does not shift, which is usually convenient for SPM tip operations. If you use the function to carry out general morphological erosion, you may want to pass FALSE.

If the operation is cancelled the size and contents of result field are undefined. Cancellation can only occur if non-NULL set_fraction or set_message is passed.

Parameters

field	A data field with surface topography.
tip	Tip data field. Its pixel size must match `field` pixel size.
result	Data field where to store eroded surface to.
set_fraction	Function that sets fraction to output (or `NULL`).	[scope call][nullable]
set_message	Function that sets message to output (or `NULL`).	[scope call][nullable]

Returns

TRUE if the operation finished, FALSE if it was cancelled.

gwy_field_tip_certainty_map()

gboolean
gwy_field_tip_certainty_map (GwyField *field,
                             GwyField *tip,
                             GwyNield *result,
                             gboolean trust_border,
                             GwySetFractionFunc set_fraction,
                             GwySetMessageFunc set_message);

Estimates tip certainty map for a data field.

The function implements the certainty map algorithm published by Villarrubia. The certainty map is a mask of points where tip did not directly touch the surface.

If the operation is cancelled, result is empty. Cancellation can only occur if non-NULL set_fraction or set_message is passed.

Parameters

field	A data field with surface topography.
tip	Tip data field. Its pixel size must match `field` pixel size.
result	Number field to fill with the ceratainty map.
trust_border	`TRUE` to try to assign certainty also to pixels close to the border, `FALSE` to always consider pixels uncertain if the tip could touch something outside the image.
set_fraction	Function that sets fraction to output (or `NULL`).
set_message	Function that sets message to output (of `NULL`).

Returns

TRUE if the operation finished, FALSE if it was cancelled.

gwy_field_tip_estimate_partial()

gint
gwy_field_tip_estimate_partial (GwyField *field,
                                GwyField *tip,
                                gdouble threshold,
                                gboolean use_edges,
                                GwySetFractionFunc set_fraction,
                                GwySetMessageFunc set_message);

Performs partial blind tip shape estimation with a data field.

The function implements the blind estimation algorithm published by Villarrubia.

The tip field must already have the intended pixel dimensions. It may be zero-filled for a fresh estimate or it can be filled with the result of a prior estimate. In the latter case, the initialisation must follow the same convention as the output, i.e. the apex value is zero and all other values are smaller (negative).

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.

If the operation is cancelled the contents of tip is a partial estimate (including possibly the tip still being in the initial state). Cancellation can only occur if non-NULL set_fraction or set_message is passed.

Parameters

field	A data field with surface topography.
tip	Tip data field to be refined. Its pixel size must match the surface pixel size.
threshold	Threshold for noise supression.
use_edges	Whether use also edges of image.
set_fraction	Function that sets fraction to output (or `NULL`).	[scope call][nullable]
set_message	Function that sets message to output (or `NULL`).	[scope call][nullable]

Returns

A positive number if the operation finished and tip was improved, zero if the operation finished without improving the tip, and a negative number if the operation was cancelled.

gwy_field_tip_estimate_full()

gint
gwy_field_tip_estimate_full (GwyField *field,
                             GwyField *tip,
                             gdouble threshold,
                             gboolean use_edges,
                             GwySetFractionFunc set_fraction,
                             GwySetMessageFunc set_message);

Performs full blind tip shape estimation with a data field.

The function implements the blind estimation algorithm published by Villarrubia.

The tip field must already have the intended pixel dimensions. It may be zero-filled for a fresh estimate or it can be filled with the result of a prior estimate, such as using gwy_field_tip_estimate_partial(). In the latter case, the initialisation must follow the same convention as the output, i.e. the apex value is zero and all other values are smaller (negative).

Parameters

field	A data field with surface topography.
tip	Tip data field to be refined. Its pixel size must match the surface pixel size.
threshold	Threshold for noise supression.
use_edges	Whether use also edges of image.
set_fraction	Function that sets fraction to output (or `NULL`).	[scope call][nullable]
set_message	Function that sets message to output (or `NULL`).	[scope call][nullable]

Returns

A positive number if the operation finished and tip was improved, zero if the operation finished without improving the tip, and a negative number if the operation was cancelled.