Top | ![]() |
![]() |
![]() |
![]() |
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.
void
gwy_data_field_invalidate (GwyDataField *data_field
);
Invalidates cached data field stats.
User code should rarely need this macro, as all GwyDataField methods do
proper invalidation when they change data, as well as
gwy_data_field_get_data()
does.
However, if you get raw data with gwy_data_field_get_data()
and then mix
direct changes to it with calls to methods like gwy_data_field_get_max()
,
you may need to explicitely invalidate cached values to let
gwy_data_field_get_max()
know it has to recompute the maximum.
#define gwy_data_field_duplicate(data_field)
Convenience macro doing gwy_serializable_duplicate()
with all the necessary
typecasting.
Use gwy_data_field_new_alike()
if you don't want to copy data, only
resolutions and units.
GwyDataField * gwy_data_field_new (gint xres
,gint yres
,gdouble xreal
,gdouble yreal
,gboolean nullme
);
Creates a new data field.
xres |
X-resolution, i.e., the number of columns. |
|
yres |
Y-resolution, i.e., the number of rows. |
|
xreal |
Real horizontal physical dimension. |
|
yreal |
Real vertical physical dimension. |
|
nullme |
Whether the data field should be initialized to zeroes. If |
GwyDataField * gwy_data_field_new_alike (GwyDataField *model
,gboolean nullme
);
Creates a new data field similar to an existing one.
Use gwy_data_field_duplicate()
if you want to copy a data field including
data.
model |
A data field to take resolutions and units from. |
|
nullme |
Whether the data field should be initialized to zeroes. If |
void
gwy_data_field_data_changed (GwyDataField *data_field
);
Emits signal "data-changed" on a data field.
GwyDataField * gwy_data_field_new_resampled (GwyDataField *data_field
,gint xres
,gint yres
,GwyInterpolationType interpolation
);
Creates a new data field by resampling an existing one.
This method is equivalent to gwy_data_field_duplicate()
followed by
gwy_data_field_resample()
, but it is more efficient.
void gwy_data_field_resample (GwyDataField *data_field
,gint xres
,gint yres
,GwyInterpolationType interpolation
);
Resamples a data field using given interpolation method
This method may invalidate raw data buffer returned by
gwy_data_field_get_data()
.
void gwy_data_field_resize (GwyDataField *data_field
,gint ulcol
,gint ulrow
,gint brcol
,gint brrow
);
Resizes (crops) a data field.
Crops a data field to a rectangle between upper-left and bottom-right points, recomputing real size.
This method may invalidate raw data buffer returned by
gwy_data_field_get_data()
.
GwyDataField * gwy_data_field_area_extract (GwyDataField *data_field
,gint col
,gint row
,gint width
,gint height
);
Extracts a rectangular part of a data field to a new data field.
void gwy_data_field_copy (GwyDataField *src
,GwyDataField *dest
,gboolean nondata_too
);
Copies the contents of an already allocated data field to a data field of the same size.
void gwy_data_field_area_copy (GwyDataField *src
,GwyDataField *dest
,gint col
,gint row
,gint width
,gint height
,gint destcol
,gint destrow
);
Copies a rectangular area from one data field to another.
The area starts at (col
, row
) in src
and its dimension is width
*height
.
It is copied to dest
starting from (destcol
, destrow
).
The source area has to be completely contained in src
. No assumptions are
made about destination position, however, parts of the source area sticking
out the destination data field dest
are cut off.
If src
is equal to dest
, the areas may not overlap.
src |
Source data field. |
|
dest |
Destination data field. |
|
col |
Area upper-left column coordinate in |
|
row |
Area upper-left row coordinate |
|
width |
Area width (number of columns), pass -1 for full |
|
height |
Area height (number of rows), pass -1 for full |
|
destcol |
Destination column in |
|
destrow |
Destination row in |
gdouble *
gwy_data_field_get_data (GwyDataField *data_field
);
Gets the raw data buffer of a data field.
The returned buffer is not guaranteed to be valid through whole data
field life time. Some function may change it, most notably
gwy_data_field_resize()
and gwy_data_field_resample()
.
This function invalidates any cached information, use
gwy_data_field_get_data_const()
if you are not going to change the data.
See gwy_data_field_invalidate()
for some discussion.
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].
const gdouble *
gwy_data_field_get_data_const (GwyDataField *data_field
);
Gets the raw data buffer of a data field, read-only.
The returned buffer is not guaranteed to be valid through whole data
field life time. Some function may change it, most notably
gwy_data_field_resize()
and gwy_data_field_resample()
.
Use gwy_data_field_get_data()
if you want to change the data.
See gwy_data_field_invalidate()
for some discussion.
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 *data_field
);
Gets X resolution (number of columns) of a data field.
gint
gwy_data_field_get_yres (GwyDataField *data_field
);
Gets Y resolution (number of rows) of the field.
gdouble
gwy_data_field_get_xreal (GwyDataField *data_field
);
Gets the X real (physical) size of a data field.
gdouble
gwy_data_field_get_yreal (GwyDataField *data_field
);
Gets the Y real (physical) size of a data field.
void gwy_data_field_set_xreal (GwyDataField *data_field
,gdouble xreal
);
Sets X real (physical) size value of a data field.
void gwy_data_field_set_yreal (GwyDataField *data_field
,gdouble yreal
);
Sets Y real (physical) size value of a data field.
#define gwy_data_field_get_xmeasure(data_field)
A convenience macro to calculate gwy_data_field_get_xreal(data_field)/gwy_data_field_get_xres(data_field).
#define gwy_data_field_get_ymeasure(data_field)
A convenience macro to calculate gwy_data_field_get_yreal(data_field)/gwy_data_field_get_yres(data_field).
gdouble
gwy_data_field_get_xoffset (GwyDataField *data_field
);
Gets the X offset of data field origin.
gdouble
gwy_data_field_get_yoffset (GwyDataField *data_field
);
Gets the Y offset of data field origin.
void gwy_data_field_set_xoffset (GwyDataField *data_field
,gdouble xoff
);
Sets the X offset of a data field origin.
Note offsets don't affect any calculation, nor functions like
gwy_data_field_rotj()
.
void gwy_data_field_set_yoffset (GwyDataField *data_field
,gdouble yoff
);
Sets the Y offset of a data field origin.
Note offsets don't affect any calculation, nor functions like
gwy_data_field_rtoi()
.
GwySIUnit *
gwy_data_field_get_si_unit_xy (GwyDataField *data_field
);
Returns lateral SI unit of a data field.
GwySIUnit *
gwy_data_field_get_si_unit_z (GwyDataField *data_field
);
Returns value SI unit of a data field.
void gwy_data_field_set_si_unit_xy (GwyDataField *data_field
,GwySIUnit *si_unit
);
Sets the SI unit corresponding to the lateral (XY) dimensions of a data field.
It does not assume a reference on si_unit
, instead it adds its own
reference.
void gwy_data_field_set_si_unit_z (GwyDataField *data_field
,GwySIUnit *si_unit
);
Sets the SI unit corresponding to the "height" (Z) dimension of a data field.
It does not assume a reference on si_unit
, instead it adds its own
reference.
GwySIValueFormat * gwy_data_field_get_value_format_xy (GwyDataField *data_field
,GwySIUnitFormatStyle style
,GwySIValueFormat *format
);
Finds value format good for displaying coordinates of a data field.
data_field |
A data field. |
|
style |
Unit format style. |
|
format |
A SI value format to modify, or |
The value format. If format
is NULL
, a newly allocated format
is returned, otherwise (modified) format
itself is returned.
GwySIValueFormat * gwy_data_field_get_value_format_z (GwyDataField *data_field
,GwySIUnitFormatStyle style
,GwySIValueFormat *format
);
Finds value format good for displaying values of a data field.
data_field |
A data field. |
|
style |
Unit format style. |
|
format |
A SI value format to modify, or |
The value format. If format
is NULL
, a newly allocated format
is returned, otherwise (modified) format
itself is returned.
void gwy_data_field_copy_units_to_data_line (GwyDataField *data_field
,GwyDataLine *data_line
);
Sets lateral and value units of a data line to match a data field.
void gwy_data_line_copy_units_to_data_field (GwyDataLine *data_line
,GwyDataField *data_field
);
Sets lateral and value units of a data field to match a data line.
gdouble gwy_data_field_itor (GwyDataField *data_field
,gdouble row
);
Transforms vertical pixel coordinate to real (physical) Y coordinate.
That is it maps range [0..y-resolution] to range [0..real-y-size].
It is not suitable for conversion of matrix indices to physical coordinates,
you have to use gwy_data_field_itor(data_field
, row
+ 0.5) for that.
gdouble gwy_data_field_jtor (GwyDataField *data_field
,gdouble col
);
Transforms horizontal pixel coordinate to real (physical) X coordinate.
That is it maps range [0..x-resolution] to range [0..real-x-size].
It is not suitable for conversion of matrix indices to physical coordinates,
you have to use gwy_data_field_jtor(data_field
, col
+ 0.5) for that.
gdouble gwy_data_field_rtoi (GwyDataField *data_field
,gdouble realy
);
Transforms real (physical) Y coordinate to row.
That is it maps range [0..real-y-size] to range [0..y-resolution].
gdouble gwy_data_field_rtoj (GwyDataField *data_field
,gdouble realx
);
Transforms real (physical) X coordinate to column.
That is it maps range [0..real-x-size] to range [0..x-resolution].
gdouble gwy_data_field_get_val (GwyDataField *data_field
,gint col
,gint row
);
Gets value at given position in a data field.
Do not access data with this function inside inner loops, it's slow.
Get the raw data buffer with gwy_data_field_get_data_const()
and access it
directly instead.
void gwy_data_field_set_val (GwyDataField *data_field
,gint col
,gint row
,gdouble value
);
Sets value at given position in a data field.
Do not set data with this function inside inner loops, it's slow. Get the
raw data buffer with gwy_data_field_get_data()
and write to it directly
instead.
gdouble gwy_data_field_get_dval (GwyDataField *data_field
,gdouble x
,gdouble y
,GwyInterpolationType interpolation
);
Gets interpolated value at arbitrary data field point indexed by pixel coordinates.
Note pixel values are centered in pixels, so to get the same
value as gwy_data_field_get_val(data_field
, j
, i
) returns,
it's necessary to add 0.5:
gwy_data_field_get_dval(data_field
, j
+0.5, i
+0.5, interpolation
).
See also gwy_data_field_get_dval_real()
that does the same, but takes
real coordinates.
gdouble gwy_data_field_get_dval_real (GwyDataField *data_field
,gdouble x
,gdouble y
,GwyInterpolationType interpolation
);
Gets interpolated value at arbitrary data field point indexed by real coordinates.
See also gwy_data_field_get_dval()
that does the same, but takes pixel
coordinates.
void gwy_data_field_rotate (GwyDataField *data_field
,gdouble angle
,GwyInterpolationType interpolation
);
Rotates a data field by a given angle.
Values that get outside of data field by the rotation are lost. Undefined values from outside of data field that get inside are set to data field minimum value.
void gwy_data_field_invert (GwyDataField *data_field
,gboolean x
,gboolean y
,gboolean z
);
Reflects amd/or inverts a data field.
In the case of value reflection, it's inverted about the mean value.
void gwy_data_field_fill (GwyDataField *data_field
,gdouble value
);
Fills a data field with given value.
void
gwy_data_field_clear (GwyDataField *data_field
);
Fills a data field with zeroes.
void gwy_data_field_multiply (GwyDataField *data_field
,gdouble value
);
Multiplies all values in a data field by given value.
void gwy_data_field_add (GwyDataField *data_field
,gdouble value
);
Adds given value to all values in a data field.
void gwy_data_field_area_fill (GwyDataField *data_field
,gint col
,gint row
,gint width
,gint height
,gdouble value
);
Fills a rectangular part of a data field with given value.
void gwy_data_field_area_clear (GwyDataField *data_field
,gint col
,gint row
,gint width
,gint height
);
Fills a rectangular part of a data field with zeroes.
void gwy_data_field_area_multiply (GwyDataField *data_field
,gint col
,gint row
,gint width
,gint height
,gdouble value
);
Multiplies values in a rectangular part of a data field by given value
void gwy_data_field_area_add (GwyDataField *data_field
,gint col
,gint row
,gint width
,gint height
,gdouble value
);
Adds given value to all values in a rectangular part of a data field.
GwyDataLine * gwy_data_field_get_profile (GwyDataField *data_field
,GwyDataLine *data_line
,gint scol
,gint srow
,gint ecol
,gint erow
,gint res
,gint thickness
,GwyInterpolationType interpolation
);
Extracts a possibly averaged profile from data field to a data line.
data_field |
A data field. |
|
data_line |
A data line. It will be resized to |
|
scol |
The column the line starts at (inclusive). |
|
srow |
The row the line starts at (inclusive). |
|
ecol |
The column the line ends at (inclusive). |
|
erow |
The row the line ends at (inclusive). |
|
res |
Requested resolution of data line (the number of samples to take).
If nonpositive, data line resolution is chosen to match |
|
thickness |
Thickness of line to be averaged. |
|
interpolation |
Interpolation type to use. |
void gwy_data_field_get_row (GwyDataField *data_field
,GwyDataLine *data_line
,gint row
);
Extracts a data field row into a data line.
void gwy_data_field_get_column (GwyDataField *data_field
,GwyDataLine *data_line
,gint col
);
Extracts a data field column into a data line.
void gwy_data_field_set_row (GwyDataField *data_field
,GwyDataLine *data_line
,gint row
);
Sets a row in the data field to values of a data line.
Data line length must be equal to width of data field.
void gwy_data_field_set_column (GwyDataField *data_field
,GwyDataLine *data_line
,gint col
);
Sets a column in the data field to values of a data line.
Data line length must be equal to height of data field.
void gwy_data_field_get_row_part (GwyDataField *data_field
,GwyDataLine *data_line
,gint row
,gint from
,gint to
);
Extracts part of a data field row into a data line.
void gwy_data_field_get_column_part (GwyDataField *data_field
,GwyDataLine *data_line
,gint col
,gint from
,gint to
);
Extracts part of a data field column into a data line.
void gwy_data_field_set_row_part (GwyDataField *data_field
,GwyDataLine *data_line
,gint row
,gint from
,gint to
);
Puts a data line into a data field row.
If data line length differs from to
-from
, it is resampled to this length.
void gwy_data_field_set_column_part (GwyDataField *data_field
,GwyDataLine *data_line
,gint col
,gint from
,gint to
);
Puts a data line into data field column.
If data line length differs from to
-from
, it is resampled to this length.
gdouble gwy_data_field_get_xder (GwyDataField *data_field
,gint col
,gint row
);
Computes central derivative in X direction.
On border points, one-side derivative is returned.
gdouble gwy_data_field_get_yder (GwyDataField *data_field
,gint col
,gint row
);
Computes central derivative in Y direction.
On border points, one-side derivative is returned.
Note the derivative is for legacy reasons calulcated for the opposite y direction than is usual elsewhere in Gwyddion, i.e. if values increase with increasing row number, the returned value is negative.
gdouble gwy_data_field_get_angder (GwyDataField *data_field
,gint col
,gint row
,gdouble theta
);
Computes derivative in direction specified by given angle.
struct GwyDataField;
The GwyDataField struct contains private data only and should be accessed using the functions below.
“data-changed”
signalvoid user_function (GwyDataField *gwydatafield, gpointer user_data)
The ::data-changed signal is never emitted by data field itself. It is intended as a means to notify others data field users they should update themselves.
gwydatafield |
The GwyDataField which received the signal. |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run First