GwyNield: Gwyddion Library Reference Manual

## GwyNield GwyNield — Two-dimensional natural number array |

## Functions

GwyNield * | gwy_nield_new ()
GwyNield * | gwy_nield_new_alike ()
GwyNield * | gwy_nield_copy ()
void | gwy_nield_assign ()
void | gwy_nield_invalidate ()
void | gwy_nield_data_changed ()
void | gwy_nield_resize ()
void | gwy_nield_crop ()
GwyNield * | gwy_nield_area_extract ()
void | gwy_nield_copy_data ()
void | gwy_nield_area_copy ()
gint * | gwy_nield_get_data ()
const gint * | gwy_nield_get_data_const ()
gint * | gwy_nield_get_data_with_size ()
void | gwy_nield_set_data_with_size ()
gint | gwy_nield_get_xres ()
gint | gwy_nield_get_yres ()
gint | gwy_nield_max ()
gint | gwy_nield_get_val ()
void | gwy_nield_set_val ()
GwyNield * | gwy_nield_new_rotated_90 ()
GwyNield * | gwy_nield_new_resampled ()
void | gwy_nield_flip ()
void | gwy_nield_transpose ()
void | gwy_nield_area_transpose ()
void | gwy_nield_fill ()
void | gwy_nield_area_fill ()
void | gwy_nield_clear ()
void | gwy_nield_area_clear ()
guint | gwy_nield_count ()
guint | gwy_nield_area_count ()

## Signals

void | data-changed | Run First

## Types and Values

struct | GwyNield
struct | GwyNieldClass

## Object Hierarchy

        GObject
        ╰── GwyNield

## Implemented Interfaces

GwyNield implements GwySerializable.

## Includes

    #include <libgwyddion/gwyddion.h>

## Description

GwyNield is a regular two-dimensional data array of natural (or whole) numbers. It represents the result of some classification of two-dimensional data. The uses vary from a simple 0/1 masking to complicated splitting to multiple regions. Usually, zero means empty space and positive numbers marked regions. Occasionally, negative values are used to distinguish different types of empty space.

Unlike GwyField, GwyNield does not have units or physical dimensions. It is just a matrix of integers.

## Functions

### gwy_nield_new()

    GwyNield *
    gwy_nield_new (gint xres,
                   gint yres);

Creates a new number field.

The field is created as zero-filled.

[constructor]

#### Parameters

xres | X-resolution, i.e., the number of columns. |
yres | Y-resolution, i.e., the number of rows. |

#### Returns

A newly created number field.

[transfer full]

### gwy_nield_new_alike()

    GwyNield *
    gwy_nield_new_alike (GwyNield *model);

Creates a new number field similar to an existing one.

The field is created as zero-filled. Use `gwy_nield_copy()` if you want to copy a number field including data.

#### Parameters

model | A number field to take resolutions from. |

#### Returns

A newly created number field.

[transfer full]

### gwy_nield_copy()

    GwyNield *
    gwy_nield_copy (GwyNield *nield);

Create a new number field as a copy of an existing one.

This function is a convenience `gwy_serializable_copy()` wrapper.

#### Parameters

nield | A number field to duplicate. |

#### Returns

A copy of the number field.

[transfer full]

### gwy_nield_assign()

    void
    gwy_nield_assign (GwyNield *destination,
                      GwyNield *source);

Makes one number field equal to another.

This function is a convenience `gwy_serializable_assign()` wrapper.

#### Parameters

destination | Target number field. |
source | Source number field. |

### gwy_nield_invalidate()

    void
    gwy_nield_invalidate (GwyNield *nield);

Invalidates cached number field stats.

User code should rarely need this macro, as all GwyNield methods do proper invalidation when they change data, as well as `gwy_nield_get_data()` does.

However, if you get raw data with `gwy_nield_get_data()` and then mix direct changes to it with calls to methods like `gwy_nield_max()`, you may need to explicitely invalidate cached values to let `gwy_nield_get_max()` know it has to recompute the maximum.

#### Parameters

nield | A number field to invalidate. |

### gwy_nield_data_changed()

    void
    gwy_nield_data_changed (GwyNield *nield);

