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

GwyDataLine

GwyDataLine — One-dimensional data representation

Functions

#define gwy_data_line_duplicate()
#define gwy_data_line_assign()
GwyDataLine * gwy_data_line_new ()
GwyDataLine * gwy_data_line_new_alike ()
void gwy_data_line_data_changed ()
GwyDataLine * gwy_data_line_new_resampled ()
void gwy_data_line_resample ()
void gwy_data_line_resize ()
GwyDataLine * gwy_data_line_part_extract ()
void gwy_data_line_copy ()
gdouble * gwy_data_line_get_data ()
const gdouble * gwy_data_line_get_data_const ()
gint gwy_data_line_get_res ()
gdouble gwy_data_line_get_real ()
void gwy_data_line_set_real ()
gdouble gwy_data_line_get_offset ()
void gwy_data_line_set_offset ()
gdouble gwy_data_line_get_dx ()
GwySIUnit * gwy_data_line_get_si_unit_x ()
GwySIUnit * gwy_data_line_get_si_unit_y ()
void gwy_data_line_set_si_unit_x ()
void gwy_data_line_set_si_unit_y ()
GwySIValueFormat * gwy_data_line_get_value_format_x ()
GwySIValueFormat * gwy_data_line_get_value_format_y ()
void gwy_data_line_copy_units ()
gdouble gwy_data_line_itor ()
gdouble gwy_data_line_rtoi ()
gdouble gwy_data_line_get_val ()
void gwy_data_line_set_val ()
gdouble gwy_data_line_get_dval ()
gdouble gwy_data_line_get_dval_real ()
void gwy_data_line_invert ()
void gwy_data_line_clear ()
void gwy_data_line_fill ()
void gwy_data_line_multiply ()
void gwy_data_line_add ()
void gwy_data_line_part_clear ()
void gwy_data_line_part_fill ()
void gwy_data_line_part_multiply ()
void gwy_data_line_part_add ()
gint gwy_data_line_threshold ()
gint gwy_data_line_part_threshold ()
void gwy_data_line_get_line_coeffs ()
void gwy_data_line_line_level ()
void gwy_data_line_rotate ()
void gwy_data_line_line_rotate ()
gdouble gwy_data_line_get_der ()
gdouble * gwy_data_line_part_fit_polynom ()
gdouble * gwy_data_line_fit_polynom ()
void gwy_data_line_part_subtract_polynom ()
void gwy_data_line_subtract_polynom ()
void gwy_data_line_cumulate ()
void gwy_data_line_sqrt ()

Signals

void data-changed Run First

Types and Values

struct GwyDataLine
struct GwyDataLineClass

Object Hierarchy

    GObject
    ╰── GwyDataLine

Implemented Interfaces

GwyDataLine implements GwySerializable.

Includes

#include <libprocess/gwyprocess.h>

Description

GwyDataLine represents 1D data arrays in Gwyddion. It is used for most of the data processing functions connected with 1D data, graphs, etc.

Functions

gwy_data_line_duplicate()

#define             gwy_data_line_duplicate(data_line)

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

Parameters

data_line

A data line to duplicate.

 

gwy_data_line_assign()

#define             gwy_data_line_assign(dest, source)

Convenience macro making one data line identical to another.

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

Parameters

dest

Target data line.

 

source

Source data line.

 

Since: 2.52

gwy_data_line_new ()

GwyDataLine *
gwy_data_line_new (gint res,
                   gdouble real,
                   gboolean nullme);

Creates a new data line.

Parameters

res

Resolution, i.e., the number of samples.

 

real

Real physical dimension.

 

nullme

Whether the data line should be initialized to zeroes. If FALSE, the data will not be initialized.

 

Returns

A newly created data line.

gwy_data_line_new_alike ()

GwyDataLine *
gwy_data_line_new_alike (GwyDataLine *model,
                         gboolean nullme);

Creates a new data line similar to an existing one.

Use gwy_data_line_duplicate() if you want to copy a data line including data.

Parameters

model

A data line to take resolutions and units from.

 

nullme

Whether the data line should be initialized to zeroes. If FALSE, the data will not be initialized.

 

Returns

A newly created data line.

gwy_data_line_data_changed ()

void
gwy_data_line_data_changed (GwyDataLine *data_line);

Emits signal "data_changed" on a data line.

