Grains: Gwyddion Library Reference Manual

## Grains Grains — Grain numbering and manipulation |

## Functions

gboolean | gwy_nield_isolate ()
gboolean | gwy_nield_isolate_at ()
gboolean | gwy_nield_clear_at ()
void | gwy_nield_clear_by_number ()
void | gwy_nield_clear_by_size ()
void | gwy_nield_clear_touching_border ()
void | gwy_nield_mark_by_threshold ()
void | gwy_nield_mark_range ()
void | gwy_nield_union ()
void | gwy_nield_intersect ()
void | gwy_nield_merge ()
void | gwy_nield_invert ()
gboolean | gwy_nield_autocrop ()
gint | gwy_nield_compactify ()
gboolean | gwy_nield_flatten ()
gint | gwy_nield_number_contiguous ()
gint | gwy_nield_number_contiguous_periodic ()
gint | gwy_nield_split_noncontiguous ()
gint * | gwy_nield_grain_numbers ()
guint * | gwy_nield_sizes ()
gboolean | gwy_nield_fill_voids ()

## Types and Values

enum | GwyMergeType

## Includes

    #include <libgwyddion/gwyddion.h>

## Description

The numbered regions in a GwyNield often represent the result of some classification. They are also often called grains, especially when talking about distinct contiguous regions as they typically arise from grain marking.

On one end, the classification can be a simple yes/no, for example marking by a height threshold. In such number field, one can often distinguish different grains as contiguous marked regions. Function `gwy_nield_number_contiguous()` takes any marking and renumbers it based on continuity. The opposite is done by `gwy_nield_flatten()` which reduces all numbers to 0 and 1.

On the other end, a clustering procedure may assign a cluster number to each pixel. The same number may be then scattered throughout the field and may not form a contiguous regions at all. In such case functions using only grain numbers are still useful, but functions based on contiguity are not.

Functions characterising marked regions usually return arrays indexed by grain numbers. An occasional hole in grain numbering is not an issue. However, avoid using unnecessarily large grain numbers, such as random integers, because it would require correspondingly huge arrays. Or apply `gwy_nield_compactify()` to compactify the numbers if you use large numbers temporarily.

## Functions

### gwy_nield_isolate()

    gboolean
    gwy_nield_isolate (GwyNield *nield,
                       gint number,
                       gint *bbox);

Clears all numbers in a number field except one.

The result is flattened, i.e. all values become either 1 (marked) or 0 (outside).

See `gwy_nield_isolate_at()` for a function which isolates a contiguous region.

See `gwy_nield_bounding_boxes()` for bounding box representation. If there are no non-zero pixels at the end, `bbox` is filled with values corresponding to a non-existent grain.

#### Parameters

nield | A number field. |
number | A grain number in `nield` . |
bbox | Optional array of 4 integers to be filled with the bounding box of the extracted grain. | [out][array size=4][nullable]

#### Returns

`TRUE` if there are any non-zero values.

### gwy_nield_isolate_at()

    gboolean
    gwy_nield_isolate_at (GwyNield *nield,
                          gint col,
                          gint row,
                          gint *bbox);

Isolates a contiguous region at given location in a number field.

The result is flattened, i.e. all values become either 1 (marked) or 0 (outside).

The region is defined by being both contiguous and having the same non-zero number as at (`col` ,`row` ). If the value at (`col` ,`row` ) is not positive, the number field is cleared.

See `gwy_nield_isolate()` for a function that isolates a possibly non-contiguous region by grain number and can be used to isolate a non-contiguous grain by postion (just read the value at (`col` , `row` )). If you instead want to isolate a contiguous marked region regardless of the grain number, use `gwy_nield_flatten()` first.

See `gwy_nield_bounding_boxes()` for bounding box representation. If there are no non-zero pixels at the end, `bbox` is filled with values corresponding to a non-existent grain.

#### Parameters

nield | A number field. |
col | Column index. |
row | Row index. |
bbox | Optional array of 4 integers to be filled with the bounding box of the extracted grain. | [out][array size=4][nullable]

