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

GwyDataField (HEAD)

GwyDataField — Two-dimensional data representation

Functions

void gwy_data_field_invalidate ()
#define gwy_data_field_duplicate()
#define gwy_data_field_assign()
GwyDataField * gwy_data_field_new ()
GwyDataField * gwy_data_field_new_alike ()
void gwy_data_field_data_changed ()
GwyDataField * gwy_data_field_new_resampled ()
void gwy_data_field_resample ()
void gwy_data_field_bin ()
GwyDataField * gwy_data_field_new_binned ()
void gwy_data_field_resize ()
GwyDataField * gwy_data_field_area_extract ()
void gwy_data_field_copy ()
void gwy_data_field_area_copy ()
gdouble * gwy_data_field_get_data ()
const gdouble * gwy_data_field_get_data_const ()
gint gwy_data_field_get_xres ()
gint gwy_data_field_get_yres ()
gdouble gwy_data_field_get_xreal ()
gdouble gwy_data_field_get_yreal ()
void gwy_data_field_set_xreal ()
void gwy_data_field_set_yreal ()
gdouble gwy_data_field_get_dx ()
gdouble gwy_data_field_get_dy ()
gdouble gwy_data_field_get_xoffset ()
gdouble gwy_data_field_get_yoffset ()
void gwy_data_field_set_xoffset ()
void gwy_data_field_set_yoffset ()
GwySIUnit * gwy_data_field_get_si_unit_xy ()
GwySIUnit * gwy_data_field_get_si_unit_z ()
void gwy_data_field_set_si_unit_xy ()
void gwy_data_field_set_si_unit_z ()
GwySIValueFormat * gwy_data_field_get_value_format_xy ()
GwySIValueFormat * gwy_data_field_get_value_format_z ()
void gwy_data_field_copy_units ()
void gwy_data_field_copy_units_to_data_line ()
void gwy_data_line_copy_units_to_data_field ()
gdouble gwy_data_field_itor ()
gdouble gwy_data_field_jtor ()
gdouble gwy_data_field_rtoi ()
gdouble gwy_data_field_rtoj ()
gdouble gwy_data_field_get_val ()
void gwy_data_field_set_val ()
gdouble gwy_data_field_get_dval ()
gdouble gwy_data_field_get_dval_real ()
void gwy_data_field_rotate ()
GwyDataField * gwy_data_field_new_rotated ()
GwyDataField * gwy_data_field_new_rotated_90 ()
void gwy_data_field_invert ()
void gwy_data_field_flip_xy ()
void gwy_data_field_area_flip_xy ()
void gwy_data_field_fill ()
void gwy_data_field_clear ()
void gwy_data_field_multiply ()
void gwy_data_field_add ()
void gwy_data_field_abs ()
void gwy_data_field_area_fill ()
void gwy_data_field_area_fill_mask ()
void gwy_data_field_area_clear ()
void gwy_data_field_area_multiply ()
void gwy_data_field_area_add ()
void gwy_data_field_area_abs ()
GwyDataLine * gwy_data_field_get_profile ()
GwyXY * gwy_data_field_get_profile_mask ()
void gwy_data_field_get_row ()
void gwy_data_field_get_column ()
void gwy_data_field_set_row ()
void gwy_data_field_set_column ()
void gwy_data_field_get_row_part ()
void gwy_data_field_get_column_part ()
void gwy_data_field_set_row_part ()
void gwy_data_field_set_column_part ()
gdouble gwy_data_field_get_xder ()
gdouble gwy_data_field_get_yder ()
gdouble gwy_data_field_get_angder ()
void gwy_data_field_average_xyz ()

Signals

void data-changed Run First

Types and Values

#define gwy_data_field_get_xmeasure
#define gwy_data_field_get_ymeasure
struct GwyDataField
struct GwyDataFieldClass

Object Hierarchy

    GObject
    ╰── GwyDataField

Implemented Interfaces

GwyDataField implements GwySerializable.

Includes

#include <libprocess/gwyprocess.h>

Description

GwyDataField is an object that is used for representation of all two-dimensional data matrices. Most of the basic data handling and processing functions in Gwyddion are declared here as they are connected with GwyDataField.

Functions

gwy_data_field_invalidate ()

void
gwy_data_field_invalidate (GwyDataField *data_field);

Invalidates cached data field stats.

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

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

Parameters

data_field

A data field to invalidate.

 

gwy_data_field_duplicate()

