GwyDataLine

GwyDataLine — One-dimensional data representation

Functions

GwyDataLine * gwy_data_line_new ()
GwyDataLine * gwy_data_line_new_alike ()
GwyDataLine * gwy_data_line_copy ()
void gwy_data_line_assign ()
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_data ()
gdouble * gwy_data_line_get_data ()
const gdouble * gwy_data_line_get_data_const ()
void gwy_data_line_invalidate ()
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 ()
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 ()
gdouble gwy_data_line_get_der ()
gdouble * gwy_data_line_part_fit_poly ()
gdouble * gwy_data_line_fit_poly ()
void gwy_data_line_part_subtract_poly ()
void gwy_data_line_subtract_poly ()
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

Object Hierarchy

    GObject
    ╰── GwyDataLine

Implemented Interfaces

GwyDataLine implements GwySerializable.

Includes

#include <libgwyddion/gwyddion.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_new()

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

Creates a new data line.

[constructor]

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.

[transfer full]


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.

[transfer full]


gwy_data_line_copy()

GwyDataLine *
gwy_data_line_copy (GwyDataLine *line);

Create a new data line as a copy of an existing one.

This function is a convenience gwy_serializable_copy() wrapper.

Parameters

line

A data line to duplicate.

 

Returns

A copy of the data line.

[transfer full]


gwy_data_line_assign()

void
gwy_data_line_assign (GwyDataLine *destination,
                      GwyDataLine *source);

Makes one data line equal to another.

This function is a convenience gwy_serializable_assign() wrapper.

Parameters

destination

Target data line.

 

source

Source data line.

 

gwy_data_line_data_changed()

void
gwy_data_line_data_changed (GwyDataLine *line);

Emits signal "data_changed" on a data line.

Parameters

line

A data line.

 

gwy_data_line_new_resampled()

