GwyDataLine

GwyDataLine — Array representing 1D data

Synopsis




enum        GwySFOutputType;
enum        GwyFitLineType;
struct      GwyDataLine;
struct      GwyDataLineClass;
GObject*    gwy_data_line_new               (gint res,
                                             gdouble real,
                                             gboolean nullme);
void        gwy_data_line_resample          (GwyDataLine *data_line,
                                             gint res,
                                             gint interpolation);
gboolean    gwy_data_line_resize            (GwyDataLine *data_line,
                                             gint from,
                                             gint to);
gboolean    gwy_data_line_copy              (GwyDataLine *data_line,
                                             GwyDataLine *b);
gdouble*    gwy_data_line_get_data          (GwyDataLine *data_line);
const gdouble* gwy_data_line_get_data_const (GwyDataLine *data_line);
gint        gwy_data_line_get_res           (GwyDataLine *data_line);
gdouble     gwy_data_line_get_real          (GwyDataLine *data_line);
void        gwy_data_line_set_real          (GwyDataLine *data_line,
                                             gdouble real);
gdouble     gwy_data_line_itor              (GwyDataLine *data_line,
                                             gdouble pixval);
gdouble     gwy_data_line_rtoi              (GwyDataLine *data_line,
                                             gdouble realval);
gdouble     gwy_data_line_get_val           (GwyDataLine *data_line,
                                             gint i);
gint        gwy_data_line_set_val           (GwyDataLine *data_line,
                                             gint i,
                                             gdouble value);
gdouble     gwy_data_line_get_dval          (GwyDataLine *data_line,
                                             gdouble x,
                                             gint interpolation);
gdouble     gwy_data_line_get_dval_real     (GwyDataLine *data_line,
                                             gdouble x,
                                             gint interpolation);
void        gwy_data_line_invert            (GwyDataLine *data_line,
                                             gboolean x,
                                             gboolean z);
void        gwy_data_line_fill              (GwyDataLine *data_line,
                                             gdouble value);
void        gwy_data_line_multiply          (GwyDataLine *data_line,
                                             gdouble value);
void        gwy_data_line_add               (GwyDataLine *data_line,
                                             gdouble value);
void        gwy_data_line_part_fill         (GwyDataLine *data_line,
                                             gint from,
                                             gint to,
                                             gdouble value);
void        gwy_data_line_part_multiply     (GwyDataLine *data_line,
                                             gint from,
                                             gint to,
                                             gdouble value);
void        gwy_data_line_part_add          (GwyDataLine *data_line,
                                             gint from,
                                             gint to,
                                             gdouble value);
gdouble     gwy_data_line_get_max           (GwyDataLine *data_line);
gdouble     gwy_data_line_get_min           (GwyDataLine *data_line);
gdouble     gwy_data_line_get_avg           (GwyDataLine *data_line);
gdouble     gwy_data_line_get_rms           (GwyDataLine *data_line);
gdouble     gwy_data_line_get_sum           (GwyDataLine *data_line);
gdouble     gwy_data_line_part_get_max      (GwyDataLine *data_line,
                                             gint from,
                                             gint to);
gdouble     gwy_data_line_part_get_min      (GwyDataLine *data_line,
                                             gint from,
                                             gint to);
gdouble     gwy_data_line_part_get_avg      (GwyDataLine *data_line,
                                             gint from,
                                             gint to);
gdouble     gwy_data_line_part_get_rms      (GwyDataLine *data_line,
                                             gint from,
                                             gint to);
gdouble     gwy_data_line_part_get_sum      (GwyDataLine *data_line,
                                             gint from,
                                             gint to);
gint        gwy_data_line_threshold         (GwyDataLine *data_line,
                                             gdouble threshval,
                                             gdouble bottom,
                                             gdouble top);
gint        gwy_data_line_part_threshold    (GwyDataLine *data_line,
                                             gint from,
                                             gint to,
                                             gdouble threshval,
                                             gdouble bottom,
                                             gdouble top);
void        gwy_data_line_line_coeffs       (GwyDataLine *data_line,
                                             gdouble *av,
                                             gdouble *bv);
void        gwy_data_line_part_line_coeffs  (GwyDataLine *data_line,
                                             gint from,
                                             gint to,
                                             gdouble *av,
                                             gdouble *bv);
void        gwy_data_line_line_level        (GwyDataLine *data_line,
                                             gdouble av,
                                             gdouble bv);
void        gwy_data_line_line_rotate       (GwyDataLine *data_line,
                                             gdouble angle,
                                             gint interpolation);