#define             gwy_data_field_duplicate(data_field)

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

Use gwy_data_field_new_alike() if you don't want to copy data, only resolutions and units.

Parameters

data_field

A data field to duplicate.

 

gwy_data_field_assign()

#define             gwy_data_field_assign(dest, source)

Convenience macro making one data field identical to another.

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

Parameters

dest

Target data field.

 

source

Source data field.

 

Since: 2.52

gwy_data_field_new ()

GwyDataField *
gwy_data_field_new (gint xres,
                    gint yres,
                    gdouble xreal,
                    gdouble yreal,
                    gboolean nullme);

Creates a new data field.

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 zeroes. If FALSE, the data will not be initialized.

 

Returns

A newly created data field.

gwy_data_field_new_alike ()

GwyDataField *
gwy_data_field_new_alike (GwyDataField *model,
                          gboolean nullme);

Creates a new data field similar to an existing one.

Use gwy_data_field_duplicate() 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 zeroes. If FALSE, the data will not be initialized.

 

Returns

A newly created data field.

gwy_data_field_data_changed ()

void
gwy_data_field_data_changed (GwyDataField *data_field);

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

Parameters

data_field

A data field.

 

gwy_data_field_new_resampled ()

GwyDataField *
gwy_data_field_new_resampled (GwyDataField *data_field,
                              gint xres,
                              gint yres,
                              GwyInterpolationType interpolation);

Creates a new data field by resampling an existing one.

This method is equivalent to gwy_data_field_duplicate() followed by gwy_data_field_resample(), but it is more efficient.

Parameters

data_field

A data field.

 

xres

Desired X resolution.

 

yres

Desired Y resolution.

 

interpolation

Interpolation method to use.

 

Returns

A newly created data field.

gwy_data_field_resample ()

