grains: Gwyddion Data Processing Library Reference Manual

## grains grains — Grain detection and processing |

## Functions

void | gwy_data_field_grains_mark_curvature ()
void | gwy_data_field_grains_mark_watershed ()
gboolean | gwy_data_field_grains_remove_grain ()
gboolean | gwy_data_field_grains_extract_grain ()
void | gwy_data_field_grains_remove_by_number ()
void | gwy_data_field_grains_remove_by_size ()
void | gwy_data_field_grains_remove_by_height ()
void | gwy_data_field_grains_remove_touching_border ()
GwyComputationState * | gwy_data_field_grains_watershed_init ()
void | gwy_data_field_grains_watershed_iteration ()
void | gwy_data_field_grains_watershed_finalize ()
void | gwy_data_field_grains_mark_height ()
void | gwy_data_field_grains_mark_slope ()
gdouble | gwy_data_field_otsu_threshold ()
void | gwy_data_field_grains_add ()
void | gwy_data_field_grains_intersect ()
void | gwy_data_field_grains_invert ()
gboolean | gwy_data_field_grains_autocrop ()
gint | gwy_data_field_number_grains ()
gint | gwy_data_field_number_grains_periodic ()
gint * | gwy_data_field_get_grain_bounding_boxes ()
gint * | gwy_data_field_get_grain_bounding_boxes_periodic ()
gint * | gwy_data_field_get_grain_sizes ()
gint * | gwy_data_field_get_grain_inscribed_boxes ()
gint * | gwy_data_field_grains_find_boundaries ()
GwyDataLine * | gwy_data_field_grains_get_distribution ()
gdouble * | gwy_data_field_grains_get_values ()
gdouble ** | gwy_data_field_grains_get_quantities ()
gboolean | gwy_grain_quantity_needs_same_units ()
GwySIUnit * | gwy_grain_quantity_get_units ()
void | gwy_data_field_area_grains_tgnd ()
void | gwy_data_field_area_grains_tgnd_range ()
void | gwy_data_field_grains_splash_water ()
void | gwy_data_field_grain_distance_transform ()
void | gwy_data_field_grain_simple_dist_trans ()
void | gwy_data_field_grains_shrink ()
void | gwy_data_field_grains_grow ()
void | gwy_data_field_grains_thin ()
gboolean | gwy_data_field_fill_voids ()
gint | gwy_data_field_waterpour ()
void | gwy_data_field_mark_extrema ()

## Includes

    #include <libprocess/gwyprocess.h>

## Description

## Functions

### gwy_data_field_grains_mark_curvature ()

    void
    gwy_data_field_grains_mark_curvature (GwyDataField *data_field,
                                          GwyDataField *grain_field,
                                          gdouble threshval,
                                          gboolean below);

Marks data that are above/below curvature threshold.

#### Parameters

data_field | Data to be used for marking. |
grain_field | Data field to store the resulting mask to. |
threshval | Relative curvature threshold, in percents. |
below | If `TRUE`, data below threshold are marked, otherwise data above threshold are marked. |

### gwy_data_field_grains_mark_watershed ()

    void
    gwy_data_field_grains_mark_watershed (GwyDataField *data_field,
                                          GwyDataField *grain_field,
                                          gint locate_steps,
                                          gint locate_thresh,
                                          gdouble locate_dropsize,
                                          gint wshed_steps,
                                          gdouble wshed_dropsize,
                                          gboolean prefilter,
                                          gboolean below);

Performs watershed algorithm.

#### Parameters

data_field | Data to be used for marking. |
grain_field | 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. |

### gwy_data_field_grains_remove_grain ()

    gboolean
    gwy_data_field_grains_remove_grain (GwyDataField *grain_field,
                                        gint col,
                                        gint row);

Removes one grain at given position.

#### Parameters

grain_field | Field of marked grains (mask). |
col | Column inside a grain. |
row | Row inside a grain. |

#### Returns