gdouble     gwy_data_line_get_der           (GwyDataLine *data_line,
                                             gint i);
void        gwy_data_line_fft               (GwyDataLine *ra,
                                             GwyDataLine *ia,
                                             GwyDataLine *rb,
                                             GwyDataLine *ib,
                                             void (*fft) (),
                                             GwyWindowingType windowing,
                                             gint direction,
                                             GwyInterpolationType interpolation,
                                             gboolean preserverms,
                                             gboolean level);
void        gwy_data_line_fft_hum           (gint direction,
                                             GwyDataLine *ra,
                                             GwyDataLine *ia,
                                             GwyDataLine *rb,
                                             GwyDataLine *ib,
                                             gint interpolation);
gdouble*    gwy_data_line_part_fit_polynom  (GwyDataLine *data_line,
                                             gint n,
                                             gdouble *coeffs,
                                             gint from,
                                             gint to);
gdouble*    gwy_data_line_fit_polynom       (GwyDataLine *data_line,
                                             gint n,
                                             gdouble *coeffs);
void        gwy_data_line_part_subtract_polynom
                                            (GwyDataLine *data_line,
                                             gint n,
                                             gdouble *coeffs,
                                             gint from,
                                             gint to);
void        gwy_data_line_subtract_polynom  (GwyDataLine *data_line,
                                             gint n,
                                             gdouble *coeffs);
gdouble     gwy_data_line_get_modus         (GwyDataLine *data_line,
                                             gint histogram_steps);
gdouble     gwy_data_line_part_get_modus    (GwyDataLine *data_line,
                                             gint from,
                                             gint to,
                                             gint histogram_steps);

Object Hierarchy


  GObject
   +----GwyDataLine

Implemented Interfaces

GwyDataLine implements GwySerializable and GwyWatchable.

Description

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

Details

enum GwySFOutputType

typedef enum {
    GWY_SF_OUTPUT_DH    = 0,
    GWY_SF_OUTPUT_CDH   = 1,
    GWY_SF_OUTPUT_DA    = 2,
    GWY_SF_OUTPUT_CDA   = 3,
    GWY_SF_OUTPUT_ACF   = 4,
    GWY_SF_OUTPUT_HHCF  = 5,
    GWY_SF_OUTPUT_PSDF  = 6
} GwySFOutputType;

Statistical function type.

GWY_SF_OUTPUT_DH Distribution of heights.
GWY_SF_OUTPUT_CDH Cumulative distribution of heights.
GWY_SF_OUTPUT_DA Distribution of angles (slopes).
GWY_SF_OUTPUT_CDA Cumulative distribution of angles (slopes).
GWY_SF_OUTPUT_ACF Autocorrelation fucntions.
GWY_SF_OUTPUT_HHCF Height-height correlation function.
GWY_SF_OUTPUT_PSDF Power spectral density fucntion.

enum GwyFitLineType

typedef enum {
    GWY_FIT_POLY_0   = 0,
    GWY_FIT_POLY_1   = 1,
    GWY_FIT_POLY_2   = 2,
    GWY_FIT_POLY_3   = 3
} GwyFitLineType;

Fit polynomial degree selection.


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;
};


gwy_data_line_new ()

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

res :
real :
nullme :
Returns :

gwy_data_line_resample ()

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

Resamples data line, i. e. changes the size of one dimensional field related with data line. The original values are used for resampling using a requested resampling alorithm.

data_line : A data line.
res : new resolution
interpolation : interpolation method used

gwy_data_line_resize ()

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

Resamples data line to (from - to) and fills it by appropriate original data line part.

data_line : A data line.
from : where to start
to : where to finish
Returns : TRUE if there were no problems.

gwy_data_line_copy ()

gboolean    gwy_data_line_copy              (GwyDataLine *data_line,
                                             GwyDataLine *b);

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

data_line : Source data line.
b : Destination data line.
Returns : TRUE if there were no problems

gwy_data_line_get_data ()

gdouble*    gwy_data_line_get_data          (GwyDataLine *data_line);

Gets the data of the line.

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

data_line : A data line.
Returns : The data as an array of doubles of length gwy_data_line_get_res().

Since 1.3


gwy_data_line_get_data_const ()

const gdouble* gwy_data_line_get_data_const (GwyDataLine *data_line);

Gets the data of the line, read-only.

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

data_line : A data line.
Returns : The data as an array of doubles of length gwy_data_line_get_res().

Since 1.7


gwy_data_line_get_res ()

