GwyField: Gwyddion Library Reference Manual

## GwyField GwyField — Two-dimensional floating point data |

## Functions

GwyField * | gwy_field_new ()
GwyField * | gwy_field_new_alike ()
GwyNield * | gwy_field_new_nield_alike ()
GwyField * | gwy_field_copy ()
void | gwy_field_assign ()
void | gwy_field_invalidate ()
void | gwy_field_data_changed ()
GwyField * | gwy_field_new_resampled ()
void | gwy_field_resample ()
void | gwy_field_bin ()
GwyField * | gwy_field_new_binned ()
void | gwy_field_make_alike ()
void | gwy_field_resize ()
void | gwy_field_crop ()
GwyField * | gwy_field_area_extract ()
void | gwy_field_copy_data ()
void | gwy_field_copy_data_mask ()
void | gwy_field_area_copy ()
gdouble * | gwy_field_get_data ()
const gdouble * | gwy_field_get_data_const ()
gdouble * | gwy_field_get_data_with_size ()
void | gwy_field_set_data_with_size ()
gint | gwy_field_get_xres ()
gint | gwy_field_get_yres ()
gdouble | gwy_field_get_xreal ()
gdouble | gwy_field_get_yreal ()
void | gwy_field_set_xreal ()
void | gwy_field_set_yreal ()
gdouble | gwy_field_get_dx ()
gdouble | gwy_field_get_dy ()
gdouble | gwy_field_get_xoffset ()
gdouble | gwy_field_get_yoffset ()
void | gwy_field_set_xoffset ()
void | gwy_field_set_yoffset ()
GwyUnit * | gwy_field_get_unit_xy ()
GwyUnit * | gwy_field_get_unit_z ()
GwyValueFormat * | gwy_field_get_value_format_xy ()
GwyValueFormat * | gwy_field_get_value_format_z ()
void | gwy_field_copy_units ()
void | gwy_field_copy_units_to_line ()
void | gwy_line_copy_units_to_field ()
gdouble | gwy_field_itor ()
gdouble | gwy_field_jtor ()
gdouble | gwy_field_rtoi ()
gdouble | gwy_field_rtoj ()
gdouble | gwy_field_get_val ()
void | gwy_field_set_val ()
gdouble | gwy_field_get_dval ()
gdouble | gwy_field_get_dval_real ()
void | gwy_field_rotate ()
GwyField * | gwy_field_new_rotated ()
GwyField * | gwy_field_new_rotated_90 ()
void | gwy_field_flip ()
void | gwy_field_invert_value ()
void | gwy_field_transpose ()
void | gwy_field_area_transpose ()
void | gwy_field_fill ()
void | gwy_field_clear ()
void | gwy_field_multiply ()
void | gwy_field_add ()
void | gwy_field_abs ()
void | gwy_field_area_fill ()
void | gwy_field_fill_mask ()
void | gwy_field_area_fill_mask ()
void | gwy_field_area_clear ()
void | gwy_field_area_multiply ()
void | gwy_field_area_add ()
void | gwy_field_area_abs ()
GwyLine * | gwy_field_profile ()
GwyXY * | gwy_field_profile_mask ()
GwyXY * | gwy_field_row_profile ()
GwyXY * | gwy_field_column_profile ()
void | gwy_field_get_row ()
void | gwy_field_get_column ()
void | gwy_field_set_row ()
void | gwy_field_set_column ()
void | gwy_field_get_row_part ()
void | gwy_field_get_column_part ()
void | gwy_field_set_row_part ()
void | gwy_field_set_column_part ()
gdouble | gwy_field_xder ()
gdouble | gwy_field_yder ()
gdouble | gwy_field_angder ()
void | gwy_field_average_xyz ()
void | gwy_field_average_xy_z ()

## Signals

void | data-changed | Run First

## Types and Values

struct | GwyField
struct | GwyFieldClass

## Object Hierarchy

        GObject
        ╰── GwyField

## Implemented Interfaces

GwyField implements GwySerializable.

## Includes

    #include <libgwyddion/gwyddion.h>

## Description

GwyField is a regular two-dimensional floating point data array (matrices, height field, image, …). Most of the basic data handling and processing functions in Gwyddion are connected with GwyField.

## Functions

### gwy_field_new()

    GwyField *
    gwy_field_new (gint xres,
                   gint yres,
                   gdouble xreal,
                   gdouble yreal,
                   gboolean nullme);

Creates a new data field.

[constructor]

#### Parameters

xres | X-resolution, i.e., the number of columns. |
yres | Y-resolution, i.e., the number of rows. |
xreal | Real horizontal physical dimension. |
yreal | Real vertical physical dimension. |
nullme | Whether the data field should be initialized to zeros. If `FALSE`, the data will not be initialized. |

#### Returns

A newly created data field.

[transfer full]

### gwy_field_new_alike()

    GwyField *
    gwy_field_new_alike (GwyField *model,
                         gboolean nullme);

Creates a new data field similar to an existing one.

Use `gwy_field_copy()` if you want to copy a data field including data.

#### Parameters

