## Grain quantities

Grain quantities — Evaluation of grain parameters

## Functions

gboolean | gwy_grain_quantity_needs_same_units ()
GwyUnit * | gwy_grain_quantity_get_units ()
gdouble * | gwy_nield_grain_quantity ()
void | gwy_nield_grain_quantities ()
gint * | gwy_nield_convex_hulls ()
gint * | gwy_nield_bounding_boxes ()
gint * | gwy_nield_bounding_boxes_periodic ()
gint * | gwy_nield_inscribed_boxes ()
gint * | gwy_nield_boundary_pixels ()

## Types and Values

enum | GwyGrainQuantity

## Includes

    #include <libgwyddion/gwyddion.h>

## Description

## Functions

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

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

#### Parameters

quantity | A grain quantity. |
unitxy | Lateral SI unit of data. |
unitz | 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. | [nullable][transfer full]

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

[transfer full]

### 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()`.

#### Parameters

nield | A number field. |
field | Data field used for height data. For some quantities its values are not used, but its dimensions determine the real dimensions of a pixel. |
quantity | The quantity to calculate. |
maxgno | Location to store the maximum grain number. Possibly `NULL` if you know the maximum grain number. | [out][nullable]

#### Returns

A newly allocated array of size `maxgno` +1 with grain values.

[transfer full]

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

#### Parameters

nield | A number field. |
field | Data field used for height data. For some quantities its values are not used, but its dimensions determine the real dimensions of a pixel. |
quantities | Array of `nquantities` items that specify the requested GwyGrainQuantity to put to corresponding items in `values` . Quantities can repeat. | [array length=nquantities][transfer none]
nquantities | The number of requested different grain values. |
results | Array of length `nquantities` of arrays of length `ngrains` +1 of doubles to put the calculated values to. |

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

#### Parameters

nield | A number field. |
cindex | Array of size at least `maxgno` +2. It will be filled with block starts in the returned array. |

#### Returns

A newly allocated array of size given by `cindex` [`maxgno` +1].

[transfer full]

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

#### Parameters

nield | A number field. |
maxgno | Location to store the maximum grain number. Possibly `NULL` if you know the maximum grain number. | [out][nullable]

#### Returns

Newly allocated array with 4×(`maxgno` +1) values giving the bounding boxes.

[transfer full]

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

#### Parameters

nield | A number field. |
maxgno | Location to store the maximum grain number. Possibly `NULL` if you know the maximum grain number. | [out][nullable]

#### Returns

Newly allocated array with 4×(`maxgno` +1) values giving the bounding boxes.

[transfer full]

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

#### Parameters

nield | A number field. |
maxgno | Location to store the maximum grain number. Possibly `NULL` if you know the maximum grain number. | [out][nullable]

#### Returns

Newly allocated array with 4×(`maxgno` +1) values giving the inscribed boxes.

[transfer full]

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

#### Parameters