void
gwy_data_field_resample (GwyDataField *data_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_data_field_get_data().

Parameters

data_field

A data field to be resampled.

 

xres

Desired X resolution.

 

yres

Desired Y resolution.

 

interpolation

Interpolation method to use.

 

gwy_data_field_bin ()

void
gwy_data_field_bin (GwyDataField *data_field,
                    GwyDataField *target,
                    gint binw,
                    gint binh,
                    gint xoff,
                    gint yoff,
                    gint trimlowest,
                    gint trimhighest);

Bins a data field into another data field.

See gwy_data_field_new_binned() for a detailed description.

Parameters

data_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.

 

Since: 2.55

gwy_data_field_new_binned ()

GwyDataField *
gwy_data_field_new_binned (GwyDataField *data_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

data_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.

Since: 2.50

gwy_data_field_resize ()

void
gwy_data_field_resize (GwyDataField *data_field,
                       gint ulcol,
                       gint ulrow,
                       gint brcol,
                       gint brrow);

Resizes (crops) a data field.

Crops a data field to a rectangle between upper-left and bottom-right points, recomputing real size.

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

Parameters

data_field

A data field to be resized

 

ulcol

Upper-left column coordinate.

 

ulrow

Upper-left row coordinate.

 

brcol

Bottom-right column coordinate + 1.

 

brrow

Bottom-right row coordinate + 1.

 

gwy_data_field_area_extract ()

GwyDataField *
gwy_data_field_area_extract (GwyDataField *data_field,
                             gint col,
                             gint row,
                             gint width,
                             gint height);

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

Parameters

data_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.

gwy_data_field_copy ()

void
gwy_data_field_copy (GwyDataField *src,
                     GwyDataField *dest,
                     gboolean nondata_too);

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

Parameters

src

Source data field.

 

dest

Destination data field.

 

nondata_too

Whether non-data (units) should be copied too.

 

gwy_data_field_area_copy ()

void
gwy_data_field_area_copy (GwyDataField *src,
                          GwyDataField *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 equal to 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), pass -1 for full src widdth.

 

height

Area height (number of rows), pass -1 for full src height.

 

destcol

Destination column in dest .

 

destrow

Destination row in dest .

 

gwy_data_field_get_data ()

gdouble *
gwy_data_field_get_data (GwyDataField *data_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_data_field_resize() and gwy_data_field_resample().

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

See gwy_data_field_invalidate() for some discussion.

Parameters

data_field

A data field

 

Returns

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

gwy_data_field_get_data_const ()

const gdouble *
gwy_data_field_get_data_const (GwyDataField *data_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_data_field_resize() and gwy_data_field_resample().

Use gwy_data_field_get_data() if you want to change the data.

See gwy_data_field_invalidate() for some discussion.

Parameters

data_field

A data field.

 

Returns

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

gwy_data_field_get_xres ()

gint
gwy_data_field_get_xres (GwyDataField *data_field);

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

Parameters

data_field

A data field.

 

Returns

X resolution.

gwy_data_field_get_yres ()

gint
gwy_data_field_get_yres (GwyDataField *data_field);

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

Parameters

data_field

A data field.

 

Returns

Y resolution.

gwy_data_field_get_xreal ()

gdouble
gwy_data_field_get_xreal (GwyDataField *data_field);

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

Parameters

data_field

A data field.

 

Returns

X real size value.

gwy_data_field_get_yreal ()

gdouble
gwy_data_field_get_yreal (GwyDataField *data_field);

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

Parameters

data_field

A data field

 

Returns

Y real size value.

gwy_data_field_set_xreal ()

void
gwy_data_field_set_xreal (GwyDataField *data_field,
                          gdouble xreal);

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

Parameters

data_field

A data field.

 

xreal

New X real size value.

 

gwy_data_field_set_yreal ()

void
gwy_data_field_set_yreal (GwyDataField *data_field,
                          gdouble yreal);

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

Parameters

data_field

A data field.

 

yreal

New Y real size value.

 

gwy_data_field_get_dx ()

gdouble
gwy_data_field_get_dx (GwyDataField *data_field);

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

The result is the same as gwy_data_field_get_xreal(data_field)/gwy_data_field_get_xres(data_field).

Parameters

data_field

A data field.

 

Returns

Horizontal pixel size.

Since: 2.52

gwy_data_field_get_dy ()

gdouble
gwy_data_field_get_dy (GwyDataField *data_field);

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

The result is the same as gwy_data_field_get_yreal(data_field)/gwy_data_field_get_yres(data_field).

Parameters

data_field

A data field.

 

Returns

Vertical pixel size.

Since: 2.52

gwy_data_field_get_xoffset ()

gdouble
gwy_data_field_get_xoffset (GwyDataField *data_field);

Gets the X offset of data field origin.

Parameters

data_field

A data field.

 

Returns

X offset value.

gwy_data_field_get_yoffset ()

gdouble
gwy_data_field_get_yoffset (GwyDataField *data_field);

Gets the Y offset of data field origin.

Parameters

data_field

A data field

 

Returns

Y offset value.

gwy_data_field_set_xoffset ()

void
gwy_data_field_set_xoffset (GwyDataField *data_field,
                            gdouble xoff);

Sets the X offset of a data field origin.

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

Parameters

data_field

A data field.

 

xoff

New X offset value.

 

gwy_data_field_set_yoffset ()

void
gwy_data_field_set_yoffset (GwyDataField *data_field,
                            gdouble yoff);

Sets the Y offset of a data field origin.

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

Parameters

data_field

A data field.

 

yoff

New Y offset value.

 

gwy_data_field_get_si_unit_xy ()

GwySIUnit *
gwy_data_field_get_si_unit_xy (GwyDataField *data_field);

Returns lateral SI unit of a data field.

Parameters

data_field

A data field.

 

Returns

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

gwy_data_field_get_si_unit_z ()

GwySIUnit *
gwy_data_field_get_si_unit_z (GwyDataField *data_field);

Returns value SI unit of a data field.

Parameters

data_field

A data field.

 

Returns

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

gwy_data_field_set_si_unit_xy ()

void
gwy_data_field_set_si_unit_xy (GwyDataField *data_field,
                               GwySIUnit *si_unit);

Sets the SI unit corresponding to the lateral (XY) dimensions of a data field.

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

Parameters

data_field

A data field.

 

si_unit

SI unit to be set.

 

gwy_data_field_set_si_unit_z ()

void
gwy_data_field_set_si_unit_z (GwyDataField *data_field,
                              GwySIUnit *si_unit);

Sets the SI unit corresponding to the "height" (Z) dimension of a data field.

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

Parameters

data_field

A data field.

 

si_unit

SI unit to be set.

 

gwy_data_field_get_value_format_xy ()

GwySIValueFormat *
gwy_data_field_get_value_format_xy (GwyDataField *data_field,
                                    GwySIUnitFormatStyle style,
                                    GwySIValueFormat *format);

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

Parameters

data_field

A data field.

 

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.

gwy_data_field_get_value_format_z ()

GwySIValueFormat *
gwy_data_field_get_value_format_z (GwyDataField *data_field,
                                   GwySIUnitFormatStyle style,
                                   GwySIValueFormat *format);

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

Parameters

data_field

A data field.

 

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.

gwy_data_field_copy_units ()

void
gwy_data_field_copy_units (GwyDataField *data_field,
                           GwyDataField *target);

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

Parameters

data_field

A data field.

 

target

Target data field.

 

Since: 2.49

gwy_data_field_copy_units_to_data_line ()

void
gwy_data_field_copy_units_to_data_line
                               (GwyDataField *data_field,
                                GwyDataLine *data_line);

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

Parameters

data_field

A data field to get units from.

 

data_line

A data line to set units of.

 

gwy_data_line_copy_units_to_data_field ()

void
gwy_data_line_copy_units_to_data_field
                               (GwyDataLine *data_line,
                                GwyDataField *data_field);

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

Parameters

data_line

A data line to get units from.

 

data_field

A data field to set units of.

 

gwy_data_field_itor ()

gdouble
gwy_data_field_itor (GwyDataField *data_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_data_field_itor(data_field , row + 0.5) for that.

Parameters

data_field

A data field.

 

row

Vertical pixel coordinate.

 

Returns

Real Y coordinate.

gwy_data_field_jtor ()

gdouble
gwy_data_field_jtor (GwyDataField *data_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_data_field_jtor(data_field , col + 0.5) for that.

Parameters

data_field

A data field.

 

col

Horizontal pixel coordinate.

 

Returns

Real X coordinate.

gwy_data_field_rtoi ()

gdouble
gwy_data_field_rtoi (GwyDataField *data_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

data_field

A data field.

 

realy

Real (physical) Y coordinate.

 

Returns

Vertical pixel coodinate.

gwy_data_field_rtoj ()

gdouble
gwy_data_field_rtoj (GwyDataField *data_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

data_field

A data field.

 

realx

Real (physical) X coodinate.

 

Returns

Horizontal pixel coordinate.

gwy_data_field_get_val ()

gdouble
gwy_data_field_get_val (GwyDataField *data_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_data_field_get_data_const() and access it directly instead.

Parameters

data_field

A data field.

 

col

Column index.

 

row

Row index.

 

Returns

Value at (col , row ).

gwy_data_field_set_val ()

void
gwy_data_field_set_val (GwyDataField *data_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_data_field_get_data() and write to it directly instead.

Parameters

data_field

A data field.

 

col

Column index.

 

row

Row index.

 

value

Value to set.

 

gwy_data_field_get_dval ()

gdouble
gwy_data_field_get_dval (GwyDataField *data_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_data_field_get_val(data_field , j , i ) returns, it's necessary to add 0.5: gwy_data_field_get_dval(data_field , j +0.5, i +0.5, interpolation ).

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

Parameters

data_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_data_field_get_dval_real ()

gdouble
gwy_data_field_get_dval_real (GwyDataField *data_field,
                              gdouble x,
                              gdouble y,
                              GwyInterpolationType interpolation);

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

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

Parameters

data_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_data_field_rotate ()

void
gwy_data_field_rotate (GwyDataField *data_field,
                       gdouble angle,
                       GwyInterpolationType interpolation);

Rotates a data field by a given angle.

This function is mostly obsolete. See gwy_data_field_new_rotated() and gwy_data_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

data_field

A data field.

 

angle

Rotation angle (in radians).

 

interpolation

Interpolation method to use.

 

gwy_data_field_new_rotated ()

GwyDataField *
gwy_data_field_new_rotated (GwyDataField *dfield,
                            GwyDataField *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 dfield (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_data_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_data_field_new_rotated_90().

Parameters

dfield

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.

Since: 2.46

gwy_data_field_new_rotated_90 ()

GwyDataField *
gwy_data_field_new_rotated_90 (GwyDataField *data_field,
                               gboolean clockwise);

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

Parameters

data_field

A data field.

 

clockwise

TRUE to rotate clocwise, FALSE to rotate anti-clockwise.

 

Returns

A newly created data field.

Since: 2.46

gwy_data_field_invert ()

void
gwy_data_field_invert (GwyDataField *data_field,
                       gboolean yflipped,
                       gboolean xflipped,
                       gboolean zflipped);

Reflects and/or inverts a data field.

In the case of value (Z) reflection, it's inverted about the mean value.

Note the unusual axis argument order, with Y and X swapped. It is because historically the arguments were called X and Y, but had a somewhat idiosyncratic interpretation, doing the opposite of one might expect intuitively.

Parameters

data_field

A data field.

 

yflipped

TRUE to reflect Y, i.e. rows within the XY plane. The image will be flipped upside down.

 

xflipped

TRUE to reflect X, i.e. columns within the XY plane. The image will be left–right mirrored.

 

zflipped

TRUE to invert values.

 

gwy_data_field_flip_xy ()

void
gwy_data_field_flip_xy (GwyDataField *src,
                        GwyDataField *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.

 

Since: 2.49

gwy_data_field_area_flip_xy ()

void
gwy_data_field_area_flip_xy (GwyDataField *src,
                             gint col,
                             gint row,
                             gint width,
                             gint height,
                             GwyDataField *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.

 

Since: 2.49

gwy_data_field_fill ()

void
gwy_data_field_fill (GwyDataField *data_field,
                     gdouble value);

Fills a data field with given value.

Parameters

data_field

A data field.

 

value

Value to be entered.

 

gwy_data_field_clear ()

void
gwy_data_field_clear (GwyDataField *data_field);

Fills a data field with zeroes.

Parameters

data_field

A data field.

 

gwy_data_field_multiply ()

void
gwy_data_field_multiply (GwyDataField *data_field,
                         gdouble value);

Multiplies all values in a data field by given value.

Parameters

data_field

A data field.

 

value

Value to multiply data_field with.

 

gwy_data_field_add ()

void
gwy_data_field_add (GwyDataField *data_field,
                    gdouble value);

Adds given value to all values in a data field.

Parameters

data_field

A data field.

 

value

Value to be added to data field values.

 

gwy_data_field_abs ()

void
gwy_data_field_abs (GwyDataField *data_field);

Takes absolute value of all values in a data field.

Parameters

data_field

A data field.

 

Since: 2.52

gwy_data_field_area_fill ()

void
gwy_data_field_area_fill (GwyDataField *data_field,
                          gint col,
                          gint row,
                          gint width,
                          gint height,
                          gdouble value);

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

Parameters

data_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 entered

 

gwy_data_field_area_fill_mask ()

void
gwy_data_field_area_fill_mask (GwyDataField *data_field,
                               GwyDataField *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.

Parameters

data_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 be entered

 

Since: 2.44

gwy_data_field_area_clear ()

void
gwy_data_field_area_clear (GwyDataField *data_field,
                           gint col,
                           gint row,
                           gint width,
                           gint height);

Fills a rectangular part of a data field with zeroes.

Parameters

data_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_data_field_area_multiply ()

void
gwy_data_field_area_multiply (GwyDataField *data_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

data_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_data_field_area_add ()

void
gwy_data_field_area_add (GwyDataField *data_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

data_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_data_field_area_abs ()

void
gwy_data_field_area_abs (GwyDataField *data_field,
                         gint col,
                         gint row,
                         gint width,
                         gint height);

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

Parameters

data_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).

 

Since: 2.52

gwy_data_field_get_profile ()

GwyDataLine *
gwy_data_field_get_profile (GwyDataField *data_field,
                            GwyDataLine *data_line,
                            gint scol,
                            gint srow,
                            gint ecol,
                            gint erow,
                            gint res,
                            gint thickness,
                            GwyInterpolationType interpolation);

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

Parameters

data_field

A data field.

 

data_line

A data line. It will be resized to res samples. It is possible to pass NULL to instantiate and return a new GwyDataLine.

 

scol

The column the line starts at (inclusive).

 

srow

The row the line starts at (inclusive).

 

ecol

The column the line ends at (inclusive).

 

erow

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 data_field 's.

 

thickness

Thickness of line to be averaged.

 

interpolation

Interpolation type to use.

 

Returns

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

gwy_data_field_get_profile_mask ()

GwyXY *
gwy_data_field_get_profile_mask (GwyDataField *data_field,
                                 gint *ndata,
                                 GwyDataField *mask,
                                 GwyMaskingType masking,
                                 gdouble xfrom,
                                 gdouble yfrom,
                                 gdouble xto,
                                 gdouble yto,
                                 gint res,
                                 gint thickness,
                                 GwyInterpolationType interpolation);

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_data_field_get_profile(), this function takes real coordinates (without offsets), not row and column indices.

Parameters

data_field

A data field.

 

ndata

Location where to store the actual number of extracted points, which may differ from res .

 

mask

Mask specifying which values to take into account/exclude, or NULL.

 

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 data_field 's.

 

thickness

Thickness of line to be averaged.

 

interpolation

Interpolation type to use.

 

Returns

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

Since: 2.49

gwy_data_field_get_row ()

void
gwy_data_field_get_row (GwyDataField *data_field,
                        GwyDataLine *data_line,
                        gint row);

Extracts a data field row into a data line.

Parameters

data_field

A data field.

 

data_line

A data line. It will be resized to width ot data_field .

 

row

Row index.

 

gwy_data_field_get_column ()

void
gwy_data_field_get_column (GwyDataField *data_field,
                           GwyDataLine *data_line,
                           gint col);

Extracts a data field column into a data line.

Parameters

data_field

A data field

 

data_line

A data line. It will be resized to height of data_field .

 

col

Column index.

 

gwy_data_field_set_row ()

void
gwy_data_field_set_row (GwyDataField *data_field,
                        GwyDataLine *data_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

data_field

A data field.

 

data_line

A data line.

 

row

Row index.

 

gwy_data_field_set_column ()

void
gwy_data_field_set_column (GwyDataField *data_field,
                           GwyDataLine *data_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

data_field

A data field.

 

data_line

A data line.

 

col

Column index.

 

gwy_data_field_get_row_part ()

void
gwy_data_field_get_row_part (GwyDataField *data_field,
                             GwyDataLine *data_line,
                             gint row,
                             gint from,
                             gint to);

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

Parameters

data_field

A data field.

 

data_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_data_field_get_column_part ()

void
gwy_data_field_get_column_part (GwyDataField *data_field,
                                GwyDataLine *data_line,
                                gint col,
                                gint from,
                                gint to);

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

Parameters

data_field

A data field.

 

data_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_data_field_set_row_part ()

void
gwy_data_field_set_row_part (GwyDataField *data_field,
                             GwyDataLine *data_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

data_field

A data field.

 

data_line

A data line.

 

row

Row index.

 

from

Start row index.

 

to

End row index + 1.

 

gwy_data_field_set_column_part ()

void
gwy_data_field_set_column_part (GwyDataField *data_field,
                                GwyDataLine *data_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

data_field

A data field.

 

data_line

A data line.

 

col

Column index.

 

from

Start row index.

 

to

End row index + 1.

 

gwy_data_field_get_xder ()

gdouble
gwy_data_field_get_xder (GwyDataField *data_field,
                         gint col,
                         gint row);

Computes central derivative in X direction.

On border points, one-side derivative is returned.

Parameters

data_field

A data field.

 

col

Column index.

 

row

Row index.

 

Returns

Derivative in X direction.

gwy_data_field_get_yder ()

gdouble
gwy_data_field_get_yder (GwyDataField *data_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

data_field

A data field.

 

col

Column index.

 

row

Row index.

 

Returns

Derivative in Y direction

gwy_data_field_get_angder ()

gdouble
gwy_data_field_get_angder (GwyDataField *data_field,
                           gint col,
                           gint row,
                           gdouble theta);

Computes derivative in direction specified by given angle.

Parameters

data_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_data_field_average_xyz ()

void
gwy_data_field_average_xyz (GwyDataField *data_field,
                            GwyDataField *density_map,
                            const GwyXYZ *points,
                            gint npoints);

Fills a data field with regularised XYZ 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) data_field will be filled entirely with the value of the closest point or something similar.

Parameters

data_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.

 

points

Array of XYZ points. Coordinates X and Y represent positions in the plane; the Z-coordinate represents values.

 

npoints

Number of points.

 

Since: 2.44

Types and Values

gwy_data_field_get_xmeasure

#define gwy_data_field_get_xmeasure gwy_data_field_get_dx

Alias for gwy_data_field_get_dx().

Parameters

data_field

A data field.

 

gwy_data_field_get_ymeasure

#define gwy_data_field_get_ymeasure gwy_data_field_get_dy

Alias for gwy_data_field_get_dy().

Parameters

data_field

A data field.

 

struct GwyDataField

struct GwyDataField;

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

struct GwyDataFieldClass

struct GwyDataFieldClass {
    GObjectClass parent_class;

    void (*data_changed)(GwyDataField *data_field);
};

Signal Details

The “data-changed” signal

void
user_function (GwyDataField *gwydatafield,
               gpointer      user_data)

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

Parameters

gwydatafield

The GwyDataField 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