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.

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.

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.

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.

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 .

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.

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.

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.

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.

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.

gwy_data_field_grains_watershed_finalize ()

void
gwy_data_field_grains_watershed_finalize
                               (GwyComputationState *state);

Destroys a watershed iterator, freeing all resources.

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.

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.

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.

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);

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);

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.

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.

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.

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.

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

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.

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.

Since: 2.47

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

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.

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.

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.

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.

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.

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.

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.

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.

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 zeroes if they are not farther than amount from the grain boundary as defined by dtype .

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 .

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.

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.

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.

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.

Since: 2.37