GwyDataLine

GwyDataLine — One-dimensional data representation

Synopsis




            GwyDataLine;
            GwyDataLineClass;
#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);
GwyDataLine* gwy_data_line_part_extract     (GwyDataLine *data_line,
                                             gint from,
                                             gint len);
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_get_offset        (GwyDataLine *data_line);
void        gwy_data_line_set_offset        (GwyDataLine *data_line,
                                             gdouble offset);
GwySIUnit*  gwy_data_line_get_si_unit_x     (GwyDataLine *data_line);
GwySIUnit*  gwy_data_line_get_si_unit_y     (GwyDataLine *data_line);
void        gwy_data_line_set_si_unit_x     (GwyDataLine *data_line,
                                             GwySIUnit *si_unit);
void        gwy_data_line_set_si_unit_y     (GwyDataLine *data_line,
                                             GwySIUnit *si_unit);
GwySIValueFormat* gwy_data_line_get_value_format_x
                                            (GwyDataLine *data_line,
                                             GwySIUnitFormatStyle style,
                                             GwySIValueFormat *format);
GwySIValueFormat* gwy_data_line_get_value_format_y
                                            (GwyDataLine *data_line,
                                             GwySIUnitFormatStyle style,
                                             GwySIValueFormat *format);
gdouble     gwy_data_line_itor              (GwyDataLine *data_line,
                                             gdouble pixpos);
gdouble     gwy_data_line_rtoi              (GwyDataLine *data_line,
                                             gdouble realpos);
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_clear             (GwyDataLine *data_line);
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_clear        (GwyDataLine *data_line,
                                             gint from,
                                             gint to);
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);
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_get_line_coeffs   (GwyDataLine *data_line,
                                             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);
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,
                                             const gdouble *coeffs,
                                             gint from,
                                             gint to);
void        gwy_data_line_subtract_polynom  (GwyDataLine *data_line,
                                             gint n,
                                             const gdouble *coeffs);
void        gwy_data_line_cumulate          (GwyDataLine *data_line);

Object Hierarchy


  GObject
   +----GwyDataLine

Implemented Interfaces

GwyDataLine implements GwySerializable.

Signals


"data-changed"
            void        user_function      (GwyDataLine *gwydataline,
                                            gpointer     user_data)        : Run first

Description

GwyDataLine 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);
    void (*reserved1)(void);
} GwyDataLineClass;


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

Creates a new data line.

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.

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.

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

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

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

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.

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

gdouble     gwy_data_line_get_offset        (GwyDataLine *data_line);

Gets the offset of data line origin.

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

data_line : A data line.
offset : New offset value.

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.

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.

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.

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" (Z) dimension of a data line.

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

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.

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.

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

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

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.

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.

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.

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.

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

void        gwy_data_line_clear             (GwyDataLine *data_line);

Fills a data line with zeroes.

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.

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

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

Fills a data line part with zeroes.

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

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

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.

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 it does not change the angles between line segments.

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.

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.

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

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.

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.

data_line : A data line.

Signal Details

The "data-changed" signal

void        user_function                  (GwyDataLine *gwydataline,
                                            gpointer     user_data)        : Run first

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.