GwyLawn: Gwyddion Data Processing Library Reference Manual

## GwyLawn GwyLawn — Three-dimensional data representation |

## Functions

gdouble | (*GwyCurveReduceFunction) ()
#define | gwy_lawn_duplicate()
#define | gwy_lawn_assign()
GwyLawn * | gwy_lawn_new ()
GwyLawn * | gwy_lawn_new_alike ()
GwyLawn * | gwy_lawn_new_part ()
void | gwy_lawn_data_changed ()
void | gwy_lawn_copy ()
gint | gwy_lawn_get_xres ()
gint | gwy_lawn_get_yres ()
gdouble | gwy_lawn_get_xreal ()
gdouble | gwy_lawn_get_yreal ()
gdouble | gwy_lawn_get_xoffset ()
gdouble | gwy_lawn_get_yoffset ()
gint | gwy_lawn_get_n_curves ()
void | gwy_lawn_set_xreal ()
void | gwy_lawn_set_yreal ()
void | gwy_lawn_set_xoffset ()
void | gwy_lawn_set_yoffset ()
gdouble | gwy_lawn_get_dx ()
gdouble | gwy_lawn_get_dy ()
GwySIUnit * | gwy_lawn_get_si_unit_xy ()
GwySIUnit * | gwy_lawn_get_si_unit_curve ()
void | gwy_lawn_set_si_unit_xy ()
void | gwy_lawn_set_si_unit_curve ()
void | gwy_lawn_copy_units ()
void | gwy_lawn_set_curve_label ()
const gchar * | gwy_lawn_get_curve_label ()
GwySIValueFormat * | gwy_lawn_get_value_format_xy ()
GwySIValueFormat * | gwy_lawn_get_value_format_curve ()
gint | gwy_lawn_get_curve_length ()
gdouble * | gwy_lawn_get_curve_data ()
const gdouble * | gwy_lawn_get_curve_data_const ()
void | gwy_lawn_set_curve_data ()
const gdouble * | gwy_lawn_get_curves_data_const ()
void | gwy_lawn_set_curves ()
gint | gwy_lawn_get_n_segments ()
const gint * | gwy_lawn_get_segments ()
void | gwy_lawn_set_segments ()
const gchar * | gwy_lawn_get_segment_label ()
void | gwy_lawn_set_segment_label ()
void | gwy_lawn_curve_set_segments ()
void | gwy_lawn_clear ()
void | gwy_lawn_area_reduce_to_plane ()
void | gwy_lawn_reduce_to_plane ()
GwyLawn * | gwy_lawn_new_rotated_90 ()
void | gwy_lawn_invert ()

## Signals

void | data-changed | Run First

## Types and Values

struct | GwyLawn
struct | GwyLawnClass

## Object Hierarchy

        GObject
        ╰── GwyLawn

## Implemented Interfaces

GwyLawn implements GwySerializable.

## Includes

    #include <libprocess/gwyprocess.h>

## Description

GwyLawn represents 3D data arrays in Gwyddion. It is typically useful for different volume data obtained from SPMs, like in force volume measurements.

## Functions

### GwyCurveReduceFunction ()

    gdouble
    (*GwyCurveReduceFunction) (gint ncurves,
                               gint curvelength,
                               const gdouble *curvedata,
                               gpointer userdata);

### gwy_lawn_duplicate()

    #define             gwy_lawn_duplicate(lawn)

Convenience macro doing `gwy_serializable_duplicate()` with all the necessary typecasting.

#### Parameters

lawn | A data lawn to duplicate. |

Since: 2.60

### gwy_lawn_assign()

    #define             gwy_lawn_assign(dest, source)

Convenience macro making one data lawn identical to another.

This is just a `gwy_serializable_clone()` wrapper with all the necessary typecasting.

#### Parameters

dest | Target data lawn. |
source | Source data lawn. |

Since: 2.60

