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

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

© David Nečas and Petr Klapetek

Home Download News Features Screenshots Documentation Communicate Participate Resources Publications Applications Site Map

Valid XHTML 1.0 Valid CSS