model | A data field to take resolutions and units from. |
nullme | Whether the data field should be initialized to zeros. If `FALSE`, the data will not be initialized. |

#### Returns

A newly created data field.

[transfer full]

### gwy_field_new_nield_alike()

    GwyNield *
    gwy_field_new_nield_alike (GwyField *field);

Creates a new number field with the same dimensions as a data field.

The field is created as zero-filled.

#### Parameters

field | A data field to take resolutions from. |

#### Returns

A newly created number field.

[transfer full]

### gwy_field_copy()

    GwyField *
    gwy_field_copy (GwyField *field);

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

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

#### Parameters

field | A data field to duplicate. |

#### Returns

A copy of the data field.

[transfer full]

### gwy_field_assign()

    void
    gwy_field_assign (GwyField *destination,
                      GwyField *source);

Makes one data field equal to another.

This function is a convenience `gwy_serializable_assign()` wrapper. See `gwy_field_make_alike()` for updating properties to match another field without copying data.

#### Parameters

destination | Target data field. |
source | Source data field. |

### gwy_field_invalidate()

    void
    gwy_field_invalidate (GwyField *field);

Invalidates cached data field stats.

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

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

#### Parameters

field | A data field to invalidate. |

### gwy_field_data_changed()

    void
    gwy_field_data_changed (GwyField *field);

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

#### Parameters

field | A data field. |

### gwy_field_new_resampled()

    GwyField *
    gwy_field_new_resampled (GwyField *field,
                             gint xres,
                             gint yres,
                             GwyInterpolationType interpolation);

Creates a new data field by resampling an existing one.

This method is equivalent to `gwy_field_copy()` followed by `gwy_field_resample()`, but it is more efficient.

#### Parameters

field | A data field. |
xres | Desired X resolution. |
yres | Desired Y resolution. |
interpolation | Interpolation method to use. |

#### Returns

A newly created data field.

[transfer full]

### gwy_field_resample()

    void
    gwy_field_resample (GwyField *field,
                        gint xres,
                        gint yres,
                        GwyInterpolationType interpolation);

Resamples a data field using given interpolation method

This method may invalidate raw data buffer returned by `gwy_field_get_data()`.

#### Parameters

field | A data field to be resampled. |
xres | Desired X resolution. |
yres | Desired Y resolution. |
interpolation | Interpolation method to use. |

### gwy_field_bin()

    void
    gwy_field_bin (GwyField *field,
                   GwyField *target,
                   gint binw,
                   gint binh,
                   gint xoff,
                   gint yoff,
                   gint trimlowest,
                   gint trimhighest);

Bins a data field into another data field.

See `gwy_field_new_binned()` for a detailed description.

#### Parameters

field | A data field. |
target | Target data field. It will be resized as necessary. |
binw | Bin height (in pixels). |
binh | Bin width (in pixels). |
xoff | Horizontal offset of bins (in pixels). |
yoff | Vertical offset of bins (in pixels). |
trimlowest | Number of lowest values to discard. |
trimhighest | Number of highest values to discard. |

### gwy_field_new_binned()

    GwyField *
    gwy_field_new_binned (GwyField *field,
                          gint binw,
                          gint binh,
                          gint xoff,
                          gint yoff,
                          gint trimlowest,
                          gint trimhighest);

Creates a new data field by binning an existing one.

The data field is divided into rectangles of dimensions `binw` ×`binh` , offset by (`xoff` , `yoff` ). The values in each complete rectangle are averaged and the average becomes the pixel value in the newly created, smaller data field.

Note that the result is the average – not sum – of the individual values. Multiply the returned data field with `binw` ×`binh` if you want sum.

By giving non-zero `trimlowest` and `trimhighest` you can change the plain average to a trimmed one (even turning it to median in the extreme case). It must always hold that `trimlowest` + `trimhighest` is smaller than `binw` ×`binh` .

#### Parameters

field | A data field. |
binw | Bin height (in pixels). |
binh | Bin width (in pixels). |
xoff | Horizontal offset of bins (in pixels). |
yoff | Vertical offset of bins (in pixels). |
trimlowest | Number of lowest values to discard. |
trimhighest | Number of highest values to discard. |

#### Returns

A newly created data field.

[transfer full]

### gwy_field_make_alike()

    void
    gwy_field_make_alike (GwyField *field,
                          GwyField *model);

Resizes a data field and updates its properties to match another data field.

Physical dimensions, offsets and units are all updated to match `model` . Since the function can resize `field` , its contents must be considered undefined. See `gwy_field_resize()` for just pixel resize and `gwy_field_assign()` for making one field completely identical to another.

#### Parameters

field | A data field to be resized |
model | A data field to take resolutions and units from. |

### gwy_field_resize()

    void
    gwy_field_resize (GwyField *field,
                      gint xres,
                      gint yres);

Resizes a data field to a different size, discarding data.

The real dimensions and offsets are unchanged. The field contents becomes undefined. The function just makes sure `field` has the correct pixel dimensions. See `gwy_field_make_alike()` for updating all properties to match another field.

#### Parameters