### gwy_lawn_new ()

    GwyLawn *
    gwy_lawn_new (gint xres,
                  gint yres,
                  gdouble xreal,
                  gdouble yreal,
                  gint ncurves,
                  gint nsegments);

Creates a new data lawn.

#### Parameters

xres | X resolution, i.e., the number of samples in x direction |
yres | Y resolution, i.e., the number of samples in y direction |
xreal | Real physical dimension in x direction. |
yreal | Real physical dimension in y direction. |
ncurves | The number of curves at each sample. |
nsegments | The number of curve segments. |

#### Returns

A newly created data lawn.

Since: 2.60

### gwy_lawn_new_alike ()

    GwyLawn *
    gwy_lawn_new_alike (GwyLawn *model);

Creates a new data lawn similar to an existing one.

Use `gwy_lawn_duplicate()` if you want to copy a data lawn including data.

#### Parameters

model | A data lawn to take resolutions, units, and labels from. |

#### Returns

A newly created data lawn.

Since: 2.60

### gwy_lawn_new_part ()

    GwyLawn *
    gwy_lawn_new_part (GwyLawn *lawn,
                       gint xpos,
                       gint ypos,
                       gint xres,
                       gint yres,
                       gboolean keep_offsets);

Creates a new data lawn as a part of existing one.

Use `gwy_lawn_duplicate()` if you want to copy a whole data lawn.

#### Parameters

lawn | A data lawn to take data from |
xpos | x position where to start from |
ypos | y position where to start from |
xres | x resolution (width) to be extracted |
yres | y resolution (height) to be extracted |
keep_offsets | keep offsets of data during extraction |

#### Returns

A newly created data lawn.

Since: 2.60

### gwy_lawn_data_changed ()

    void
    gwy_lawn_data_changed (GwyLawn *lawn);

Emits signal "data_changed" on a data lawn.

#### Parameters

lawn | A data lawn. |

Since: 2.60

### gwy_lawn_copy ()

    void
    gwy_lawn_copy (GwyLawn *src,
                   GwyLawn *dest,
                   gboolean nondata_too);

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

#### Parameters

src | Source lawn. |
dest | Destination lawn. |
nondata_too | Whether non-data (units, labels, segment information) should be copied too. |

### gwy_lawn_get_xres ()

    gint
    gwy_lawn_get_xres (GwyLawn *lawn);

Gets the x resolution of a data lawn.

#### Parameters

lawn | A data lawn. |

#### Returns

Resolution (number of data points).

Since: 2.60

### gwy_lawn_get_yres ()

    gint
    gwy_lawn_get_yres (GwyLawn *lawn);

Gets the y resolution of a data lawn.

#### Parameters

lawn | A data lawn. |

#### Returns

Resolution (number of data points).

Since: 2.60

### gwy_lawn_get_xreal ()

    gdouble
    gwy_lawn_get_xreal (GwyLawn *lawn);

Gets the physical size of a data lawn in the x direction.

#### Parameters

lawn | A data lawn. |

#### Returns

Real size of a data lawn the x direction.

Since: 2.60

### gwy_lawn_get_yreal ()

    gdouble
    gwy_lawn_get_yreal (GwyLawn *lawn);

Gets the physical size of a data lawn in the y direction.

#### Parameters

lawn | A data lawn. |

#### Returns

Real size of a data lawn the y direction.

Since: 2.60

### gwy_lawn_get_xoffset ()

    gdouble
    gwy_lawn_get_xoffset (GwyLawn *lawn);

Gets the offset of data lawn origin in x direction.

#### Parameters

lawn | A data lawn. |

#### Returns

Offset value.

Since: 2.60

### gwy_lawn_get_yoffset ()

    gdouble
    gwy_lawn_get_yoffset (GwyLawn *lawn);

Gets the offset of data lawn origin in y direction.

#### Parameters

lawn | A data lawn. |

#### Returns

Offset value.

Since: 2.60

### gwy_lawn_get_n_curves ()

    gint
    gwy_lawn_get_n_curves (GwyLawn *lawn);

