synth module utils: Gwyddion Application Library Reference Manual

## synth module utils 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