![]() |
![]() |
Gwyddion Data Processing Library Reference Manual | ![]() |
|
---|---|---|---|---|
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);
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); void (*reserved1)(void); } 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. |
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
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.
gwy_data_field_copy()
, it copies
only data. It will be probably changed.
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 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() .
|
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() .
|
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.
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.
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 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).
|
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.
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. |
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.
|
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) : 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. |