Gets the number of curves at each sample.

#### Parameters

lawn | A data lawn. |

#### Returns

Number of curves.

Since: 2.60

### gwy_lawn_set_xreal ()

    void
    gwy_lawn_set_xreal (GwyLawn *lawn,
                        gdouble xreal);

Sets the real x dimension of a lawn.

#### Parameters

lawn | A data lawn. |
xreal | New real x dimensions value |

Since: 2.60

### gwy_lawn_set_yreal ()

    void
    gwy_lawn_set_yreal (GwyLawn *lawn,
                        gdouble yreal);

Sets the real y dimension of a lawn.

#### Parameters

lawn | A data lawn. |
yreal | New real y dimensions value |

Since: 2.60

### gwy_lawn_set_xoffset ()

    void
    gwy_lawn_set_xoffset (GwyLawn *lawn,
                          gdouble xoffset);

Sets the offset of a data lawn origin in the x direction.

Note offsets don't affect any calculation.

#### Parameters

lawn | A data lawn. |
xoffset | New offset value. |

Since: 2.60

### gwy_lawn_set_yoffset ()

    void
    gwy_lawn_set_yoffset (GwyLawn *lawn,
                          gdouble yoffset);

Sets the offset of a data lawn origin in the y direction.

Note offsets don't affect any calculation.

#### Parameters

lawn | A data lawn. |
yoffset | New offset value. |

Since: 2.60

### gwy_lawn_get_dx ()

    gdouble
    gwy_lawn_get_dx (GwyLawn *lawn);

Gets the horizontal (X) pixel size of a lawn in real units.

The result is the same as gwy_lawn_get_xreal(lawn)/gwy_lawn_get_xres(lawn).

#### Parameters

lawn | A data lawn. |

#### Returns

Horizontal pixel size.

Since: 2.60

### gwy_lawn_get_dy ()

    gdouble
    gwy_lawn_get_dy (GwyLawn *lawn);

Gets the vertical (Y) pixel size of a lawn in real units.

The result is the same as gwy_lawn_get_yreal(lawn)/gwy_lawn_get_yres(lawn).

#### Parameters

lawn | A data lawn. |

#### Returns

Vertical pixel size.

Since: 2.60

### gwy_lawn_get_si_unit_xy ()

    GwySIUnit *
    gwy_lawn_get_si_unit_xy (GwyLawn *lawn);

Returns x- and y-direction SI unit of a data lawn.

#### Parameters

lawn | A data lawn. |

#### Returns

SI unit corresponding to the lateral (X) dimension of the data lawn. Its reference count is not incremented.

Since: 2.60

### gwy_lawn_get_si_unit_curve ()

    GwySIUnit *
    gwy_lawn_get_si_unit_curve (GwyLawn *lawn,
                                gint n);

Returns value SI unit of the n-th curve of a data lawn.

#### Parameters

lawn | A data lawn. |
n | Index of a curve in `lawn` . |

#### Returns

SI unit corresponding to the "value" of the data lawn. Its reference count is not incremented.

Since: 2.60

### gwy_lawn_set_si_unit_xy ()

    void
    gwy_lawn_set_si_unit_xy (GwyLawn *lawn,
                             GwySIUnit *si_unit);

Sets the SI unit corresponding to the lateral (X, Y) dimensions of a data lawn.

It does not assume a reference on `si_unit` , instead it adds its own reference.

#### Parameters

lawn | A data lawn. |
si_unit | SI unit to be set. |

Since: 2.60

### gwy_lawn_set_si_unit_curve ()

    void
    gwy_lawn_set_si_unit_curve (GwyLawn *lawn,
                                gint n,
                                GwySIUnit *si_unit);

Sets the SI unit corresponding of the n-th curve of a data lawn.

It does not assume a reference on `si_unit` , instead it adds its own reference.

#### Parameters

lawn | A data lawn. |
n | Index of a curve in `lawn` . |
si_unit | SI unit to be set. |

