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

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.