Operation log: Gwyddion Application Library Reference Manual

Operation log

Operation log — Logging data processing operations

Functions

void	gwy_log_add_full ()
void	gwy_log_add_params_full ()
void	gwy_log_add ()
void	gwy_log_add_import ()
void	gwy_log_add_synth ()
void	gwy_log_add_tool ()
void	gwy_log_add_tool_target ()
gboolean	gwy_log_get_enabled ()
void	gwy_log_set_enabled ()

Includes

#include <libgwyapp/gwyapp.h>

Description

The data processing operation log is a linear sequence of operations applied to a image, volume, XYZ or curve map data. The log is informative and not meant to capture all information necessary to reply the operations, even though it can be sufficient for this purpose in simple cases.

The log is a linear sequence. This is only an approximation of the actual flow of information in the data processing, which corresponds to an acyclic directed graph (not necessarily connected as data, masks and presentations can have distinct sources). The following rules thus apply to make it meaningful and useful.

Each logging function takes two data identifiers: source and target. The source corresponds to the operation input, the target corresponds to the data whose log is being updated. The target may have already a log only if it is the same as the source (which corresponds to simple data modification such as levelling or grain marking). In all other cases the target must not have a log yet – they represent the creation of new data either from scratch or based on existing data (in the latter case the log of the existing data is replicated to the new one).

Complex multi-data operations are approximated by one of the simple operations. For instance, data arithmetic can be treated as the construction of a new channel from scratch as it is unclear which input data the output channel is actually based on, if any at all. Modifications that use data from other channels, such as masking using another data or tip convolution, should be represented as simple modifications of the primary channel.

Logging functions such as gwy_log_add() take settings values corresponding to the function name and store them in the log entry. If the settings are stored under a different name, use the "settings-name" logging option to set the correct name.

Functions

gwy_log_add_full()

void
gwy_log_add_full (GwyFile *file,
                  GwyDataKind data_kind,
                  gint previd,
                  gint newid,
                  const gchar *function,
                  ...);

Adds an entry to the log of data processing operations for a channel.

See the introduction for a description of valid previd and newid .

It is possible to pass NULL as function . In this case the log is just copied from source to target without adding any entries. This can be useful to prevent duplicate log entries in modules that modify a data field and then can also create secondary outputs. Note you still need to pass a second NULL argument as the argument list terminator.

Parameters

file	A data file container.
data_kind	Type of the data object modified or created.
previd	Identifier of the previous (source) data object of the same type in the container. Pass -1 for a no-source (or unclear source) operation or operations involving disparate data objects.
newid	Identifier of the new (target) data object in the container.
function	Quailified name of the function applied as shown by the module browser. For instance "image::facet-level" or "tool::GwyToolCrop".
...	Logging options as a `NULL`-terminated list of pairs name, value.

gwy_log_add_params_full()

void
gwy_log_add_params_full (GwyFile *file,
                         GwyDataKind prev_data_kind,
                         GwyDataKind new_data_kind,
                         gint previd,
                         gint newid,
                         const gchar *function,
                         GwyParams *params);

Adds an entry to the log for a data processing operation executed with an explicit parameter set.

This is a general and relatively low-level function. In most cases, you can use a more convenient log function which does not require providing all the information manually.

It is valid to pass NULL params if the function has no parameters. If the operation has no single identifiable source data, you can pass previd as GWY_FILE_ID_NONE and prev_data_kind and GWY_FILE_NONE. However, the data created or modified by the operation must always be valid.

Parameters

file	A data file container.	[transfer none]
prev_data_kind	Type of the source data object modified or created.
new_data_kind	Type of the destination data object modified or created.
previd	Identifier of the previous (source) data object in the file. Pass -1 for a no-source (or unclear source) operation.
newid	Identifier of the new (target) data object in the file.
function	Quailified name of the function applied as shown by the module browser. For instance "image::facet-level" or "tool::crop".
params	A parameter value set used in the operation.	[nullable][transfer none]

gwy_log_add()

void
gwy_log_add (GwyFile *file,
             GwyDataKind data_kind,
             gint previd,
             gint newid);

