![]() | ![]() | Gwyddion Data Processing Library Reference Manual | ![]() |
---|
GwyDataField — Array representing 2D data
struct GwyDataField; struct GwyDataFieldClass; enum GwyComputationStateType; GObject* gwy_data_field_new (gint xres, gint yres, gdouble xreal, gdouble yreal, gboolean nullme); void gwy_data_field_resample (GwyDataField *a, gint xres, gint yres, GwyInterpolationType interpolation); gboolean gwy_data_field_resize (GwyDataField *a, gint ulcol, gint ulrow, gint brcol, gint brrow); gboolean gwy_data_field_copy (GwyDataField *a, GwyDataField *b); gboolean gwy_data_field_area_copy (GwyDataField *src, GwyDataField *dest, gint ulcol, gint ulrow, gint brcol, gint brrow, gint destcol, gint destrow); gdouble* gwy_data_field_get_data (GwyDataField *a); gint gwy_data_field_get_xres (GwyDataField *a); gint gwy_data_field_get_yres (GwyDataField *a); gdouble gwy_data_field_get_xreal (GwyDataField *a); gdouble gwy_data_field_get_yreal (GwyDataField *a); void gwy_data_field_set_xreal (GwyDataField *a, gdouble xreal); void gwy_data_field_set_yreal (GwyDataField *a, gdouble yreal); GwySIUnit* gwy_data_field_get_si_unit_xy (GwyDataField *a); GwySIUnit* gwy_data_field_get_si_unit_z (GwyDataField *a); void gwy_data_field_set_si_unit_xy (GwyDataField *a, GwySIUnit *si_unit); void gwy_data_field_set_si_unit_z (GwyDataField *a, GwySIUnit *si_unit); GwySIValueFormat* gwy_data_field_get_value_format_xy (GwyDataField *data_field, GwySIValueFormat *format); GwySIValueFormat* gwy_data_field_get_value_format_z (GwyDataField *data_field, GwySIValueFormat *format); gdouble gwy_data_field_itor (GwyDataField *a, gdouble pixval); gdouble gwy_data_field_jtor (GwyDataField *a, gdouble pixval); gdouble gwy_data_field_rtoi (GwyDataField *a, gdouble realval); gdouble gwy_data_field_rtoj (GwyDataField *a, gdouble realval); gboolean gwy_data_field_outside (GwyDataField *a, gint col, gint row); gdouble gwy_data_field_get_val (GwyDataField *a, gint col, gint row); void gwy_data_field_set_val (GwyDataField *a, gint col, gint row, gdouble value); gdouble gwy_data_field_get_dval (GwyDataField *a, gdouble x, gdouble y, GwyInterpolationType interpolation); gdouble gwy_data_field_get_dval_real (GwyDataField *a, gdouble x, gdouble y, GwyInterpolationType interpolation); void gwy_data_field_rotate (GwyDataField *a, gdouble angle, GwyInterpolationType interpolation); void gwy_data_field_invert (GwyDataField *a, gboolean x, gboolean y, gboolean z); void gwy_data_field_fill (GwyDataField *a, gdouble value); void gwy_data_field_multiply (GwyDataField *a, gdouble value); void gwy_data_field_add (GwyDataField *a, gdouble value); void gwy_data_field_area_fill (GwyDataField *a, gint ulcol, gint ulrow, gint brcol, gint brrow, gdouble value); void gwy_data_field_area_multiply (GwyDataField *a, gint ulcol, gint ulrow, gint brcol, gint brrow, gdouble value); void gwy_data_field_area_add (GwyDataField *a, gint ulcol, gint ulrow, gint brcol, gint brrow, gdouble value); gint gwy_data_field_threshold (GwyDataField *a, gdouble threshval, gdouble bottom, gdouble top); gint gwy_data_field_area_threshold (GwyDataField *a, gint ulcol, gint ulrow, gint brcol, gint brrow, gdouble threshval, gdouble bottom, gdouble top); gint gwy_data_field_clamp (GwyDataField *a, gdouble bottom, gdouble top); gint gwy_data_field_area_clamp (GwyDataField *a, gint ulcol, gint ulrow, gint brcol, gint brrow, gdouble bottom, gdouble top); gboolean gwy_data_field_get_data_line (GwyDataField *a, GwyDataLine *b, gint ulcol, gint ulrow, gint brcol, gint brrow, gint res, GwyInterpolationType interpolation); gboolean gwy_data_field_get_data_line_averaged (GwyDataField *a, GwyDataLine *b, gint ulcol, gint ulrow, gint brcol, gint brrow, gint res, gint thickness, GwyInterpolationType interpolation); void gwy_data_field_get_row (GwyDataField *a, GwyDataLine *b, gint row); void gwy_data_field_get_column (GwyDataField *a, GwyDataLine *b, gint col); void gwy_data_field_set_row (GwyDataField *a, GwyDataLine *b, gint row); void gwy_data_field_set_column (GwyDataField *a, GwyDataLine *b, gint col); void gwy_data_field_get_row_part (GwyDataField *a, GwyDataLine *b, gint row, gint from, gint to); void gwy_data_field_get_column_part (GwyDataField *a, GwyDataLine *b, gint col, gint from, gint to); gdouble gwy_data_field_get_xder (GwyDataField *a, gint col, gint row); gdouble gwy_data_field_get_yder (GwyDataField *a, gint col, gint row); gdouble gwy_data_field_get_angder (GwyDataField *a, gint col, gint row, gdouble theta); void gwy_data_field_shade (GwyDataField *data_field, GwyDataField *target_field, gdouble theta, gdouble phi); void gwy_data_field_fit_lines (GwyDataField *data_field, gint ulcol, gint ulrow, gint brcol, gint brrow, GwyFitLineType fit_type, gboolean exclude, GtkOrientation orientation);
GwyDataField is an object that is used for representation of all two-dimensional data matrices. Most of the basic data handling and processing functions in Gwyddion are declared here as they are connected with GwyDataField.
typedef enum { GWY_COMP_INIT = 0, /*start initializations*/ GWY_COMP_ITERATE = 1, /*locate steps*/ GWY_COMP_FINISHED = 2 } GwyComputationStateType;
GObject* gwy_data_field_new (gint xres, gint yres, gdouble xreal, gdouble yreal, gboolean nullme);
xres : | |
yres : | |
xreal : | |
yreal : | |
nullme : | |
Returns : |
void gwy_data_field_resample (GwyDataField *a, gint xres, gint yres, GwyInterpolationType interpolation);
Resamples GwyDataField using given interpolation method
a : | A data field to be resampled |
xres : | desired X resolution |
yres : | desired Y resolution |
interpolation : | interpolation method |
gboolean gwy_data_field_resize (GwyDataField *a, gint ulcol, gint ulrow, gint brcol, gint brrow);
Resizes (crops) the GwyDataField.
Extracts part of the GwyDataField.between upper-left and bottom-right points.
a : | A data field to be resized |
ulcol : | upper-left column coordinate |
ulrow : | upper-left row coordinate |
brcol : | bottom-right column coordinate (exclusive) |
brrow : | bottom-right row coordinate (exclusive) |
Returns : | TRUE on success. |
gboolean gwy_data_field_copy (GwyDataField *a, GwyDataField *b);
Copies the contents of an already allocated data field to a data field of the same size.
a : | source data field. |
b : | destination data field. |
Returns : |
gboolean gwy_data_field_area_copy (GwyDataField *src, GwyDataField *dest, gint ulcol, gint ulrow, gint brcol, gint brrow, gint destcol, gint destrow);
Copies a rectangular area from src to dest.
The area starts at (ulcol, ulrow) in src and ends at (brcol, brrow) (noninclusive). It is copied to dest starting from (destcol, destrow).
There must be enough room in the destination data field, areas sticking out are rejected. If src is equal to dest, the areas may not overlap.
src : | Source data field. |
dest : | Destination data field. |
ulcol : | Starting column. |
ulrow : | Starting row. |
brcol : | Ending column (noninclusive). |
brrow : | Ending row (noninclusive). |
destcol : | Destination column. |
destrow : | Destination row. |
Returns : | Whether it succeeded (area sizes OK). |
gdouble* gwy_data_field_get_data (GwyDataField *a);
Get the data of the field.
a : | A data field |
Returns : | The data field as a pointer to an array of gwy_data_field_get_xres()*gwy_data_field_get_yres() gdouble's, ordered by lines. I.e., they are to be accessed as data[row*xres + column]. |
gint gwy_data_field_get_xres (GwyDataField *a);
Get X resolution of the field.
a : | A data field |
Returns : | X resolution |
gint gwy_data_field_get_yres (GwyDataField *a);
Get Y resolution of the field.
a : | A data field |
Returns : | Y resolution |
gdouble gwy_data_field_get_xreal (GwyDataField *a);
Get the X real size value
a : | A data field |
Returns : | X real size value |
gdouble gwy_data_field_get_yreal (GwyDataField *a);
Get the Y real size value
a : | A data field |
Returns : | Y real size value |
void gwy_data_field_set_xreal (GwyDataField *a, gdouble xreal);
Set the X real size value
a : | A data field |
xreal : | new X real size value |
void gwy_data_field_set_yreal (GwyDataField *a, gdouble yreal);
Set the Y real size value
a : | A data field |
yreal : | new Y real size value |
GwySIUnit* gwy_data_field_get_si_unit_xy (GwyDataField *a);
a : | A data field |
Returns : | SI unit corresponding to the lateral (XY) dimensions of the field |
GwySIUnit* gwy_data_field_get_si_unit_z (GwyDataField *a);
a : | A data field |
Returns : | SI unit corresponding to the "height" (Z) dimension of the field |
void gwy_data_field_set_si_unit_xy (GwyDataField *a, GwySIUnit *si_unit);
Sets the SI unit corresponding to the lateral (XY) dimensions of the field.
a : | A data field |
si_unit : | SI unit to be set |
void gwy_data_field_set_si_unit_z (GwyDataField *a, GwySIUnit *si_unit);
Sets the SI unit corresponding to the "height" (Z) dimension of the field.
a : | A data field |
si_unit : | SI unit to be set |
GwySIValueFormat* gwy_data_field_get_value_format_xy (GwyDataField *data_field, GwySIValueFormat *format);
Finds value format good for displaying coordinates of data_field.
data_field : | A data field. |
format : | A SI value format to modify, or NULL to allocate a new one. |
Returns : | The value format. If format was NULL, a newly allocated format is returned, otherwise (modified) format itself is returned. |
GwySIValueFormat* gwy_data_field_get_value_format_z (GwyDataField *data_field, GwySIValueFormat *format);
Finds value format good for displaying values of data_field.
data_field : | A data field. |
format : | A SI value format to modify, or NULL to allocate a new one. |
Returns : | The value format. If format was NULL, a newly allocated format is returned, otherwise (modified) format itself is returned. |
gdouble gwy_data_field_itor (GwyDataField *a, gdouble pixval);
recomputes row pixel coordinate to real coordinate
a : | A data field |
pixval : | value at data (pixel) coordinates |
Returns : | recomputed value |
gdouble gwy_data_field_jtor (GwyDataField *a, gdouble pixval);
recomputes column real coordinate to pixel coordinate
Note: for field represented by square grid (same distance between adjacent pixels in X and Y dimension, the functions gwy_data_field_itor() and gwy_data_field_jtor() are identical.
a : | A data field |
pixval : | value at real coordinates |
Returns : | recomputed value |
gdouble gwy_data_field_rtoi (GwyDataField *a, gdouble realval);
recomputes row real coordinate to pixel coordinate
a : | A data field |
realval : | value at real coordinates |
Returns : | recomputed value |
gdouble gwy_data_field_rtoj (GwyDataField *a, gdouble realval);
recomputes column real coordinate to pixel coordinate
a : | A data field |
realval : | value at real coordinates |
Returns : | recomputed value |
gboolean gwy_data_field_outside (GwyDataField *a, gint col, gint row);
a : | |
col : | |
row : | |
Returns : |
gdouble gwy_data_field_get_val (GwyDataField *a, gint col, gint row);
Get value at given pixel
a : | A data field |
col : | column position |
row : | row position |
Returns : | value at (i, j) |
void gwy_data_field_set_val (GwyDataField *a, gint col, gint row, gdouble value);
Set value at given pixel
a : | A data field |
col : | column position |
row : | row position |
value : | value to set |
gdouble gwy_data_field_get_dval (GwyDataField *a, gdouble x, gdouble y, GwyInterpolationType interpolation);
Interpolates to extract a value of the field in arbitrary position.
a : | A data field |
x : | x position |
y : | y postition |
interpolation : | interpolation method to be used |
Returns : | value at the position (x,y). |
gdouble gwy_data_field_get_dval_real (GwyDataField *a, gdouble x, gdouble y, GwyInterpolationType interpolation);
Get value at arbitrary point given by real values.
See also gwy_data_field_get_dval() that does the same for arbitrary point given by data (pixel) coordinate values.
a : | A data field |
x : | x postion in real coordinates |
y : | y postition in real coordinates |
interpolation : | interpolation method |
Returns : | value at point x, y |
void gwy_data_field_rotate (GwyDataField *a, gdouble angle, GwyInterpolationType interpolation);
Rotates field by a given angle.
The values that will be outside of square after rotation will be lost. The new unknown values will be set to field minimum value.
a : | A data field |
angle : | angle (in degrees) |
interpolation : | interpolation method |
void gwy_data_field_invert (GwyDataField *a, gboolean x, gboolean y, gboolean z);
Make requested inversion(s).
a : | pointer fo field |
x : | invert in X direction? |
y : | invert in Y direction? |
z : | invert in Z direction? |
void gwy_data_field_fill (GwyDataField *a, gdouble value);
Fill GwyDataField with given value
a : | A data field |
value : | value to be entered |
void gwy_data_field_multiply (GwyDataField *a, gdouble value);
Multiply GwyDataField by given value.
a : | A data field |
value : | value to be used for multiplication |
void gwy_data_field_add (GwyDataField *a, gdouble value);
Add given value to GwyDataField
a : | A data field |
value : | value to be added |
void gwy_data_field_area_fill (GwyDataField *a, gint ulcol, gint ulrow, gint brcol, gint brrow, gdouble value);
Fill a specified part of the field witha given value
a : | A data field |
ulcol : | upper-left column coordinate |
ulrow : | upper-left row coordinate |
brcol : | bottom-right column coordinate + 1 |
brrow : | bottom-right row coordinate + 1 |
value : | value to be entered |
void gwy_data_field_area_multiply (GwyDataField *a, gint ulcol, gint ulrow, gint brcol, gint brrow, gdouble value);
Multiply a specified part of the field by the given value
a : | A data field |
ulcol : | upper-left column coordinate |
ulrow : | upper-left row coordinate |
brcol : | bottom-right column coordinate + 1 |
brrow : | bottom-right row coordinate + 1 |
value : | value to be used |
void gwy_data_field_area_add (GwyDataField *a, gint ulcol, gint ulrow, gint brcol, gint brrow, gdouble value);
Add the given value to a specified part of the field
a : | A data field |
ulcol : | upper-left column coordinate |
ulrow : | upper-left row coordinate |
brcol : | bottom-right column coordinate + 1 |
brrow : | bottom-right row coordinate + 1 |
value : | value to be used |
gint gwy_data_field_threshold (GwyDataField *a, gdouble threshval, gdouble bottom, gdouble top);
Tresholds values of GwyDataField. Values smaller than threshold will be set to value bottom, values higher than threshold or equal to it will be set to value top
a : | A data field |
threshval : | threshold value |
bottom : | lower value |
top : | upper value |
Returns : | total number of values above threshold. |
gint gwy_data_field_area_threshold (GwyDataField *a, gint ulcol, gint ulrow, gint brcol, gint brrow, gdouble threshval, gdouble bottom, gdouble top);
a : | |
ulcol : | |
ulrow : | |
brcol : | |
brrow : | |
threshval : | |
bottom : | |
top : | |
Returns : |
gint gwy_data_field_clamp (GwyDataField *a, gdouble bottom, gdouble top);
Limits data field values to the range [bottom, top].
a : | A data field |
bottom : | Lower limit value. |
top : | Upper limit value. |
Returns : | The number of changed values. |
gint gwy_data_field_area_clamp (GwyDataField *a, gint ulcol, gint ulrow, gint brcol, gint brrow, gdouble bottom, gdouble top);
Limits values in a rectangular part of a data field to the range [bottom, top].
a : | A data field |
ulcol : | Upper-left column coordinate (inclusive). |
ulrow : | Upper-left row coordinate (inclusive). |
brcol : | Bottom-right column coordinate (exclusive). |
brrow : | Bottom-right row coordinate (exclusive). |
bottom : | Lower limit value. |
top : | Upper limit value. |
Returns : | The number of changed values. |
gboolean gwy_data_field_get_data_line (GwyDataField *a, GwyDataLine *b, gint ulcol, gint ulrow, gint brcol, gint brrow, gint res, GwyInterpolationType interpolation);
Extracts a profile from data field and puts it into data line. It is expected that the data line is allready allocated.
a : | A data field |
b : | A data line |
ulcol : | upper-left column coordinate |
ulrow : | upper-left row coordinate |
brcol : | bottom-right column coordinate + 1 |
brrow : | bottom-right row coordinate + 1 |
res : | requested resolution of data line |
interpolation : | interpolation type |
Returns : | true at success |
gboolean gwy_data_field_get_data_line_averaged (GwyDataField *a, GwyDataLine *b, gint ulcol, gint ulrow, gint brcol, gint brrow, gint res, gint thickness, GwyInterpolationType interpolation);
Extracts an averaged profile from data field and puts it into data line. It is expected that the data line is allready allocated.
a : | A data field |
b : | A data line |
ulcol : | upper-left column coordinate |
ulrow : | upper-left row coordinate |
brcol : | bottom-right column coordinate + 1 |
brrow : | bottom-right row coordinate + 1 |
res : | requested resolution of data line |
thickness : | thickness of line to be averaged |
interpolation : | interpolation type |
Returns : | TRUE on success. |
Since 1.2
void gwy_data_field_get_row (GwyDataField *a, GwyDataLine *b, gint row);
Extracts row into data line. Data line should be allocated allready.
a : | A data field |
b : | A data line |
row : | index of row |
void gwy_data_field_get_column (GwyDataField *a, GwyDataLine *b, gint col);
Extracts column into data line. Data line should be allocated allready.
a : | A data field |
b : | A data line |
col : | index of column |
void gwy_data_field_set_row (GwyDataField *a, GwyDataLine *b, gint row);
Sets the row in the data field to values of data line.
a : | A data field |
b : | A data line |
row : | index of row |
void gwy_data_field_set_column (GwyDataField *a, GwyDataLine *b, gint col);
Sets the column in the data field to values of data line.
a : | A data field |
b : | A data line |
col : | index of column |
void gwy_data_field_get_row_part (GwyDataField *a, GwyDataLine *b, gint row, gint from, gint to);
Extracts row part into data line. Data line should be allocated allready.
a : | A data field |
b : | A data line |
row : | index of row |
from : | beginning index |
to : | end index |
void gwy_data_field_get_column_part (GwyDataField *a, GwyDataLine *b, gint col, gint from, gint to);
Extracts column part into data line. Data line should be allocated allready.
a : | A data field |
b : | A data line |
col : | index of column |
from : | beginning index |
to : | end index |
gdouble gwy_data_field_get_xder (GwyDataField *a, gint col, gint row);
Computes derivative in x-direction.
a : | A data field |
col : | column coordinate |
row : | row coordinate |
Returns : | Derivative in x-direction |
gdouble gwy_data_field_get_yder (GwyDataField *a, gint col, gint row);
Computes derivative in y-direction.
a : | A data field |
col : | column coordinate |
row : | row coordinate |
Returns : | Derivative in y-direction |
gdouble gwy_data_field_get_angder (GwyDataField *a, gint col, gint row, gdouble theta);
Computes derivative in direction specified by given angle. Angle is given in degrees.
a : | A data field |
col : | column coordinate |
row : | row coordinate |
theta : | angle specifying direction |
Returns : | Derivative in direction given by angle theta |
void gwy_data_field_shade (GwyDataField *data_field, GwyDataField *target_field, gdouble theta, gdouble phi);
Creates a shaded data field. Target field should be allready allocated.
data_field : | A data field |
target_field : | A shaded data field |
theta : | shading angle |
phi : | shading angle |
void gwy_data_field_fit_lines (GwyDataField *data_field, gint ulcol, gint ulrow, gint brcol, gint brrow, GwyFitLineType fit_type, gboolean exclude, GtkOrientation orientation);
data_field : | |
ulcol : | |
ulrow : | |
brcol : | |
brrow : | |
fit_type : | |
exclude : | |
orientation : |
<< GwyDataLine | cdline >> |