Since: 2.60

### gwy_lawn_copy_units ()

    void
    gwy_lawn_copy_units (GwyLawn *lawn,
                         GwyLawn *target);

Sets lateral and curve units of a data lawn to match another data lawn.

#### Parameters

lawn | A data lawn. |
target | Target data lawn. |

Since: 2.60

### gwy_lawn_set_curve_label ()

    void
    gwy_lawn_set_curve_label (GwyLawn *lawn,
                              gint n,
                              const gchar *label);

Sets the label of a curve in data lawn.

#### Parameters

lawn | A data lawn. |
n | Index of a curve in `lawn` . |
label | New curve label. |

Since: 2.60

### gwy_lawn_get_curve_label ()

    const gchar *
    gwy_lawn_get_curve_label (GwyLawn *lawn,
                              gint n);

Gets the label of a curve in data lawn.

#### Parameters

lawn | A data lawn. |
n | Index of a curve in `lawn` . |

#### Returns

Curve label, as a string owned by `lawn` . It may be `NULL`.

Since: 2.60

### gwy_lawn_get_value_format_xy ()

    GwySIValueFormat *
    gwy_lawn_get_value_format_xy (GwyLawn *lawn,
                                  GwySIUnitFormatStyle style,
                                  GwySIValueFormat *format);

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

#### Parameters

lawn | A data lawn. |
style | Unit format style. |
format | A SI value format to modify, or `NULL` to allocate a new one. |

#### Returns

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

Since: 2.60

### gwy_lawn_get_value_format_curve ()

    GwySIValueFormat *
    gwy_lawn_get_value_format_curve (GwyLawn *lawn,
                                     gint n,
                                     GwySIUnitFormatStyle style,
                                     GwySIValueFormat *format);

### gwy_lawn_get_curve_length ()

    gint
    gwy_lawn_get_curve_length (GwyLawn *lawn,
                               gint col,
                               gint row);

Gets the length of the curves at given position in a data lawn.

#### Parameters

lawn | A data lawn. |
col | Position in the lawn (column index). |
row | Position in the lawn (row index). |

#### Returns

The curves length at given index.

Since: 2.60

### gwy_lawn_get_curve_data ()

    gdouble *
    gwy_lawn_get_curve_data (GwyLawn *lawn,
                             gint col,
                             gint row,
                             gint n,
                             gint *curvelength);

Gets the data array of the n-th curve at given position in a data lawn.

The returned buffer is not guaranteed to be valid through whole data lawn life time.

#### Parameters

lawn | A data lawn. |
col | Position in the lawn (column index). |
row | Position in the lawn (row index). |
n | Index of a curve in `lawn` . |
curvelength | Location to store the length of the curve, or `NULL`. |

#### Returns

The n-th curve data at given index.

Since: 2.60

### gwy_lawn_get_curve_data_const ()

    const gdouble *
    gwy_lawn_get_curve_data_const (GwyLawn *lawn,
                                   gint col,
                                   gint row,
                                   gint n,
                                   gint *curvelength);

Gets the data array of the n-th curve at given position in a data lawn.

#### Parameters

lawn | A data lawn. |
col | Position in the lawn (column index). |
row | Position in the lawn (row index). |
n | Index of a curve in `lawn` . |
curvelength | To store the length of the curve (optional). |

#### Returns

The `n` -th curve data at given index. The returned data are owned by `lawn` and must not be modified nor freed.

Since: 2.60

### gwy_lawn_set_curve_data ()

    void
    gwy_lawn_set_curve_data (GwyLawn *lawn,
                             gint col,
                             gint row,
                             gint n,
                             const gdouble *curvedata);

Sets the data of a single curve in a data lawn.

The number of points remains the same since all curves at give pixel must have the same number of points. If you want to change the number of points set the data of all curves together using `gwy_lawn_set_curves()`.

#### Parameters

