## Watershed

Watershed — Watershed grain detection

## Functions

void | gwy_field_splash_water ()
GwyComputationState * | gwy_field_watershed_init ()
void | gwy_field_watershed_iteration ()
void | gwy_field_watershed_finalize ()
gint | gwy_field_waterpour ()
void | gwy_field_mark_extrema ()
void | gwy_field_mark_watershed ()

## Types and Values

enum | GwyWatershedStateType

## Includes

    #include <libgwyddion/gwyddion.h>

## Description

## Functions

### gwy_field_splash_water()

    void
    gwy_field_splash_water (GwyField *field,
                            GwyNield *water,
                            GwyField *markbuf,
                            gint locate_steps,
                            gdouble locate_dropsize);

Performs a few location steps of watershed marking.

If a non-`NULL` `markbuf` is passed, it must have the same dimensions as `field` and `water` .

#### Parameters

field | Data field used for marking. |
water | Number field where to mark minima. |
markbuf | Scratch space data field to avoid frequent allocations if used repeatedly. | [nullable]
locate_steps | Locating algorithm steps. |
locate_dropsize | Locating drop size. |

### gwy_field_watershed_init()

    GwyComputationState *
    gwy_field_watershed_init (GwyField *field,
                              GwyNield *grains,
                              gint locate_steps,
                              gint locate_thresh,
                              gdouble locate_dropsize,
                              gint wshed_steps,
                              gdouble wshed_dropsize,
                              gboolean prefilter,
                              gboolean below);

Initializes the watershed algorithm.

This iterator reports its state as GwyWatershedStateType.

#### Parameters

field | Data to be used for marking. |
grains | Result of marking (mask). |
locate_steps | Locating algorithm steps. |
locate_thresh | Locating algorithm threshold. |
locate_dropsize | Locating drop size. |
wshed_steps | Watershed steps. |
wshed_dropsize | Watershed drop size. |
prefilter | Use prefiltering. |
below | If `TRUE`, valleys are marked, otherwise mountains are marked. |

#### Returns

A new watershed iterator.

### gwy_field_watershed_iteration()

    void
    gwy_field_watershed_iteration (GwyComputationState *state);

Performs one iteration of the watershed algorithm.

Fields `state` and progress `fraction` of watershed state are updated (fraction is calculated for each phase individually). Once `state` becomes `GWY_WATERSHED_STATE_FINISHED`, the calculation is finised.

A watershed iterator can be created with `gwy_field_watershed_init()`. When iteration ends, either by finishing or being aborted, `gwy_field_watershed_finalize()` must be called to release allocated resources.

#### Parameters

state | Watershed iterator. |

### gwy_field_watershed_finalize()

    void
    gwy_field_watershed_finalize (GwyComputationState *state);

Destroys a watershed iterator, freeing all resources.

#### Parameters

state | Watershed iterator. |

### gwy_field_waterpour()

    gint
    gwy_field_waterpour (GwyField *field,
                         GwyNield *grains);

Performs the classical Vincent watershed segmentation of a data field.

The segmentation always results in the entire field being masked with the exception of thin (8-connectivity) lines separating the segments (grains). The grains are already numbered in the same manner as `gwy_nield_number_contiguous()` as a side-effect.

Compared to `gwy_field_mark_watershed()`, this algorithm is very fast. However, when used alone, it typically results in a serious oversegmentation as each local minimum gives raise to a grain. Furthermore, the full segmentation means that also pixels which would be considered outside any grain in the topographical sense will be assigned to some catchment basin. Therefore, pre- and/or postprocessing is usually necessary, using the gradient image or a more sophisticated method.

The function does not assign pixels with value `G_MAXDOUBLE` or larger to any segment. This can be used to pre-mark certain areas explicitly as boundaries.

#### Parameters

field | A data field to segmentate. |
grains | Number field that will be filled with the resulting mask grain numbers. It will be resized to the dimensions of `field` . |

#### Returns

The number of segments (grains) in the result, excluding the separators.

### gwy_field_mark_extrema()

    void
    gwy_field_mark_extrema (GwyField *field,
                            GwyNield *extrema,
                            gboolean maxima);

Marks local maxima or minima in a two-dimensional data field.

Local (or regional) maximum is a contiguous set of pixels that have the same value and this value is sharply greater than the value of any pixel touching the set. A minimum is defined analogously. A field filled with a single value is considered to have neither minimum nor maximum.

#### Parameters

field | A two-dimensional data field. |
extrema | Target number field for the extrema mask. |
maxima | `TRUE` to mark maxima, `FALSE` to mark minima. |

### gwy_field_mark_watershed()

    void
    gwy_field_mark_watershed (GwyField *field,
                              GwyNield *grains,
                              gint locate_steps,
                              gint locate_thresh,
                              gdouble locate_dropsize,
                              gint wshed_steps,
                              gdouble wshed_dropsize,
                              gboolean prefilter,
                              gboolean below);

Performs watershed algorithm.

#### Parameters

field | Data to be used for marking. |
grains | Result of marking (mask). |
locate_steps | Locating algorithm steps. |
locate_thresh | Locating algorithm threshold. |
locate_dropsize | Locating drop size. |
wshed_steps | Watershed steps. |
wshed_dropsize | Watershed drop size. |
prefilter | Use prefiltering. |
below | If `TRUE`, valleys are marked, otherwise mountains are marked. |

## Types and Values

### enum GwyWatershedStateType

#### Members

GWY_WATERSHED_STATE_INIT |  |
GWY_WATERSHED_STATE_LOCATE |  |
GWY_WATERSHED_STATE_MIN |  |
GWY_WATERSHED_STATE_WATERSHED |  |
GWY_WATERSHED_STATE_MARK |  |
GWY_WATERSHED_STATE_FINISHED |  |