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);
GwyDataLine*        gwy_data_line_new_resampled         (GwyDataLine *data_line,
                                                         gint res,
                                                         GwyInterpolationType interpolation);
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"                                   : 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_new_resampled ()

GwyDataLine*        gwy_data_line_new_resampled         (GwyDataLine *data_line,
                                                         gint res,
                                                         GwyInterpolationType interpolation);

Creates a new data line by resampling an existing one.

This method is equivalent to gwy_data_line_duplicate() followed by gwy_data_line_resample(), but it is more efficient.

data_line : A data line.
res : Desired resolution.
interpolation : Interpolation method to use.
Returns : A newly created data line.

Since 2.1


gwy_data_line_resample ()

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

Resamples a data line.

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

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

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

gwy_data_line_get_data_const ()

const gdouble*      gwy_data_line_get_data_const        (GwyDataLine *data_line);

Gets the raw data buffer of a data line, read-only.

The returned buffer is not guaranteed to be valid through whole data line life time. Some function may change it, most notably gwy_data_line_resize() and gwy_data_line_resample().

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

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.