field | A data field to be resized |
xres | Desired X resolution. |
yres | Desired Y resolution. |

### gwy_field_crop()

    void
    gwy_field_crop (GwyField *field,
                    gint col,
                    gint row,
                    gint width,
                    gint height);

Crops a data field to a smaller size.

The real dimensions are updated according to the pixel size. Offsets are set to zero.

This method may invalidate raw data buffer returned by `gwy_field_get_data()`.

#### Parameters

field | A data 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_field_area_extract()

    GwyField *
    gwy_field_area_extract (GwyField *field,
                            gint col,
                            gint row,
                            gint width,
                            gint height);

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

The real dimensions are computed to match the pixel size. Offsets are set to zero.

#### Parameters

field | A data 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 data field.

[transfer full]

### gwy_field_copy_data()

    void
    gwy_field_copy_data (GwyField *field,
                         GwyField *target);

Copies the contents of a data field to another data field of the same size.

Only the data are copied. To make a data field completely identical to another, including units and change of dimensions, you can use `gwy_field_assign()`.

See also `gwy_field_copy_data_mask()` which copies only some values, decided by a mask.

#### Parameters

field | Source data field. |
target | Destination data field. |

### gwy_field_copy_data_mask()

    void
    gwy_field_copy_data_mask (GwyField *field,
                              GwyField *target,
                              GwyNield *mask,
                              GwyMaskingType masking);

Copies some values from a data field to another data field of the same size determined by a mask.

Included pixels (according to the masking mode) are copied from `source` to `target` . Excluded pixels in `target` are left untouched.

Using `mask` =`NULL` or `masking` =`GWY_MASK_INCLUDE` is not particularly useful since the function then just becomes `gwy_field_copy_data()`. It is, however, allowed for simplicity.

#### Parameters

field | Source data field. |
target | Destination data field. |
mask | Mask specifying which values to copy, or `NULL`. | [nullable]
masking | Masking mode to use. |

### gwy_field_area_copy()

    void
    gwy_field_area_copy (GwyField *src,
                         GwyField *dest,
                         gint col,
                         gint row,
                         gint width,
                         gint height,
                         gint destcol,
                         gint destrow);

Copies a rectangular area from one data 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 data field `dest` are cut off.

If `src` is the same data field as `dest` , the areas may not overlap.

#### Parameters

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

### gwy_field_get_data()

    gdouble *
    gwy_field_get_data (GwyField *field);

Gets the raw data buffer of a data field.

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

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

See `gwy_field_invalidate()` for some discussion.

[rename-to gwy_field_get_data_pointer]

#### Parameters

field | A data field |

#### Returns

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

[type gpointer]

### gwy_field_get_data_const()

    const gdouble *
    gwy_field_get_data_const (GwyField *field);

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

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

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

See `gwy_field_invalidate()` for some discussion.

#### Parameters

field | A data field. |

#### Returns

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

### gwy_field_get_data_with_size()

    gdouble *
    gwy_field_get_data_with_size (GwyField *field,
                                  gsize *out_count);

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

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

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

See `gwy_field_invalidate()` for some discussion.

[rename-to gwy_field_get_data]

#### Parameters

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

#### Returns

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

[transfer none][array length=out_count]

### gwy_field_set_data_with_size()

    void
    gwy_field_set_data_with_size (GwyField *field,
                                  gdouble *data,
                                  gsize data_count);

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

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

[rename-to gwy_field_set_data]

#### Parameters

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

### gwy_field_get_xres()

    gint
    gwy_field_get_xres (GwyField *field);

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

#### Parameters

field | A data field. |

#### Returns

X resolution.

### gwy_field_get_yres()

    gint
    gwy_field_get_yres (GwyField *field);

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

#### Parameters

field | A data field. |

#### Returns

Y resolution.

### gwy_field_get_xreal()

    gdouble
    gwy_field_get_xreal (GwyField *field);

Gets the X real (physical) size of a data field.

#### Parameters

field | A data field. |

#### Returns

X real size value.

### gwy_field_get_yreal()

    gdouble
    gwy_field_get_yreal (GwyField *field);

Gets the Y real (physical) size of a data field.

#### Parameters

field | A data field |

#### Returns

Y real size value.

### gwy_field_set_xreal()

    void
    gwy_field_set_xreal (GwyField *field,
                         gdouble xreal);

Sets X real (physical) size value of a data field.

#### Parameters

field | A data field. |
xreal | New X real size value. |

### gwy_field_set_yreal()

    void
    gwy_field_set_yreal (GwyField *field,
                         gdouble yreal);

Sets Y real (physical) size value of a data field.

#### Parameters

field | A data field. |
yreal | New Y real size value. |

### gwy_field_get_dx()

    gdouble
    gwy_field_get_dx (GwyField *field);

Gets the horizontal pixel size of a data field in real units.

The result is the same as gwy_field_get_xreal(field)/gwy_field_get_xres(field).

#### Parameters

field | A data field. |

#### Returns

Horizontal pixel size.

### gwy_field_get_dy()

    gdouble
    gwy_field_get_dy (GwyField *field);

