Gwyddion – Free SPM (AFM, SNOM/NSOM, STM, MFM, …) data analysis software

synth module utils (HEAD)

synth module utils — Helper functions for data synthesis modules

Functions

void	gwy_synth_define_dimensions_params ()
void	gwy_synth_sanitise_params ()
void	gwy_synth_append_dimensions_to_param_table ()
void	gwy_synth_use_dimensions_template ()
void	gwy_synth_update_value_unitstrs ()
void	gwy_synth_update_lateral_alts ()
void	gwy_synth_update_like_current_button_sensitivity ()
gboolean	gwy_synth_handle_param_changed ()
GwyAppDataId	gwy_synth_add_result_to_file ()
GwyDataField *	gwy_synth_make_result_data_field ()
GwyDataField *	gwy_synth_make_preview_data_field ()
GwySynthUpdateType	gwy_synth_update_progress ()

Types and Values

enum	GwySynthResponseType
enum	GwySynthDimsParam
enum	GwySynthDimsFlags
enum	GwySynthUpdateType

Includes

#include <app/gwyapp.h>

Description

Functions

gwy_synth_define_dimensions_params ()

void
gwy_synth_define_dimensions_params (GwyParamDef *paramdef,
                                    gint first_id);

Defines the standard set of dimension parameters for a data synthesis module.

Parameters with ids starting from first_id will become GwySynthDimsParam paramers. For instance first_id + GWY_DIMS_PARAMS_XREAL will be the id of the standard xreal parameter.

Parameters

paramdef	A set of parameter definitions.
first_id	First free id for the block of dimension parameters.

Since: 2.59

gwy_synth_sanitise_params ()

void
gwy_synth_sanitise_params (GwyParams *params,
                           gint first_id,
                           GwyDataField *template_);

Ensures a basic consistency the standard set of dimension parameters for a data synthesis module.

This function also remembers first_id and template_ for params . Other helper functions then do not take these arguments, but you need to call this function to set up the association. If the module has constrains on possible templates it has to ensure the template is valid; if the template is not valid pass NULL instead.

Parameters

params	A set of parameter values.
first_id	First id of the block of dimension parameters.
template_	Template data field. Normally it is the current image, or `NULL` if there is no current image.

Since: 2.59

gwy_synth_append_dimensions_to_param_table ()

void
gwy_synth_append_dimensions_to_param_table
                               (GwyParamTable *partable,
                                GwySynthDimsFlags flags);

Appends the standard set of dimension parameters for a data synthesis module to a parameter table.

Usually, this is used to fill the content of a ‘Dimensions’ tab of the dialogue.

The parameter table must be created for a set of parameters defined with gwy_synth_define_dimensions_params() and set up with gwy_synth_sanitise_params().

Parameters

partable	Set of parameter value controls.
flags	Set of flags controlling the available parameters.

Since: 2.59

gwy_synth_use_dimensions_template ()

void
gwy_synth_use_dimensions_template (GwyParamTable *partable);

Updates a set of dimension parameters for a data synthesis module to match the template.

This will result in invocation of “param-changed” signal with id -1.

The parameter table must be created for a set of parameters defined with gwy_synth_define_dimensions_params() and set up with gwy_synth_sanitise_params() – this is where the template to use was defined.

Parameters

partable

Set of parameter value controls.

Since: 2.59

gwy_synth_update_value_unitstrs ()

void
gwy_synth_update_value_unitstrs (GwyParamTable *partable,
                                 const gint *ids,
                                 guint nids);

Updates unit strings of value-like parameters in a synth module parameter table.

The parameters should be free-form value-like parameters, for instance heights.

The parameter table must be created for a set of parameters defined with gwy_synth_define_dimensions_params() and set up with gwy_synth_sanitise_params().

Parameters

partable	Set of parameter value controls.
ids	Array of parameter ids (controlled by `partable` ).
nids	The number of items in `ids` .

Since: 2.59

gwy_synth_update_lateral_alts ()

void
gwy_synth_update_lateral_alts (GwyParamTable *partable,
                               const gint *ids,
                               guint nids);

Updates unit strings of dimension-like parameters in a synth module parameter table.

The parameters should be lateral pixel dimension parameters with alternative real dimensions.

The parameter table must be created for a set of parameters defined with gwy_synth_define_dimensions_params() and set up with gwy_synth_sanitise_params().

Parameters

partable	Set of parameter value controls.
ids	Array of parameter ids (controlled by `partable` ).
nids	The number of items in `ids` .

Since: 2.59

gwy_synth_update_like_current_button_sensitivity ()

void
gwy_synth_update_like_current_button_sensitivity
                               (GwyParamTable *partable,
                                gint id);

Updates the sensitivity of the standard Like Current Image button in a synth module parameter table.

The buttons is made sensitive if the value units of the template data field match the selected value units. If there is no template the button is usually now show at all. It is safe to call this function even in this case.

The parameter table must be created for a set of parameters defined with gwy_synth_define_dimensions_params() and set up with gwy_synth_sanitise_params().

Parameters

partable	Set of parameter value controls.
id	Parameter id corresponding to the Like Current Image button.

Since: 2.59

gwy_synth_handle_param_changed ()

gboolean
gwy_synth_handle_param_changed (GwyParamTable *partable,
                                gint id);

Handles changes in a set of standard dimension parameters in a data synthesis module.

The parameter table must be created for a set of parameters defined with gwy_synth_define_dimensions_params() and set up with gwy_synth_sanitise_params().

Parameters

partable	Set of parameter value controls.
id	Changed parameter id (as obtained in the signal handler).

Returns

TRUE if the action taken was a mass parameter update. The caller should then proceed as if id was -1, whether it was originally or not.

Since: 2.59

gwy_synth_add_result_to_file ()

