![]() |
![]() |
Gwyddion Data Processing Library Reference Manual | ![]() |
---|
GwyDataLineGwyDataLine — One-dimensional data representation |
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, gdouble *coeffs, gint from, gint to); void gwy_data_line_subtract_polynom (GwyDataLine *data_line, gint n, gdouble *coeffs); void gwy_data_line_cumulate (GwyDataLine *data_line);
GwyDataLine represents 1D data arrays in Gwyddion. It is used for most of the data processing functions connected with 1D data, graphs, etc.
typedef struct _GwyDataLine GwyDataLine;
The GwyDataLine struct contains private data only and should be accessed using the functions below.
typedef struct { GObjectClass parent_class; void (*data_changed)(GwyDataLine *data_line); } GwyDataLineClass;
#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. |
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. |
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. |
void gwy_data_line_data_changed (GwyDataLine *data_line);
Emits signal "data_changed" on a data line.
data_line : | A data line. |
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. |
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. |
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. |
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. |
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(). |
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(). |
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). |
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. |
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 |
gdouble gwy_data_line_get_offset (GwyDataLine *data_line);
Gets the offset of data line origin.
data_line : | A data line. |
Returns : | Offset value. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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). |
void gwy_data_line_clear (GwyDataLine *data_line);
Fills a data line with zeroes.
data_line : | A data line. |
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. |
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. |
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. |
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. |
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. |
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. |
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 |
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 |
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 |
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. |
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. |
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). |
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. |
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). |
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). |
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. |
void gwy_data_line_subtract_polynom (GwyDataLine *data_line, gint n, gdouble *coeffs);
Subtracts polynom from a data line;
data_line : | A data line. |
n : | Polynom degree. |
coeffs : | An array of size n+1 with polynom coefficients to. |
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. |
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. |
<< Gwyddion Data Processing Library Reference Manual | GwyDataField >> |