`TRUE` if a grain was actually removed, i.e. (`col` ,`row` ) was inside a grain.

### gwy_data_field_grains_extract_grain ()

    gboolean
    gwy_data_field_grains_extract_grain (GwyDataField *grain_field,
                                         gint col,
                                         gint row);

Removes all grains except that one at given position.

If there is no grain at (`col` , `row` ), all grains are removed.

#### Parameters

grain_field | Field of marked grains (mask). |
col | Column inside a grain. |
row | Row inside a grain. |

#### Returns

`TRUE` if a grain remained (i.e., (`col` ,`row` ) was inside a grain).

### gwy_data_field_grains_remove_by_number ()

    void
    gwy_data_field_grains_remove_by_number
                                   (GwyDataField *grain_field,
                                    gint number);

Removes grain identified by `number` .

#### Parameters

grain_field | Field of marked grains (mask). |
number | Grain number was filled by `gwy_data_field_number_grains()`. |

Since: 2.35

### gwy_data_field_grains_remove_by_size ()

    void
    gwy_data_field_grains_remove_by_size (GwyDataField *grain_field,
                                          gint size);

Removes all grains below specified area.

#### Parameters

grain_field | Field of marked grains (mask). |
size | Grain area threshold, in square pixels. |

### gwy_data_field_grains_remove_by_height ()

    void
    gwy_data_field_grains_remove_by_height
                                   (GwyDataField *data_field,
                                    GwyDataField *grain_field,
                                    gdouble threshval,
                                    gboolean below);

Removes grains that are higher/lower than given threshold value.

#### Parameters

data_field | Data to be used for marking |
grain_field | Field of marked grains (mask) |
threshval | Relative height threshold, in percents. |
below | If `TRUE`, grains below threshold are removed, otherwise grains above threshold are removed. |

### gwy_data_field_grains_remove_touching_border ()

    void
    gwy_data_field_grains_remove_touching_border
                                   (GwyDataField *grain_field);

Removes all grains that touch field borders.

#### Parameters

grain_field | Field of marked grains (mask). |

Since: 2.30