Gets the vertical pixel size of a data field in real units.

The result is the same as gwy_field_get_yreal(field)/gwy_field_get_yres(field).

#### Parameters

field | A data field. |

#### Returns

Vertical pixel size.

### gwy_field_get_xoffset()

    gdouble
    gwy_field_get_xoffset (GwyField *field);

Gets the X offset of data field origin.

#### Parameters

field | A data field. |

#### Returns

X offset value.

### gwy_field_get_yoffset()

    gdouble
    gwy_field_get_yoffset (GwyField *field);

Gets the Y offset of data field origin.

#### Parameters

field | A data field |

#### Returns

Y offset value.

### gwy_field_set_xoffset()

    void
    gwy_field_set_xoffset (GwyField *field,
                           gdouble xoff);

Sets the X offset of a data field origin.

Note offsets don't affect any calculation, nor functions like `gwy_field_rtoj()`.

#### Parameters

field | A data field. |
xoff | New X offset value. |

### gwy_field_set_yoffset()

    void
    gwy_field_set_yoffset (GwyField *field,
                           gdouble yoff);

Sets the Y offset of a data field origin.

Note offsets don't affect any calculation, nor functions like `gwy_field_rtoi()`.

#### Parameters

field | A data field. |
yoff | New Y offset value. |

### gwy_field_get_unit_xy()

    GwyUnit *
    gwy_field_get_unit_xy (GwyField *field);

Returns lateral SI unit of a data field.

The returned object can be modified to change the field lateral units.

#### Parameters

field | A data field. |

#### Returns

SI unit corresponding to the lateral (XY) dimensions of the data field. Its reference count is not incremented.

[transfer none]

### gwy_field_get_unit_z()

    GwyUnit *
    gwy_field_get_unit_z (GwyField *field);

Returns value SI unit of a data field.

The returned object can be modified to change the field value units.

#### Parameters

field | A data field. |

#### Returns

SI unit corresponding to the "height" (Z) dimension of the data field. Its reference count is not incremented.

[transfer none]

### gwy_field_get_value_format_xy()

    GwyValueFormat *
    gwy_field_get_value_format_xy (GwyField *field,
                                   GwyUnitFormatStyle style,
                                   GwyValueFormat *format);

Finds value format good for displaying coordinates of a data field.

#### Parameters

field | A data field. |
style | Unit format style. |
format | A SI value format to modify, or `NULL` to allocate a new one. | [nullable]

#### Returns

The value format. If `format` is `NULL`, a newly allocated format is returned, otherwise (modified) `format` itself is returned.

### gwy_field_get_value_format_z()

    GwyValueFormat *
    gwy_field_get_value_format_z (GwyField *field,
                                  GwyUnitFormatStyle style,
                                  GwyValueFormat *format);

Finds value format good for displaying values of a data field.

#### Parameters

field | A data field. |
style | Unit format style. |
format | A SI value format to modify, or `NULL` to allocate a new one. | [nullable]

#### Returns

The value format. If `format` is `NULL`, a newly allocated format is returned, otherwise (modified) `format` itself is returned.

### gwy_field_copy_units()

    void
    gwy_field_copy_units (GwyField *field,
                          GwyField *target);

Sets lateral and value units of a data field to match another data field.

#### Parameters

field | A data field. |
target | Target data field. |

### gwy_field_copy_units_to_line()

    void
    gwy_field_copy_units_to_line (GwyField *field,
                                  GwyLine *line);

Sets lateral and value units of a data line to match a data field.

#### Parameters

field | A data field to get units from. |
line | A data line to set units of. |

### gwy_line_copy_units_to_field()

    void
    gwy_line_copy_units_to_field (GwyLine *line,
                                  GwyField *field);

Sets lateral and value units of a data field to match a data line.

#### Parameters

line | A data line to get units from. |
field | A data field to set units of. |

### gwy_field_itor()

    gdouble
    gwy_field_itor (GwyField *field,
                    gdouble row);

Transforms vertical pixel coordinate to real (physical) Y coordinate.

That is it maps range [0..y-resolution] to range [0..real-y-size]. It is not suitable for conversion of matrix indices to physical coordinates, you have to use gwy_field_itor(`field` , `row` + 0.5) for that.

#### Parameters

field | A data field. |
row | Vertical pixel coordinate. |

#### Returns

Real Y coordinate.

### gwy_field_jtor()

    gdouble
    gwy_field_jtor (GwyField *field,
                    gdouble col);

Transforms horizontal pixel coordinate to real (physical) X coordinate.

That is it maps range [0..x-resolution] to range [0..real-x-size]. It is not suitable for conversion of matrix indices to physical coordinates, you have to use gwy_field_jtor(`field` , `col` + 0.5) for that.

#### Parameters

field | A data field. |
col | Horizontal pixel coordinate. |

#### Returns

Real X coordinate.

### gwy_field_rtoi()

    gdouble
    gwy_field_rtoi (GwyField *field,
                    gdouble realy);

Transforms real (physical) Y coordinate to row.

That is it maps range [0..real-y-size] to range [0..y-resolution].

