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.

gwy_grain_quantity_get_units()

GwyUnit *
gwy_grain_quantity_get_units (GwyGrainQuantity quantity,
                              GwyUnit *unitxy,
                              GwyUnit *unitz,
                              GwyUnit *result);

Calculates the units of a grain quantity.

gwy_nield_grain_quantity()

gdouble *
gwy_nield_grain_quantity (GwyNield *nield,
                          GwyField *field,
                          GwyGrainQuantity quantity,
                          gint *maxgno);

Calculates a single characteristics of grains in a number field.

Some quantities are currently calculated incorrectly for non-contiguous grains. In particular those related to the grain boundary. Others may be technically correct for non-contiguous grains, but not really meaningful.

This function can be inefficient. When multiple related quantities are evaluated, gwy_nield_grain_quantities() avoids doing the same work twice. See also gwy_nield_grain_values() for the evaluation of non-builtin grain values.

The zeroth item in the returned array does not correspond to any grain and does not generally contain any useful information. Although the function fills some placeholder values for empty grains, it is recommended to apply gwy_nield_compactify().

gwy_nield_grain_quantities()

void
gwy_nield_grain_quantities (GwyNield *nield,
                            GwyField *field,
                            const GwyGrainQuantity *quantities,
                            guint nquantities,
                            gdouble **results);

Calculates multiple characteristics of grains in a number field simultaneously.

See gwy_nield_grain_quantity() for some discussion. This function can a lot more efficient than repeated gwy_nield_grain_quantity() if several related grain quantities need to be calculated since gwy_nield_grain_values() must do lot of repeated work in such case.

Some quantities are meaningful for marked regions of any shape, others really only for comtiguous grains, although the functions always computes something even for non-contiguous grains. Grain boundaries and borders are lines separating a grain from anything that is not this grain, whether it is the unmarked area or a different grain (when grains are touching).

gwy_nield_convex_hulls()

gint *
gwy_nield_convex_hulls (GwyNield *nield,
                        guint *cindex);

Finds convex hulls of all grains in a number field.

Use gwy_nield_max() to obtain maxgno and allocate correct cindex .

The returned array contains pairs (col,row) of pixel vertices of the convex hull, concatenated all one after another. In each block, the vertices are enumerated in the anti-clockwise order.

The column and row coordinates come from the intervals [0,xres ] and [0,yres ]. Note that these interval are inclusive on both ends. The convex hull covers the full pixels as little rectangles (not just their centres or other selected points).

The block for grain with number i starts at position cindex [i ] and ends one before position cindex [i +1] where the next block starts. The end is also stored for the last block, which does not have any next block, and gives the total size of the returned array.

The convex hull of the no-grain area (non-positive values) is not computed. Therefore, the first two elements of cindex will be always zeros.

gwy_nield_bounding_boxes()

gint *
gwy_nield_bounding_boxes (GwyNield *nield,
                          gint *maxgno);

Finds bounding boxes of all grains in a number field.

The zeroth element of the returned array does not correspond to any grain; grain numbers start from 1.

The rectangles are stored as quadruples of indices: (column, row, width, height). Empty grains, which can occur when grain numbers have holes, have negative bounding box width and height.

The function works for non-contiguous numbered regions and gives the overall bounding boxes for all the pieces.

gwy_nield_bounding_boxes_periodic()

gint *
gwy_nield_bounding_boxes_periodic (GwyNield *nield,
                                   gint *maxgno);

Find bounding boxes of all grains in a number field with periodic boundary conditions.

The zeroth element of bboxes does not correspond to any grain; grain numbers start from 1. The rectangles 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.

gwy_nield_inscribed_boxes()

gint *
gwy_nield_inscribed_boxes (GwyNield *nield,
                           gint *maxgno);

Find maximum-area inscribed boxes of all grains in a number field.

The zeroth element of the returned array does not correspond to any grain and does not contain useful information; grain numbers start from 1. The rectangles are stored as quadruples of indices: (column, row, width, height). Empty grains, which can occur when grain numbers have holes, have negative bounding box width and height.

The function works for non-contiguous numbered regions. One of the pieces will contain the maximum rectangle.

gwy_nield_boundary_pixels()

gint *
gwy_nield_boundary_pixels (GwyNield *nield,
                           guint *bindex,
                           gboolean from_border);

Enumerates boundary pixels of all grains in a number field.

Use gwy_nield_max() to obtain maxgno and allocate correct bindex .

The returned array contains pixel indices of grain boundaries, concatenated all one after another. In each block, the indices are enumerated in ascending order.

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 end is also stored for the last block, which does not have any next block, and gives the total size of the returned array.

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

The boundary of the no-grain area (non-positive values) is not computed. Therefore, the first two elements of bindex will be always zeros.

enum GwyGrainQuantity

Grain quantity to request from gwy_nield_grain_quantity() and similar functions.