Parameters

data_line

A data line.

 

gwy_data_line_new_resampled ()

GwyDataLine *
gwy_data_line_new_resampled (GwyDataLine *data_line,
                             gint res,
                             GwyInterpolationType interpolation);

Creates a new data line by resampling an existing one.

This method is equivalent to gwy_data_line_duplicate() followed by gwy_data_line_resample(), but it is more efficient.

Parameters

data_line

A data line.

 

res

Desired resolution.

 

interpolation

Interpolation method to use.

 

Returns

A newly created data line.

Since: 2.1

gwy_data_line_resample ()

void
gwy_data_line_resample (GwyDataLine *data_line,
                        gint res,
                        GwyInterpolationType interpolation);

Resamples a data line.

In other words changes the size of one dimensional field related with data line. The original values are used for resampling using a requested interpolation alorithm.

Parameters

data_line

A data line.

 

res

Desired resolution.

 

interpolation

Interpolation method to use.

 

gwy_data_line_resize ()

void
gwy_data_line_resize (GwyDataLine *data_line,
                      gint from,
                      gint to);

Resizes (crops) a data line.

Extracts a part of data line in range from ..(to -1), recomputing real sizes.

Parameters

data_line

A data line.

 

from

Where to start.

 

to

Where to finish + 1.

 

gwy_data_line_part_extract ()

GwyDataLine *
gwy_data_line_part_extract (GwyDataLine *data_line,
                            gint from,
                            gint len);

Extracts a part of a data line to a new data line.

Parameters

data_line

A data line.

 

from

Where to start.

 

len

Length of extracted segment.

 

Returns

The extracted area as a newly created data line.

gwy_data_line_copy ()

void
gwy_data_line_copy (GwyDataLine *data_line,
                    GwyDataLine *target);

Copies the contents of a data line to another already allocated data line of the same size.

Warning

Semantic of method differs from gwy_data_field_copy(), it copies only data. It will be probably changed.

Parameters

data_line

Source data line.

 

target

Destination data line.

 

gwy_data_line_get_data ()

gdouble *
gwy_data_line_get_data (GwyDataLine *data_line);

Gets the raw data buffer of a data line.

The returned buffer is not guaranteed to be valid through whole data line life time. Some function may change it, most notably gwy_data_line_resize() and gwy_data_line_resample().

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

Parameters

data_line

A data line.

 

Returns

The data as an array of doubles of length gwy_data_line_get_res().

gwy_data_line_get_data_const ()

const gdouble *
gwy_data_line_get_data_const (GwyDataLine *data_line);

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

The returned buffer is not guaranteed to be valid through whole data line life time. Some function may change it, most notably gwy_data_line_resize() and gwy_data_line_resample().

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

Parameters

data_line

A data line.

 

Returns

The data as an array of doubles of length gwy_data_line_get_res().

gwy_data_line_get_res ()

gint
gwy_data_line_get_res (GwyDataLine *data_line);

Gets the number of data points in a data line.

Parameters

data_line

A data line.

 

Returns

Resolution (number of data points).

gwy_data_line_get_real ()

gdouble
gwy_data_line_get_real (GwyDataLine *data_line);

Gets the physical size of a data line.

Parameters

data_line

A data line.

 

Returns

Real size of data line.

gwy_data_line_set_real ()

void
gwy_data_line_set_real (GwyDataLine *data_line,
                        gdouble real);

Sets the real data line size.

Parameters

data_line

A data line.

 

real

value to be set

 

gwy_data_line_get_offset ()

gdouble
gwy_data_line_get_offset (GwyDataLine *data_line);

Gets the offset of data line origin.

Parameters

data_line

A data line.

 

Returns

Offset value.

gwy_data_line_set_offset ()

void
gwy_data_line_set_offset (GwyDataLine *data_line,
                          gdouble offset);

Sets the offset of a data line origin.

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

Parameters

data_line

A data line.

 

offset

New offset value.

 

gwy_data_line_get_dx ()

gdouble
gwy_data_line_get_dx (GwyDataLine *data_line);

Gets the sample distance (pixel size) of a data line in real units.

The result is the same as gwy_data_line_get_real(data_line)/gwy_data_line_get_res(data_line).

Parameters

data_line

A data line.

 

Returns

Sampling step size.

Since: 2.52

