File: module-tutorial-overview.xml

package info (click to toggle)
gwyddion 2.52-1
  • links: PTS, VCS
  • area: main
  • in suites: buster
  • size: 46,588 kB
  • sloc: ansic: 367,740; python: 7,788; sh: 5,245; makefile: 4,317; xml: 3,631; cpp: 2,550; pascal: 418; perl: 154; ruby: 130
file content (139 lines) | stat: -rw-r--r-- 6,746 bytes parent folder | download | duplicates (4)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 
               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<refentry id="gwymodule-tutorial-overview" revision="$Id: module-tutorial-overview.xml 20682 2017-12-18 18:39:00Z yeti-dn $">
  <refmeta>
    <refentrytitle>Gwyddion Module Overview</refentrytitle>
    <manvolnum>3</manvolnum>
    <refmiscinfo>Gwyddion</refmiscinfo>
  </refmeta>

  <refnamediv>
    <refname>Gwyddion Module Overview</refname>
    <refpurpose>
      Overview of <application>Gwyddion</application> modules
    </refpurpose>
  </refnamediv>

  <refsect1>
    <title>Module Types</title>
    <para>
      <application>Gwyddion</application> is quite a modular application.  In
      fact, most of its basic functionallity is provided by modules.  Modules
      allow to easily extend <application>Gwyddion</application> without the
      need to recompile.  However, it is currently impossible to load, unload
      and change modules while <application>Gwyddion</application> is running,
      therefore it has to be restarted when the set of modules change. Modules
      are then automatically detected, registered and the functions provided by
      modules are added to <application>Gwyddion</application> menus and/or
      toolboxes.
    </para>
    <para>
      There are several distinct module types:
      <itemizedlist>
        <listitem><para>
          <link linkend="gwymodule-tutorial-process">data processing
          modules</link> that provide functions for processing of
          two-dimensional data arrays (e.g. <emphasis>Fast Fourier
          Transform</emphasis> module), or changing the graphical presentation
          of data (e.g. <emphasis>shading</emphasis> module). Data processing
          modules usually get data (i.e. two-dimensional field of SPM data),
          possibly ask for processing options and do the requested data
          processing. More interactive functions are typically better
          implemented as tool modules.
        </para></listitem>
        <listitem><para>
          <link linkend="gwymodule-tutorial-file">file loading and saving
          modules</link> that handle import and export of foreign file formats,
          also the <application>Gwyddion</application> native file format is
          handled by a module.
        </para></listitem>
        <listitem><para>
          <link linkend="gwymodule-tutorial-graph">graph modules</link> that
          operate on one-dimensional data (graphs), e.g. profiles obtained by
          <emphasis>Profile selection</emphasis> tool. An example is
          <emphasis>Function fit</emphasis> module.
        </para></listitem>
        <listitem><para>
          <link linkend="gwymodule-tutorial-tool">tool modules</link> that
          provide tools operating on two-dimensional data directly in
          application data windows. They have typically more interactive
          interface than processing modules and allow to select objects on the
          data with mouse.  Examples include <emphasis>Read value</emphasis> or
          <emphasis>Three-point leveling</emphasis> tools.
        </para></listitem>
        <listitem><para>
          <link linkend="gwymodule-tutorial-layer">layer modules</link> that
          implement two-dimensional data selections as <emphasis>rectangular
          selection</emphasis> or <emphasis>line selection</emphasis>.
          Selections are mostly employed in tool modules, however several data
          processing modules use them too.
        </para></listitem>
      </itemizedlist>
    </para>
    <para>
      The above types are in fact <emphasis>function</emphasis> types, not
      module types.  One module often provides a single function, but it can
      also provide a whole bunch of completely unrelated functions, even of
      different types.  However, it is usual to group functions containing
      considreable amount of common code to one module (to allow sharing), and
      use separate modules for unrelated functions.
    </para>
    <para>
      More precisely, a file (i.e., a shared/dynamically linked library) always
      corresponds to a one <application>Gwyddion</application> module.
      A module can register zero or more functions (features) of arbitrary
      type.
    </para>
  </refsect1>

  <refsect1>
    <title>Data Representation</title>
    <para>
      The object representing a data file in Gwyddion is #GwyContainer.
      It is a general container that can hold values of mixes types: atomic,
      strings or objects.  Its items are identified with #GQuark<!--x-->s,
      that is either by strings or by integers associated with the strings.
    </para>
    <para>
      Two-dimensional data arrays (represented with #GwyDataField) or
      one-dimensional curve data (represented with #GwyGraphModel and
      #GwyGraphCurveModel) and auxiliary data are stored at keys resembling
      Unix file paths and forming a kind of hierarchical structure.
      For instance the data of the zeroth channel and its title can be
      obtained with
    </para>
    <informalexample><programlisting><![CDATA[
data_field = gwy_container_get_object_by_name(container, "/0/data");
title      = gwy_container_get_string_by_name(container, "/0/data/title");
]]></programlisting></informalexample>
    <para>
      The location of certain items is given by historical reasons and do not
      always make much sense.  Fortunately a module author is rarely forced to
      resort to this low-level interface. The
      <link linkend="libgwyapp-data-browser">data browser</link> provides
      high-level view of the file and means to perform all common operations.
    </para>
    <para>
      In the high-level view, channels and graphs in a file are simply numbered
      by small integers (each data type has its own numbering) and to uniquely
      identify an object one uses the (container, id) couple.
      The id number an object does not change during its lifetime (however,
      it can change when the file is saved, closed and then opend again).
      There are also functions with similar interface, operating on auxiliary
      data.
    </para>
    <para>
      For example to add a new data field to a container (file) we call
    </para>
    <informalexample><programlisting><![CDATA[
new_id = gwy_app_data_browser_add_data_field(data_field, container, TRUE);
]]></programlisting></informalexample>
    <para>
      The function gwy_app_data_browser_add_data_field() takes care of finding
      a free id, storing the data field at the right key and even creation of
      a window showing the new data field.
    </para>
  </refsect1>
</refentry>