#### Parameters

field | A data field. |
realy | Real (physical) Y coordinate. |

#### Returns

Vertical pixel coodinate.

### gwy_field_rtoj()

    gdouble
    gwy_field_rtoj (GwyField *field,
                    gdouble realx);

Transforms real (physical) X coordinate to column.

That is it maps range [0..real-x-size] to range [0..x-resolution].

#### Parameters

field | A data field. |
realx | Real (physical) X coodinate. |

#### Returns

Horizontal pixel coordinate.

### gwy_field_get_val()

    gdouble
    gwy_field_get_val (GwyField *field,
                       gint col,
                       gint row);

Gets value at given position in a data field.

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

#### Parameters

field | A data field. |
col | Column index. |
row | Row index. |

#### Returns

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

### gwy_field_set_val()

    void
    gwy_field_set_val (GwyField *field,
                       gint col,
                       gint row,
                       gdouble value);

Sets value at given position in a data field.

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

#### Parameters

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

### gwy_field_get_dval()

    gdouble
    gwy_field_get_dval (GwyField *field,
                        gdouble x,
                        gdouble y,
                        GwyInterpolationType interpolation);

Gets interpolated value at arbitrary data field point indexed by pixel coordinates.

Note pixel values are centered in pixels, so to get the same value as gwy_field_get_val(`field` , `j` , `i` ) returns, it's necessary to add 0.5: gwy_field_get_dval(`field` , `j` +0.5, `i` +0.5, `interpolation` ).

See also `gwy_field_get_dval_real()` that does the same, but takes real coordinates.

#### Parameters

field | A data field |
x | Horizontal position in pixel units, in range [0, x-resolution]. |
y | Vertical postition in pixel units, in range [0, y-resolution]. |
interpolation | Interpolation method to be used. |

#### Returns

Interpolated value at position (`x` ,`y` ).

### gwy_field_get_dval_real()

    gdouble
    gwy_field_get_dval_real (GwyField *field,
                             gdouble x,
                             gdouble y,
                             GwyInterpolationType interpolation);

Gets interpolated value at arbitrary data field point indexed by real coordinates.

See also `gwy_field_get_dval()` that does the same, but takes pixel coordinates.

#### Parameters

field | A data field. |
x | X postion in real coordinates. |
y | Y postition in real coordinates. |
interpolation | Interpolation method to use. |

#### Returns

Value at position (`x` ,`y` ).

### gwy_field_rotate()

    void
    gwy_field_rotate (GwyField *field,
                      gdouble angle,
                      GwyInterpolationType interpolation);

Rotates a data field by a given angle.

This function is mostly obsolete. See `gwy_field_new_rotated()` and `gwy_field_new_rotated_90()`.

Values that get outside of data field by the rotation are lost. Undefined values from outside of data field that get inside are set to data field minimum value.

The rotation is performed in pixel space, i.e. it can be in fact a more general affine transform in the real coordinates when pixels are not square.

#### Parameters

field | A data field. |
angle | Rotation angle (in radians). |
interpolation | Interpolation method to use. |

### gwy_field_new_rotated()

    GwyField *
    gwy_field_new_rotated (GwyField *field,
                           GwyNield *exterior_mask,
                           gdouble angle,
                           GwyInterpolationType interp,
                           GwyRotateResizeType resize);

Creates a new data field by rotating a data field by an atribtrary angle.

The returned data field can have pixel corresponding to exterior in `field` (unless `resize` is `GWY_ROTATE_RESIZE_CUT`). They are filled with a neutral value; pass `exterior_mask` and replace them as you wish if you need more control.

The rotation is performed in real space, i.e. it is a more general affine transform in the pixel space for data field with non-square pixels. See `gwy_field_rotate()` which rotates in the pixel space.

The returned data field has always square pixels. If you want to rotate by a multiple of `G_PI`/2 while preserving non-square pixels, you must use explicitly a function such as `gwy_field_new_rotated_90()`.

#### Parameters

field | A data field. |
exterior_mask | Optional data field where pixels corresponding to exterior will be set to 1. It will be resized to match the returned field. |
angle | Rotation angle (in radians). |
interp | Interpolation type to use. |
resize | Controls how the result size is determined. |

#### Returns

A newly created data field.

[transfer full]

### gwy_field_new_rotated_90()

    GwyField *
    gwy_field_new_rotated_90 (GwyField *field,
                              gboolean clockwise);

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

#### Parameters

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

#### Returns

A newly created data field.

[transfer full]

### gwy_field_flip()

    void
    gwy_field_flip (GwyField *field,
                    gboolean xflipped,
                    gboolean yflipped);

Reflects a data field in place.

Since real sizes cannot go backward, flipping an axis results in the corresponding offset being reset (the real dimension stays positive).

Note that in Gwyddion 2 the arguments `xflipped` and `yflipped` are swapped (to much wailing and gnashing of theeth).

#### Parameters

field | A data 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_field_invert_value()

    void
    gwy_field_invert_value (GwyField *field);

Inverts values in a data field.