### gwy_data_field_grains_watershed_init ()

    GwyComputationState *
    gwy_data_field_grains_watershed_init (GwyDataField *data_field,
                                          GwyDataField *grain_field,
                                          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

data_field | Data to be used for marking. |
grain_field | 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_data_field_grains_watershed_iteration ()

    void
    gwy_data_field_grains_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_data_field_grains_watershed_init()`. When iteration ends, either by finishing or being aborted, `gwy_data_field_grains_watershed_finalize()` must be called to release allocated resources.

#### Parameters

state | Watershed iterator. |

### gwy_data_field_grains_watershed_finalize ()

    void
    gwy_data_field_grains_watershed_finalize
                                   (GwyComputationState *state);

Destroys a watershed iterator, freeing all resources.

#### Parameters

state | Watershed iterator. |

### gwy_data_field_grains_mark_height ()

    void
    gwy_data_field_grains_mark_height (GwyDataField *data_field,
                                       GwyDataField *grain_field,
                                       gdouble threshval,
                                       gboolean below);

Marks data that are above/below height threshold.

#### Parameters

data_field | Data to be used for marking. |
grain_field | Data field to store the resulting mask to. |
threshval | Relative height threshold, in percents. |
below | If `TRUE`, data below threshold are marked, otherwise data above threshold are marked. |

### gwy_data_field_grains_mark_slope ()

    void
    gwy_data_field_grains_mark_slope (GwyDataField *data_field,
                                      GwyDataField *grain_field,
                                      gdouble threshval,
                                      gboolean below);

Marks data that are above/below slope threshold.

#### Parameters

data_field | Data to be used for marking. |
grain_field | Data field to store the resulting mask to. |
threshval | Relative slope threshold, in percents. |
below | If `TRUE`, data below threshold are marked, otherwise data above threshold are marked. |

### gwy_data_field_otsu_threshold ()

    gdouble
    gwy_data_field_otsu_threshold (GwyDataField *data_field);

Finds Otsu's height threshold for a data field.

The Otsu's threshold is optimal in the sense that it minimises the inter-class variances of two classes of pixels: above and below theshold.

#### Parameters

data_field | A data field. |

Since: 2.37

### gwy_data_field_grains_add ()

    void
    gwy_data_field_grains_add (GwyDataField *grain_field,
                               GwyDataField *add_field);

Adds `add_field` grains to `grain_field` .

Note: This function is equivalent to

    1
    gwy_data_field_max_of_fields(grain_field, grain_field, add_field);

#### Parameters

grain_field | Field of marked grains (mask). |
add_field | Field of marked grains (mask) to be added. |

### gwy_data_field_grains_intersect ()

    void
    gwy_data_field_grains_intersect (GwyDataField *grain_field,
                                     GwyDataField *intersect_field);

Performs intersection betweet two grain fields, result is stored in `grain_field` .

Note: This function is equivalent to

    1
    gwy_data_field_min_of_fields(grain_field, grain_field, intersect_field);

#### Parameters

grain_field | Field of marked grains (mask). |
intersect_field | Field of marked grains (mask). |

### gwy_data_field_grains_invert ()

    void
    gwy_data_field_grains_invert (GwyDataField *grain_field);

Inverts a data field representing a mask.

All non-positive values are transformed to 1.0. All positive values are transformed to 0.0.

#### Parameters

grain_field | Data field (mask) of marked grains. |

Since: 2.43

### gwy_data_field_grains_autocrop ()

    gboolean
    gwy_data_field_grains_autocrop (GwyDataField *mask_field,
                                    gboolean symmetrically,
                                    guint *left,
                                    guint *right,
                                    guint *up,
                                    guint *down);

Removes empty border rows and columns from a data field representing a mask.

If there are border rows and columns filled completely with non-positive values the size of the data field is reduced, removing these rows. The parameter `symmetrically` controls whether the size reduction is maximum possible or symmetrical.

When there is no positive value in the field the field size is reduced to the smallest possible. This means 1x1 for `symmetrical` being `FALSE` and even original dimensions to 2 for `symmetrical` being `TRUE`.

#### Parameters

mask_field | Data field representing a mask. |
symmetrically | `TRUE` to remove borders symmetrically, i.e the same number of pixels from left and right, and also top and bottom. `FALSE` to remove as many empty rows and columns as possible. |
left | Location to store how many column were removed from the left, or `NULL`. |
right | Location to store how many column were removed from the right, or `NULL`. |
up | Location to store how many row were removed from the top, or `NULL`. |
down | Location to store how many row were removed from the bottom, or `NULL`. |

#### Returns

`TRUE` if the field size was reduced at all. Detailed information about the reduction can be obtained from `left` , `right` , `up` and `down` .

Since: 2.43

### gwy_data_field_number_grains ()

    gint
    gwy_data_field_number_grains (GwyDataField *mask_field,
                                  gint *grains);

Numbers grains in a mask data field.

#### Parameters

mask_field | Data field containing positive values in grains, nonpositive in free space. |
grains | Zero-filled array of integers of equal size to `mask_field` to put grain numbers to. Empty space will be left 0, pixels inside a grain will be set to grain number. Grains are numbered sequentially 1, 2, 3, ... |

#### Returns

The number of last grain (note they are numbered from 1).

### gwy_data_field_number_grains_periodic ()

    gint
    gwy_data_field_number_grains_periodic (GwyDataField *mask_field,
                                           gint *grains);

Numbers grains in a periodic mask data field.

This function differs from `gwy_data_field_number_grains()` by the assumption of periodicity, i.e. grains can touch across the opposite field edges.

Note that some grain operations assume that grains are contiguous within the image and do not work with periodic grains.

You can use `gwy_data_field_get_grain_sizes()` and there is `gwy_data_field_get_grain_bounding_boxes_periodic()` for bouding boxes of periodic grains. As for grain quantities, simple quantities that do not depend on the shape (mean, median, etc.) are evaluated correctly even for periodic grains. You cannot evaluate quantities depending on grain boundaries though.

#### Parameters

mask_field | Data field containing positive values in grains, nonpositive in free space. |
grains | Zero-filled array of integers of equal size to `mask_field` to put grain numbers to. Empty space will be left 0, pixels inside a grain will be set to grain number. Grains are numbered sequentially 1, 2, 3, ... |

#### Returns

The number of last grain (note they are numbered from 1).

Since: 2.38

### gwy_data_field_get_grain_bounding_boxes ()

    gint *
    gwy_data_field_get_grain_bounding_boxes
                                   (GwyDataField *mask_field,
                                    gint ngrains,
                                    const gint *grains,
                                    gint *bboxes);

Find bounding boxes of all grains.

As usual the zeroth element of `bboxes` does not correspond to any grain; grain numbers start from 1. The bounding boxes are stored as quadruples of indices: (column, row, width, height).

#### Parameters

mask_field | Data field containing positive values in grains, nonpositive in free space. However its contents is ignored as all grain information is taken from `grains` (its dimensions determine the dimensions of `grains` ). |
ngrains | The number of grains as returned by `gwy_data_field_number_grains()`. |
grains | Grain numbers filled with `gwy_data_field_number_grains()`. |
bboxes | Array of size at least 4*(`ngrains` +1) to fill with grain bounding boxes. It can be `NULL` to allocate a new array. |

#### Returns

Either `bboxes` (if it was not `NULL`), or a newly allocated array of size 4(`ngrains` + 1).

Since: 2.3

### gwy_data_field_get_grain_bounding_boxes_periodic ()

    gint *
    gwy_data_field_get_grain_bounding_boxes_periodic
                                   (GwyDataField *mask_field,
                                    gint ngrains,
                                    const gint *grains,
                                    gint *bboxes);

Find bounding boxes of all grains.

As usual zeroth element of `bboxes` does not correspond to any grain; grain numbers start from 1. The bounding boxes are stored as quadruples of indices: (column, row, width, height).

The row and column always lie inside the the image. However, width and height may specify an area which sticks outside. In this case periodicity needs to be taken into account.

#### Parameters

mask_field | Data field containing positive values in grains, nonpositive in free space. However its contents is ignored as all grain information is taken from `grains` (its dimensions determine the dimensions of `grains` ). |
ngrains | The number of grains as returned by `gwy_data_field_number_grains_periodic()`. |
grains | Grain numbers filled with `gwy_data_field_number_grains_periodic()`. |
bboxes | Array of size at least 4*(`ngrains` +1) to fill with grain bounding boxes. It can be `NULL` to allocate a new array. |

#### Returns

Either `bboxes` (if it was not `NULL`), or a newly allocated array of size 4(`ngrains` + 1).

Since: 2.51

### gwy_data_field_get_grain_sizes ()

    gint *
    gwy_data_field_get_grain_sizes (GwyDataField *mask_field,
                                    gint ngrains,
                                    const gint *grains,
                                    gint *sizes);

Find sizes of all grains in a mask data field.

Size is the number of pixels in the grain.

The zeroth element of `sizes` is filled with the number of pixels not covered by the mask.

#### Parameters

mask_field | Data field containing positive values in grains, nonpositive in free space. However its contents is ignored as all grain information is taken from `grains` (its dimensions determine the dimensions of `grains` ). |
ngrains | The number of grains as returned by `gwy_data_field_number_grains()`. |
grains | Grain numbers filled with `gwy_data_field_number_grains()`. |
sizes | Array of size at least `ngrains` +1 to fill with grain sizes (as usual zero does not correspond to any grain, grains start from 1). It can be `NULL` to allocate a new array. |

#### Returns

Either `sizes` (if it was not `NULL`), or a newly allocated array of size `ngrains` +1.

Since: 2.47

### gwy_data_field_get_grain_inscribed_boxes ()

    gint *
    gwy_data_field_get_grain_inscribed_boxes
                                   (GwyDataField *mask_field,
                                    gint ngrains,
                                    const gint *grains,
                                    gint *iboxes);

Find maximum-area inscribed boxes of all grains.

As usual zeroth element of `iboxes` does not correspond to any grain; grain numbers start from 1. The bounding boxes are stored as quadruples of indices: (column, row, width, height).

#### Parameters

mask_field | Data field containing positive values in grains, nonpositive in free space. However its contents is ignored as all grain information is taken from `grains` (its dimensions determine the dimensions of `grains` ). |
ngrains | The number of grains as returned by `gwy_data_field_number_grains()`. |
grains | Grain numbers filled with `gwy_data_field_number_grains()`. |
iboxes | Array of size at least 4*(`ngrains` +1) to fill with grain bounding boxes. It can be `NULL` to allocate a new array. |

#### Returns

Either `iboxes` (if it was not `NULL`), or a newly allocated array of size 4(`ngrains` + 1).

Since: 2.53

### gwy_data_field_grains_find_boundaries ()

    gint *
    gwy_data_field_grains_find_boundaries (GwyDataField *data_field,
                                           const gint *grains,
                                           gint ngrains,
                                           gint *bindex,
                                           gboolean from_border);

Find boundary pixels of all grains in a data field.

The returned array contains pixel indices of grain boundaries, concatenated all one after another. The block for grain with number `i` starts at position `bindex` [`i` ] and ends one before position `bindex` [`i` +1] where the next block starts. The indices in each block are stored in ascending order.

Boundary pixels are considered in the usual 4-connected metric.

The boundary of the no-grain area is not computed. Therefore, the first two elements of `bindex` will be always zeros.

#### Parameters

mask_field | Data field containing positive values in grains, nonpositive in free space. However its contents is ignored as all grain information is taken from `grains` (its dimensions determine the dimensions of `grains` ). |
grains | Grain numbers filled with `gwy_data_field_number_grains()`. |
ngrains | The number of grains as returned by `gwy_data_field_number_grains()`. |
bindex | Array of size at least `ngrains` +2. It will be filled block starts in the returned array. |
from_border | `TRUE` to consider image edges to be grain boundaries. |

#### Returns

A newly allocated array of size given by `bindex` [`ngrains` +1].

Since: 2.61

### gwy_data_field_grains_get_distribution ()

    GwyDataLine *
    gwy_data_field_grains_get_distribution
                                   (GwyDataField *data_field,
                                    GwyDataField *grain_field,
                                    GwyDataLine *distribution,
                                    gint ngrains,
                                    const gint *grains,
                                    GwyGrainQuantity quantity,
                                    gint nstats);

Computes distribution of requested grain characteristics.

Puts number of grains vs. grain value data into `distribution` , units, scales and offsets of `distribution` are updated accordingly.

Note the `i` -th bin is [`i` *`dx` +`off` ,(`i` +1)*`dx` +`off` ] so the central value you probably want to use for plotting is (`i` +0.5)*`dx` +`off` (where `dx` is the `distribution` data line pixel size, `off` is its offset).

#### Parameters

data_field | Data field used for marking. For some quantities its values are not used, but units and physical dimensions are always taken from it. |
grain_field | Data field (mask) of marked grains. Note if you pass non-`NULL` `grains` all grain information is taken from it and `grain_field` can be even `NULL` then. |
distribution | Data line to store grain distribution to. |
grains | Grain numbers filled with `gwy_data_field_number_grains()` if you have it, or `NULL` (the function then finds grain numbers itself which is not efficient for repeated use on the same grain field). |
ngrains | The number of grains as returned by `gwy_data_field_number_grains()`. Ignored in `grains` is `NULL`. |
quantity | The quantity to calculate. |
nstats | The number of samples to take on the distribution function. If nonpositive, a suitable resolution is determined automatically. |

#### Returns

A data line with the distribution: `distribution` itself if it was not `NULL`, otherwise a newly created GwyDataLine caller must destroy. If there are no grains, `NULL` is returned and `distribution` is not changed.

### gwy_data_field_grains_get_values ()

    gdouble *
    gwy_data_field_grains_get_values (GwyDataField *data_field,
                                      gdouble *values,
                                      gint ngrains,
                                      const gint *grains,
                                      GwyGrainQuantity quantity);

Calculates characteristics of grains.

This is a bit low-level function, see also `gwy_data_field_grains_get_distribution()`.

The array `values` will be filled with the requested grain value for each individual grain (0th item of `values` which does not correspond to any grain will be overwritten with an arbitrary value and should be ignored).

The grain numbers serve as indices in `values` . Therefore as long as the same `grains` is used, the same position in `values` corresponds to the same particular grain. This enables one for instance to calculate grain sizes and grain heights and then correlate them.

#### Parameters

data_field | Data field used for marking. For some quantities its values are not used, but its dimensions determine the dimensions of `grains` . |
values | Array of size `ngrains` +1 to put grain values to. It can be `NULL` to allocate and return a new array. |
grains | Grain numbers filled with `gwy_data_field_number_grains()`. |
ngrains | The number of grains as returned by `gwy_data_field_number_grains()`. |
quantity | The quantity to calculate. |

#### Returns

`values` itself if it was not `NULL`, otherwise a newly allocated array that caller has to free.

### gwy_data_field_grains_get_quantities ()

    gdouble **
    gwy_data_field_grains_get_quantities (GwyDataField *data_field,
                                          gdouble **values,
                                          const GwyGrainQuantity *quantities,
                                          guint nquantities,
                                          guint ngrains,
                                          const gint *grains);

Calculates multiple characteristics of grains simultaneously.

See `gwy_data_field_grains_get_values()` for some discussion. This function is more efficient if several grain quantities need to be calculated since `gwy_data_field_grains_get_values()` can do lot of repeated work in such case.

#### Parameters

data_field | Data field used for marking. For some quantities its values are not used, but its dimensions determine the dimensions of `grains` . |
values | Array of `nquantities` pointers to blocks of length `ngrains` +1 to put the calculated grain values to. Each block corresponds to one requested quantity. `NULL` can be passed to allocate and return a new array. |
quantities | Array of `nquantities` items that specify the requested GwyGrainQuantity to put to corresponding items in `values` . Quantities can repeat. |
nquantities | The number of requested different grain values. |
grains | Grain numbers filled with `gwy_data_field_number_grains()`. |
ngrains | The number of grains as returned by `gwy_data_field_number_grains()`. |

#### Returns

`values` itself if it was not `NULL`, otherwise a newly allocated array that caller has to free with `g_free()`, including the contained arrays.

Since: 2.22

### gwy_grain_quantity_needs_same_units ()

    gboolean
    gwy_grain_quantity_needs_same_units (GwyGrainQuantity quantity);

Tests whether a grain quantity is defined only when lateral and value units match.

#### Parameters

quantity | A grain quantity. |

#### Returns

`TRUE` if `quantity` is meaningless when lateral and value units differ, `FALSE` if it is always defined.

Since: 2.7

### gwy_grain_quantity_get_units ()

    GwySIUnit *
    gwy_grain_quantity_get_units (GwyGrainQuantity quantity,
                                  GwySIUnit *siunitxy,
                                  GwySIUnit *siunitz,
                                  GwySIUnit *result);

Calculates the units of a grain quantity.

#### Parameters

quantity | A grain quantity. |
siunitxy | Lateral SI unit of data. |
siunitz | Value SI unit of data. |
result | An SI unit to set to the units of `quantity` . It can be `NULL`, a new SI unit is created then and returned. |

#### Returns

When `result` is `NULL`, a newly creates SI unit that has to be dereferenced when no longer used later. Otherwise `result` itself is simply returned, its reference count is NOT increased.

Since: 2.7

### gwy_data_field_area_grains_tgnd ()

    void
    gwy_data_field_area_grains_tgnd (GwyDataField *data_field,
                                     GwyDataLine *target_line,
                                     gint col,
                                     gint row,
                                     gint width,
                                     gint height,
                                     gboolean below,
                                     gint nstats);

Calculates threshold grain number distribution.

This function is a simple `gwy_data_field_area_grains_tgnd_range()` that calculates the distribution in the full range.

#### Parameters

data_field | A data field. |
target_line | A data line to store the distribution to. It will be resampled to the requested width. |
col | Upper-left column coordinate. |
row | Upper-left row coordinate. |
width | Area width (number of columns). |
height | Area height (number of rows). |
below | If `TRUE`, valleys are marked, otherwise mountains are marked. |
nstats | The number of samples to take on the distribution function. If nonpositive, a suitable resolution is determined automatically. |

### gwy_data_field_area_grains_tgnd_range ()

    void
    gwy_data_field_area_grains_tgnd_range (GwyDataField *data_field,
                                           GwyDataLine *target_line,
                                           gint col,
                                           gint row,
                                           gint width,
                                           gint height,
                                           gdouble min,
                                           gdouble max,
                                           gboolean below,
                                           gint nstats);

Calculates threshold grain number distribution in given height range.

This is the number of grains for each of `nstats` equidistant height threshold levels. For large `nstats` this function is much faster than the equivalent number of `gwy_data_field_grains_mark_height()` calls.

#### Parameters

data_field | A data field. |
target_line | A data line to store the distribution to. It will be resampled to the requested width. |
col | Upper-left column coordinate. |
row | Upper-left row coordinate. |
width | Area width (number of columns). |
height | Area height (number of rows). |
min | Minimum threshold value. |
max | Maximum threshold value. |
below | If `TRUE`, valleys are marked, otherwise mountains are marked. |
nstats | The number of samples to take on the distribution function. If nonpositive, a suitable resolution is determined automatically. |

### gwy_data_field_grains_splash_water ()

    void
    gwy_data_field_grains_splash_water (GwyDataField *data_field,
                                        GwyDataField *minima,
                                        gint locate_steps,
                                        gdouble locate_dropsize);

### gwy_data_field_grain_distance_transform ()

    void
    gwy_data_field_grain_distance_transform
                                   (GwyDataField *data_field);

Performs Euclidean distance transform of a data field with grains.

Each non-zero value will be replaced with Euclidean distance to the grain boundary, measured in pixels.

See also `gwy_data_field_grain_simple_dist_trans()` for simple distance transforms such as city-block or chessboard.

#### Parameters

data_field | A data field with zeros in empty space and nonzeros in grains. |

Since: 2.36

### gwy_data_field_grain_simple_dist_trans ()

    void
    gwy_data_field_grain_simple_dist_trans
                                   (GwyDataField *data_field,
                                    GwyDistanceTransformType dtype,
                                    gboolean from_border);

Performs a distance transform of a data field with grains.

Each non-zero value will be replaced with a distance to the grain boundary, measured in pixels.

Note this function can calculate the true Euclidean distance transform only since 2.43. Use `gwy_data_field_grain_distance_transform()` for the EDT if you need compatibility with older versions.

#### Parameters

data_field | A data field with zeros in empty space and nonzeros in grains. |
dtype | Type of simple distance to use. |
from_border | `TRUE` to consider image edges to be grain boundaries. |

Since: 2.41

### gwy_data_field_grains_shrink ()

    void
    gwy_data_field_grains_shrink (GwyDataField *data_field,
                                  gdouble amount,
                                  GwyDistanceTransformType dtype,
                                  gboolean from_border);

Erodes a data field containing mask by specified amount using a distance measure.

Non-zero pixels in `data_field` will be replaced with zeros if they are not farther than `amount` from the grain boundary as defined by `dtype` .

#### Parameters

data_field | A data field with zeros in empty space and nonzeros in grains. |
amount | How much the grains should be reduced, in pixels. It is inclusive, i.e. pixels that are `amount` far from the border will be removed. |
dtype | Type of simple distance to use. |
from_border | `TRUE` to consider image edges to be grain boundaries. `FALSE` to reduce grains touching field boundaries only along the boundaries. |

Since: 2.43

### gwy_data_field_grains_grow ()

    void
    gwy_data_field_grains_grow (GwyDataField *data_field,
                                gdouble amount,
                                GwyDistanceTransformType dtype,
                                gboolean prevent_merging);

Dilates a data field containing mask by specified amount using a distance measure.

Non-positive pixels in `data_field` will be replaced with ones if they are not farther than `amount` from the grain boundary as defined by `dtype` .

#### Parameters

data_field | A data field with zeros in empty space and nonzeros in grains. |
amount | How much the grains should be expanded, in pixels. It is inclusive, i.e. exterior pixels that are `amount` far from the border will be filled. |
dtype | Type of simple distance to use. |
prevent_merging | `TRUE` to prevent grain merging, i.e. the growth stops where two grains would merge. `FALSE` to simply expand the grains, without regard to grain connectivity. |

Since: 2.43

### gwy_data_field_grains_thin ()

    void
    gwy_data_field_grains_thin (GwyDataField *data_field);

Performs thinning of a data field containing mask.

The result of thinning is a ‘skeleton’ mask consisting of single-pixel thin lines.

#### Parameters

data_field | A data field with zeros in empty space and nonzeros in grains. |

Since: 2.48

### gwy_data_field_fill_voids ()

    gboolean
    gwy_data_field_fill_voids (GwyDataField *data_field,
                               gboolean nonsimple);

Fills voids in grains in a data field representing a mask.

Voids in grains are zero pixels in `data_field` from which no path exists through other zero pixels to the field boundary. The paths are considered in 8-connectivity because grains themselves are considered in 4-connectivity.

#### Parameters

data_field | A data field with zeroes in empty space and nonzeroes in grains. |
nonsimple | Pass `TRUE` to fill also voids that are not simple-connected (e.g. ring-like). This can result in grain merging if a small grain is contained within a void. Pass `FALSE` to fill only simple-connected grains. |

#### Returns

`TRUE` if any voids were filled at all, `FALSE` if no change was made.

Since: 2.37

### gwy_data_field_waterpour ()

    gint
    gwy_data_field_waterpour (GwyDataField *data_field,
                              GwyDataField *result,
                              gint *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).

Compared to `gwy_data_field_grains_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- or postprocessing is usually necessary, using the gradient image or a more sophisticated method.

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

Since the algorithm numbers the grains as a side effect, you can pass a `grains` array and get the grain numbers immediatelly, avoiding the relatively (although not drastically) expensive `gwy_data_field_number_grains()` call.

#### Parameters

data_field | A data field to segmentate. |
result | Data field that will be filled with the resulting mask. It will be resized to the dimensions of `data_field` and its properties set accordingly. |
grains | Optionally, an array with the same number of items as `data_field` . If non-`NULL`, it will be filled with grain numbers in the same manner as `gwy_data_field_number_grains()`. Pass `NULL` to ignore. |

#### Returns

The number of segments (grains) in the result, excluding the separators, i.e. the same convention as in `gwy_data_field_number_grains()` is used.

Since: 2.37

### gwy_data_field_mark_extrema ()

    void
    gwy_data_field_mark_extrema (GwyDataField *dfield,
                                 GwyDataField *extrema,
                                 gboolean maxima);

Marks local maxima or minima in a two-dimensional 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

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

Since: 2.37