GwyDataLine

GwyDataLine — Array representing 1D data

Synopsis




            GwyDataLine;
            GwyDataLineClass;
void        (*GwyFFTFunc)                   (GwyTransformDirection dir,
                                             GwyDataLine *re_in,
                                             GwyDataLine *im_in,
                                             GwyDataLine *re_out,
                                             GwyDataLine *im_out,
                                             GwyInterpolationType interpolation);
#define     gwy_data_line_duplicate         (data_line)
GwyDataLine* gwy_data_line_new              (gint res,
                                             gdouble real,
                                             gboolean nullme);
GwyDataLine* gwy_data_line_new_alike        (GwyDataLine *model,
                                             gboolean nullme);
void        gwy_data_line_data_changed      (GwyDataLine *data_line);
void        gwy_data_line_resample          (GwyDataLine *data_line,
                                             gint res,
                                             GwyInterpolationType interpolation);
void        gwy_data_line_resize            (GwyDataLine *data_line,
                                             gint from,
                                             gint to);
void        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);
void        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,
                                             GwyFFTFunc fft,
                                             GwyWindowingType windowing,
                                             GwyTransformDirection direction,
                                             GwyInterpolationType interpolation,
                                             gboolean preserverms,
                                             gboolean level);
void        gwy_data_line_fft_hum           (GwyTransformDirection direction,
                                             GwyDataLine *ra,
                                             GwyDataLine *ia,
                                             GwyDataLine *rb,
                                             GwyDataLine *ib,
                                             GwyInterpolationType 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.

Signal Prototypes


"data-changed"
            void        user_function      (GwyDataLine *gwydataline,
                                            gpointer user_data);

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

GwyDataLine

typedef struct _GwyDataLine GwyDataLine;

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


GwyDataLineClass

typedef struct {
    GObjectClass parent_class;

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


GwyFFTFunc ()

void        (*GwyFFTFunc)                   (GwyTransformDirection dir,
                                             GwyDataLine *re_in,
                                             GwyDataLine *im_in,
                                             GwyDataLine *re_out,
                                             GwyDataLine *im_out,
                                             GwyInterpolationType interpolation);

Fast Fourier Transform (FFT) function type.

dir : Transform direction (forward or backward).
re_in : Data line with real part of input data.
im_in : Data line with imaginary part of input data.
re_out : Data line to store real part of output data to.
im_out : Data line to store imaginary part of output data to.
interpolation : Interpolation type to use.

gwy_data_line_duplicate()

#define     gwy_data_line_duplicate(data_line)

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

data_line : A data line to duplicate.

gwy_data_line_new ()

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

res :
real :
nullme :
Returns :

gwy_data_line_new_alike ()

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

model :
nullme :
Returns :

gwy_data_line_data_changed ()

void        gwy_data_line_data_changed      (GwyDataLine *data_line);

Emits signal "data_changed" on a data line.

data_line : A data line.

gwy_data_line_resample ()

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

Resamples a data line.

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

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.

data_line : A data line.
from : Where to start.
to : Where to finish + 1.

gwy_data_line_copy ()

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

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

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

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.

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.

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

Transforms pixel coordinate to real (physical) coordinate.

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

gwy_data_line_rtoi ()

gdouble     gwy_data_line_rtoi              (GwyDataLine *data_line,
                                             gdouble realval);

Transforms real (physical) coordinate to pixel coordinate.

data_line : A data line.
realval : value in real coordinates
Returns : realval 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.

data_line : A data line.
i : index (pixel coordinates)
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.

data_line : data line
i : pixel coordinates
value : value to be 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.

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

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

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

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

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.

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

void        gwy_data_line_fill              (GwyDataLine *data_line,
                                             gdouble value);

Fills data line with specified value.

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.

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.

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

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.

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

gdouble     gwy_data_line_get_max           (GwyDataLine *data_line);

Finds the maximum value of a data line.

data_line : A data line.
Returns : The maximum value.

gwy_data_line_get_min ()

gdouble     gwy_data_line_get_min           (GwyDataLine *data_line);

Finds the minimum value of a data line.

data_line : A data line.
Returns : The minimum value.

gwy_data_line_get_avg ()

gdouble     gwy_data_line_get_avg           (GwyDataLine *data_line);

Computes average value of a data line.

data_line : A data line.
Returns : Average value

gwy_data_line_get_rms ()

gdouble     gwy_data_line_get_rms           (GwyDataLine *data_line);

Computes root mean square value of a data line.

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

gwy_data_line_get_sum ()

gdouble     gwy_data_line_get_sum           (GwyDataLine *data_line);

Computes sum of all values in a 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);

Finds the maximum value of a part of a data line.

data_line : A data line.
from : Index the line part starts at.
to : Index the line part ends at + 1.
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);

Finds the minimum value of a part of a data line.

data_line : A data line.
from : Index the line part starts at.
to : Index the line part ends at + 1.
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);

Computes mean value of all values in a part of a data line.

data_line : A data line.
from : Index the line part starts at.
to : Index the line part ends at + 1.
Returns : Average value within given interval.

gwy_data_line_part_get_rms ()

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

Computes root mean square value of a part of a data line.

data_line : A data line.
from : Index the line part starts at.
to : Index the line part ends at + 1.
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);

Computes sum of all values in a part of a data line.

data_line : A data line.
from : Index the line part starts at.
to : Index the line part ends at + 1.
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 : 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.

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_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 radians)
interpolation : interpolation mode used

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.

data_line : A data line.
i : Pixel coordinate.
Returns : Derivation at given position.

gwy_data_line_fft ()

void        gwy_data_line_fft               (GwyDataLine *ra,
                                             GwyDataLine *ia,
                                             GwyDataLine *rb,
                                             GwyDataLine *ib,
                                             GwyFFTFunc fft,
                                             GwyWindowingType windowing,
                                             GwyTransformDirection 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 data line.
ia : Imaginary input data line.
rb : Real output data line.
ib : Imaginary output data line.
fft : FFT alorithm to use.
windowing : Windowing mode.
direction : FFT direction.
interpolation : Interpolation type.
preserverms : TRUE to preserve RMS value while windowing.
level : TRUE to level line before computation.

gwy_data_line_fft_hum ()

void        gwy_data_line_fft_hum           (GwyTransformDirection direction,
                                             GwyDataLine *ra,
                                             GwyDataLine *ia,
                                             GwyDataLine *rb,
                                             GwyDataLine *ib,
                                             GwyInterpolationType 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 : Index the line part starts at.
to : Index the line part ends at + 1.
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);

Subtracts polynom from a part of a data line;

data_line : A data line.
n : Polynom degree.
coeffs : An array of size n+1 with polynom 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,
                                             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.

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.

Signals

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.

gwydataline : The GwyDataLine which received the signal.
user_data :user data set when the signal handler was connected.