The values are inverted about the mean value. Use `gwy_field_multiply()` to change the signs of all values.

#### Parameters

field | A data field. |

### gwy_field_transpose()

    void
    gwy_field_transpose (GwyField *src,
                         GwyField *dest,
                         gboolean minor);

Copies data from one data field to another with transposition.

The destination data field is resized as necessary, its real dimensions set to transposed `src` dimensions and its offsets are reset. Units are not updated.

#### Parameters

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

### gwy_field_area_transpose()

    void
    gwy_field_area_transpose (GwyField *src,
                              gint col,
                              gint row,
                              gint width,
                              gint height,
                              GwyField *dest,
                              gboolean minor);

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

The destination data field is resized as necessary, its real dimensions set to transposed `src` area dimensions and its offsets are reset. Units are not updated.

#### Parameters

src | Source data 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 data field. |
minor | `TRUE` to mirror about the minor diagonal; `FALSE` to mirror about major diagonal. |

### gwy_field_fill()

    void
    gwy_field_fill (GwyField *field,
                    gdouble value);

Fills a data field with given value.

#### Parameters

field | A data field. |
value | Value to be entered. |

### gwy_field_clear()

    void
    gwy_field_clear (GwyField *field);

Fills a data field with zeros.

#### Parameters

field | A data field. |

### gwy_field_multiply()

    void
    gwy_field_multiply (GwyField *field,
                        gdouble value);

Multiplies all values in a data field by given value.

#### Parameters

field | A data field. |
value | Value to multiply `field` with. |

### gwy_field_add()

    void
    gwy_field_add (GwyField *field,
                   gdouble value);

Adds given value to all values in a data field.

#### Parameters

field | A data field. |
value | Value to be added to data field values. |

### gwy_field_abs()

    void
    gwy_field_abs (GwyField *field);

Takes absolute value of all values in a data field.

#### Parameters

field | A data field. |

### gwy_field_area_fill()

    void
    gwy_field_area_fill (GwyField *field,
                         GwyNield *mask,
                         GwyMaskingType mode,
                         gint col,
                         gint row,
                         gint width,
                         gint height,
                         gdouble value);

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

See also `gwy_field_area_fill_mask()` for filling the entire rectangle, but with different values depending on the mask.

#### Parameters

field | A data 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 set all affected pixels to. |

### gwy_field_fill_mask()

    void
    gwy_field_fill_mask (GwyField *field,
                         GwyNield *mask,
                         gdouble unmasked,
                         gdouble masked);

Fills a data field with two values depending on a mask.

See `gwy_field_area_fill_mask()` for description. This function simply sets the values in entire `field` .

#### Parameters

field | A data field. |
mask | Mask specifying which values to fill with which value. | [nullable]
unmasked | Value to set all unmasked pixels to. |
masked | Value to set all masked pixels to. |

### gwy_field_area_fill_mask()

    void
    gwy_field_area_fill_mask (GwyField *field,
                              GwyNield *mask,
                              gint col,
                              gint row,
                              gint width,
                              gint height,
                              gdouble unmasked,
                              gdouble masked);

Fills a rectangular part of a data field with two values depending on a mask.

Unlike `gwy_field_area_fill()`, this function sets all values in the rectangle. But whether to `masked` or `unmasked` , that depends on `mask` . It is equivalent to calling `gwy_field_area_fill()` twice, once in `GWY_MASK_INCLUDE` mode and `masked` fill value and once in `GWY_MASK_EXCLUDE` mode and `unmasked` fill value.

The function has no masking mode because it always applies both. It is possible to pass a `NULL` mask; the entire rectangle is then filled with `masked` .

#### Parameters

field | A data field. |
mask | Mask specifying which values to fill with which value. | [nullable]
col | Upper-left column coordinate. |
row | Upper-left row coordinate. |
width | Area width (number of columns). |
height | Area height (number of rows). |
unmasked | Value to set all unmasked pixels to. |
masked | Value to set all masked pixels to. |

### gwy_field_area_clear()

    void
    gwy_field_area_clear (GwyField *field,
                          gint col,
                          gint row,
                          gint width,
                          gint height);

Fills a rectangular part of a data field with zeros.

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

#### Parameters

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

### gwy_field_area_multiply()

    void
    gwy_field_area_multiply (GwyField *field,
                             gint col,
                             gint row,
                             gint width,
                             gint height,
                             gdouble value);

Multiplies values in a rectangular part of a data field by given value

#### Parameters

field | A data field. |
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 multiply area with. |

### gwy_field_area_add()

    void
    gwy_field_area_add (GwyField *field,
                        gint col,
                        gint row,
                        gint width,
                        gint height,
                        gdouble value);

Adds given value to all values in a rectangular part of a data field.

#### Parameters

field | A data field. |
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 added to area values. |

### gwy_field_area_abs()

    void
    gwy_field_area_abs (GwyField *field,
                        gint col,
                        gint row,
                        gint width,
                        gint height);

Takes absolute value of values in a rectangular part of a data field.

#### Parameters

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