Emits signal "data-changed" on a number field.

#### Parameters

nield | A number field. |

### gwy_nield_resize()

    void
    gwy_nield_resize (GwyNield *nield,
                      gint xres,
                      gint yres);

Resizes a number field.

The content becomes undefined and the raw data returned by `gwy_nield_get_data()` may become invalid pointer.

#### Parameters

nield | A number field to be resized |
xres | New number of columns. |
yres | New number of rows. |

### gwy_nield_crop()

    void
    gwy_nield_crop (GwyNield *nield,
                    gint col,
                    gint row,
                    gint width,
                    gint height);

Crops a number field to a smaller size.

#### Parameters

nield | A number field to be resized |
row | Upper-left row coordinate. |
col | Upper-left column coordinate. |
width | Area width (number of columns). |
height | Area height (number of rows). |

### gwy_nield_area_extract()

    GwyNield *
    gwy_nield_area_extract (GwyNield *nield,
                            gint col,
                            gint row,
                            gint width,
                            gint height);

Extracts a rectangular part of a number field to a new number field.

#### Parameters

nield | A number field to be resized |
row | Upper-left row coordinate. |
col | Upper-left column coordinate. |
width | Area width (number of columns). |
height | Area height (number of rows). |

#### Returns

The extracted area as a newly created number field.

[transfer full]

### gwy_nield_copy_data()

    void
    gwy_nield_copy_data (GwyNield *nield,
                         GwyNield *target);

Copies the contents of an already allocated number field to a number field of the same size.

Only the data are copied. However, as GwyNield currently does not have any additional properties, the function has the same effect as `gwy_nield_assign()`.

#### Parameters

nield | Source number field. |
target | Destination number field. |

### gwy_nield_area_copy()

    void
    gwy_nield_area_copy (GwyNield *src,
                         GwyNield *dest,
                         gint col,
                         gint row,
                         gint width,
                         gint height,
                         gint destcol,
                         gint destrow);

Copies a rectangular area from one number field to another.

The area starts at (`col` , `row` ) in `src` and its dimension is `width` *`height` . It is copied to `dest` starting from (`destcol` , `destrow` ).

The source area has to be completely contained in `src` . No assumptions are made about destination position, however, parts of the source area sticking out the destination number field `dest` are cut off.

If `src` is equal to `dest` , the areas may not overlap.

#### Parameters

src | Source number field. |
dest | Destination number field. |
col | Area upper-left column coordinate in `src` . |
row | Area upper-left row coordinate `src` . |
width | Area width (number of columns), pass -1 for full `src` widdth. |
height | Area height (number of rows), pass -1 for full `src` height. |
destcol | Destination column in `dest` . |
destrow | Destination row in `dest` . |

### gwy_nield_get_data()

    gint *
    gwy_nield_get_data (GwyNield *nield);

Gets the raw data buffer of a number field.

The returned buffer is not guaranteed to be valid through whole number field life time. Some function may change it, most notably `gwy_nield_resize()` and `gwy_nield_crop()`.

This function invalidates any cached information, use `gwy_nield_get_data_const()` if you are not going to change the data.

See `gwy_nield_invalidate()` for some discussion.

#### Parameters

nield | A number field |

#### Returns

The number field as a pointer to an array of `gwy_nield_get_xres()`*gwy_nield_get_yres() gint's, ordered by lines. I.e., they are to be accessed as data[row*xres + column].

### gwy_nield_get_data_const()

    const gint *
    gwy_nield_get_data_const (GwyNield *nield);

Gets the raw data buffer of a number field, read-only.

The returned buffer is not guaranteed to be valid through whole number field life time. Some function may change it, most notably `gwy_nield_resize()` and `gwy_nield_crop()`.

Use `gwy_nield_get_data()` if you want to change the data.

See `gwy_nield_invalidate()` for some discussion.

#### Parameters

nield | A number field. |

#### Returns

The number field as a pointer to an array of `gwy_nield_get_xres()`*gwy_nield_get_yres() gint's, ordered by lines. I.e., they are to be accessed as data[row*xres + column].