gwy_data_line_get_si_unit_x ()

GwySIUnit *
gwy_data_line_get_si_unit_x (GwyDataLine *data_line);

Returns lateral SI unit of a data line.

Parameters

data_line

A data line.

 

Returns

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

gwy_data_line_get_si_unit_y ()

GwySIUnit *
gwy_data_line_get_si_unit_y (GwyDataLine *data_line);

Returns value SI unit of a data line.

Parameters

data_line

A data line.

 

Returns

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

gwy_data_line_set_si_unit_x ()

void
gwy_data_line_set_si_unit_x (GwyDataLine *data_line,
                             GwySIUnit *si_unit);

Sets the SI unit corresponding to the lateral (X) dimension of a data line.

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

Parameters

data_line

A data line.

 

si_unit

SI unit to be set.

 

gwy_data_line_set_si_unit_y ()

void
gwy_data_line_set_si_unit_y (GwyDataLine *data_line,
                             GwySIUnit *si_unit);

Sets the SI unit corresponding to the "height" (Y) dimension of a data line.

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

Parameters

data_line

A data line.

 

si_unit

SI unit to be set.

 

gwy_data_line_get_value_format_x ()

GwySIValueFormat *
gwy_data_line_get_value_format_x (GwyDataLine *data_line,
                                  GwySIUnitFormatStyle style,
                                  GwySIValueFormat *format);

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

Parameters

data_line

A data line.

 

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_line_get_value_format_y ()

GwySIValueFormat *
gwy_data_line_get_value_format_y (GwyDataLine *data_line,
                                  GwySIUnitFormatStyle style,
                                  GwySIValueFormat *format);

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

Note this functions searches for minimum and maximum value in data_line , therefore it's relatively slow.

Parameters

data_line

A data line.

 

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_line_copy_units ()

void
gwy_data_line_copy_units (GwyDataLine *data_line,
                          GwyDataLine *target);

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

Parameters

data_line

A data line.

 

target

Destination data line.

 

Since: 2.49

gwy_data_line_itor ()

gdouble
gwy_data_line_itor (GwyDataLine *data_line,
                    gdouble pixpos);

Transforms pixel coordinate to real (physical) coordinate.

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

Parameters

data_line

A data line.

 

pixpos

Pixel coordinate.

 

Returns

pixpos in real coordinates.

gwy_data_line_rtoi ()

gdouble
gwy_data_line_rtoi (GwyDataLine *data_line,
                    gdouble realpos);

Transforms real (physical) coordinate to pixel coordinate.

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

Parameters

data_line

A data line.

 

realpos

Real coordinate.

 

Returns

realpos in pixel coordinates.

gwy_data_line_get_val ()

gdouble
gwy_data_line_get_val (GwyDataLine *data_line,
                       gint i);

Gets value at given position in a data line.

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

Parameters

data_line

A data line.

 

i

Position in the line (index).

 

Returns

Value at given index.

gwy_data_line_set_val ()

void
gwy_data_line_set_val (GwyDataLine *data_line,
                       gint i,
                       gdouble value);

Sets the value at given position in a data line.

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

Parameters

data_line

A data line.

 

i

Position in the line (index).

 

value

Value to set.

 

gwy_data_line_get_dval ()

gdouble
gwy_data_line_get_dval (GwyDataLine *data_line,
                        gdouble x,
                        gint interpolation);

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

Note pixel values are centered in intervals [j , j +1], so to get the same value as gwy_data_line_get_val(data_line , j ) returns, it's necessary to add 0.5: gwy_data_line_get_dval(data_line , j +0.5, interpolation ).

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

Parameters

data_line

A data line.

 

x

Position in data line in range [0, resolution]. If the value is outside this range, the nearest border value is returned.

 

interpolation

Interpolation method to use.

 

Returns

Value interpolated in the data line.

gwy_data_line_get_dval_real ()

gdouble
gwy_data_line_get_dval_real (GwyDataLine *data_line,
                             gdouble x,
                             gint interpolation);

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

See also gwy_data_line_get_dval() for interpolation explanation.

Parameters

data_line

A data line.

 

x

real coordinates position

 

interpolation

interpolation method used

 

Returns

Value interpolated in the data line.

gwy_data_line_invert ()

void
gwy_data_line_invert (GwyDataLine *data_line,
                      gboolean x,
                      gboolean z);

