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

GwyDataLine (HEAD)

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 ()
void	gwy_data_line_sum_lines ()
void	gwy_data_line_subtract_lines ()
void	gwy_data_line_multiply_lines ()
void	gwy_data_line_linear_combination ()
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_filter_slope ()
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 and/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_sum_lines ()

void
gwy_data_line_sum_lines (GwyDataLine *result,
                         GwyDataLine *operand1,
                         GwyDataLine *operand2);

Sums two data lines.

Parameters

result	A data line to put the result to. May be one of `operand1` , `operand2` .
operand1	First data line operand.
operand2	Second data line operand.

Since: 2.56

gwy_data_line_subtract_lines ()

void
gwy_data_line_subtract_lines (GwyDataLine *result,
                              GwyDataLine *operand1,
                              GwyDataLine *operand2);

Subtracts two data lines.

Parameters

result	A data line to put the result to. May be one of `operand1` , `operand2` .
operand1	First data line operand.
operand2	Second data line operand.

Since: 2.56

gwy_data_line_multiply_lines ()

void
gwy_data_line_multiply_lines (GwyDataLine *result,
                              GwyDataLine *operand1,
                              GwyDataLine *operand2);

Multiplies two data lines.

Parameters

result	A data line to put the result to. May be one of `operand1` , `operand2` .
operand1	First data line operand.
operand2	Second data line operand.

Since: 2.56

gwy_data_line_linear_combination ()

void
gwy_data_line_linear_combination (GwyDataLine *result,
                                  gdouble coeff1,
                                  GwyDataLine *operand1,
                                  gdouble coeff2,
                                  GwyDataLine *operand2,
                                  gdouble constant);

Computes point-wise general linear combination of two data lines.

Parameters

result	A data line to put the result to. May be one of `operand1` , `operand2` .
constant	Constant term to add to the result.
operand1	First data line operand.
coeff1	Factor to multiply the first operand with.
operand2	Second data line operand.
coeff2	Factor to multiply the second operand with.

Since: 2.61

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

void
gwy_data_line_filter_slope (GwyDataLine *data_line,
                            GwyDataLine *der);

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