### gwy_nield_get_data_with_size()

    gint *
    gwy_nield_get_data_with_size (GwyNield *nield,
                                  gsize *out_count);

Gets the raw data buffer of a number field. Used for gobject-introspection bindings.

The returned buffer is not guaranteed to be valid through whole number field life time. Some function may change it, most notably `gwy_nield_resize()` and `gwy_nield_crop()`.

This function invalidates any cached information. See `gwy_nield_invalidate()` for some discussion.

#### Parameters

nield | A number field |
out_count | Number of items in the returned buffer. | [out]

#### Returns

The number field as a pointer to an array of `gwy_nield_get_xres()`*gwy_nield_get_yres() gint's, ordered by lines. I.e., they are to be accessed as data[row*xres + column].

[transfer none][array length=out_count]

### gwy_nield_set_data_with_size()

    void
    gwy_nield_set_data_with_size (GwyNield *nield,
                                  gint *data,
                                  gsize data_count);

Sets new values to the raw data buffer of a number field. Used for gobject-introspection bindings.

This function invalidates any cached information. See `gwy_nield_invalidate()` for some discussion.

#### Parameters

nield | A number field |
data | The data to be set as a pointer to an array of `data_len` gints. | [array length=data_count]
data_count | Number of items in `data` . It has to be equal to `gwy_nield_get_xres()`*gwy_nield_get_yres(), else the function does nothing. |

### gwy_nield_get_xres()

    gint
    gwy_nield_get_xres (GwyNield *nield);

Gets X resolution (number of columns) of a number field.

#### Parameters

nield | A number field. |

#### Returns

X resolution.

### gwy_nield_get_yres()

    gint
    gwy_nield_get_yres (GwyNield *nield);

Gets Y resolution (number of rows) of the field.

#### Parameters

nield | A number field. |

#### Returns

Y resolution.

### gwy_nield_max()

    gint
    gwy_nield_max (GwyNield *nield);

Finds the maximum value in a number field.

This quantity is cached. Although it is not common, the return value can also be negative.

#### Parameters

nield | A number field. |

#### Returns

The maximum value.

### gwy_nield_get_val()

    gint
    gwy_nield_get_val (GwyNield *nield,
                       gint col,
                       gint row);

Gets value at given position in a number field.

Do not access data with this function inside inner loops, it's slow. Get the raw data buffer with `gwy_nield_get_data_const()` and access it directly instead.

#### Parameters

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

#### Returns

Value at (`col` , `row` ).

### gwy_nield_set_val()

    void
    gwy_nield_set_val (GwyNield *nield,
                       gint col,
                       gint row,
                       gint value);

Sets value at given position in a number field.

Do not set data with this function inside inner loops, it's slow. Get the raw data buffer with `gwy_nield_get_data()` and write to it directly instead.

#### Parameters

nield | A number field. |
col | Column index. |
row | Row index. |
value | Value to set. |

### gwy_nield_new_rotated_90()

    GwyNield *
    gwy_nield_new_rotated_90 (GwyNield *nield,
                              gboolean clockwise);

Creates a new number field by rotating a number field by 90 degrees.

#### Parameters

nield | A number field. |
clockwise | `TRUE` to rotate clocwise, `FALSE` to rotate anti-clockwise. |

#### Returns

A newly created number field.

[transfer full]

### gwy_nield_new_resampled()

    GwyNield *
    gwy_nield_new_resampled (GwyNield *nield,
                             gint xres,
                             gint yres);

Resamples a number field.

The result is always flattened (as in `gwy_nield_flatten()`). Pixels of the new number field which are covered by positive values by at least 1/2 are set to 1. Pixels covered from less than 1/2 are set to 0.

#### Parameters

nield | A number field. |
xres | New number of columns. |
yres | New number of rows. |

#### Returns

A newly created number field.

[transfer full]

### gwy_nield_flip()

    void
    gwy_nield_flip (GwyNield *nield,
                    gboolean xflipped,
                    gboolean yflipped);

Reflects a number field.

#### Parameters

nield | A number field. |
xflipped | `TRUE` to reflect X, i.e. rows within the XY plane. The image will be left–right mirrored. |
yflipped | `TRUE` to reflect Y, i.e. columns within the XY plane. The image will be flipped upside down. |