### gwy_field_profile()

    GwyLine *
    gwy_field_profile (GwyField *field,
                       GwyLine *line,
                       gint col1,
                       gint row1,
                       gint col2,
                       gint row2,
                       gint res,
                       gint thickness,
                       GwyInterpolationType interpolation);

Extracts a possibly averaged profile from data field to a data line.

#### Parameters

field | A data field. |
line | A data line. It will be resized to `res` samples. It is possible to pass `NULL` to instantiate and return a new GwyLine. | [nullable]
col1 | The column the line starts at (inclusive). |
row1 | The row the line starts at (inclusive). |
col2 | The column the line ends at (inclusive). |
row2 | The row the line ends at (inclusive). |
res | Requested resolution of data line (the number of samples to take). If nonpositive, data line resolution is chosen to match `field` 's. |
thickness | Thickness of line to be averaged. |
interpolation | Interpolation type to use. |

#### Returns

`line` itself if it was not `NULL`, otherwise a newly created data line.

[transfer full]

### gwy_field_profile_mask()

    GwyXY *
    gwy_field_profile_mask (GwyField *field,
                            GwyNield *mask,
                            GwyMaskingType masking,
                            gdouble xfrom,
                            gdouble yfrom,
                            gdouble xto,
                            gdouble yto,
                            gint res,
                            gint thickness,
                            GwyInterpolationType interpolation,
                            gint *ndata);

Extracts a possibly averaged profile from data field, with masking.

The extracted profile can contain holes due to masking. It can also contain no points at all if the all data values along the profile were excluded due to masking – in this case `NULL` is returned.

Unlike `gwy_field_profile()`, this function takes real coordinates (without offsets), not row and column indices.

#### Parameters

field | A data field. |
mask | Mask specifying which values to take into account/exclude, or `NULL`. | [nullable]
masking | Masking mode to use. |
xfrom | The real `x` -coordinate where the line starts. |
yfrom | The real `y` -coordinate where line starts. |
xto | The real `x` -coordinate where the line ends. |
yto | The real `y` -coordinate where line ends. |
res | Requested resolution, i.e. the number of samples to take. If nonpositive, sampling is chosen to match `field` 's. |
thickness | Thickness of line to be averaged. |
interpolation | Interpolation type to use. |
ndata | Location where to store the actual number of extracted points, which may differ from `res` . You must not pass `NULL` and remain ignorant of the returned array size. | [out]

#### Returns

A newly allocated array of GwyXY coordinare pairs, or `NULL`. The caller must free the returned array with `g_free()`.

[transfer full]

### gwy_field_row_profile()

    GwyXY *
    gwy_field_row_profile (GwyField *field,
                           GwyNield *mask,
                           GwyMaskingType masking,
                           gint row,
                           gint thickness,
                           gint *npoints);

Extracts a profile from averaged rows from data field, with masking.

If masking is used, the returned array can have fewer points than the field resolution (including no points at all). You need to use `npoints` to obtain its actual size.

#### Parameters

field | A data field. |
mask | Mask specifying which values to fill with which value. | [nullable]
masking | Masking mode to use. |
row | Row index. |
thickness | Thickness of line to be averaged. |
npoints | Location for the number of points in the returned array. | [out]

#### Returns

Newly allocated array with the extracted data.

[transfer full][array size=npoints]

### gwy_field_column_profile()

    GwyXY *
    gwy_field_column_profile (GwyField *field,
                              GwyNield *mask,
                              GwyMaskingType masking,
                              gint col,
                              gint thickness,
                              gint *npoints);

Extracts a profile from averaged columns from data field, with masking.

If masking is used, the returned array can have fewer points than the field resolution (including no points at all). You need to use `npoints` to obtain its actual size.

#### Parameters

field | A data field. |
mask | Mask specifying which values to fill with which value. | [nullable]
masking | Masking mode to use. |
col | Column index. |
thickness | Thickness of line to be averaged. |
npoints | Location for the number of points in the returned array. | [out]

#### Returns

Newly allocated array with the extracted data.

[transfer full][array size=npoints]

### gwy_field_get_row()

    void
    gwy_field_get_row (GwyField *field,
                       GwyLine *line,
                       gint row);

Extracts a data field row into a data line.

#### Parameters

field | A data field. |
line | A data line. It will be resized to width ot `field` . |
row | Row index. |

### gwy_field_get_column()

    void
    gwy_field_get_column (GwyField *field,
                          GwyLine *line,
                          gint col);

Extracts a data field column into a data line.

#### Parameters

field | A data field |
line | A data line. It will be resized to height of `field` . |
col | Column index. |

### gwy_field_set_row()

    void
    gwy_field_set_row (GwyField *field,
                       GwyLine *line,
                       gint row);

Sets a row in the data field to values of a data line.

Data line length must be equal to width of data field.

#### Parameters

field | A data field. |
line | A data line. |
row | Row index. |

### gwy_field_set_column()

    void
    gwy_field_set_column (GwyField *field,
                          GwyLine *line,
                          gint col);

Sets a column in the data field to values of a data line.

Data line length must be equal to height of data field.

#### Parameters

