Gwyddion – Free SPM (AFM, SNOM/NSOM, STM, MFM, …) data analysis software

GwyLawn (HEAD)

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