### gwy_nield_transpose()

    void
    gwy_nield_transpose (GwyNield *src,
                         GwyNield *dest,
                         gboolean minor);

Copies data from one number field to another with transposition.

The destination number field is resized as necessary.

#### Parameters

src | Source number field. |
dest | Destination number field. |
minor | `TRUE` to mirror about the minor diagonal; `FALSE` to mirror about major diagonal. |

### gwy_nield_area_transpose()

    void
    gwy_nield_area_transpose (GwyNield *src,
                              gint col,
                              gint row,
                              gint width,
                              gint height,
                              GwyNield *dest,
                              gboolean minor);

Copies data from a rectangular part of one number field to another with transposition.

The destination number field is resized as necessary.

#### Parameters

src | Source number field. |
col | Upper-left column coordinate in `src` . |
row | Upper-left row coordinate in `src` . |
width | Area width (number of columns) in `src` . |
height | Area height (number of rows) in `src` . |
dest | Destination number field. |
minor | `TRUE` to mirror about the minor diagonal; `FALSE` to mirror about major diagonal. |

### gwy_nield_fill()

    void
    gwy_nield_fill (GwyNield *nield,
                    gint value);

Fills a number field with given value.

#### Parameters

nield | A number field. |
value | Value to be entered. |

### gwy_nield_area_fill()

    void
    gwy_nield_area_fill (GwyNield *nield,
                         GwyNield *mask,
                         GwyMaskingType mode,
                         gint col,
                         gint row,
                         gint width,
                         gint height,
                         gint value);

Fills a masked rectangular part of a number field with given value.

#### Parameters

nield | A number field. |
mask | Mask specifying which values to take into account/exclude, or `NULL`. |
mode | Masking mode to use. See the introduction for description of masking modes. |
col | Upper-left column coordinate. |
row | Upper-left row coordinate. |
width | Area width (number of columns). |
height | Area height (number of rows). |
value | Value to be entered |

### gwy_nield_clear()

    void
    gwy_nield_clear (GwyNield *nield);

Fills a number field with zeroes.

#### Parameters

nield | A number field. |

### gwy_nield_area_clear()

    void
    gwy_nield_area_clear (GwyNield *nield,
                          gint col,
                          gint row,
                          gint width,
                          gint height);

Fills a rectangular part of a number field with zeroes.

Use `gwy_nield_area_fill()` to clear an area with masking. Clearing is only more efficient without masking.

#### Parameters

nield | A number field. |
col | Upper-left column coordinate. |
row | Upper-left row coordinate. |
width | Area width (number of columns). |
height | Area height (number of rows). |

### gwy_nield_count()

    guint
    gwy_nield_count (GwyNield *nield);

Counts positive values in a number field.

#### Parameters

nield | A number field. |

#### Returns

The number of positive values.

### gwy_nield_area_count()

    guint
    gwy_nield_area_count (GwyNield *nield,
                          GwyNield *mask,
                          GwyMaskingType mode,
                          gint col,
                          gint row,
                          gint width,
                          gint height);

Counts positive values in a rectangular region of a number field.

#### Parameters

nield | A number field. |
mask | Mask specifying which values to take into account/exclude, or `NULL`. |
mode | Masking mode to use. See the introduction for description of masking modes. |
col | Upper-left column coordinate. |
row | Upper-left row coordinate. |
width | Area width (number of columns). |
height | Area height (number of rows) |

#### Returns

The number of positive values.

## Types and Values

### struct GwyNield

    struct GwyNield;

### struct GwyNieldClass

    struct GwyNieldClass {
        GObjectClass parent_class;

        void (*data_changed)(GwyNield *nield);
    };

## Signal Details

### The `“data-changed”` signal

    void
    user_function (GwyNield *gwynield,
                   gpointer  user_data)

The ::data-changed signal is never emitted by number field itself. It is intended as a means to notify others number field users they should update themselves.

#### Parameters

gwynield | The GwyNield which received the signal. |
user_data | user data set when the signal handler was connected. |

Flags: Run First