lawn | A data lawn. |
col | Position in the lawn (column index). |
row | Position in the lawn (row index). |
n | Index of a curve in `lawn` . |
curvedata | New data of the `n` -th curve. |

Since: 2.60

### gwy_lawn_get_curves_data_const ()

    const gdouble *
    gwy_lawn_get_curves_data_const (GwyLawn *lawn,
                                    gint col,
                                    gint row,
                                    gint *curvelength);

Gets the data array of all curves at given position in a data lawn.

#### Parameters

lawn | A data lawn. |
col | Position in the lawn (column index). |
row | Position in the lawn (row index). |
curvelength | To store the length of the curves (optional). |

#### Returns

The curves data at given index.

Since: 2.60

### gwy_lawn_set_curves ()

    void
    gwy_lawn_set_curves (GwyLawn *lawn,
                         gint col,
                         gint row,
                         gint curvelength,
                         const gdouble *curvesdata,
                         const gint *segments);

Sets data for all curves at given position in a data lawn.

Note that passing `NULL` `segments` can result in segmentation which is not valid for `curvelength` . In such case you need to correct the segmentation afterwards.

#### Parameters

lawn | A data lawn. |
col | Position in the lawn (column index). |
row | Position in the lawn (row index). |
curvelength | Length of each of the curves. |
curvesdata | Curve data array. |
segments | Segmentation for the curve. May be `NULL` to leave the current segmentation unchanged. |

Since: 2.60

### gwy_lawn_get_n_segments ()

    gint
    gwy_lawn_get_n_segments (GwyLawn *lawn);

Gets the number of segments marked in curves in a data lawn.

All curves have the same number of segments, even empty curves. Empty curves simply have the corresponding number of trivial zero-length segments.

#### Parameters

lawn | A data lawn. |

#### Returns

The number of segments. Zero is returned if no segments are marked.

Since: 2.60

### gwy_lawn_get_segments ()

    const gint *
    gwy_lawn_get_segments (GwyLawn *lawn,
                           gint col,
                           gint row,
                           gint *nsegments);

Gets the segmentation of a curve in a data lawn.

#### Parameters

lawn | A data lawn. |
col | Position in the lawn (column index). |
row | Position in the lawn (row index). |
nsegments | Location where to store the number of segments, or `NULL`. |

#### Returns

The segmentation for the curve, as an array owned by `lawn` which must not be modified nor freed.

See `gwy_lawn_set_segments()` for the array format.

Since: 2.60

### gwy_lawn_set_segments ()

    void
    gwy_lawn_set_segments (GwyLawn *lawn,
                           gint nsegments,
                           const gint *segments);

Sets the segmentation of all curves in a data lawn.

This is the only function which allows changing the number of segments. If the number of segments changes all the labels are reset.

See `gwy_lawn_curve_set_segments()` for the single-curve `segments` array format. When setting the data for an entire `lawn` the array must contain this data for all pixels, concatenated.

#### Parameters

lawn | A data lawn. |
nsegments | New number of segments. |
segments | The new segmentation for entire `lawn` . |

Since: 2.60

### gwy_lawn_get_segment_label ()

    const gchar *
    gwy_lawn_get_segment_label (GwyLawn *lawn,
                                gint segment);

Gets the label of a curve segment in data lawn.

#### Parameters

lawn | A data lawn. |
segment | Index of a curve segment in `lawn` . |

#### Returns

Segment label, as a string owned by `lawn` . It may be `NULL`.

Since: 2.60

### gwy_lawn_set_segment_label ()

    void
    gwy_lawn_set_segment_label (GwyLawn *lawn,
                                gint segment,
                                const gchar *label);

Sets the label of a curve segment in data lawn.

Since all curves in `lawn` are segmented into the same segments the segments share labels. The first segment label corresponds to the first segment in all the curves.

#### Parameters

lawn | A data lawn. |
segment | Index of a curve segment in `lawn` . |
label | New segment label. |

Since: 2.60