field | A data field. |
line | A data line. |
col | Column index. |

### gwy_field_get_row_part()

    void
    gwy_field_get_row_part (GwyField *field,
                            GwyLine *line,
                            gint row,
                            gint from,
                            gint to);

Extracts part of a data field row into a data line.

#### Parameters

field | A data field. |
line | A data line. It will be resized to the row part width. |
row | Row index. |
from | Start column index. |
to | End column index + 1. |

### gwy_field_get_column_part()

    void
    gwy_field_get_column_part (GwyField *field,
                               GwyLine *line,
                               gint col,
                               gint from,
                               gint to);

Extracts part of a data field column into a data line.

#### Parameters

field | A data field. |
line | A data line. It will be resized to the column part height. |
col | Column index. |
from | Start row index. |
to | End row index + 1. |

### gwy_field_set_row_part()

    void
    gwy_field_set_row_part (GwyField *field,
                            GwyLine *line,
                            gint row,
                            gint from,
                            gint to);

Puts a data line into a data field row.

If data line length differs from `to` -`from` , it is resampled to this length.

#### Parameters

field | A data field. |
line | A data line. |
row | Row index. |
from | Start row index. |
to | End row index + 1. |

### gwy_field_set_column_part()

    void
    gwy_field_set_column_part (GwyField *field,
                               GwyLine *line,
                               gint col,
                               gint from,
                               gint to);

Puts a data line into data field column.

If data line length differs from `to` -`from` , it is resampled to this length.

#### Parameters

field | A data field. |
line | A data line. |
col | Column index. |
from | Start row index. |
to | End row index + 1. |

### gwy_field_xder()

    gdouble
    gwy_field_xder (GwyField *field,
                    gint col,
                    gint row);

Computes central derivative in X direction.

On border points, one-side derivative is returned.

#### Parameters

field | A data field. |
col | Column index. |
row | Row index. |

#### Returns

Derivative in X direction.

### gwy_field_yder()

    gdouble
    gwy_field_yder (GwyField *field,
                    gint col,
                    gint row);

Computes central derivative in Y direction.

On border points, one-side derivative is returned.

Note the derivative is for legacy reasons calulcated for the opposite y direction than is usual elsewhere in Gwyddion, i.e. if values increase with increasing row number, the returned value is negative.

#### Parameters

field | A data field. |
col | Column index. |
row | Row index. |

#### Returns

Derivative in Y direction

### gwy_field_angder()

    gdouble
    gwy_field_angder (GwyField *field,
                      gint col,
                      gint row,
                      gdouble theta);

Computes derivative in direction specified by given angle.

#### Parameters

field | A data field. |
col | Column index. |
row | Row index. |
theta | Angle defining the direction (in radians, counterclockwise). |

#### Returns

Derivative in direction given by angle `theta` .

### gwy_field_average_xyz()

    void
    gwy_field_average_xyz (GwyField *field,
                           GwyField *density_map,
                           const GwyXYZ *points,
                           gsize npoints);

Fills a data field with regularised XYZ data using a simple method.

See `gwy_field_average_xy_z()` for discussion.

#### Parameters

field | A data field to fill with regularised XYZ data. |
density_map | Optional data field to fill with XYZ point density map. It can be `NULL`. | [nullable]
points | Array of XYZ points. Coordinates X and Y represent positions in the plane; the Z-coordinate represents values. |
npoints | Number of points. |

### gwy_field_average_xy_z()

    void
    gwy_field_average_xy_z (GwyField *field,
                            GwyField *density_map,
                            const GwyXY *coords,
                            const gdouble *values,
                            gsize npoints);

Fills a data field with regularised XY+Z data using a simple method.

The real dimensions and offsets of `field` determine the rectangle in the XY plane that will be regularised. The regularisation method is fast but simple and there are no absolute guarantees of quality, even though the result will be usually quite acceptable.

This especially applies to reasonable views of the XYZ data. Unreasonable views can be rendered unreasonably. In particular if the rectangle does not contain any point from `points` (either due to high zoom to an empty region or by just being completely off) `field` will be filled entirely with the value of the closest point or something similar.

#### Parameters

field | A data field to fill with regularised XYZ data. |
density_map | Optional data field to fill with XYZ point density map. It can be `NULL`. | [nullable]
coords | Array of `npoints` XY coordinates which represent positions in the plane. |
values | Array of `npoints` values in each point. Pass `NULL` to give each point the constant value of 1, useful when you are only interested in the density map. | [nullable]
npoints | Number of points. |

## Types and Values

### struct GwyField

    struct GwyField;

### struct GwyFieldClass

    struct GwyFieldClass {
        GObjectClass parent_class;

        void (*data_changed)(GwyField *field);
    };

## Signal Details

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

    void
    user_function (GwyField *gwyfield,
                   gpointer  user_data)

The ::data-changed signal is never emitted by the object itself. It is intended as a means to notify object users they should update themselves, usually when a computation modifying the data is finished.

#### Parameters

gwyfield | The GwyField which received the signal. |
user_data | user data set when the signal handler was connected. |

Flags: Run First