#### Returns

`TRUE` if there are any non-zero values.

### gwy_nield_clear_at()

    gboolean
    gwy_nield_clear_at (GwyNield *nield,
                        gint col,
                        gint row);

Clears a contiguous region at given location in a number field.

The region is defined by being both contiguous and having the same non-zero number as at (`col` ,`row` ). If the value at (`col` ,`row` ) is not positive, the function is no-op.

See `gwy_nield_clear_by_number()` for a function which clears a possibly non-contiguous region by grain number. If you want to clear a contiguous marked region regardless of the grain number, use `gwy_nield_flatten()` first.

#### Parameters

nield | A number field. |
col | Column index. |
row | Row index. |

#### Returns

`TRUE` if anything was cleared.

### gwy_nield_clear_by_number()

    void
    gwy_nield_clear_by_number (GwyNield *nield,
                               gint number,
                               gboolean compactify);

Clears a single grain in a number field, given by number.

If `compactify` is `FALSE`, there will be a hole in the grain numbers. Passing `TRUE` moves larger grain numbers down by one. However, this only removes the newly created hole in numbers, not any pre-existing ones. Use `gwy_nield_compactify()` to remove all holes in grain numbers.

#### Parameters

nield | A number field. |
number | A grain number in `nield` . |
compactify | `TRUE` to shift all grains with large values one down. |

### gwy_nield_clear_by_size()

    void
    gwy_nield_clear_by_size (GwyNield *nield,
                             gint size);

Clears all grains below specified area in a number field.

All numbered regions with total pixel area smaller than `size` are filled with 0.

Grain numbers are not modified, so holes in grain numbers are likely to occur. Use `gwy_nield_compactify()` to remove the holes if it matters.

#### Parameters

nield | A number field. |
size | Minimum grain area, in pixels. |

### gwy_nield_clear_touching_border()

    void
    gwy_nield_clear_touching_border (GwyNield *nield,
                                     gboolean completely);

Clears all grains that touch any of a number field's borders.

Grain numbers are not modified, so holes in grain numbers are likely to occur. Use `gwy_nield_compactify()` to remove the holes if it matters.

#### Parameters

nield | A number field. |
completely | Pass `TRUE` to clear non-contiguous grains completely, `FALSE` to only clear the touching parts. |

### gwy_nield_mark_by_threshold()

    void
    gwy_nield_mark_by_threshold (GwyNield *nield,
                                 GwyField *field,
                                 gdouble threshold,
                                 gboolean above);

Marks all values in a data field based on a global threshold.

If `above` is `TRUE`, values ≤ `threshold` are marked. Otherwise values ≥ `threshold` are marked. Values equal to the threshold are marked in both cases.

See also `gwy_nield_mark_range()` for marking a range of values.

#### Parameters

nield | A number field. |
field | Source data field. |
threshold | Marking threshold. |
above | `TRUE` for marking values above the threshold, `FALSE` for marking values below. |

### gwy_nield_mark_range()

    void
    gwy_nield_mark_range (GwyNield *nield,
                          GwyField *field,
                          gdouble lower,
                          gdouble upper);

Marks all values in a data field within (or outside) an interval.

If `lower` ≤ `upper` , `field` values in the closed interval [`lower` , `upper` ] are marked in `nield` with 1, the rest marked with 0.

If `lower` > `upper` , `field` values in the two closed intervals [-∞, `lower` ] and [`upper` , ∞] are marked in `nield` with 1, the rest marked with 0. The closed intervals should be read as all ‘values ≤ `lower` ’ and ‘values ≥ `upper` ’.

See also `gwy_nield_mark_range()` for marking using a single threshold and `gwy_field_mark_outliers2()` and `gwy_field_mark_outliers_iqr()` for outlier marking.

#### Parameters

nield | A number field. |
field | Source data field. |
lower | Lower threshold for marking. |
upper | Upper threshold for marking. |

### gwy_nield_union()

    void
    gwy_nield_union (GwyNield *nield,
                     GwyNield *union_with);