### gwy_lawn_curve_set_segments ()

    void
    gwy_lawn_curve_set_segments (GwyLawn *lawn,
                                 gint col,
                                 gint row,
                                 const gint *segments);

Sets the segmentation of a curve in data lawn.

All curves have the same number of segments, equal to the value returned by `gwy_lawn_get_n_segments()`.

The array `segments` contains twice as much elements as there are segments. They are organised [`start₀` , `end₀` , `start₁` , `end₁` , etc.]. A segment starts at the postion `start` and has length `end` -`start` . In other words, `start` is inclusive, but `end` is exclusive. If a segment is zero-length even `start` can correspond to non-existent data (the typical case is an empty curve).

#### Parameters

lawn | A data lawn. |
col | Position in the lawn (column index). |
row | Position in the lawn (row index). |
segments | The new segmentation for the curve. |

Since: 2.60

### gwy_lawn_clear ()

    void
    gwy_lawn_clear (GwyLawn *lawn);

Removes curve data at all samples (curve number, units, and labels preserved).

#### Parameters

lawn | A data lawn. |

Since: 2.60

### gwy_lawn_area_reduce_to_plane ()

    void
    gwy_lawn_area_reduce_to_plane (GwyLawn *lawn,
                                   GwyDataField *target,
                                   GwyCurveReduceFunction func,
                                   gpointer user_data,
                                   gint col,
                                   gint row,
                                   gint width,
                                   gint height,
                                   gboolean keep_offsets);

Reduces curves data at each point of a rectangular region to a value, storing the results in a data field.

#### Parameters

lawn | A data lawn. |
target | Datafield to be filled by summed plane. Its dimensions should be (width, height). |
func | Function to reduce the curves data array to a single value. |
user_data | Data passed to `func` . |
col | Column where to start (pixel coordinates). |
row | Row where to start (pixel coordinates). |
width | Pixel width of summed plane. |
height | Pixel height of summed plane. |
keep_offsets | Keep the physical offsets in extracted field. |

Since: 2.60

### gwy_lawn_reduce_to_plane ()

    void
    gwy_lawn_reduce_to_plane (GwyLawn *lawn,
                              GwyDataField *target,
                              GwyCurveReduceFunction func,
                              gpointer user_data);

Sums all z-profiles of a data lawn to a data field.

Reduces curves data at each point of the lawn to a value, storing the results in a data field.

#### Parameters

lawn | A data lawn. |
target | Datafield to be filled by the summary data. It should have the same dimensions as lawn. |
func | Function to reduce the curves data array to a single value. |
user_data | Data passed to `func` . |

Since: 2.60

### gwy_lawn_new_rotated_90 ()

    GwyLawn *
    gwy_lawn_new_rotated_90 (GwyLawn *lawn,
                             gboolean clockwise);

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

#### Parameters

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

#### Returns

A newly created data lawn.

Since: 2.60

### gwy_lawn_invert ()

    void
    gwy_lawn_invert (GwyLawn *lawn,
                     gboolean xflipped,
                     gboolean yflipped);

Flips a data lawn 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 the axis parameter convention is different from the confusing one of `gwy_data_field_invert()`. Here parameters simply correspond to directions that should be flipped.

#### Parameters

lawn | A data lawn. |
xflipped | `TRUE` to reflect X, i.e. rows. |
yflipped | `TRUE` to reflect Y, i.e. columns. |

Since: 2.60

## Types and Values

### struct GwyLawn

    struct GwyLawn;

The GwyLawn struct contains private data only and should be accessed using the functions below.

Since: 2.60

### struct GwyLawnClass

    struct GwyLawnClass {
        GObjectClass parent_class;

        void (*data_changed)(GwyLawn *lawn);
    };

## Signal Details

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

    void
    user_function (GwyLawn *gwylawn,
                   gpointer user_data)

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

#### Parameters

gwylawn | The GwyLawn which received the signal. |
user_data | user data set when the signal handler was connected. |

Flags: Run First