gint        gwy_data_line_get_res           (GwyDataLine *data_line);

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

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.

data_line : A data line.
real : value to be set

gwy_data_line_itor ()

gdouble     gwy_data_line_itor              (GwyDataLine *data_line,
                                             gdouble pixval);

data_line : A data line.
pixval : value in pixel coordinates
Returns : value in real coordinates.

gwy_data_line_rtoi ()

gdouble     gwy_data_line_rtoi              (GwyDataLine *data_line,
                                             gdouble realval);

data_line : A data line.
realval : value in real coordinates
Returns : value in pixel coordinates.

gwy_data_line_get_val ()

gdouble     gwy_data_line_get_val           (GwyDataLine *data_line,
                                             gint i);

data_line : A data line.
i : index (pixel coordinates)
Returns : value at given index.

gwy_data_line_set_val ()

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

Sets the value at given index.

data_line : data line
i : pixel coordinates
value : value to be set
Returns : TRUE it there were no problems.

gwy_data_line_get_dval ()

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

Using a specified interpolation returns value in any point wihin data line.

data_line : A data line.
x : position requested (0 - resolution)
interpolation : interpolation used
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);

Same as gwy_data_line_get_dval() fucntion, but uses real coordinates input.

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

Inverts values. If x is TRUE it inverts x-axis values (x1...xn) to (xn...x1), if z is TRUE inverts z-axis values (peaks to valleys and valleys to peaks).

data_line : A data line.
x : invert x axis
z : invert z axis

gwy_data_line_fill ()

void        gwy_data_line_fill              (GwyDataLine *data_line,
                                             gdouble value);

Fills whole data lien with specified number.

data_line : A data line.
value : value to be used for filling

gwy_data_line_multiply ()

void        gwy_data_line_multiply          (GwyDataLine *data_line,
                                             gdouble value);

Multiplies whole data line with a specified number.

data_line : A data line.
value : value to be used for multiplication

gwy_data_line_add ()

void        gwy_data_line_add               (GwyDataLine *data_line,
                                             gdouble value);

Adds a specified number to whole data line.

data_line : A data line.
value : value to be added.

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

data_line : A data line.
from : where to start
to : where to finish
value : value to be used for filling

gwy_data_line_part_multiply ()

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

Multiplies specified part of data line by specified number

data_line : A data line.
from : where to start
to : where to finish
value : value to be used for multiplication

gwy_data_line_part_add ()

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

Adds specified number to a part of data line.

data_line : A data line.
from : where to start
to : where to finish
value : value to be added

gwy_data_line_get_max ()

gdouble     gwy_data_line_get_max           (GwyDataLine *data_line);

data_line : A data line.
Returns : Maximum value

gwy_data_line_get_min ()

gdouble     gwy_data_line_get_min           (GwyDataLine *data_line);

data_line : A data line.
Returns : Minimum value

gwy_data_line_get_avg ()

gdouble     gwy_data_line_get_avg           (GwyDataLine *data_line);

data_line : A data line.
Returns : Average value

gwy_data_line_get_rms ()

gdouble     gwy_data_line_get_rms           (GwyDataLine *data_line);

data_line : A data line.
Returns : Root mean square deviation of heights

gwy_data_line_get_sum ()

gdouble     gwy_data_line_get_sum           (GwyDataLine *data_line);

data_line : A data line.
Returns : sum of all the values

gwy_data_line_part_get_max ()

gdouble     gwy_data_line_part_get_max      (GwyDataLine *data_line,
                                             gint from,
                                             gint to);

data_line : A data line.
from : where to start (in pixels)
to : where to finish (in pixels)
Returns : Maximum within given interval

gwy_data_line_part_get_min ()

gdouble     gwy_data_line_part_get_min      (GwyDataLine *data_line,
                                             gint from,
                                             gint to);

data_line : A data line.
from : where to start (in pixels)
to : where to finish (in pixels)
Returns : Minimum within given interval

gwy_data_line_part_get_avg ()

gdouble     gwy_data_line_part_get_avg      (GwyDataLine *data_line,
                                             gint from,
                                             gint to);

data_line : A data line.
from : where to start (in pixels)
to : where to finish (in pixels)
Returns : Average within given interval

gwy_data_line_part_get_rms ()

gdouble     gwy_data_line_part_get_rms      (GwyDataLine *data_line,
                                             gint from,
                                             gint to);

data_line : A data line.
from : where to start (in pixels)
to : where to finish (in pixels)
Returns : Root mean square deviation of heights within a given interval