GwyAppDataId
gwy_synth_add_result_to_file (GwyDataField *result,
                              GwyContainer *data,
                              gint id,
                              GwyParams *params);

Adds the result of data synthesis to a file.

This function takes care of handling correctly the GWY_DIMS_PARAM_REPLACE and GWY_DIMS_PARAM_INITIALIZE options (the latter with regard to logging and sync; actual computation input is handled by the module) in the various cases such as data and/or id existing or not.

The parameter value set must be created for a set of parameters defined with gwy_synth_define_dimensions_params() and set up with gwy_synth_sanitise_params().

Parameters

result	Data field with the simulation output.
data	Data container corresponding to the current file, or `NULL` is there is none.
id	Id or the current image (or -1 if there is none).
params	The set of parameter values for the synth module.

Returns

Data id of the result. It can correspond a newly created image or an existing image, depending on the settings.

Since: 2.59

gwy_synth_make_result_data_field ()

GwyDataField *
gwy_synth_make_result_data_field (GwyDataField *data_field,
                                  GwyParams *params,
                                  gboolean always_use_template);

Creates a data field for the output of a data synthesis module.

The new data field properties match either data_field or values of the dimension and unit parameters, depending on GWY_DIMS_PARAM_REPLACE and GWY_DIMS_PARAM_INITIALIZE (and also always_use_template ).

The parameter value set must be created for a set of parameters defined with gwy_synth_define_dimensions_params() and set up with gwy_synth_sanitise_params().

Parameters

data_field	Data field to be used as template, possibly `NULL`.
params	The set of parameter values for the synth module.
always_use_template	`TRUE` to always prefer creating a new data field matching `data_field` , unless it is `NULL`.

Returns

A newly created data field.

Since: 2.59

gwy_synth_make_preview_data_field ()

GwyDataField *
gwy_synth_make_preview_data_field (GwyDataField *data_field,
                                   gint size);

Creates a suitable data field running a data synthesis module in the preview mode.

The preview data field is created by a combination of cutting the central part of data_field (if too large) and resampling it to higher resolution (if too small). It will always be square, size by size .

For some data synthesis modules is can make more sense to run even the preview for the actual image size. Do not use this function in such case.

Parameters

data_field	Data field to be used as template, possibly `NULL`.
size	Pixel size of the result.

Returns

A newly created data field.

Since: 2.59

gwy_synth_update_progress ()

GwySynthUpdateType
gwy_synth_update_progress (GTimer *timer,
                           gdouble preview_time,
                           gulong i,
                           gulong niters);

Manages progress bar updates and preview animation in a data synthesis module.

This helper functions updates the progress bar to i /niters and check whether a preview should be done when it is animated.

Parameters

timer	A timer started together with the computation. Pass `NULL` to forget the last preview time.
preview_time	Minimum time between previews, in seconds. Pass a non-positive value if previews are not animated.
i	Current iteration/cycle. A monotonically increasing number.
niters	The total number of iterations/cycles.

Returns

What should happen.

Since: 2.59

Types and Values

enum GwySynthResponseType

Dialog responses for buttons created by gwy_synth_append_dimensions_to_param_table().

Members

GWY_RESPONSE_SYNTH_TAKE_DIMS	Take dimensions and units from the current image.
GWY_RESPONSE_SYNTH_INIT_Z	Set value scale to match the value scale of the current image.

Since: 2.59

enum GwySynthDimsParam

Ids of parameters created by gwy_synth_define_dimensions_params().

The enum also includes a few GUI elements to satisfy the id uniqueness required by GwyParamTable.

Members

GWY_DIMS_PARAM_XRES	Horizontal pixel resolution.
GWY_DIMS_PARAM_YRES	Vertical pixel resolution.
GWY_DIMS_PARAM_SQUARE_IMAGE	Whether the image is square (pixelwise).
GWY_DIMS_PARAM_XREAL	Horizontal physical dimension, in base SI units.
GWY_DIMS_PARAM_YREAL	Vertical physical dimension, in base SI units.
GWY_DIMS_PARAM_SQUARE_PIXELS	Whether pixels are physically square.
GWY_DIMS_PARAM_XYUNIT	Unit of lateral dimensions.
GWY_DIMS_PARAM_ZUNIT	Unit of values.
GWY_DIMS_PARAM_REPLACE	Whether the simulation result should replace the current image.
GWY_DIMS_PARAM_INITIALIZE	Whether the simulation should start from the current image.
GWY_DIMS_BUTTON_TAKE	Button Like Current Image.
GWY_DIMS_HEADER_PIXEL	Header for the pixel dimensions section.
GWY_DIMS_HEADER_PHYSICAL	Header for the physical dimensions section.
GWY_DIMS_HEADER_UNITS	Header for the unit section.
GWY_DIMS_HEADER_CURRENT_IMAGE	Header for the Current Image section.

Since: 2.59

enum GwySynthDimsFlags

Possible flags passed to gwy_synth_append_dimensions_to_param_table().

Members

GWY_SYNTH_FIXED_XYUNIT	The lateral unit is fixed and cannot be set by the user.
GWY_SYNTH_FIXED_ZUNIT	The value unit is fixed and cannot be set by the user.
GWY_SYNTH_FIXED_UNITS	No units can be set by the uset.
GWY_SYNTH_NO_INITIALIZE	The option to start from the current image is not available. (Since 2.62)

Since: 2.59

enum GwySynthUpdateType

Possible return values from gwy_synth_update_progress().

Members

GWY_SYNTH_UPDATE_CANCELLED	The computation was cancelled by the user.
GWY_SYNTH_UPDATE_NOTHING	Nothing has changed; proceed with computation.
GWY_SYNTH_UPDATE_DO_PREVIEW	Render a preview of the current computation state.

Since: 2.59