Reflects amd/or inverts a data line.

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

Parameters

data_line

A data line.

 

x

Whether to invert data point order.

 

z

Whether to invert in Z direction (i.e., invert values).

 

gwy_data_line_clear ()

void
gwy_data_line_clear (GwyDataLine *data_line);

Fills a data line with zeroes.

Parameters

data_line

A data line.

 

gwy_data_line_fill ()

void
gwy_data_line_fill (GwyDataLine *data_line,
                    gdouble value);

Fills a data line with specified value.

Parameters

data_line

A data line.

 

value

Value to fill data line with.

 

gwy_data_line_multiply ()

void
gwy_data_line_multiply (GwyDataLine *data_line,
                        gdouble value);

Multiplies all values in a data line with a specified value.

Parameters

data_line

A data line.

 

value

Value to multiply data line with.

 

gwy_data_line_add ()

void
gwy_data_line_add (GwyDataLine *data_line,
                   gdouble value);

Adds a specified value to all values in a data line.

Parameters

data_line

A data line.

 

value

Value to be added.

 

gwy_data_line_part_clear ()

void
gwy_data_line_part_clear (GwyDataLine *data_line,
                          gint from,
                          gint to);

Fills a data line part with zeroes.

Parameters

data_line

A data line.

 

from

Index the line part starts at.

 

to

Index the line part ends at + 1.

 

gwy_data_line_part_fill ()

void
gwy_data_line_part_fill (GwyDataLine *data_line,
                         gint from,
                         gint to,
                         gdouble value);

Fills specified part of data line with specified number

Parameters

data_line

A data line.

 

from

Index the line part starts at.

 

to

Index the line part ends at + 1.

 

value

Value to fill data line part with.

 

gwy_data_line_part_multiply ()

void
gwy_data_line_part_multiply (GwyDataLine *data_line,
                             gint from,
                             gint to,
                             gdouble value);

Multiplies all values in a part of data line by specified value.

Parameters

data_line

A data line.

 

from

Index the line part starts at.

 

to

Index the line part ends at + 1.

 

value

Value multiply data line part with.

 

gwy_data_line_part_add ()

void
gwy_data_line_part_add (GwyDataLine *data_line,
                        gint from,
                        gint to,
                        gdouble value);

Adds specified value to all values in a part of a data line.

Parameters

data_line

A data line.

 

from

Index the line part starts at.

 

to

Index the line part ends at + 1.

 

value

Value to be added

 

gwy_data_line_threshold ()

gint
gwy_data_line_threshold (GwyDataLine *data_line,
                         gdouble threshval,
                         gdouble bottom,
                         gdouble top);

Sets all the values to bottom or top value depending on whether the original values are below or above threshold value

Parameters

data_line

A data line.

 

threshval

Threshold value.

 

bottom

Lower replacement value.

 

top

Upper replacement value.

 

Returns

total number of values above threshold

gwy_data_line_part_threshold ()

gint
gwy_data_line_part_threshold (GwyDataLine *data_line,
                              gint from,
                              gint to,
                              gdouble threshval,
                              gdouble bottom,
                              gdouble top);

Sets all the values within interval to bottom or top value depending on whether the original values are below or above threshold value.

Parameters

data_line

A data line.

 

from

Index the line part starts at.

 

to

Index the line part ends at + 1.

 

threshval

Threshold value.

 

bottom

Lower replacement value.

 

top

Upper replacement value.

 

Returns

total number of values above threshold within interval

gwy_data_line_get_line_coeffs ()

void
gwy_data_line_get_line_coeffs (GwyDataLine *data_line,
                               gdouble *av,
                               gdouble *bv);

Finds line leveling coefficients.

The coefficients can be used for line leveling using relation data[i] := data[i] - (av + bv*i);

Parameters

data_line

A data line.

 

av

Height coefficient.

 

bv

Slope coeficient.

 

gwy_data_line_line_level ()

void
gwy_data_line_line_level (GwyDataLine *data_line,
                          gdouble av,
                          gdouble bv);

Performs line leveling.

See gwy_data_line_get_line_coeffs() for deails.

Parameters

data_line

A data line.

 

av

Height coefficient.

 

bv

Slope coefficient.

 

gwy_data_line_rotate ()