gwy_data_line_part_get_sum ()

gdouble     gwy_data_line_part_get_sum      (GwyDataLine *data_line,
                                             gint from,
                                             gint to);

data_line : A data line.
from : where to start (in pixels)
to : where to finish (in pixels)
Returns : Sum of all values within the interval

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

data_line : A data line.
threshval : value used for thresholding
bottom : lower value
top : upper 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.

data_line : A data line.
from : where to start
to : where to finish
threshval : value used for thresholding
bottom : lower value
top : upper value
Returns : total number of values above threshold within interval

gwy_data_line_line_coeffs ()

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

Finds coefficients that can be used for line leveling using relation data[i] -= av + bv*real_index;

data_line : A data line.
av : height coefficient
bv : slope coeficient

gwy_data_line_part_line_coeffs ()

void        gwy_data_line_part_line_coeffs  (GwyDataLine *data_line,
                                             gint from,
                                             gint to,
                                             gdouble *av,
                                             gdouble *bv);

data_line :
from :
to :
av :
bv :

gwy_data_line_line_level ()

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

Performs line leveling using relation data[i] -= av + bv*real_index.

data_line : A data line.
av : height coefficient
bv : slope coefficient

gwy_data_line_line_rotate ()

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

Performs line rotation. This is operation similar to leveling, but not changing the angles between line segments.

data_line : A data line.
angle : angle of rotation (in degrees)
interpolation : interpolation mode used

gwy_data_line_get_der ()

gdouble     gwy_data_line_get_der           (GwyDataLine *data_line,
                                             gint i);

data_line : A data line.
i : pixel coordinate
Returns : derivation at given pixel

gwy_data_line_fft ()

void        gwy_data_line_fft               (GwyDataLine *ra,
                                             GwyDataLine *ia,
                                             GwyDataLine *rb,
                                             GwyDataLine *ib,
                                             void (*fft) (),
                                             GwyWindowingType windowing,
                                             gint direction,
                                             GwyInterpolationType interpolation,
                                             gboolean preserverms,
                                             gboolean level);

Performs Fast Fourier transform using a given algorithm. A windowing or data leveling can be applied if requested.

ra : real input
ia : imaginary input
rb : real output
ib : imaginary output
fft : fft alorithm
windowing : windowing mode
direction : FFT direction (1 or -1)
interpolation : interpolation mode
preserverms : preserve RMS value while windowing
level : level line before computation

gwy_data_line_fft_hum ()

void        gwy_data_line_fft_hum           (gint direction,
                                             GwyDataLine *ra,
                                             GwyDataLine *ia,
                                             GwyDataLine *rb,
                                             GwyDataLine *ib,
                                             gint interpolation);

Performs 1D FFT using the alogrithm ffthum (see simplefft.h). Resamples data to closest 2^N and then resamples result back. Resample data by yourself if you want further FFT processing as resampling of the FFT spectrum can destroy some information in it.

direction : FFT direction (1 or -1)
ra : real input
ia : imaginary input
rb : real output
ib : imaginary output
interpolation : interpolation used

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 polynom through a part of a data line.

Please see gwy_data_line_fit_polynom() for more details.

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 : The index in data_line to start from (inclusive).
to : The index in data_line to stop (noninclusive).
Returns : The coefficients of the polynom (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 polynom through a data line.

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

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

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 polynom (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,
                                             gdouble *coeffs,
                                             gint from,
                                             gint to);

data_line :
n :
coeffs :
from :
to :

gwy_data_line_subtract_polynom ()

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

data_line :
n :
coeffs :

gwy_data_line_get_modus ()

gdouble     gwy_data_line_get_modus         (GwyDataLine *data_line,
                                             gint histogram_steps);

Finds approximate modus of a data line.

As each number in the data line is usually unique, this function does not return modus of the data itself, but modus of a histogram.

data_line : A data line.
histogram_steps : Number of histogram steps used for modus searching, pass a nonpositive number to autosize.
Returns : The modus.

Since 1.4.


gwy_data_line_part_get_modus ()

gdouble     gwy_data_line_part_get_modus    (GwyDataLine *data_line,
                                             gint from,
                                             gint to,
                                             gint histogram_steps);

Finds approximate modus of a data line part.

data_line : A data line.
from : The index in data_line to start from (inclusive).
to : The index in data_line to stop (noninclusive).
histogram_steps : Number of histogram steps used for modus searching, pass a nonpositive number to autosize.
Returns : The modus.

Since 1.4.