Adds an entry to the log of the current data processing operation.

This simplified variant of gwy_log_add_full() takes the currently running data processing function name for the corresponding data kind and constructs the qualified function name from that. The source and target data kinds need to be the same and correspond to the function type. If the function creates data of a different kind than the ‘natural’ kind for this type of function, you need gwy_log_add_full().

Use gwy_log_add_import() to log data import from third party files and gwy_log_add_synth() to log data synthesis.

Parameters

file	A file data container.
data_kind	Type of the data object.
previd	Identifier of the previous (source) data object in the file. Pass -1 for a no-source (or unclear source) operation.
newid	Identifier of the new (target) data object in the file.

gwy_log_add_import()

void
gwy_log_add_import (GwyFile *file,
                    GwyDataKind data_kind,
                    gint id,
                    const gchar *filetype,
                    const gchar *filename);

Logs the import of a data object from third-party file.

This is a convenience wrapper for gwy_log_add_full(). The source id will be set to -1. The file name will be added to function arguments.

Parameters

file	A data file container.
data_kind	Type of the data object.
id	Numerical id of a data in file.
filetype	File type, i.e. the name of the function importing the data (without any "file::" prefix). It is possible to pass `NULL` to fill the name of the currently running file type function automatically.
filename	Name of the imported file. If it is not valid UTF-8, it will be converted to UTF-8 using `g_filename_to_utf8()`. Failing even that, non-ASCII characters will be escaped.

gwy_log_add_synth()

void
gwy_log_add_synth (GwyFile *file,
                   GwyDataKind data_kind,
                   gint previd,
                   gint newid);

Adds an entry to the log of the current synthetic data operation.

This simplified variant of gwy_log_add_full() takes the currently running synthetic data function name for the corresponding data kind and constructs the qualified function name from that.

Parameters

file	A file data container.
data_kind	Type of the data object.
previd	Identifier of the initialisation data object in the file. Pass -1 if the data were generated from scatch, not by modification of existing data.
newid	Identifier of the new data object in the file.

gwy_log_add_tool()

void
gwy_log_add_tool (GwyTool *tool);

Logs an in-place data modification operation by an interactive tool.

The parameters, data kind and id are taken from the tool. Tools often modify data in place, and this function is then sufficient. Use gwy_log_add_tool_target() if you need to specify different target data, for example when the tool creates a data of different kind. In the most complex cases, use gwy_log_add_params_full() directly; all the information can be obtained using gwy_tool_get_something() calls.

Parameters

tool

An interactive tool.

gwy_log_add_tool_target()

void
gwy_log_add_tool_target (GwyTool *tool,
                         GwyDataKind new_data_kind,
                         gint newid,
                         gboolean copy_log);

Logs a creation of new data by an interactive tool.

The parameters, source data kind and id are taken from the tool. The new data must be valid.

The function is mainly intended for cases such as adding another curve to a target graph which already has a log. Therefore, pass copy_log as FALSE. The operation is then logged as a single entry; it does not copy the entire data log of tool's current primary data.

A case when copy_log should be TRUE is a crop tool creating a new data.

Parameters

tool	An interactive tool.
new_data_kind	Type of the destination data object modified or created.
newid	Identifier of the new data object in the file.
copy_log	Pass `TRUE` to copy the source log; `FALSE` to just add a single entry.

gwy_log_get_enabled()

gboolean
gwy_log_get_enabled (void);

Reports whether logging of data processing operations is globally enabled.

Returns

TRUE if logging is enabled, FALSE if it is disabled.

gwy_log_set_enabled()

void
gwy_log_set_enabled (gboolean setting);

Globally enables or disables logging of data processing operations.

By default, logging is enabled. Non-GUI applications that run module functions may wish to disable it. Of course, the log will presist only if the data container is saved into a GWY file.

If logging is disabled logging functions such as gwy_log_add() become no-op. It is possible to run the log viewer with gwy_log_browser() to see log entries created when logging was enabled.

Parameters

setting

TRUE to enable logging, FALSE to disable it.