|
Gwyfile Library
|
Functions | |
| GwyfileObject * | gwyfile_object_new_datafield (int xres, int yres, double xreal, double yreal,...) |
Creates a new GWY file GwyDataField object. More... | |
| bool | gwyfile_object_datafield_get (const GwyfileObject *object, GwyfileError **error,...) |
Obtains information and/or data from a GWY file GwyDataField object. More... | |
| GwyfileObject * | gwyfile_object_new_dataline (int res, double real,...) |
Creates a new GWY file GwyDataLine object. More... | |
| bool | gwyfile_object_dataline_get (const GwyfileObject *object, GwyfileError **error,...) |
Obtains information and/or data from a GWY file GwyDataLine object. More... | |
| GwyfileObject * | gwyfile_object_new_brick (int xres, int yres, int zres, double xreal, double yreal, double zreal,...) |
Creates a new GWY file GwyBrick object. More... | |
| bool | gwyfile_object_brick_get (const GwyfileObject *object, GwyfileError **error,...) |
Obtains information and/or data from a GWY file GwyBrick object. More... | |
| GwyfileObject * | gwyfile_object_new_surface (int n,...) |
Creates a new GWY file GwySurface object. More... | |
| bool | gwyfile_object_surface_get (const GwyfileObject *object, GwyfileError **error,...) |
Obtains information and/or data from a GWY file GwySurface object. More... | |
| GwyfileObject * | gwyfile_object_new_lawn (int xres, int yres, int ncurves, double xreal, double yreal,...) |
Creates a new GWY file GwyLawn object. More... | |
| bool | gwyfile_object_lawn_get (const GwyfileObject *object, GwyfileError **error,...) |
Obtains information and/or data from a GWY file GwyLawn object. More... | |
| GwyfileObject * | gwyfile_object_new_spectra (int ncurves, GwyfileObject **curves,...) |
Creates a new GWY file GwySpectra object. More... | |
| bool | gwyfile_object_spectra_get (const GwyfileObject *object, GwyfileError **error,...) |
Obtains information and/or data from a GWY file GwySpectra object. More... | |
| GwyfileObject * | gwyfile_object_new_graphmodel (int ncurves,...) |
Creates a new GWY file GwyGraphModel object. More... | |
| bool | gwyfile_object_graphmodel_get (const GwyfileObject *object, GwyfileError **error,...) |
Obtains information and/or data from a GWY file GwyGraphModel object. More... | |
| GwyfileObject * | gwyfile_object_new_graphcurvemodel (int ndata,...) |
Creates a new GWY file GwyGraphCurveModel object. More... | |
| bool | gwyfile_object_graphcurvemodel_get (const GwyfileObject *object, GwyfileError **error,...) |
Obtains information and/or data from a GWY file GwyGraphCurveModel object. More... | |
| GwyfileObject * | gwyfile_object_new_selectionpoint (int nsel,...) |
Creates a new GWY file GwySelectionPoint object. More... | |
| bool | gwyfile_object_selectionpoint_get (const GwyfileObject *object, GwyfileError **error,...) |
Obtains information and/or data from a GWY file GwySelectionPoint object. More... | |
| GwyfileObject * | gwyfile_object_new_selectioncross (int nsel,...) |
Creates a new GWY file GwySelectionCross object. More... | |
| bool | gwyfile_object_selectioncross_get (const GwyfileObject *object, GwyfileError **error,...) |
Obtains information and/or data from a GWY file GwySelectionCross object. More... | |
| GwyfileObject * | gwyfile_object_new_selectionline (int nsel,...) |
Creates a new GWY file GwySelectionLine object. More... | |
| bool | gwyfile_object_selectionline_get (const GwyfileObject *object, GwyfileError **error,...) |
Obtains information and/or data from a GWY file GwySelectionLine object. More... | |
| GwyfileObject * | gwyfile_object_new_selectionrectangle (int nsel,...) |
Creates a new GWY file GwySelectionRectangle object. More... | |
| bool | gwyfile_object_selectionrectangle_get (const GwyfileObject *object, GwyfileError **error,...) |
Obtains information and/or data from a GWY file GwySelectionRectangle object. More... | |
| GwyfileObject * | gwyfile_object_new_selectionellipse (int nsel,...) |
Creates a new GWY file GwySelectionEllipse object. More... | |
| bool | gwyfile_object_selectionellipse_get (const GwyfileObject *object, GwyfileError **error,...) |
Obtains information and/or data from a GWY file GwySelectionEllipse object. More... | |
| GwyfileObject * | gwyfile_object_new_selectionlattice (int nsel,...) |
Creates a new GWY file GwySelectionLattice object. More... | |
| bool | gwyfile_object_selectionlattice_get (const GwyfileObject *object, GwyfileError **error,...) |
Obtains information and/or data from a GWY file GwySelectionLattice object. More... | |
| GwyfileObject * | gwyfile_object_new_selectionprojective (int nsel,...) |
Creates a new GWY file GwySelectionProjective object. More... | |
| bool | gwyfile_object_selectionprojective_get (const GwyfileObject *object, GwyfileError **error,...) |
Obtains information and/or data from a GWY file GwySelectionProjective object. More... | |
| GwyfileObject * | gwyfile_object_new_selectionaxis (int nsel, int orientation,...) |
Creates a new GWY file GwySelectionAxis object. More... | |
| bool | gwyfile_object_selectionaxis_get (const GwyfileObject *object, GwyfileError **error,...) |
Obtains information and/or data from a GWY file GwySelectionAxis object. More... | |
| GwyfileObject * | gwyfile_object_new_selectionpath (int nsel, double slackness, bool closed,...) |
Creates a new GWY file GwySelectionPath object. More... | |
| bool | gwyfile_object_selectionpath_get (const GwyfileObject *object, GwyfileError **error,...) |
Obtains information and/or data from a GWY file GwySelectionPath object. More... | |
| GwyfileObject * | gwyfile_object_new_siunit (const char *unitstr) |
Creates a new GWY file GwySIUnit object. More... | |
| bool | gwyfile_object_siunit_get (const GwyfileObject *object, GwyfileError **error,...) |
Obtains information and/or data from a GWY file GwySIUnit object. More... | |
Convenience constructors and information extractors are available for most types of Gwyddion objects.
No constructor is provided for GwyContainer because it is a generic data container with no mandatory items so gwyfile_object_new() works just fine. Use the application-level functions to manage channels, graph or volume data inside a GwyContainer representing a GWY file.
Furthermore, classes such as GwyCalData, Gwy3DSetup and GwyStringList are too specialised to warrant convenience constructors.
The convenience information extractors paper over less serious conformance problems, such as missing or non-positive real field dimensions, and return sane and safe default values. They also supply defaults for optional data items. This is what one usually wants from a convenience function. The raw truth can be obtained by the low-level object and item interface.
| bool gwyfile_object_brick_get | ( | const GwyfileObject * | object, |
| GwyfileError ** | error, | ||
| ... | |||
| ) |
Obtains information and/or data from a GWY file GwyBrick object.
The function checks if the object type is actually "GwyBrick" and if it contains sane data items. Every GwyBrick must contain at least the pixel resolutions "xres", "yres" and "zres" and a matching array of doubles "data" of the corresponding size.
If object does not seem to represent a valid GwyBrick object the function fails, does not fill any output arguments (beside the error) and returns false.
All other items have default values that will be returned if the corresponding item is not found, is of the wrong type or has an invalid value (e.g. NaN physical dimension). Unknown additional items are simply ignored. The function does not fail in these cases and returns true.
Possible items to request:
"data" – array of doubles of size xres × yres × zres. The array ownership does not change (as if gwyfile_item_get_double_array() was used)."data(take)" – array of doubles of size xres × yres × zres. The array ownership is transferred to the caller (as if gwyfile_item_take_double_array() was used) who has to free it with free() later. Taking the data is not permitted if they are not owned by the data item. Hence you may request "data" repeatedly but "data(take)" may be requested from each object at most once."xres" – 32bit integer. Horizontal dimension in pixels."yres" – 32bit integer. Vertical dimension in pixels."zres" – 32bit integer. Depth-wise dimension in pixels."xreal" – double. Horizontal size in physical units."yreal" – double. Vertical size in physical units."zreal" – double. Depth-wise size in physical units."xoff" – double. Horizontal offset of the top-left upper corner in physical units."yoff" – double. Vertical offset of the top-left upper corner in physical units."zoff" – double. Depth-wise offset of the top-left upper corner in physical units."si_unit_x" – string. Physical units of horizontal dimensions, base SI units, e.g. "m". The returned string is newly allocated and the caller must free it with free()."si_unit_y" – string. Physical units of vertical dimensions, base SI units, e.g. "m". The returned string is newly allocated and the caller must free it with free()."si_unit_z" – string. Physical units of depth dimensions, base SI units, e.g. "m". The returned string is newly allocated and the caller must free it with free()."si_unit_w" – string. Physical units of brick values, base SI units, e.g. "A". The returned string is newly allocated and the caller must free it with free().| object | A GWY file data object, presumably a GwyBrick. |
| error | Location for the error (or NULL). |
| ... | Requested data items specified as name, pointer-to-value pairs. Terminated by NULL. |
true if the object looks acceptable and the item values were filled. | bool gwyfile_object_datafield_get | ( | const GwyfileObject * | object, |
| GwyfileError ** | error, | ||
| ... | |||
| ) |
Obtains information and/or data from a GWY file GwyDataField object.
The function checks if the object type is actually "GwyDataField" and if it contains sane data items. Every GwyDataField must contain at least the pixel resolutions "xres" and "yres" and a matching array of doubles "data" of the corresponding size.
If object does not seem to represent a valid GwyDataField object the function fails, does not fill any output arguments (beside the error) and returns false.
All other items have default values that will be returned if the corresponding item is not found, is of the wrong type or has an invalid value (e.g. NaN physical dimension). Unknown additional items are simply ignored. The function does not fail in these cases and returns true.
Possible items to request:
"data" – array of doubles of size xres × yres. The array ownership does not change (as if gwyfile_item_get_double_array() was used)."data(take)" – array of doubles of size xres × yres. The array ownership is transferred to the caller (as if gwyfile_item_take_double_array() was used) who has to free it with free() later. Taking the data is not permitted if they are not owned by the data item. Hence you may request "data" repeatedly but "data(take)" may be requested from each object at most once."xres" – 32bit integer. Horizontal dimension in pixels."yres" – 32bit integer. Vertical dimension in pixels."xreal" – double. Horizontal size in physical units."yreal" – double. Vertical size in physical units."xoff" – double. Horizontal offset of the top-left corner in physical units."yoff" – double. Vertical offset of the top-left corner in physical units."si_unit_xy" – string. Physical units of lateral dimensions, base SI units, e.g. "m". The returned string is newly allocated and the caller must free it with free()."si_unit_z" – string. Physical units of field values, base SI units, e.g. "A". The returned string is newly allocated and the caller must free it with free().| object | A GWY file data object, presumably a GwyDataField. |
| error | Location for the error (or NULL). |
| ... | Requested data items specified as name, pointer-to-value pairs. Terminated by NULL. |
true if the object looks acceptable and the item values were filled. | bool gwyfile_object_dataline_get | ( | const GwyfileObject * | object, |
| GwyfileError ** | error, | ||
| ... | |||
| ) |
Obtains information and/or data from a GWY file GwyDataLine object.
The function checks if the object type is actually "GwyDataLine" and if it contains sane data items. Every GwyDataLine must contain at least the pixel resolution "res" and a matching array of doubles "data" of the corresponding size.
If object does not seem to represent a valid GwyDataLine object the function fails, does not fill any output arguments (beside the error) and returns false.
All other items have default values that will be returned if the corresponding item is not found, is of the wrong type or has an invalid value (e.g. NaN physical dimension). Unknown additional items are simply ignored. The function does not fail in these cases and returns true.
Possible items to request:
"data" – array of doubles of size res. The array ownership does not change (as if gwyfile_item_get_double_array() was used)."data(take)" – array of doubles of size res. The array ownership is transferred to the caller (as if gwyfile_item_take_double_array() was used) who has to free it with free() later. Taking the data is not permitted if they are not owned by the data item. Hence you may request "data" repeatedly but "data(take)" may be requested from each object at most once."res" – 32bit integer. Dimension in pixels."real" – double. Dimension in physical units."off" – double. Offset of the left edge in physical units."si_unit_x" – string. Physical units of the abscissa, base SI units, e.g. "m". The returned string is newly allocated and the caller must free it with free()."si_unit_y" – string. Physical units of values, base SI units, e.g. "A". The returned string is newly allocated and the caller must free it with free().| object | A GWY file data object, presumably a GwyDataLine. |
| error | Location for the error (or NULL). |
| ... | Requested data items specified as name, pointer-to-value pairs. Terminated by NULL. |
true if the object looks acceptable and the item values were filled. | bool gwyfile_object_graphcurvemodel_get | ( | const GwyfileObject * | object, |
| GwyfileError ** | error, | ||
| ... | |||
| ) |
Obtains information and/or data from a GWY file GwyGraphCurveModel object.
The function checks if the object type is actually "GwyGraphCurveModel" and if it contains sane data items. Every GwyGraphCurveModel must contain at least the abscissa and ordinate data "xdata" and "ydata" of the same size.
If object does not seem to represent a valid GwyGraphCurveModel object the function fails, does not fill any output arguments (beside the error) and returns false.
All other items have default values that will be returned if the corresponding item is not found, is of the wrong type or has an invalid value (e.g. colour component outisde [0, 1]). Unknown additional items are simply ignored. The function does not fail in these cases and returns true.
Possible items to request:
"ndata" – 32bit integer. The number of points in the curve, equal to the length of both "xdata" and "ydata" arrays."xdata" – array of doubles of size ndata. The array ownership does not change (as if gwyfile_item_get_double_array() was used)."xdata(take)" – array of doubles of size ndata. The array ownership is transferred to the caller (as if gwyfile_item_take_double_array() was used) who has to free it with free() later. Taking the data is not permitted if they are not owned by the data item. Hence you may request "xdata" repeatedly but "xdata(take)" may be requested from each object at most once."ydata" – array of doubles of size ndata. The array ownership does not change (as if gwyfile_item_get_double_array() was used)."ydata(take)" – array of doubles of size ndata. The array ownership is transferred to the caller (as if gwyfile_item_take_double_array() was used) who has to free it with free() later. Taking the data is not permitted if they are not owned by the data item. Hence you may request "ydata" repeatedly but "ydata(take)" may be requested from each object at most once."description" – string. Curve label. The returned string is newly allocated and the caller must free it with free()."type" – 32bit integer. See GwyGraphCurveType in Gwyddion API documentation for the list of curve modes."point_type" – 32bit integer. See GwyGraphPointType in Gwyddion API documentation for the list of point types."line_style" – 32bit integer. See GdkLineStyle in Gtk+ 2 API documentation for the list of line styles."point_size" – 32bit integer. Point size."line_size" – 32bit integer. Line width."color.red" – double. Red colour component from the interval [0, 1]."color.green" – double. Green colour component from the interval [0, 1]."color.blue" – double. Blue colour component from the interval [0, 1].| object | A GWY file data object, presumably a GwyGraphCurveModel. |
| error | Location for the error (or NULL). |
| ... | Requested data items specified as name, pointer-to-value pairs. Terminated by NULL. |
true if the object looks acceptable and the item values were filled. | bool gwyfile_object_graphmodel_get | ( | const GwyfileObject * | object, |
| GwyfileError ** | error, | ||
| ... | |||
| ) |
Obtains information and/or data from a GWY file GwyGraphModel object.
The function checks if the object type is actually "GwyGraphModel" and if it contains sane data items. Every GwyGraphModel must contain at least the abscissa and ordinate data "xdata" and "ydata" of the same size.
If object does not seem to represent a valid GwyGraphModel object the function fails, does not fill any output arguments (beside the error) and returns false.
All other items have default values that will be returned if the corresponding item is not found, is of the wrong type or has an invalid value. Unknown additional items are simply ignored. The function does not fail in these cases and returns true.
Possible items to request:
"ncurves" – 32bit integer. The number of curves in the graph, equal to the length of "curves" array. It may be zero."curves" – array of _GwyfileObject pointers of size ncurves. Both the array and objects inside remain to be owned by the item. The pointer will be filled with NULL when there are no curves."title" – string. Graph title. The returned string is newly allocated and the caller must free it with free()."top_label" – string. Top axis label. The returned string is newly allocated and the caller must free it with free()."left_label" – string. Left axis label. The returned string is newly allocated and the caller must free it with free()."right_label" – string. Right axis label. The returned string is newly allocated and the caller must free it with free()."bottom_label" – string. Bottom axis label. The returned string is newly allocated and the caller must free it with free()."x_unit" – string. Physical units of abscissa, in base SI units, e.g. "m". The returned string is newly allocated and the caller must free it with free()."y_unit" – string. Physical units of ordinate, in base SI units, e.g. "A". The returned string is newly allocated and the caller must free it with free()."x_min" – double. Minimum value of abscissa. Effective if "x_min_set" is true."x_min_set" – boolean. Whether the minimum value of abscissa is set explicitly (i.e. user-requested)."x_max" – double. Maximum value of abscissa. Effective if "x_max_set" is true."x_max_set" – boolean. Whether the maximum value of abscissa is set explicitly (i.e. user-requested)."y_min" – double. Minimum value of ordinate. Effective if "y_min_set" is true."y_min_set" – boolean. Whether the minimum value of ordinate is set explicitly (i.e. user-requested)."y_max" – double. Maximum value of ordinate. Effective if "y_max_set" is true."y_max_set" – boolean. Whether the maximum value of ordinate is set explicitly (i.e. user-requested)."x_is_logarithmic" – boolean. Whether abscissa is displayed in logaritmic scale."y_is_logarithmic" – boolean. Whether ordinate is displayed in logaritmic scale."label.visible" – boolean. Whether the graph key is visible."label.has_frame" – boolean. Whether the graph key has a frame."label.reverse" – boolean. Whether the graph key should be displayed with a reversed layout."label.frame_thickness" – 32bit integer. Thickness of the graph key frame."label.position" – 32bit integer. See GwyGraphLabelPosition in Gwyddion API documentation for the list of graph label position types."grid-type" – 32bit integer. See GwyGraphGridType in Gwyddion API documentation for the list of graph grid types. Note this property has never been actually implemented in Gwyddion.| object | A GWY file data object, presumably a GwyGraphModel. |
| error | Location for the error (or NULL). |
| ... | Requested data items specified as name, pointer-to-value pairs. Terminated by NULL. |
true if the object looks acceptable and the item values were filled. | bool gwyfile_object_lawn_get | ( | const GwyfileObject * | object, |
| GwyfileError ** | error, | ||
| ... | |||
| ) |
Obtains information and/or data from a GWY file GwyLawn object.
The function checks if the object type is actually "GwyLawn" and if it contains sane data items. Every GwyLawn must contain at least the pixel resolutions "xres", "yres" and "ncurves" an array of 32bit integers "curvelengths" and a matching array of doubles "data" of the corresponding size.
If object does not seem to represent a valid GwyLawn object the function fails, does not fill any output arguments (beside the error) and returns false.
All other items have default values that will be returned if the corresponding item is not found, is of the wrong type or has an invalid value (e.g. NaN physical dimension). Unknown additional items are simply ignored. The function does not fail in these cases and returns true.
Possible items to request:
"data" – array of doubles of size computed from "curvelengths" as described in gwyfile_object_new_lawn(). The array ownership does not change (as if gwyfile_item_get_double_array() was used)."data(take)" – array of doubles of size computed from "curvelengths" as described in gwyfile_object_new_lawn(). The array ownership is transferred to the caller (as if gwyfile_item_take_double_array() was used) who has to free it with free() later. Taking the data is not permitted if they are not owned by the data item. Hence you may request "data" repeatedly but "data(take)" may be requested from each object at most once."curvelengths" – array of 32bit integers of size xres × yres. The array ownership does not change (as if gwyfile_item_get_int32_array() was used)."curvelengths(take)" – array of 32bit integers of size xres × yres. The array ownership is transferred to the caller (as if gwyfile_item_take_int32_array() was used) who has to free it with free() later. Taking the data is not permitted if they are not owned by the data item. Hence you may request "curvelengths" repeatedly but "curvelengths(take)" may be requested from each object at most once."xres" – 32bit integer. Horizontal dimension in pixels."yres" – 32bit integer. Vertical dimension in pixels."ncurves" – 32bit integer. Number of curves for each pixel."nsegments" – 32bit integer. The number of segments each curve is split into, possibly zero for no segmentation."xreal" – double. Horizontal size in physical units."yreal" – double. Vertical size in physical units."xoff" – double. Horizontal offset of the top-left upper corner in physical units."yoff" – double. Vertical offset of the top-left upper corner in physical units."si_unit_xy" – string. Physical units of horizontal dimensions, base SI units, e.g. "m". The returned string is newly allocated and the caller must free it with free()."si_units_curves" – array of strings of size ncurves. Physical units of curve data, base SI units, e.g. "m". The returned strings and the array itself are newly allocated and the caller must free them with free()."curve_labels" – array of strings of size ncurves. Label of each curve. The returned strings and the array itself are newly allocated and the caller must free them with free()."segment_labels" – array of strings of size nsegments. Label of each segment. The returned strings and the array itself are newly allocated and the caller must free them with free(). If there is no segmentation the pointer is simply filled with NULL."segments" – array of 32bit integers of size xres × yres × 2nsegments. The segmentation for all curves. The array ownership does not change (as if gwyfile_item_get_int32_array() was used). If there is no segmentation the pointer is simply filled with NULL."segments(take)" – array of 32bit integers of size xres × yres × 2nsegments. The segmentation for all curves. The array ownership is transferred to the caller (as if gwyfile_item_take_int32_array() was used) who has to free it with free() later. Taking the data is not permitted if they are not owned by the data item. Hence you may request "curvelengths" repeatedly but "curvelengths(take)" may be requested from each object at most once. If there is no segmentation the pointer is simply filled with NULL.| object | A GWY file data object, presumably a GwyLawn. |
| error | Location for the error (or NULL). |
| ... | Requested data items specified as name, pointer-to-value pairs. Terminated by NULL. |
true if the object looks acceptable and the item values were filled. | GwyfileObject* gwyfile_object_new_brick | ( | int | xres, |
| int | yres, | ||
| int | zres, | ||
| double | xreal, | ||
| double | yreal, | ||
| double | zreal, | ||
| ... | |||
| ) |
Creates a new GWY file GwyBrick object.
A GwyBrick must also have an item "data" containing the data that you must add explicitly, depending on how you want to handle the memory. It can be added by passing one of the additional items listed below. Additional items can be also added using the standard function gwyfile_object_add().
Possible additional items:
"data" – array of doubles of size xres × yres × zres. It will be consumed by the object which will take care of freeing it later."data(copy)" – array of doubles of size xres × yres × zres. It will be copied by the object."data(const)" – array of doubles of size xres × yres × zres. It will be just used the object. You must ensure the array exists during the entire lifetime of the created object."xoff" – double. Horizontal offset of the top-left upper corner in physical units."yoff" – double. Vertical offset of the top-left upper corner in physical units."zoff" – double. Depth-wise offset of the top-left upper corner in physical units."si_unit_x" – string. Physical units of horizontal dimensions, base SI units, e.g. "m". It will be used to create a contained GwySIUnit object item."si_unit_y" – string. Physical units of vertical dimensions, base SI units, e.g. "m". It will be used to create a contained GwySIUnit object item."si_unit_z" – string. Physical units of vertical dimensions, base SI units, e.g. "m". It will be used to create a contained GwySIUnit object item."si_unit_w" – string. Physical units of brick values, base SI units, e.g. "A". It will be used to create a contained GwySIUnit object item."calibration" – object of type GwyDataLine, with resolution equal to zres that represents a non-linear z-axis calibration. It will be consumed by the created object.| xres | Horizontal dimension in pixels (positive integer). |
| yres | Vertical dimension in pixels (positive integer). |
| zres | Depth-wise dimension in pixels (positive integer). |
| xreal | Horizontal size in physical units (positive number). |
| yreal | Vertical size in physical units (positive number). |
| zreal | Depth-wise size in physical units (positive number). |
| ... | Additional data items specified as name, value pairs. Terminated by NULL. |
| GwyfileObject* gwyfile_object_new_datafield | ( | int | xres, |
| int | yres, | ||
| double | xreal, | ||
| double | yreal, | ||
| ... | |||
| ) |
Creates a new GWY file GwyDataField object.
A GwyDataField must also have an item "data" containing the data that you must add explicitly, depending on how you want to handle the memory. It can be added by passing one of the additional items listed below. Additional items can be also added using the standard function gwyfile_object_add().
Possible additional items:
"data" – array of doubles of size xres × yres. It will be consumed by the object which will take care of freeing it later."data(copy)" – array of doubles of size xres × yres. It will be copied by the object."data(const)" – array of doubles of size xres × yres. It will be just used the object. You must ensure the array exists during the entire lifetime of the created object."xoff" – double. Horizontal offset of the top-left corner in physical units."yoff" – double. Vertical offset of the top-left corner in physical units."si_unit_xy" – string. Physical units of lateral dimensions, base SI units, e.g. "m". It will be used to create a contained GwySIUnit object item."si_unit_z" – string. Physical units of field values, base SI units, e.g. "A". It will be used to create a contained GwySIUnit object item.| xres | Horizontal dimension in pixels (positive integer). |
| yres | Vertical dimension in pixels (positive integer). |
| xreal | Horizontal size in physical units (positive number). |
| yreal | Vertical size in physical units (positive number). |
| ... | Additional data items specified as name, value pairs. Terminated by NULL. |
| GwyfileObject* gwyfile_object_new_dataline | ( | int | res, |
| double | real, | ||
| ... | |||
| ) |
Creates a new GWY file GwyDataLine object.
A GwyDataLine must also have an item "data" containing the data that you must add explicitly, depending on how you want to handle the memory. It can be added by passing one of the additional items listed below. Additional items can be also added using the standard function gwyfile_object_add().
Possible additional items:
"data" – array of doubles of size res. It will be consumed by the object which will take care of freeing it later."data(copy)" – array of doubles of size res. It will be copied by the object."data(const)" – array of doubles of size res. It will be just used the object. You must ensure the array exists during the entire lifetime of the created object."off" – double. Offset of the left edge in physical units."si_unit_x" – string. Physical units of lateral dimensions, base SI units, e.g. "m". It will be used to create a contained GwySIUnit object item."si_unit_y" – string. Physical units of line values, base SI units, e.g. "A". It will be used to create a contained GwySIUnit object item.| res | Dimension in pixels (positive integer). |
| real | Size in physical units (positive number). |
| ... | Additional data items specified as name, value pairs. Terminated by NULL. |
| GwyfileObject* gwyfile_object_new_graphcurvemodel | ( | int | ndata, |
| ... | |||
| ) |
Creates a new GWY file GwyGraphCurveModel object.
A GwyGraphCurveModel must also have items "xdata" and "ydata" containing the data that you must add explicitly, depending on how you want to handle the memory. They can be added by passing one of the additional items listed below. Additional items can be also added using the standard function gwyfile_object_add().
Possible additional items:
"xdata" – array of doubles of size ndata. It will be consumed by the object which will take care of freeing it later."xdata(copy)" – array of doubles of size ndata. It will be copied by the object."xdata(const)" – array of doubles of size ndata. It will be just used the object. You must ensure the array exists during the entire lifetime of the created object."ydata" – array of doubles of size ndata. It will be consumed by the object which will take care of freeing it later."ydata(copy)" – array of doubles of size ndata. It will be copied by the object."ydata(const)" – array of doubles of size ndata. It will be just used the object. You must ensure the array exists during the entire lifetime of the created object."description" – string. Curve label. It will be copied by the object."type" – 32bit integer. See GwyGraphCurveType in Gwyddion API documentation for the list of curve modes."point_type" – 32bit integer. See GwyGraphPointType in Gwyddion API documentation for the list of point types."line_style" – 32bit integer. See GdkLineStyle in Gtk+ 2 API documentation for the list of line styles."point_size" – 32bit integer. Point size."line_size" – 32bit integer. Line width."color.red" – double. Red colour component from the interval [0, 1]."color.green" – double. Green colour component from the interval [0, 1]."color.blue" – double. Blue colour component from the interval [0, 1].| ndata | Number of data points (positive integer). |
| ... | Additional data items specified as name, value pairs. Terminated by NULL. |
| GwyfileObject* gwyfile_object_new_graphmodel | ( | int | ncurves, |
| ... | |||
| ) |
Creates a new GWY file GwyGraphModel object.
A GwyGraphModel must also have item "curves" containing the data that you must add explicitly. If you pass ncurves as zero, the item is not created at all and you should use gwyfile_object_add() afterward. If you pass non-zero ncurves you should also pass an additional "curves" item with the specified number of curves.
Possible additional items:
"curves" – _GwyfileObject* array with ncurves items. May only be passed if ncurves is non-zero. Both the array and the objects inside become owned by the newly created object as with gwyfile_item_new_object_array()."title" – string. Graph title. It will be copied by the object."top_label" – string. Top axis label. It will be copied by the object."left_label" – string. Left axis label. It will be copied by the object."right_label" – string. Right axis label. It will be copied by the object."bottom_label" – string. Bottom axis label. It will be copied by the object."x_unit" – string. Physical units of abscissa, in base SI units, e.g. "m". It will be used to create a contained GwySIUnit object item."y_unit" – string. Physical units of ordinate, in base SI units, e.g. "A". It will be used to create a contained GwySIUnit object item."x_min" – double. Minimum value of abscissa. Effective if "x_min_set" is true."x_min_set" – boolean. Whether the minimum value of abscissa is set explicitly (i.e. user-requested)."x_max" – double. Maximum value of abscissa. Effective if "x_max_set" is true."x_max_set" – boolean. Whether the maximum value of abscissa is set explicitly (i.e. user-requested)."y_min" – double. Minimum value of ordinate. Effective if "y_min_set" is true."y_min_set" – boolean. Whether the minimum value of ordinate is set explicitly (i.e. user-requested)."y_max" – double. Maximum value of ordinate. Effective if "y_max_set" is true."y_max_set" – boolean. Whether the maximum value of ordinate is set explicitly (i.e. user-requested)."x_is_logarithmic" – boolean. Whether abscissa is displayed in logaritmic scale."y_is_logarithmic" – boolean. Whether ordinate is displayed in logaritmic scale."label.visible" – boolean. Whether the graph key is visible."label.has_frame" – boolean. Whether the graph key has a frame."label.reverse" – boolean. Whether the graph key should be displayed with a reversed layout."label.frame_thickness" – 32bit integer. Thickness of the graph key frame."label.position" – 32bit integer. See GwyGraphLabelPosition in Gwyddion API documentation for the list of graph label position types."grid-type" – 32bit integer. See GwyGraphGridType in Gwyddion API documentation for the list of graph grid types. Note this property has never been actually implemented in Gwyddion.| ncurves | Number of curves (non-negative integer). If you pass zero you must not pass any "curves" additional item to this function. |
| ... | Additional data items specified as name, value pairs. Terminated by NULL. |
| GwyfileObject* gwyfile_object_new_lawn | ( | int | xres, |
| int | yres, | ||
| int | ncurves, | ||
| double | xreal, | ||
| double | yreal, | ||
| ... | |||
| ) |
Creates a new GWY file GwyLawn object.
A GwyLawn must also have items "data" and "curvelengths" containing the data and point counts for all pixels. You must add them explicitly, depending on how you want to handle the memory. It can be added by passing one of the additional items listed below. Additional items can be also added using the standard function gwyfile_object_add().
The size of "data" is computed from "curvelengths", which is an array of size xres × yres. The number of points in each curve in a pixel is given by the corresponding "curvelengths" entry. This is multiplied by ncurves. The lenghts of all pixels are summed, and this must be length of "data".
Although it is not strictly necessary to keep "curvelengths" and "data" consistent at all times, it is strongly recommended to set them together. And "curvelengths" must always be set first because it is used to calculate the size of "data".
A similar rule applies to "nsegments" and "segments". Either both should be set or none. And if both are set "nsegments" must be set first.
Possible additional items:
"data" – array of doubles whose size is described above. It will be consumed by the object which will take care of freeing it later. Note that "curvelengths" must be set correctly prior to setting "data"."data(copy)" – array of doubles whose size is described above. It will be copied by the object. Note that "curvelengths" must be set correctly prior to setting "data(copy)"."data(const)" – array of doubles whose size id described above. It will be just used the object. You must ensure the array exists during the entire lifetime of the created object. Note that "curvelengths" must be set correctly prior to setting "data(const)"."curvelengths" – array of 32bit integers of size xres × yres. It will be consumed by the object which will take care of freeing it later."curvelengths(copy)" – array of 32bit integers of size xres × yres. It will be copied by the object."curvelengths(const)" – array of 32bit integers of size xres × yres. It will be just used the object. You must ensure the array exists during the entire lifetime of the created object."xoff" – double. Horizontal offset of the top-left upper corner in physical units."yoff" – double. Vertical offset of the top-left upper corner in physical units."si_unit_xy" – string. Physical units of horizontal dimensions, base SI units, e.g. "m". It will be used to create a contained GwySIUnit object item."si_units_curves" – array of ncurves strings. Physical units of values, base SI units, e.g. "m". It will be used to create an item containing and array of GwySIUnit objects. Both the strings and the the array itself are copied."curve_labels" – array of ncurves strings. Label of each curve. It will be used to create an item containing an array of strings. Both the strings and the the array itself are copied."nsegments" – 32bit integer. The number of segments each curve is split into. It must be set prior to any other segmentation-related item."segments" – array of 32bit integers of size xres × yres × 2nsegments. The segmentation for all curves. It will be consumed by the object which will take care of freeing it later. Note that "nsegments" must be set prior to setting "segments"."segments(copy)" – array of 32bit integers of size xres × yres × 2nsegments. The segmentation for all curves. It will be copied by the object. Note that "nsegments" must be set prior to setting "segments"."segments(const)" – array of 32bit integers of size xres × yres × 2nsegments. The segmentation for all curves. It will be just used the object. You must ensure the array exists during the entire lifetime of the created object. Note that "nsegments" must be set prior to setting "segments"."segment_labels" – array of nsegments strings. Label of each curve segment – "nsegments" has to be set first. It will be used to create an item containing an array of strings. Both the strings and the the array itself are copied.| xres | Horizontal dimension in pixels (positive integer). |
| yres | Vertical dimension in pixels (positive integer). |
| ncurves | Number of curves for each pixel (positive integer). |
| xreal | Horizontal size in physical units (positive number). |
| yreal | Vertical size in physical units (positive number). |
| ... | Additional data items specified as name, value pairs. Terminated by NULL. |
| GwyfileObject* gwyfile_object_new_selectionaxis | ( | int | nsel, |
| int | orientation, | ||
| ... | |||
| ) |
Creates a new GWY file GwySelectionAxis object.
A non-empty GwySelectionAxis must also have item "data" containing the coordinates that you must add explicitly, depending on how you want to handle the memory. They can be added by passing one of the additional items listed below. Additional items can be also added using the standard function gwyfile_object_add().
Possible additional items:
"data" – array of doubles of size nsel. It will be consumed by the object which will take care of freeing it later."data(copy)" – array of doubles of size nsel. It will be copied by the object."data(const)" – array of doubles of size nsel. It will be just used the object. You must ensure the array exists during the entire lifetime of the created object.This constructor creates automatically a 32bit integer "max" item with the same value as nsel. This item specifies the maximum number of shapes in the selection. However, this number is usually changed to some suitable value by Gwyddion tools. Hence it is only created to ensure the maximum number is at least the actual number of shapes.
| nsel | Number of axes in the selection. Zero is allowed, any data item is ignored then. |
| orientation | Axis orientation. See GwyOrientation in Gwyddion API documentation for description. |
| ... | Additional data items specified as name, value pairs. Terminated by NULL. |
| GwyfileObject* gwyfile_object_new_selectioncross | ( | int | nsel, |
| ... | |||
| ) |
Creates a new GWY file GwySelectionCross object.
A non-empty GwySelectionCross must also have item "data" containing the coordinates that you must add explicitly, depending on how you want to handle the memory. They can be added by passing one of the additional items listed below. Additional items can be also added using the standard function gwyfile_object_add().
Possible additional items:
"data" – array of doubles of size 2 × nsel. It will be consumed by the object which will take care of freeing it later."data(copy)" – array of doubles of size 2 × nsel. It will be copied by the object."data(const)" – array of doubles of size 2 × nsel. It will be just used the object. You must ensure the array exists during the entire lifetime of the created object.This constructor creates automatically a 32bit integer "max" item with the same value as nsel. This item specifies the maximum number of shapes in the selection. However, this number is usually changed to some suitable value by Gwyddion tools. Hence it is only created to ensure the maximum number is at least the actual number of shapes.
| nsel | Number of crosses in the selection. Zero is allowed, any data item is ignored then. Note that the number of coordinates is 2 × nsel. |
| ... | Additional data items specified as name, value pairs. Terminated by NULL. |
| GwyfileObject* gwyfile_object_new_selectionellipse | ( | int | nsel, |
| ... | |||
| ) |
Creates a new GWY file GwySelectionEllipse object.
A non-empty GwySelectionEllipse must also have item "data" containing the coordinates that you must add explicitly, depending on how you want to handle the memory. They can be added by passing one of the additional items listed below. Additional items can be also added using the standard function gwyfile_object_add().
Possible additional items:
"data" – array of doubles of size 4 × nsel. It will be consumed by the object which will take care of freeing it later."data(copy)" – array of doubles of size 4 × nsel. It will be copied by the object."data(const)" – array of doubles of size 4 × nsel. It will be just used the object. You must ensure the array exists during the entire lifetime of the created object.This constructor creates automatically a 32bit integer "max" item with the same value as nsel. This item specifies the maximum number of shapes in the selection. However, this number is usually changed to some suitable value by Gwyddion tools. Hence it is only created to ensure the maximum number is at least the actual number of shapes.
| nsel | Number of ellipses in the selection. Zero is allowed, any data item is ignored then. Note that the number of coordinates is 4 × nsel. |
| ... | Additional data items specified as name, value pairs. Terminated by NULL. |
| GwyfileObject* gwyfile_object_new_selectionlattice | ( | int | nsel, |
| ... | |||
| ) |
Creates a new GWY file GwySelectionLattice object.
A non-empty GwySelectionLattice must also have item "data" containing the coordinates that you must add explicitly, depending on how you want to handle the memory. They can be added by passing one of the additional items listed below. Additional items can be also added using the standard function gwyfile_object_add().
Possible additional items:
"data" – array of doubles of size 4 × nsel. It will be consumed by the object which will take care of freeing it later."data(copy)" – array of doubles of size 4 × nsel. It will be copied by the object."data(const)" – array of doubles of size 4 × nsel. It will be just used the object. You must ensure the array exists during the entire lifetime of the created object.This constructor creates automatically a 32bit integer "max" item with the same value as nsel. This item specifies the maximum number of shapes in the selection. However, this number is usually changed to some suitable value by Gwyddion tools. Hence it is only created to ensure the maximum number is at least the actual number of shapes.
| nsel | Number of lattices in the selection. Zero is allowed, any data item is ignored then. Note that the number of coordinates is 4 × nsel. |
| ... | Additional data items specified as name, value pairs. Terminated by NULL. |
| GwyfileObject* gwyfile_object_new_selectionline | ( | int | nsel, |
| ... | |||
| ) |
Creates a new GWY file GwySelectionLine object.
A non-empty GwySelectionLine must also have item "data" containing the coordinates that you must add explicitly, depending on how you want to handle the memory. They can be added by passing one of the additional items listed below. Additional items can be also added using the standard function gwyfile_object_add().
Possible additional items:
"data" – array of doubles of size 4 × nsel. It will be consumed by the object which will take care of freeing it later."data(copy)" – array of doubles of size 4 × nsel. It will be copied by the object."data(const)" – array of doubles of size 4 × nsel. It will be just used the object. You must ensure the array exists during the entire lifetime of the created object.This constructor creates automatically a 32bit integer "max" item with the same value as nsel. This item specifies the maximum number of shapes in the selection. However, this number is usually changed to some suitable value by Gwyddion tools. Hence it is only created to ensure the maximum number is at least the actual number of shapes.
| nsel | Number of lines in the selection. Zero is allowed, any data item is ignored then. Note that the number of coordinates is 4 × nsel. |
| ... | Additional data items specified as name, value pairs. Terminated by NULL. |
| GwyfileObject* gwyfile_object_new_selectionpath | ( | int | nsel, |
| double | slackness, | ||
| bool | closed, | ||
| ... | |||
| ) |
Creates a new GWY file GwySelectionPath object.
A non-empty GwySelectionPath must also have item "data" containing the coordinates that you must add explicitly, depending on how you want to handle the memory. They can be added by passing one of the additional items listed below. Additional items can be also added using the standard function gwyfile_object_add().
Possible additional items:
"data" – array of doubles of size 2 × nsel. It will be consumed by the object which will take care of freeing it later."data(copy)" – array of doubles of size 2 × nsel. It will be copied by the object."data(const)" – array of doubles of size 2 × nsel. It will be just used the object. You must ensure the array exists during the entire lifetime of the created object.This constructor creates automatically a 32bit integer "max" item with the same value as nsel. This item specifies the maximum number of shapes in the selection. However, this number is usually changed to some suitable value by Gwyddion tools. Hence it is only created to ensure the maximum number is at least the actual number of shapes.
| nsel | Number of points in the selection. Zero is allowed, any data item is ignored then. |
| slackness | Spline path slackness (number between 0 and √2). See GwySelectionPath in Gwyddion API documentation for description. |
| closed | Whether the path is closed (true) or open (false). |
| ... | Additional data items specified as name, value pairs. Terminated by NULL. |
| GwyfileObject* gwyfile_object_new_selectionpoint | ( | int | nsel, |
| ... | |||
| ) |
Creates a new GWY file GwySelectionPoint object.
A non-empty GwySelectionPoint must also have item "data" containing the coordinates that you must add explicitly, depending on how you want to handle the memory. They can be added by passing one of the additional items listed below. Additional items can be also added using the standard function gwyfile_object_add().
Possible additional items:
"data" – array of doubles of size 2 × nsel. It will be consumed by the object which will take care of freeing it later."data(copy)" – array of doubles of size 2 × nsel. It will be copied by the object."data(const)" – array of doubles of size 2 × nsel. It will be just used the object. You must ensure the array exists during the entire lifetime of the created object.This constructor creates automatically a 32bit integer "max" item with the same value as nsel. This item specifies the maximum number of shapes in the selection. However, this number is usually changed to some suitable value by Gwyddion tools. Hence it is only created to ensure the maximum number is at least the actual number of shapes.
| nsel | Number of points in the selection. Zero is allowed, any data item is ignored then. Note that the number of coordinates is 2 × nsel. |
| ... | Additional data items specified as name, value pairs. Terminated by NULL. |
| GwyfileObject* gwyfile_object_new_selectionprojective | ( | int | nsel, |
| ... | |||
| ) |
Creates a new GWY file GwySelectionProjective object.
A non-empty GwySelectionProjective must also have item "data" containing the coordinates that you must add explicitly, depending on how you want to handle the memory. They can be added by passing one of the additional items listed below. Additional items can be also added using the standard function gwyfile_object_add().
Possible additional items:
"data" – array of doubles of size 8 × nsel. It will be consumed by the object which will take care of freeing it later."data(copy)" – array of doubles of size 8 × nsel. It will be copied by the object."data(const)" – array of doubles of size 8 × nsel. It will be just used the object. You must ensure the array exists during the entire lifetime of the created object.This constructor creates automatically a 32bit integer "max" item with the same value as nsel. This item specifies the maximum number of shapes in the selection. However, this number is usually changed to some suitable value by Gwyddion tools. Hence it is only created to ensure the maximum number is at least the actual number of shapes.
| nsel | Number of projective rectangles in the selection. Zero is allowed, any data item is ignored then. Note that the number of coordinates is 8 × nsel. |
| ... | Additional data items specified as name, value pairs. Terminated by NULL. |
| GwyfileObject* gwyfile_object_new_selectionrectangle | ( | int | nsel, |
| ... | |||
| ) |
Creates a new GWY file GwySelectionRectangle object.
A non-empty GwySelectionRectangle must also have item "data" containing the coordinates that you must add explicitly, depending on how you want to handle the memory. They can be added by passing one of the additional items listed below. Additional items can be also added using the standard function gwyfile_object_add().
Possible additional items:
"data" – array of doubles of size 4 × nsel. It will be consumed by the object which will take care of freeing it later."data(copy)" – array of doubles of size 4 × nsel. It will be copied by the object."data(const)" – array of doubles of size 4 × nsel. It will be just used the object. You must ensure the array exists during the entire lifetime of the created object.This constructor creates automatically a 32bit integer "max" item with the same value as nsel. This item specifies the maximum number of shapes in the selection. However, this number is usually changed to some suitable value by Gwyddion tools. Hence it is only created to ensure the maximum number is at least the actual number of shapes.
| nsel | Number of rectangles in the selection. Zero is allowed, any data item is ignored then. Note that the number of coordinates is 4 × nsel. |
| ... | Additional data items specified as name, value pairs. Terminated by NULL. |
| GwyfileObject* gwyfile_object_new_siunit | ( | const char * | unitstr | ) |
Creates a new GWY file GwySIUnit object.
The unit string should represent an unprefixed SI unit such as "m", "A" or "N/m".
| unitstr | String representation of the SI unit (to be copied). |
NULL. | GwyfileObject* gwyfile_object_new_spectra | ( | int | ncurves, |
| GwyfileObject ** | curves, | ||
| ... | |||
| ) |
Creates a new GWY file GwySpectra object.
A GwySpectra must also have an item "coords" containing the real spectra coordinates that you must add explicitly, depending on how you want to handle the memory. It can be added by passing one of the additional items listed below. Additional items can be also added using the standard function gwyfile_object_add().
Possible additional items:
"coords" – array of doubles of size 2ncurves. It will be consumed by the object which will take care of freeing it later."coords(copy)" – array of doubles of size 2ncurves. It will be copied by the object."coords(const)" – array of doubles of size 2ncurves. It will be just used the object. You must ensure the array exists during the entire lifetime of the created object."title" – string. Title of the spectra. It will be copied by the object."spec_xlabel" – string. Label of the spectra curve abscissae. It will be copied by the object."spec_ylabel" – string. Label of the spectra curve ordinates. It will be copied by the object."si_unit_xy" – string. Physical units of lateral dimensions, base SI units, e.g. "m". It will be used to create a contained GwySIUnit object item."selected" – array of 32bit integers with ceil(ncurves/32) elements describing which spectra are currently selected. A set (one) bit means selected spectrum, unset (zero) means the spectrum is not selected. The array will be copied by the object.| ncurves | Number of spectra curves (positive integer). |
| curves | Array of ncurves GwySpectra objects. Both the array and the objects within will be consumed by the function that will take care of freeing them later. |
| ... | Additional data items specified as name, value pairs. Terminated by NULL. |
| GwyfileObject* gwyfile_object_new_surface | ( | int | n, |
| ... | |||
| ) |
Creates a new GWY file GwySurface object.
A GwySurface must also have an item "data" containing the data that you must add explicitly, depending on how you want to handle the memory. It can be added by passing one of the additional items listed below. Additional items can be also added using the standard function gwyfile_object_add().
The size of the data is three times the number of points. The data consits of triplets (x, y, z) representing the coordinates of individual data points, concatenated to a single continuous block of doubles.
Possible additional items:
"data" – array of doubles of size 3 × n. It will be consumed by the object which will take care of freeing it later."data(copy)" – array of doubles of size 3 × n. It will be copied by the object."data(const)" – array of doubles of size 3 × n. It will be just used the object. You must ensure the array exists during the entire lifetime of the created object."si_unit_xy" – string. Physical units of X and Y coordinates, base SI units, e.g. "m". It will be used to create a contained GwySIUnit object item."si_unit_z" – string. Physical units of Z values, base SI units, e.g. "A". It will be used to create a contained GwySIUnit object item.| n | The number of points in the XYZ surface. |
| ... | Additional data items specified as name, value pairs. Terminated by NULL. |
| bool gwyfile_object_selectionaxis_get | ( | const GwyfileObject * | object, |
| GwyfileError ** | error, | ||
| ... | |||
| ) |
Obtains information and/or data from a GWY file GwySelectionAxis object.
The function checks if the object type is actually "GwySelectionAxis" and if it contains sane data items.
If object does not seem to represent a valid GwySelectionAxis object the function fails, does not fill any output arguments (beside the error) and returns false.
All items have default values that will be returned if the corresponding item is not found, is of the wrong type or has an invalid value. Unknown additional items are simply ignored. The function does not fail in these cases and returns true.
Possible items to request:
"nsel" – 32bit integer. The number of axes in the selection (not the number of double values)."orientation" – 32bit integer from the GwyOrientation enum. The axis orientation."data" – array of doubles of size nsel. It will be returned as NULL for empty selections. The array ownership does not change (as if gwyfile_item_get_double_array() was used)."data(take)" – array of doubles of size nsel. It will be returned as NULL for empty selections. The array ownership is transferred to the caller (as if gwyfile_item_take_double_array() was used) who has to free it with free() later. Taking the data is not permitted if they are not owned by the data item. Hence you may requested "data" repeatedly but "data(take)" may be requested from each object at most once.| object | A GWY file data object, presumably a GwySelectionAxis. |
| error | Location for the error (or NULL). |
| ... | Requested data items specified as name, pointer-to-value pairs. Terminated by NULL. |
true if the object looks acceptable and the item values were filled. | bool gwyfile_object_selectioncross_get | ( | const GwyfileObject * | object, |
| GwyfileError ** | error, | ||
| ... | |||
| ) |
Obtains information and/or data from a GWY file GwySelectionCross object.
The function checks if the object type is actually "GwySelectionCross" and if it contains sane data items.
If object does not seem to represent a valid GwySelectionCross object the function fails, does not fill any output arguments (beside the error) and returns false.
All items have default values that will be returned if the corresponding item is not found, is of the wrong type or has an invalid value. Unknown additional items are simply ignored. The function does not fail in these cases and returns true.
Possible items to request:
"nsel" – 32bit integer. The number of points in the selection (not the number of double values)."data" – array of doubles of size 2×nsel. It will be returned as NULL for empty selections. The array ownership does not change (as if gwyfile_item_get_double_array() was used)."data(take)" – array of doubles of size 2×nsel. It will be returned as NULL for empty selections. The array ownership is transferred to the caller (as if gwyfile_item_take_double_array() was used) who has to free it with free() later. Taking the data is not permitted if they are not owned by the data item. Hence you may request "data" repeatedly but "data(take)" may be requested from each object at most once.| object | A GWY file data object, presumably a GwySelectionCross. |
| error | Location for the error (or NULL). |
| ... | Requested data items specified as name, pointer-to-value pairs. Terminated by NULL. |
true if the object looks acceptable and the item values were filled. | bool gwyfile_object_selectionellipse_get | ( | const GwyfileObject * | object, |
| GwyfileError ** | error, | ||
| ... | |||
| ) |
Obtains information and/or data from a GWY file GwySelectionEllipse object.
The function checks if the object type is actually "GwySelectionEllipse" and if it contains sane data items.
If object does not seem to represent a valid GwySelectionEllipse object the function fails, does not fill any output arguments (beside the error) and returns false.
All items have default values that will be returned if the corresponding item is not found, is of the wrong type or has an invalid value. Unknown additional items are simply ignored. The function does not fail in these cases and returns true.
Possible items to request:
"nsel" – 32bit integer. The number of ellipses in the selection (not the number of double values)."data" – array of doubles of size 4×nsel. It will be returned as NULL for empty selections. The array ownership does not change (as if gwyfile_item_get_double_array() was used)."data(take)" – array of doubles of size 4×nsel. It will be returned as NULL for empty selections. The array ownership is transferred to the caller (as if gwyfile_item_take_double_array() was used) who has to free it with free() later. Taking the data is not permitted if they are not owned by the data item. Hence you may request "data" repeatedly but "data(take)" may be requested from each object at most once.| object | A GWY file data object, presumably a GwySelectionEllipse. |
| error | Location for the error (or NULL). |
| ... | Requested data items specified as name, pointer-to-value pairs. Terminated by NULL. |
true if the object looks acceptable and the item values were filled. | bool gwyfile_object_selectionlattice_get | ( | const GwyfileObject * | object, |
| GwyfileError ** | error, | ||
| ... | |||
| ) |
Obtains information and/or data from a GWY file GwySelectionLattice object.
The function checks if the object type is actually "GwySelectionLattice" and if it contains sane data items.
If object does not seem to represent a valid GwySelectionLattice object the function fails, does not fill any output arguments (beside the error) and returns false.
All items have default values that will be returned if the corresponding item is not found, is of the wrong type or has an invalid value. Unknown additional items are simply ignored. The function does not fail in these cases and returns true.
Possible items to request:
"nsel" – 32bit integer. The number of lattices in the selection (not the number of double values)."data" – array of doubles of size 4×nsel. It will be returned as NULL for empty selections. The array ownership does not change (as if gwyfile_item_get_double_array() was used)."data(take)" – array of doubles of size 4×nsel. It will be returned as NULL for empty selections. The array ownership is transferred to the caller (as if gwyfile_item_take_double_array() was used) who has to free it with free() later. Taking the data is not permitted if they are not owned by the data item. Hence you may request "data" repeatedly but "data(take)" may be requested from each object at most once.| object | A GWY file data object, presumably a GwySelectionLattice. |
| error | Location for the error (or NULL). |
| ... | Requested data items specified as name, pointer-to-value pairs. Terminated by NULL. |
true if the object looks acceptable and the item values were filled. | bool gwyfile_object_selectionline_get | ( | const GwyfileObject * | object, |
| GwyfileError ** | error, | ||
| ... | |||
| ) |
Obtains information and/or data from a GWY file GwySelectionLine object.
The function checks if the object type is actually "GwySelectionLine" and if it contains sane data items.
If object does not seem to represent a valid GwySelectionLine object the function fails, does not fill any output arguments (beside the error) and returns false.
All items have default values that will be returned if the corresponding item is not found, is of the wrong type or has an invalid value. Unknown additional items are simply ignored. The function does not fail in these cases and returns true.
Possible items to request:
"nsel" – 32bit integer. The number of lines in the selection (not the number of double values)."data" – array of doubles of size 4×nsel. It will be returned as NULL for empty selections. The array ownership does not change (as if gwyfile_item_get_double_array() was used)."data(take)" – array of doubles of size 4×nsel. It will be returned as NULL for empty selections. The array ownership is transferred to the caller (as if gwyfile_item_take_double_array() was used) who has to free it with free() later. Taking the data is not permitted if they are not owned by the data item. Hence you may request "data" repeatedly but "data(take)" may be requested from each object at most once.| object | A GWY file data object, presumably a GwySelectionLine. |
| error | Location for the error (or NULL). |
| ... | Requested data items specified as name, pointer-to-value pairs. Terminated by NULL. |
true if the object looks acceptable and the item values were filled. | bool gwyfile_object_selectionpath_get | ( | const GwyfileObject * | object, |
| GwyfileError ** | error, | ||
| ... | |||
| ) |
Obtains information and/or data from a GWY file GwySelectionPath object.
The function checks if the object type is actually "GwySelectionPath" and if it contains sane data items.
If object does not seem to represent a valid GwySelectionPath object the function fails, does not fill any output arguments (beside the error) and returns false.
All items have default values that will be returned if the corresponding item is not found, is of the wrong type or has an invalid value. Unknown additional items are simply ignored. The function does not fail in these cases and returns true.
Possible items to request:
"nsel" – 32bit integer. The number of points in the selection (not the number of double values)."slackness" – double. Spline path slackness."closed" – boolean. Whether the path is closed."data" – array of doubles of size nsel. It will be returned as NULL for empty selections. The array ownership does not change (as if gwyfile_item_get_double_array() was used)."data(take)" – array of doubles of size nsel. It will be returned as NULL for empty selections. The array ownership is transferred to the caller (as if gwyfile_item_take_double_array() was used) who has to free it with free() later. Taking the data is not permitted if they are not owned by the data item. Hence you may requested "data" repeatedly but "data(take)" may be requested from each object at most once.| object | A GWY file data object, presumably a GwySelectionPath. |
| error | Location for the error (or NULL). |
| ... | Requested data items specified as name, pointer-to-value pairs. Terminated by NULL. |
true if the object looks acceptable and the item values were filled. | bool gwyfile_object_selectionpoint_get | ( | const GwyfileObject * | object, |
| GwyfileError ** | error, | ||
| ... | |||
| ) |
Obtains information and/or data from a GWY file GwySelectionPoint object.
The function checks if the object type is actually "GwySelectionPoint" and if it contains sane data items.
If object does not seem to represent a valid GwySelectionPoint object the function fails, does not fill any output arguments (beside the error) and returns false.
All items have default values that will be returned if the corresponding item is not found, is of the wrong type or has an invalid value. Unknown additional items are simply ignored. The function does not fail in these cases and returns true.
Possible items to request:
"nsel" – 32bit integer. The number of points in the selection (not the number of double values)."data" – array of doubles of size 2×nsel. It will be returned as NULL for empty selections. The array ownership does not change (as if gwyfile_item_get_double_array() was used)."data(take)" – array of doubles of size 2×nsel. It will be returned as NULL for empty selections. The array ownership is transferred to the caller (as if gwyfile_item_take_double_array() was used) who has to free it with free() later. Taking the data is not permitted if they are not owned by the data item. Hence you may request "data" repeatedly but "data(take)" may be requested from each object at most once.| object | A GWY file data object, presumably a GwySelectionPoint. |
| error | Location for the error (or NULL). |
| ... | Requested data items specified as name, pointer-to-value pairs. Terminated by NULL. |
true if the object looks acceptable and the item values were filled. | bool gwyfile_object_selectionprojective_get | ( | const GwyfileObject * | object, |
| GwyfileError ** | error, | ||
| ... | |||
| ) |
Obtains information and/or data from a GWY file GwySelectionProjective object.
The function checks if the object type is actually "GwySelectionProjective" and if it contains sane data items.
If object does not seem to represent a valid GwySelectionProjective object the function fails, does not fill any output arguments (beside the error) and returns false.
All items have default values that will be returned if the corresponding item is not found, is of the wrong type or has an invalid value. Unknown additional items are simply ignored. The function does not fail in these cases and returns true.
Possible items to request:
"nsel" – 32bit integer. The number of projective rectangles in the selection (not the number of double values)."data" – array of doubles of size 8×nsel. It will be returned as NULL for empty selections. The array ownership does not change (as if gwyfile_item_get_double_array() was used)."data(take)" – array of doubles of size 8×nsel. It will be returned as NULL for empty selections. The array ownership is transferred to the caller (as if gwyfile_item_take_double_array() was used) who has to free it with free() later. Taking the data is not permitted if they are not owned by the data item. Hence you may request "data" repeatedly but "data(take)" may be requested from each object at most once.| object | A GWY file data object, presumably a GwySelectionProjective. |
| error | Location for the error (or NULL). |
| ... | Requested data items specified as name, pointer-to-value pairs. Terminated by NULL. |
true if the object looks acceptable and the item values were filled. | bool gwyfile_object_selectionrectangle_get | ( | const GwyfileObject * | object, |
| GwyfileError ** | error, | ||
| ... | |||
| ) |
Obtains information and/or data from a GWY file GwySelectionRectangle object.
The function checks if the object type is actually "GwySelectionRectangle" and if it contains sane data items.
If object does not seem to represent a valid GwySelectionRectangle object the function fails, does not fill any output arguments (beside the error) and returns false.
All items have default values that will be returned if the corresponding item is not found, is of the wrong type or has an invalid value. Unknown additional items are simply ignored. The function does not fail in these cases and returns true.
Possible items to request:
"nsel" – 32bit integer. The number of rectangles in the selection (not the number of double values)."data" – array of doubles of size 4×nsel. It will be returned as NULL for empty selections. The array ownership does not change (as if gwyfile_item_get_double_array() was used)."data(take)" – array of doubles of size 4×nsel. It will be returned as NULL for empty selections. The array ownership is transferred to the caller (as if gwyfile_item_take_double_array() was used) who has to free it with free() later. Taking the data is not permitted if they are not owned by the data item. Hence you may request "data" repeatedly but "data(take)" may be requested from each object at most once.| object | A GWY file data object, presumably a GwySelectionRectangle. |
| error | Location for the error (or NULL). |
| ... | Requested data items specified as name, pointer-to-value pairs. Terminated by NULL. |
true if the object looks acceptable and the item values were filled. | bool gwyfile_object_siunit_get | ( | const GwyfileObject * | object, |
| GwyfileError ** | error, | ||
| ... | |||
| ) |
Obtains information and/or data from a GWY file GwySIUnit object.
The function checks if the object type is actually "GwySIUnit" and if it contains sane data items. Note functions for specific Gwyddion data objects, such as gwyfile_object_datafield_get(), can extract the unit strings directly, saving you dealing explicitly with the unit object.
If object does not seem to represent a valid GwySIUnit object the function fails, does not fill any output arguments (beside the error) and returns false.
Every GwySIUnit object must contain at least the "unitstr" item. Unknown additional items are simply ignored. The function does not fail in these cases and returns true.
Possible items to request:
"unitstr" – string. Physical units, in base SI units, e.g. "m". The returned string is newly allocated and the caller must free it with free().| object | A GWY file data object, presumably a GwySIUnit. |
| error | Location for the error (or NULL). |
| ... | Requested data items specified as name, pointer-to-value pairs. Terminated by NULL. |
true if the object looks acceptable and the item values were filled. | bool gwyfile_object_spectra_get | ( | const GwyfileObject * | object, |
| GwyfileError ** | error, | ||
| ... | |||
| ) |
Obtains information and/or data from a GWY file GwySpectra object.
The function checks if the object type is actually "GwySpectra" and if it contains sane data items. Every GwySpectra must contain at least the curves "data" and their coordinates "coords" of the corresponding sizes.
If object does not seem to represent a valid GwySpectra object the function fails, does not fill any output arguments (beside the error) and returns false.
All other items have default values that will be returned if the corresponding item is not found, is of the wrong type or has an invalid value. Unknown additional items are simply ignored. The function does not fail in these cases and returns true.
Possible items to request:
"ndata" – 32bit integer. The number of curves in the spectra, equal to the length of "data" array. It may be zero."data" – array of _GwyfileObject pointers of size ndata. Both the array and objects inside remain to be owned by the item. The pointer will be filled with NULL when there are no spectra curves."coords" – array of doubles of size 2ndata. The array ownership does not change (as if gwyfile_item_get_double_array() was used)."coords(take)" – array of doubles of size 2ndata. The array ownership is transferred to the caller (as if gwyfile_item_take_double_array() was used) who has to free it with free() later. Taking the coords is not permitted if they are not owned by the data item. Hence you may request "coords" repeatedly but "coords(take)" may be requested from each object at most once."title" – string. Spectra title. The returned string is newly allocated and the caller must free it with free()."spec_xlabel" – string. Spectra abscissa label. The returned string is newly allocated and the caller must free it with free()."spec_ylabel" – string. Spectra ordinate label. The returned string is newly allocated and the caller must free it with free()."si_unit_xy" – string. Physical units of ordinate, in base SI units, e.g. "m". The returned string is newly allocated and the caller must free it with free()."selected" – array of 32bit integers with ceil(ndata/32) elements describing which spectra are currently selected. The returned array is newly allocated and the caller must free it with free(). It will be filled with NULL if the item is not present or there are no curves.| object | A GWY file data object, presumably a GwySpectra. |
| error | Location for the error (or NULL). |
| ... | Requested data items specified as name, pointer-to-value pairs. Terminated by NULL. |
true if the object looks acceptable and the item values were filled. | bool gwyfile_object_surface_get | ( | const GwyfileObject * | object, |
| GwyfileError ** | error, | ||
| ... | |||
| ) |
Obtains information and/or data from a GWY file GwySurface object.
The function checks if the object type is actually "GwySurface" and if it contains sane data items. Every GwySurface must contain at least an array of doubles "data" of size that is a multiple of 3.
If object does not seem to represent a valid GwySurface object the function fails, does not fill any output arguments (beside the error) and returns false.
All other items have default values that will be returned if the corresponding item is not found, is of the wrong type or has an invalid value. Unknown additional items are simply ignored. The function does not fail in these cases and returns true.
Possible items to request:
"data" – array of doubles of size 3 × n. The array ownership does not change (as if gwyfile_item_get_double_array() was used)."data(take)" – array of doubles of size 3 × n. The array ownership is transferred to the caller (as if gwyfile_item_take_double_array() was used) who has to free it with free() later. Taking the data is not permitted if they are not owned by the data item. Hence you may request "data" repeatedly but "data(take)" may be requested from each object at most once."n" – 32bit integer. Number of points. Note that the number values in the data array is three times the number of points."si_unit_xy" – string. Physical units of X and Y coordinates, base SI units, e.g. "m". The returned string is newly allocated and the caller must free it with free()."si_unit_z" – string. Physical units of Z values, base SI units, e.g. "A". The returned string is newly allocated and the caller must free it with free().| object | A GWY file data object, presumably a GwySurface. |
| error | Location for the error (or NULL). |
| ... | Requested data items specified as name, pointer-to-value pairs. Terminated by NULL. |
true if the object looks acceptable and the item values were filled. 1.9.1