Combines two number fields by grain union.

More precisely, the resulting numbers are the maxima of the two inputs. The result is not renumbered in any manner. Although this is valid when just distinguishing marked and empty regions, often you will want to apply `gwy_nield_number_contiguous()` or `gwy_nield_flatten()` aftewards.

#### Parameters

nield | A number field. |
union_with | Another field to union the number field with. |

### gwy_nield_intersect()

    void
    gwy_nield_intersect (GwyNield *nield,
                         GwyNield *intersect_with);

Combines two number fields by grain intersection.

More precisely, the resulting numbers are the minima of the two inputs. The result is not renumbered in any manner. Although this is valid when just distinguishing marked and empty regions, often you will want to apply `gwy_nield_number_contiguous()` or `gwy_nield_flatten()` aftewards.

#### Parameters

nield | A number field. |
intersect_with | Another field to intersect the number field with. |

### gwy_nield_merge()

    void
    gwy_nield_merge (GwyNield *nield,
                     GwyNield *operand,
                     GwyMergeType operation);

Combines two number fields by grain logical operation.

The function is a shorthand for doing either `gwy_nield_union()` or `gwy_nield_intersect()` depending on a GwyMergeType setting. If `operand` is `NULL`, `nield` is left unmodified.

Value outside the enum are allowed as `operation` , meaning to do nothing. However, GwyMergeType can be extended to other logical operations, so you need to pass a value like -1 or `G_MAXINT`.

#### Parameters

nield | A number field. |
operand | Another field to intersect or union the number field with. | [nullable]
operation | Logical operation to apply. |

### gwy_nield_invert()

    void
    gwy_nield_invert (GwyNield *nield);

Swaps marked and empty regions in a number field.

The result is flattened. All previously empty pixels are set to 1 and all previously marked to 0.

#### Parameters

nield | A number field. |

### gwy_nield_autocrop()

    gboolean
    gwy_nield_autocrop (GwyNield *nield,
                        gboolean symmetrically,
                        guint *left,
                        guint *right,
                        guint *up,
                        guint *down);

Removes empty border rows and columns from a number field.

If there are border rows and columns filled completely with non-positive values the size of the data field is reduced, removing these rows or columns. 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. It means 1×1 for `symmetrical` being `FALSE` or odd original dimensions. If the original dimensions are even and `symmetrical` `TRUE`, only the field is reduced to 2×2.

#### Parameters

