Grain quantities: Gwyddion Library Reference Manual

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_get_quantity ()
void	gwy_nield_get_quantities ()

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 *siunitxy,
                              GwyUnit *siunitz,
                              GwyUnit *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.

[transfer none]

gwy_nield_get_quantity()

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

gwy_nield_get_quantities()

void
gwy_nield_get_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_get_quantity() for some discussion. This function can a lot more efficient than repeated gwy_nield_get_quantity() if several related grain quantities need to be calculated since gwy_field_grains_get_values() must do lot of repeated work in such case.

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.

Types and Values

enum GwyGrainQuantity

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

Members

GWY_GRAIN_PROJECTED_AREA	Projected (flat) grain area.
GWY_GRAIN_EQUIV_SQUARE_SIDE	Side of a square with the same area as the grain.
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.
GWY_GRAIN_HALF_HEIGHT_AREA	Projected area of the part of grain that is above the half-height, i.e. the height between the minimum and maximum.
GWY_GRAIN_FLAT_BOUNDARY_LENGTH	Length of projected grain boundary. Note for grains not topologically equivalent to disc, only the length of the outer boundary is calculated.
GWY_GRAIN_RMS	Standard deviation of grain values.
GWY_GRAIN_MINIMUM_BOUND_SIZE	Minimum lateral bounding size, in other words the minimum length of grain projection to any line in the horizontal plane.
GWY_GRAIN_MINIMUM_BOUND_ANGLE	Direction of the minimum lateral bounding size (arbitrary one if the minimum is not unique).
GWY_GRAIN_MAXIMUM_BOUND_SIZE	Maximum lateral bounding size, in other words the maximum length of grain projection to any line in the horizontal plane.
GWY_GRAIN_MAXIMUM_BOUND_ANGLE	Direction of the maximum lateral bounding size (arbitrary one 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.
GWY_GRAIN_VOLUME_LAPLACE	Grain volume calculated with grain basis calculated by laplacian interpolation of surrounding values.
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.
GWY_GRAIN_BOUNDARY_MINIMUM	Minimum value on the grain inner boundary.
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` .
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.