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

© David Nečas and Petr Klapetek

Home Download News Features Screenshots Documentation Communicate Participate Resources Publications Applications Site Map

Valid XHTML 1.0 Valid CSS