void
gwy_data_line_rotate (GwyDataLine *data_line,
                      gdouble angle,
                      GwyInterpolationType interpolation);

Performs line rotation.

This is operation similar to leveling, but it does not change the angles between line segments (on the other hand it introduces other deformations due to discretization).

Parameters

data_line

A data line.

 

angle

Angle of rotation (in radians), counterclockwise.

 

interpolation

Interpolation method to use (can be only of two-point type).

 

Since: 2.7

gwy_data_line_line_rotate ()

void
gwy_data_line_line_rotate (GwyDataLine *data_line,
                           gdouble angle,
                           gint interpolation);

Warning

gwy_data_line_line_rotate is deprecated and should not be used in newly-written code.

Performs line rotation.

Use gwy_data_line_rotate() instead.

Parameters

data_line

A data line.

 

angle

Angle of rotation (in radians), counterclockwise.

 

interpolation

Interpolation method to use (can be only of two-point type).

 

gwy_data_line_get_der ()

gdouble
gwy_data_line_get_der (GwyDataLine *data_line,
                       gint i);

Computes central derivaltion at given index in a data line.

Parameters

data_line

A data line.

 

i

Pixel coordinate.

 

Returns

Derivation at given position.

gwy_data_line_part_fit_polynom ()

gdouble *
gwy_data_line_part_fit_polynom (GwyDataLine *data_line,
                                gint n,
                                gdouble *coeffs,
                                gint from,
                                gint to);

Fits a polynomial through a part of a data line.

Please see gwy_data_line_fit_polynom() for more details.

Parameters

data_line

A data line.

 

n

Polynom degree.

 

coeffs

An array of size n +1 to store the coefficients to, or NULL (a fresh array is allocated then).

 

from

Index the line part starts at.

 

to

Index the line part ends at + 1.

 

Returns

The coefficients of the polynomial (coeffs when it was not NULL, otherwise a newly allocated array).

gwy_data_line_fit_polynom ()

gdouble *
gwy_data_line_fit_polynom (GwyDataLine *data_line,
                           gint n,
                           gdouble *coeffs);

Fits a polynomial through a data line.

Note n is polynomial degree, so the size of coeffs is n +1. X-values are indices in the data line.

For polynomials of degree 0 and 1 it's better to use gwy_data_line_get_avg() and gwy_data_line_get_line_coeffs() because they are faster.

Parameters

data_line

A data line.

 

n

Polynom degree.

 

coeffs

An array of size n +1 to store the coefficients to, or NULL (a fresh array is allocated then).

 

Returns

The coefficients of the polynomial (coeffs when it was not NULL, otherwise a newly allocated array).

gwy_data_line_part_subtract_polynom ()

void
gwy_data_line_part_subtract_polynom (GwyDataLine *data_line,
                                     gint n,
                                     const gdouble *coeffs,
                                     gint from,
                                     gint to);

Subtracts a polynomial from a part of a data line.

Parameters

data_line

A data line.

 

n

Polynom degree.

 

coeffs

An array of size n +1 with polynomial coefficients to.

 

from

Index the line part starts at.

 

to

Index the line part ends at + 1.

 

gwy_data_line_subtract_polynom ()

void
gwy_data_line_subtract_polynom (GwyDataLine *data_line,
                                gint n,
                                const gdouble *coeffs);

Subtracts a polynomial from a data line.

Parameters

data_line

A data line.

 

n

Polynom degree.

 

coeffs

An array of size n +1 with polynomial coefficients to.

 

gwy_data_line_cumulate ()

void
gwy_data_line_cumulate (GwyDataLine *data_line);

Transforms a distribution in a data line to cummulative distribution.

Each element becomes sum of all previous elements in the line, including self.

Parameters

data_line

A data line.

 

gwy_data_line_sqrt ()

void
gwy_data_line_sqrt (GwyDataLine *data_line);

Applies sqrt() to each element in a data line.

Parameters

data_line

A data line.

 

Types and Values

struct GwyDataLine

struct GwyDataLine;

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

struct GwyDataLineClass

struct GwyDataLineClass {
    GObjectClass parent_class;

    void (*data_changed)(GwyDataLine *data_line);
};

Signal Details

The “data-changed” signal

void
user_function (GwyDataLine *gwydataline,
               gpointer     user_data)

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

Parameters

gwydataline

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