GwyDataLine *
gwy_data_line_new_resampled (GwyDataLine *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

line

A data line.

 

res

Desired resolution.

 

interpolation

Interpolation method to use.

 

Returns

A newly created data line.

[transfer full]


gwy_data_line_resample()

void
gwy_data_line_resample (GwyDataLine *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

line

A data line.

 

res

Desired resolution.

 

interpolation

Interpolation method to use.

 

gwy_data_line_resize()

void
gwy_data_line_resize (GwyDataLine *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

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 *line,
                            gint from,
                            gint len);

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

Parameters

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

void
gwy_data_line_copy_data (GwyDataLine *line,
                         GwyDataLine *target);

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

Only the data points are copied. To make a data line completely identical to another, including units and change of dimensions, you can use gwy_data_line_assign().

Parameters

line

Source data line.

 

target

Destination data line.

 

gwy_data_line_get_data()

gdouble *
gwy_data_line_get_data (GwyDataLine *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

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 *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

line

A data line.

 

Returns

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


gwy_data_line_invalidate()

void
gwy_data_line_invalidate (GwyDataLine *line);

Invalidates cached data line stats.

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

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

Parameters

line

A data line.

 

gwy_data_line_get_res()

gint
gwy_data_line_get_res (GwyDataLine *line);

Gets the number of data points in a data line.

Parameters

line

A data line.

 

Returns

Resolution (number of data points).


gwy_data_line_get_real()

gdouble
gwy_data_line_get_real (GwyDataLine *line);

Gets the physical size of a data line.

Parameters

line

A data line.

 

Returns

Real size of data line.


gwy_data_line_set_real()

void
gwy_data_line_set_real (GwyDataLine *line,
                        gdouble real);

Sets the real data line size.

Parameters

line

A data line.

 

real

value to be set

 

gwy_data_line_get_offset()

gdouble
gwy_data_line_get_offset (GwyDataLine *line);

Gets the offset of data line origin.

Parameters

line

A data line.

 

Returns

Offset value.


gwy_data_line_set_offset()

void
gwy_data_line_set_offset (GwyDataLine *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

line

A data line.

 

offset

New offset value.

 

gwy_data_line_get_dx()

gdouble
gwy_data_line_get_dx (GwyDataLine *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(line)/gwy_data_line_get_res(line).

Parameters

line

A data line.

 

Returns

Sampling step size.


gwy_data_line_get_si_unit_x()

GwySIUnit *
gwy_data_line_get_si_unit_x (GwyDataLine *line);

Returns lateral SI unit of a data line.

The returned object can be modified to change the line x units.

Parameters

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 *line);

Returns value SI unit of a data line.

The returned object can be modified to change the line value units.

Parameters

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

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

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

Parameters

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 *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 line , therefore it's relatively slow.

Parameters

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 *line,
                          GwyDataLine *target);

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

Parameters

line

A data line.

 

target

Destination data line.

 

gwy_data_line_itor()

gdouble
gwy_data_line_itor (GwyDataLine *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(line , pixpos + 0.5) for that.

Parameters

line

A data line.

 

pixpos

Pixel coordinate.

 

Returns

pixpos in real coordinates.


gwy_data_line_rtoi()

gdouble
gwy_data_line_rtoi (GwyDataLine *line,
                    gdouble realpos);

Transforms real (physical) coordinate to pixel coordinate.

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

Parameters

line

A data line.

 

realpos

Real coordinate.

 

Returns

realpos in pixel coordinates.


gwy_data_line_get_val()

gdouble
gwy_data_line_get_val (GwyDataLine *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

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 *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

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 *line,
                        gdouble x,
                        GwyInterpolationType 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(line , j ) returns, it's necessary to add 0.5: gwy_data_line_get_dval(line , * j +0.5, interpolation ).

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

Parameters

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 *line,
                             gdouble x,
                             GwyInterpolationType interpolation);

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

See also gwy_data_line_get_dval() for interpolation explanation.

Parameters

line

A data line.

 

x

Position in real coordinates.

 

interpolation

Interpolation method to use.

 

Returns

Value interpolated in the data line.


gwy_data_line_invert()

void
gwy_data_line_invert (GwyDataLine *line,
                      gboolean xflipped,
                      gboolean yflipped);

Reflects and/or inverts a data line.

In the case of value reflection, values are inverted about mean value.

Parameters

line

A data line.

 

xflipped

Whether to invert data point order.

 

yflipped

Whether to invert in Y direction, i.e. invert values.

 

gwy_data_line_clear()

void
gwy_data_line_clear (GwyDataLine *line);

Fills a data line with zeroes.

Parameters

line

A data line.

 

gwy_data_line_fill()

void
gwy_data_line_fill (GwyDataLine *line,
                    gdouble value);

Fills a data line with specified value.

Parameters

line

A data line.

 

value

Value to fill data line with.

 

gwy_data_line_multiply()

void
gwy_data_line_multiply (GwyDataLine *line,
                        gdouble value);

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

Parameters

line

A data line.

 

value

Value to multiply data line with.

 

gwy_data_line_add()

void
gwy_data_line_add (GwyDataLine *line,
                   gdouble value);

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

Parameters

line

A data line.

 

value

Value to be added.

 

gwy_data_line_part_clear()

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

Fills a data line part with zeroes.

Parameters

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 *line,
                         gint from,
                         gint to,
                         gdouble value);

Fills specified part of data line with specified number

Parameters

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 *line,
                             gint from,
                             gint to,
                             gdouble value);

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

Parameters

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 *line,
                        gint from,
                        gint to,
                        gdouble value);

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

Parameters

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 *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

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 *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

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 *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

line

A data line.

 

av

Height coefficient.

 

bv

Slope coeficient.

 

gwy_data_line_line_level()

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

Levels a data line by subtraction.

See gwy_data_line_get_line_coeffs() for deails.

Parameters

line

A data line.

 

av

Height coefficient.

 

bv

Slope coefficient.

 

gwy_data_line_rotate()

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

Levels a data line by rotation.

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

Parameters

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 *line,
                       gint i);

Computes central derivaltion at given index in a data line.

Parameters

line

A data line.

 

i

Pixel coordinate.

 

Returns

Derivation at given position.


gwy_data_line_part_fit_poly()

gdouble *
gwy_data_line_part_fit_poly (GwyDataLine *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_poly() for more details.

Parameters

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

gdouble *
gwy_data_line_fit_poly (GwyDataLine *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

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

void
gwy_data_line_part_subtract_poly (GwyDataLine *line,
                                  gint n,
                                  const gdouble *coeffs,
                                  gint from,
                                  gint to);

Subtracts a polynomial from a part of a data line.

Parameters

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

void
gwy_data_line_subtract_poly (GwyDataLine *line,
                             gint n,
                             const gdouble *coeffs);

Subtracts a polynomial from a data line.

Parameters

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 *line);

Transforms a distribution in a data line to cummulative distribution.

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

See also gwy_accumulate_counts().

Parameters

line

A data line.

 

gwy_data_line_filter_slope()

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

gwy_data_line_sqrt()

void
gwy_data_line_sqrt (GwyDataLine *line);

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

Parameters

line

A data line.

 

Types and Values

struct GwyDataLine

struct GwyDataLine;

struct GwyDataLineClass

struct GwyDataLineClass {
    GObjectClass parent_class;

    void (*data_changed)(GwyDataLine *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