nield | A number field. |
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`. | [out][optional]
right | Location to store how many column were removed from the right, or `NULL`. | [out][optional]
up | Location to store how many row were removed from the top, or `NULL`. | [out][optional]
down | Location to store how many row were removed from the bottom, or `NULL`. | [out][optional]

#### Returns

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

### gwy_nield_compactify()

    gint
    gwy_nield_compactify (GwyNield *nield);

Compactifies the numbering of marked regions in a number field.

Positive grain numbers will form an uninterrupted sequence from 1 to the return value. This is useful for removing holes in grain numbers. Non-positive values are unchanged by this function.

#### Parameters

nield | A number field. |

#### Returns

The new maximum grain number.

### gwy_nield_flatten()

    gboolean
    gwy_nield_flatten (GwyNield *nield);

Flattens all values in a number field to 0 or 1.

#### Parameters

nield | A number field. |

#### Returns

`TRUE` if there are any positive values.

### gwy_nield_number_contiguous()

    gint
    gwy_nield_number_contiguous (GwyNield *nield);

Renumbers regions in a number field based on contiguity.

Each distinct 4-connected region will have a unique number, and these will form an uninterrputed sequence starting from 1. Non-positive values are unchanged.

#### Parameters

nield | A number field. |

#### Returns

The new maximum grain number.

### gwy_nield_number_contiguous_periodic()

    gint
    gwy_nield_number_contiguous_periodic (GwyNield *nield);

Renumbers regions in a number field based on periodic contiguity.

An alternative version of `gwy_nield_number_contiguous()` which considers the number field as peroidic in the plane, i.e. grains can also connect through the opposite edges.

#### Parameters

nield | A number field. |

#### Returns

The new maximum grain number.

### gwy_nield_split_noncontiguous()

    gint
    gwy_nield_split_noncontiguous (GwyNield *nield);

Splits regions in a number field based on contiguity.

Numbered regions formed by multiple disconnected parts are split, giving each part a distinct number. Touching regions with distinct numbers are not merged; use `gwy_nield_number_contiguous()` if you want also merging, not just splitting. Non-positive values are unchanged.

#### Parameters

nield | A number field. |

#### Returns

The new maximum grain number.

### gwy_nield_grain_numbers()

    gint *
    gwy_nield_grain_numbers (GwyNield *nield,
                             gint *ngrains);

Gets all the distinct positive grain numbers in a number field.

#### Parameters

nield | A number field. |
ngrains | Location to store the number of distinct grain numbers. | [out]

#### Returns

Newly allocated array with distinct grain numbers, in ascending order.

[transfer full][array length=ngrains][nullable]

### gwy_nield_sizes()

    guint *
    gwy_nield_sizes (GwyNield *nield,
                     gint *maxgno);

Computes the numbers of pixels 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.

#### 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 (`maxgno` +1) values giving the sizes.

[transfer full]

### gwy_nield_fill_voids()

    gboolean
    gwy_nield_fill_voids (GwyNield *nield,
                          gboolean nonsimple);

Fills voids in grains in a number field.

Voids are regions of non-positive numbers in `nield` from which no path exists through other non-positive values to the number field boundary. The paths are considered in 8-connectivity because grains themselves are considered in 4-connectivity.

When `nonsimple` is `FALSE`, the total number of grains dos not change, only grain areas. When it is `TRUE`, some grains may disappear. In either case, the function does not attempt to produce any reasonable grain numbering. The result works as a mask, but needs renumbering for any grain operation.

#### Parameters

nield | A number field. |
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 holes. |

#### Returns

`TRUE` if `nield` has changed.

## Types and Values

### enum GwyMergeType

Mask merge type (namely used in grain processing).

#### Members

GWY_MERGE_CLEAR | Zero, disregarding both operands. |
GWY_MERGE_INTERSECTION | Intersection (logical-and/minimum) merging. |
GWY_MERGE_AND | Alternative name for `GWY_MERGE_INTERSECTION` . |
GWY_MERGE_MIN | Alternative name for `GWY_MERGE_INTERSECTION` . |
GWY_MERGE_SUBTRACT | Subtraction (clearing the first operand where the second is set). |
GWY_MERGE_KEEP | Values are given by the first operand. |
GWY_MERGE_REVSUBTRACT | Reverse subtraction (second operand, except where the first is set). |
GWY_MERGE_COPY | Values are given by the second operand. |
GWY_MERGE_XOR | Exclusive or merging (if exactly one operand is set, keeping this one). |
GWY_MERGE_UNION | Union (logical-or/maximum) merging. |
GWY_MERGE_OR | Alternative name for `GWY_MERGE_UNION` . |
GWY_MERGE_MAX | Alternative name for `GWY_MERGE_UNION` . |
GWY_MERGE_NOR | Alternative name for `GWY_MERGE_OUTSIDE` . |
GWY_MERGE_OUTSIDE | Positive only if both operands are unset. |
GWY_MERGE_NXOR | Alternative name for `GWY_MERGE_EQUAL` . |
GWY_MERGE_EQUAL | Positive where both operands are set or both unset (if they are both positive, the value is kept). |
GWY_MERGE_NCOPY | Values are given by the negation of the second operand. |
GWY_MERGE_CONVERSE | Positive except when the first operand is set and the second unset. |
GWY_MERGE_NOT | Values are given by the negation of the first operand. |
GWY_MERGE_IMPLIES | Positive except when the second operand is set and the first unset. |
GWY_MERGE_NAND | Positive only if either operand is unset. |
GWY_MERGE_FILL | Set, disregarding both operands. |