nield | A number field. |
bindex | Array of size at least `maxgno` +2. It will be filled with 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` [`maxgno` +1].

[transfer full]

## Types and Values

### enum GwyGrainQuantity

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

#### Members

GWY_GRAIN_PROJECTED_AREA | Projected (flat) grain area. |
GWY_GRAIN_ID | Grain number, always a whole number. It is not particlarly useful, except when you want to handle the grain number generically as a grain quantity. |
GWY_GRAIN_EQUIV_DISC_RADIUS | Radius of a disc with the same area as the grain. |
GWY_GRAIN_SURFACE_AREA | Surface area. |
GWY_GRAIN_MAXIMUM | Minimum value. |
GWY_GRAIN_MINIMUM | Maximum value. |
GWY_GRAIN_MEAN | Mean value. |
GWY_GRAIN_MEDIAN | Median value. |
GWY_GRAIN_PIXEL_AREA | Flat grain area measured in pixels. This value is redundant but it is useful for filtering. It is always a whole number. |
GWY_GRAIN_HALF_HEIGHT_AREA | Projected area of the part of grain that is strictly above the half-height, i.e. the height between the minimum and maximum. |
GWY_GRAIN_PERIMETER | Length of grain boundary projected to the horizontal plane. |
GWY_GRAIN_RMS | Standard deviation of grain values. |
GWY_GRAIN_MINIMUM_PROJECT_SIZE | The minimum size of grain projection to any line in the horizontal plane. It is also known as the minimum Feret diameter. |
GWY_GRAIN_MINIMUM_PROJECT_ANGLE | Direction of the minimum projection (any of them if the minimum is not unique). |
GWY_GRAIN_MAXIMUM_PROJECT_SIZE | The maximum size of grain projection to any line in the horizontal plane. It is also known as the maximum Feret diameter. |
GWY_GRAIN_MAXIMUM_PROJECT_ANGLE | Direction of the maximum projection (any of them if the maximum is not unique). |
GWY_GRAIN_CENTER_X | Grain centre horizontal position, i.e. the mean value of its physical x-coordinates. |
GWY_GRAIN_CENTER_Y | Grain centre vertical position, i.e. the mean value of its physical y-coordinates. |
GWY_GRAIN_VOLUME_0 | Grain volume calculated with grain basis at `z` =0 (therefore it is just an integral it can be negative). |
GWY_GRAIN_VOLUME_MIN | Grain volume calculated with grain basis at grain minimum value. This value is a lower bound of the volume. |
GWY_GRAIN_VOLUME_LAPLACE | Grain volume calculated with grain basis calculated by Laplacian interpolation of surrounding values (as with `gwy_field_laplace_solve()`). |
GWY_GRAIN_FERET_LENGTH | Size of particle projection to the direction perpendicular to the minimum Feret diameter, i.e. perpendicular to `GWY_GRAIN_MINIMUM_PROJECT_ANGLE` . |
GWY_GRAIN_SLOPE_THETA | Spherical angle theta of grain normal (0 is upwards). |
GWY_GRAIN_SLOPE_PHI | Spherical angle phi of grain normal (0 is in positive x direction). |
GWY_GRAIN_BOUNDARY_MAXIMUM | Maximum value in the grain inner boundary (image edges are not considered grain boundaries). |
GWY_GRAIN_BOUNDARY_MINIMUM | Minimum value on the grain inner boundary (image edges are not considered grain boundaries). |
GWY_GRAIN_CURVATURE_CENTER_X | Grain curvature centre horizontal position. For too small or flat grains it reduces to the horizontal position of geometrical centre. |
GWY_GRAIN_CURVATURE_CENTER_Y | Grain curvature centre vertical position. For too small or flat grains it reduces to the vertical position of geometrical centre. |
GWY_GRAIN_CURVATURE_CENTER_Z | The value at curvature centre. Note this is the value in the origin of the fitted quadratic surface, not at the real surface. |
GWY_GRAIN_CURVATURE1 | Smaller grain curvature. |
GWY_GRAIN_CURVATURE2 | Larger grain curvature. |
GWY_GRAIN_CURVATURE_ANGLE1 | Direction of the smaller grain curvature radius. If the grain is flat or too small the angle is reported as 0. |
GWY_GRAIN_CURVATURE_ANGLE2 | Direction of the larger grain curvature radius. If the grain is flat or too small the angle is reported as π/2. |
GWY_GRAIN_INSCRIBED_DISC_R | Radius of maximum disc that fits inside the grain |
GWY_GRAIN_INSCRIBED_DISC_X | Real X-coordinate of the centre of the maximum inscribed disc. |
GWY_GRAIN_INSCRIBED_DISC_Y | Real Y-coordinate of the centre of the maximum inscribed disc. |
GWY_GRAIN_CONVEX_HULL_AREA | Projected (flat) area of grain convex hull. |
GWY_GRAIN_CIRCUMCIRCLE_R | Radius of minimum circle containing the grain. |
GWY_GRAIN_CIRCUMCIRCLE_X | Real X-coordinate of the centre of the minimum circumcircle. |
GWY_GRAIN_CIRCUMCIRCLE_Y | Real Y-coordinate of the centre of the minimum circumcircle. |
GWY_GRAIN_MEAN_RADIUS | Mean distance from boundary to the grain centre as defined by `GWY_GRAIN_CENTER_X` and `GWY_GRAIN_CENTER_Y` . All boundaries are included (even internal). |
GWY_GRAIN_EQUIV_ELLIPSE_MAJOR | Length of major semiaxis of equivalent ellipse. |
GWY_GRAIN_EQUIV_ELLIPSE_MINOR | Length of minor semiaxis of equivalent ellipse. |
GWY_GRAIN_EQUIV_ELLIPSE_ANGLE | Orientation of the major axis of equivalent ellipse. |
GWY_GRAIN_MINIMUM_MARTIN_DIAMETER | Minimum value of Martin diameter. |
GWY_GRAIN_MINIMUM_MARTIN_ANGLE | Direction corresponding to minimum Martin diameter. |
GWY_GRAIN_MAXIMUM_MARTIN_DIAMETER | Maximum value of Martin diameter. |
GWY_GRAIN_MAXIMUM_MARTIN_ANGLE | Direction corresponding to maximum Martin diameter. |
GWY_GRAIN_MEAN_BOUNDARY_DISTANCE | Mean distance from a grain point to the closest boundary point. |
GWY_GRAIN_SHAPE_NUMBER | Circularity measure based on the mean edge distance. |