![]() |
![]() |
Gwyddion Data Processing Library Reference Manual | ![]() |
|
---|---|---|---|---|
Top | Description | Object Hierarchy | Implemented Interfaces | Signals |
#include <libprocess/gwyprocess.h> struct GwyDataLine; struct 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_rotate (GwyDataLine *data_line
,gdouble angle
,GwyInterpolationType interpolation
); 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
); void gwy_data_line_sqrt (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.
struct GwyDataLine;
The GwyDataLine struct contains private data only and should be accessed using the functions below.
struct GwyDataLineClass { GObjectClass parent_class; void (*data_changed)(GwyDataLine *data_line); void (*reserved1)(void); };
#define gwy_data_line_duplicate(data_line)
Convenience macro doing gwy_serializable_duplicate()
with all the necessary
typecasting.
|
A data line to duplicate. |
GwyDataLine * gwy_data_line_new (gint res
,gdouble real
,gboolean nullme
);
Creates a new data line.
|
Resolution, i.e., the number of samples. |
|
Real physical dimension. |
|
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.
|
A data line to take resolutions and units from. |
|
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.
|
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.
|
A data line. |
|
Desired resolution. |
|
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.
|
A data line. |
|
Desired resolution. |
|
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.
|
A data line. |
|
Where to start. |
|
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.
|
A data line. |
|
Where to start. |
|
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.
|
Source data line. |
|
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.
|
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.
|
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.
|
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.
|
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.
|
A data line. |
|
value to be set |
gdouble gwy_data_line_get_offset (GwyDataLine *data_line
);
Gets the offset of data line origin.
|
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()
.
|
A data line. |
|
New offset value. |
GwySIUnit * gwy_data_line_get_si_unit_x (GwyDataLine *data_line
);
Returns lateral SI unit of a 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.
|
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.
|
A data line. |
|
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.
|
A data line. |
|
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.
|
A data line. |
|
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].
|
A data line. |
|
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.
|
A data line. |
|
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.
|
A data line. |
|
Position in the line (index). |
|
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.
|
A data line. |
|
Position in data line in range [0, resolution]. If the value is outside this range, the nearest border value is returned. |
|
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.
|
A data line. |
|
real coordinates position |
|
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.
|
A data line. |
|
Whether to invert data point order. |
|
Whether to invert in Z direction (i.e., invert values). |
void gwy_data_line_clear (GwyDataLine *data_line
);
Fills a data line with zeroes.
|
A data line. |
void gwy_data_line_fill (GwyDataLine *data_line
,gdouble value
);
Fills a data line with specified value.
|
A data line. |
|
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.
|
A data line. |
|
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.
|
A data line. |
|
Value to be added. |
void gwy_data_line_part_clear (GwyDataLine *data_line
,gint from
,gint to
);
Fills a data line part with zeroes.
|
A data line. |
|
Index the line part starts at. |
|
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
|
A data line. |
|
Index the line part starts at. |
|
Index the line part ends at + 1. |
|
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.
|
A data line. |
|
Index the line part starts at. |
|
Index the line part ends at + 1. |
|
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.
|
A data line. |
|
Index the line part starts at. |
|
Index the line part ends at + 1. |
|
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
|
A data line. |
|
Threshold value. |
|
Lower replacement value. |
|
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.
|
A data line. |
|
Index the line part starts at. |
|
Index the line part ends at + 1. |
|
Threshold value. |
|
Lower replacement value. |
|
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);
|
A data line. |
|
Height coefficient. |
|
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.
|
A data line. |
|
Height coefficient. |
|
Slope coefficient. |
void gwy_data_line_rotate (GwyDataLine *data_line
,gdouble angle
,GwyInterpolationType interpolation
);
Performs line rotation.
This is operation similar to leveling, but it does not change the angles between line segments (on the other hand it introduces other deformations due to discretization).
|
A data line. |
|
Angle of rotation (in radians), counterclockwise. |
|
Interpolation method to use (can be only of two-point type). |
Since 2.7
void gwy_data_line_line_rotate (GwyDataLine *data_line
,gdouble angle
,gint interpolation
);
gwy_data_line_line_rotate
is deprecated and should not be used in newly-written code.
Performs line rotation.
Use gwy_data_line_rotate()
instead.
|
A data line. |
|
Angle of rotation (in radians), counterclockwise. |
|
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.
|
A data line. |
|
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.
|
A data line. |
|
Polynom degree. |
|
An array of size n +1 to store the coefficients to, or NULL
(a fresh array is allocated then). |
|
Index the line part starts at. |
|
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.
|
A data line. |
|
Polynom degree. |
|
An array of size n +1 with polynomial coefficients to. |
|
Index the line part starts at. |
|
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.
|
A data line. |
|
Polynom degree. |
|
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.
|
A data line. |
void gwy_data_line_sqrt (GwyDataLine *data_line
);
Applies sqrt()
to each element in a data line.
|
A data line. |
"data-changed"
signalvoid 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.
|
The GwyDataLine which received the signal. |
|
user data set when the signal handler was connected. |