2 :keywords: mesh, field, manipulation, user guide
3 :author: Guillaume Boulant
5 .. include:: medop-definitions.rst
7 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
8 MED module: User guide for graphical interface
9 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
11 This document is a quick guide for Graphical User Interface of MED module. It
12 shows how to use this module on the basis of a few reference examples, built
13 from use cases identified during requirement analysis stage.
15 .. warning:: This document is self-contained, but it is strongly advised to
16 read :doc:`the specification document<medop-specifications>` (in
17 french), at least to clarify concepts and terminology.
19 .. contents:: Contents
23 .. warning:: Screenshots are not up-to-date. They were extracted from SALOME
24 6 with data visualization achieved using VISU module. In SALOME
25 7, VISU module has been replaced by PARAVIS module. The
26 look-and-feel may thus be slightly different.
28 General presentation of MED module
29 ==================================
31 The overall ergonomics of MED module for field manipulation is inspired by
32 softwares such as octave or scilab. It combines a graphical interface (GUI) to
33 select and prepare data, with a textual interface (the python console, TUI)
34 for actual work on data.
36 This module provides two user environments that are marked by the red and
37 green rectangles on the screenshot below:
39 * **The data space** (*dataspace*), in which user defines the MED data sources
40 (*datasource*), that is to say the med files from which meshes and fields
41 are read. This data space allows for the exploration of meshes and fields
42 provided by the different data sources.
43 * **The workspace** (*workspace*), in which user may drop fields selected in
44 the source space, and then use them for example to produce new fields using
45 the operations on fields provided by the TUI.
47 .. image:: images/xmed-gui-withframe.png
50 A typical use of field manipulation functions is:
52 1. Load a med file in the data space and explore its contents: meshes and
53 fields defined on these meshes, defined for one or several time steps.
54 2. Select (using GUI) fields to be manipulated in workspace ; it is possible
55 to introduce restrictions on time steps, components or groups of cells.
56 3. Create new fields executing algebraic operations (+,-,*,/) on fields,
57 applying simple mathematical functions (pow, sqrt, abs), or initializing
58 them "from scratch" on a support mesh.
59 4. Visually control produced fields, using PARAVIS module in SALOME,
60 automatically controlled from user interface.
61 5. Save (parts of) produced fields to a med file.
64 Quick tour on functions available in MED module
65 ===============================================
67 This section presents some use examples of MED module like a "storyboard",
68 illustrating the functions proposed by the module.
70 .. warning:: This section is under construction. Please consider that its
71 contents and organization are still incomplete and may change
72 until this warning is removed.
74 Example 1: Explore data sources
75 -------------------------------
77 .. note:: This example illustrates the following functions:
80 * "Extends field series" and "Visualize" functions
82 .. |ICO_DATASOURCE_ADD| image:: images/ico_datasource_add.png
85 .. |ICO_XMED| image:: images/ico_xmed.png
88 .. |ICO_DATASOURCE_EXPAND| image:: images/ico_datasource_expandfield.png
91 .. |ICO_DATASOURCE_VIEW| image:: images/ico_datasource_view.png
94 At startup the field manipulation module, identified by icon |ICO_XMED|, shows
97 .. image:: images/xmed-gui-start.png
101 The first step consists in adding one or several med data sources in
102 "dataspace". For this, user clicks on icon "Add datasource"
103 |ICO_DATASOURCE_ADD| to select a med file:
105 .. image:: images/xmed-gui-datasource-selectfile.png
109 This operation adds a new entry (datasource) in data space. The contents can
110 be explored using the data tree. The figure below (left image) shows the
111 result of loading the file ``timeseries.med`` containing a mesh named
112 ``Grid_80x80`` on which a field on nodes named ``Pulse`` is defined. By
113 default, the field composition (in terms of time steps and components) is not
114 displayed to avoid visual congestion of data tree. User must explicitly ask
115 for visualization using the command "Expand field timeseries"
116 |ICO_DATASOURCE_EXPAND| available in the field contextual menu. The result is
117 displayed on center image. The list of field ``Pulse`` iterations can be advised.
119 .. |IMG_DATASOURCE_EXPLORE| image:: images/xmed-gui-datasource-explore-zoom.png
121 .. |IMG_DATASOURCE_MENUCON| image:: images/xmed-gui-datasource-menucontextuel-zoom.png
123 .. |IMG_DATASOURCE_EXPANDF| image:: images/xmed-gui-datasource-expand-zoom.png
126 +--------------------------+--------------------------+--------------------------+
127 | |IMG_DATASOURCE_EXPLORE| | |IMG_DATASOURCE_MENUCON| | |IMG_DATASOURCE_EXPANDF| |
128 +--------------------------+--------------------------+--------------------------+
130 .. note:: Strictly speaking, the *field* concept in MED model corresponds to
131 a given iteration. A set of iterations is identified by the term
132 *field time series*. If there is no ambiguity, the field name will
133 refer to both the field itself or the time series it belongs to.
135 Finally, it is possible from dataspace to visualize the field general shape
136 using a scalar map displayed in SALOME viewer. For this, user selects the time step to
137 display then uses the command "Visualize" |ICO_DATASOURCE_VIEW| available in
138 the associated contextual menu:
140 .. image:: images/xmed-gui-datasource-visualize-zoom.png
144 .. note:: This graphical representation aims at providing a quick visual
145 control. Scalar maps are displayed using the PARAVIS module.
147 Example 2: Combine fields from different sources
148 ------------------------------------------------
150 .. note:: This example illustrates the following functions:
152 * function "Use in workspace"
155 .. |ICO_DATASOURCE_USE| image:: images/ico_datasource_use.png
157 .. |ICO_WORKSPACE_SAVE| image:: images/ico_workspace_save.png
160 The objective is to access data contained in several med files, then to
161 combine them in the same output file.
163 User starts by adding med data sources in dataspace. In the example below,
164 dataspace contains two sources names ``parametric_01.med`` and
165 ``smallmesh_varfiled.med``. The first one contains the mesh ``Grid_80x80_01``
166 on which the field ``StiffExp_01`` is defined. The second source contains the
167 mesh ``My2DMesh`` on which the two fields ``testfield1`` are ``testfield2``
170 .. image:: images/xmed-userguide-example2-datasource.png
174 In this example, ``StiffExp_01`` and ``testfield2`` are combined then saved to
175 ``result.med`` file. The procedure consists in importing the two fields in
176 workspace, then to save the workspace. For this user selects the fields and
177 uses the command "Use in workspace" |ICO_DATASOURCE_USE| available in the
178 contextual menu. Both selected fields appear in the workspace tree:
180 .. image:: images/xmed-userguide-example2-workspace.png
184 Workspace is saved using the command "Save workspace" |ICO_WORKSPACE_SAVE|
185 available in the module toolbar. A dialog window lets user set the save
188 .. image:: images/xmed-userguide-example2-workspace-save.png
192 The file ``result.med`` can then be reloaded in MED module (or PARAVIS module)
193 to check the presence of saved fields.
195 .. BUG: plantage à l'utilsation dans XMED d'un fichier rechargé
196 .. (invalid mesh on field)
198 .. _xmed.userguide.exemple3:
200 Example 3: Apply a formula on fields
201 ------------------------------------
203 .. note:: This example illustrates the following functions:
205 * execute mathematical operations in TUI console
206 * function "put" to refer to a work field in the list of persisting fields.
207 * function "Visualize" from TUI.
209 The most common usage of field manipulation module is to execute mathematical
210 operations on fields or on their components.
212 Assume data sources are already defined in dataspace (in the following example
213 a temporal series named ``Pulse`` contains 10 time steps defined on a mesh
214 named ``Grid_80x80``, all read from ``timeseries.med`` data source).
216 As previously seen, a field can be manipulated in workspace after selecting
217 the field and applying the command "Use in
218 workspace" |ICO_DATASOURCE_USE| from contextual menu. Here only one file is
219 selected (two in the previous example) and the command then opens a dialog
220 window to select data to work on and the way they will be manipulated:
222 .. image:: images/xmed-gui-datasource-useinworkspace-alias.png
226 .. note:: In the current state of development, the interface only propose to
227 define the name of a variable representing the field in TUI. In
228 a next version, user will have the possibility to specify the field
229 component(s) to be used and a group of cells to introduce
230 a geometrical restriction. Conversely it will be possible to select
231 a complete time series to apply global operations on all time steps.
233 After validation, the field if put in workspace tree and a variable
234 ``<alias>`` is automatically created in the TUI to designate the field. In
235 this example, ``<alias>`` is ``f3``, as set by user to recall that variable
236 corresponds to the third time step:
238 .. image:: images/xmed-gui-workspace.png
242 Field manipulation can start. In the example below, use creates the field``r``
243 as the result of an affine transformation of field ``f3`` (multiplication of
244 field by a scale factor 2.7 then addition of offset 5.2)::
248 Other operations can be applied, as detailed in module specifications
249 (cf. :ref:`Spécification des opérations<xmed-specifications>`):
251 >>> r=f3/1000 # the values of r are the ones of f3 reduced by a factor 1000
252 >>> r=1/f3 # the values of r are the inverted values of f3
253 >>> r=f3*f3 # the values of r are the squared values of f3
254 >>> r=pow(f3,2) # same result
255 >>> r=abs(f3) # absolute value of field f3
258 The two operands can be fields. If ``f4`` is the fourth time step of field
259 ``Pulse``, then algebraic combinations of fields can be computed::
266 Scalar variables can be used if needed::
271 In theses examples, the variable ``r`` corresponds to a work field containing
272 the operation result. By default the field is nor referenced in workspace
273 tree. If user wants to add it, for example to make it considered when saving,
274 then the following command is used::
278 The function ``put`` aims at tagging the field as persisting, the to store it
279 in the workspace tree to make it visible and selectable. Among all fields that
280 could be created in console during the work session, all do not need to be
281 saved. Some may only be temporary variables used in the construction of final
282 fields. That is why only fields in workspace tree are saved when saving the
285 Variables defined in console have other uses. First they allow for printing
286 information relative to the manipulated field. For this one enters the
287 variable name then validates::
290 field name (id) = Pulse (3)
291 mesh name (id) = Grid_80x80 (0)
292 discretization = ON_NODES
293 (iter, order) = (3,-1)
294 data source = file:///home/gboulant/development/projets/salome/MEDOP/XMED/xmed/resources/datafiles/timeseries.med
296 Second, variables can be used as command arguments (the list of commands
297 available in TUI is described in section :ref:`Documentation of textual
298 interface<xmed.userguide.tui>`). For example the function ``view`` displays
299 the field scalar map in the viewer::
305 .. image:: images/xmed-gui-workspace-view.png
309 .. note:: It is easy to compare two time steps of a field, computing the
310 difference ``f3-f4``, then producing a scalar map preview using the
315 Finally the field data can be displayed using the command``print``::
331 It is important to note that operations between fields can only be applied if
332 fields are defined on the same mesh. It corresponds to a specification of MED
333 model that forbids operations between fields defined on meshes geometrically
334 different. Technically it means that the conceptual objects *fields* must share
335 the same conceptual object *mesh*.
337 If user do want to use fields defined on different meshes, for example to
338 manipulate the field values at the interface of two meshes sharing a 2D
339 geometrical area, it is necessary first to make all fields be defined on the
340 same surface mesh using a projection operation.
342 .. note:: Such projection operations are available in the MEDCoupling library.
344 Another classical need is using fields defined on meshes geometrically
345 identical, but technically different for example when they are loaded from
346 different med files. For such a case, the MEDCoupling library proposes
347 a function "Change support mesh" ; its use in field manipulation module is
348 illustrated in :ref:`example 4<xmed.userguide.exemple4>` described hereafter.
350 .. _xmed.userguide.exemple4:
352 Example 4: Compare fields derived from different sources
353 --------------------------------------------------------
355 .. note:: This example illustrates the following function:
357 * Change the underlying (support) mesh
359 Assume here that fields have been defined on same mesh, geometrically
360 speaking, but saved in different med files. This occurs for example for
361 a parametric study in which several computations are achieved with variants on
362 some parameters of the simulated model, each computation producing a med file.
364 Let ``parametric_01.med`` and ``parametric_02.med`` be two med files
365 containing the fields to compare, for example computing the difference of
366 their values and visualizing the result.
368 After loading data sources user sees two meshes, this time from the technical
369 point of view, that is to say fields are associated to different conceptual
370 mesh objects, while geometrically identical.
372 However field manipulation functions do not allow operations on fields lying
373 on different support meshes (see remark at the end of :ref:`example
374 3<xmed.userguide.exemple3>`).
376 To circumvent this issue, the module offers the function "Change underlying
377 mesh" to replace a field mesh support by another, provided that the two meshes
378 are geometrically identical, that is to say nodes have the same spatial
381 .. |ICO_DATASOURCE_CHG| image:: images/ico_datasource_changeUnderlyingMesh.png
384 In the proposed example, user selects the first time step of field
385 ``StiffExp_01`` in data source ``parametric_01.med``, and imports it in
386 workspace using the command "Use in workspace" |ICO_DATASOURCE_USE|. User then
387 selects the first time step of field ``StiffExp_02`` in data source
388 ``parametric_02.med``, but imports it in workspace using the command "Change
389 underlying mesh" |ICO_DATASOURCE_CHG|. The following dialog window appears to
390 let user select the new support mesh in dataspace tree:
392 .. image:: images/xmed-gui-datasource-changeUnderlyingMesh.png
395 In this example, the support mesh ``Grid_80x80_01`` of field ``StiffExp_01``
396 to compare with is selected. After validation the workspace tree contains the
397 field ``StiffExp_02`` defined on mesh ``Grid_80x80_01``:
399 .. image:: images/xmed-gui-datasource-changeUnderlyingMesh_wsview.png
402 .. note:: The function "Change underlying mesh" does not modify the field
403 selected in dataspace (basic running principle of dataspace), but
404 creates a field copy in workspace to then change support mesh. This
405 explains the default name for field ``dup(<name of selected
406 field>)`` (dup stands for "duplicate").
408 All we have to do now is to associate a variable to this field, in order to
409 manipulate it in TUI. This can be done using the command "Use in console"
410 available in workspace contextual menu.
412 Finally, if ``f1`` is a field from datasource ``parametric_01.med`` and ``f2``
413 is a field from datasource
414 ``parametric_02.med`` according to the above procedure, then comparison values
415 can be achieved as explained in :ref:`example 3<xmed.userguide.exemple3>`::
420 .. note:: As a general remark concerning this example, one may note:
422 * the geometrical equality of two meshes is constrained to a numerical
423 error that can be technically set, but not through the module interface.
424 This tolerance is empirically set to a standard value regarding to
425 success of most of the use cases. The usefulness of setting this value in
426 the interface could be later investigated.
428 * User must explicitly ask for changing a field support mesh, in order to
429 compare fields coming from different data sources. This choice has been
430 made to keep trace of modifications made on data (no modification is made
431 without user knowing, even to improve ergonomics).
434 Example 5: Create a field on a spatial domain
435 ---------------------------------------------
437 .. note:: This example illustrates the following functions:
439 * initialize with function of spatial position
440 * initialize on a group of cells
442 The geometrical domain on which the field to create is defined is here given
443 by cell group data. This use case is provided for producing initial load
444 conditions of a structure, for example defining a field on a geometry surface
445 identified by a group of cells.
447 .. warning:: DEVELOPMENT IN PROGRESS
449 Example 6: Extract a field part
450 -------------------------------
452 .. note:: This example illustrates the following functions:
454 * extract a component (or a subset of components)
455 * extract a geometrical domain (values on a group of cells)
456 * extract one or several time steps
458 .. warning:: DEVELOPMENT IN PROGRESS
460 Here the restriction functions that allow to get some components only, have
461 to be illustrated. The principle is creating a new field that is
462 a restriction of input field to a list of given components (use the
463 function __call__ of fieldproxy).
465 For time step extraction, we can reduce to the case of example 2 with a single
468 Example 7: Create a field from a to[mp]ographic image
469 -----------------------------------------------------
471 .. note:: This example illustrates the following function:
473 * Create a field without data source (neither mesh nor field), from an
476 In tomography or topography studies, measurement devices produce images that
477 represent a physical quantity using gray levels on a given cutting plane. The
478 following image represents for example a internal view of human body obtained
481 .. image:: images/xmed-irm.png
485 This image is a subset of pixels organized on a Cartesian grid. It can thus be
486 represented as a scalar field whose values are defined on cells of a mesh
487 having the same dimension as the image (number of pixels):
489 .. image:: images/xmed-irm-field.png
493 The field manipulation module provides a tool named ``image2med.py`` to
494 convert a file image to a med file containing the image representation as
495 a scalar field (only the gray level is kept)::
497 $ <xmed_root_dir>/bin/salome/xmed/image2med.py -i myimage.png -m myfield.med
499 .. |ICO_IMAGESOURCE| image:: images/ico_imagesource.png
502 This conversion operation can be automatically achieved using the command "Add
503 Image Source" |ICO_IMAGESOURCE| available in GUI toolbar. This command opens
504 the following window to let user select a file image:
506 .. image:: images/medop_image2med_dialog.png
509 The name of result med file is set by default (changing file extension to
510 ``*.med``) but can be modified. Finally user can ask for automatic load of
511 this med file in data space. Fields can then be manipulated like presented in
512 the standard use cases.
514 For example, the image below depicts the result of the difference between two
515 images, added to the reference image: if i1 and i2 are the fields created from
516 these two images, then ``r = i1 + 5*(i2-i1)`` with 5 an arbitrary factor to
517 amplify the region of interest (above the left eye):
519 .. image:: images/xmed-irm-diff.png
523 The example below is the result of loading a tomographic image courtesy of MAP
524 project (Charles Toulemonde, EDF/R&D/MMC). The tomographic image:
526 .. image:: images/champ_altitude_MAP.png
530 The result of loading:
532 .. image:: images/medop_image2med_tomographie.png
536 Example 8: Continue analysis in PARAVIS
537 ---------------------------------------
539 .. note:: This example illustrates the following functio:
541 * Export fields to PARAVIS module
543 The solutions for field representation in MED module aims at proposing a quick
546 For a detailed analysis of fields, user shall switch to PARAVIS. The field
547 manipulation module has a function to facilitate this transition, with
548 automatic load in PARAVIS and proposing a default visualization (scalar map).
550 For this user selects in workspace the fields to export, then call the export
551 function from contextual menu:
553 .. image:: images/medop_exportparavis.png
556 Selected fields are grouped in a single MED entry in PARAVIS, and the first
557 field is depicted as a scalar map:
559 .. image:: images/medop_exportparavis_result.png
563 .. note:: The export function is a convenience function. The same operation
564 can be manually achieved, first saving fields to a med file then
565 loading the created file in PARAVIS module for visualization.
567 .. _xmed.userguide.tui:
569 Using the textual interface (TUI)
570 =================================
572 All operations driven through GUI can be done (more or less easily) using TUI.
573 The field manipulation module can even be used exclusively in textual mode.
574 For this run the command::
576 $ <path/to/appli>/medop.sh
578 This command opens a command console ``medop>``. A med file can be loaded and
579 manipulated, for example to create fields from file data.
581 Whatever textual or graphical mode is used, a typical workflow in console
582 looks like the following instructions::
584 >>> load("/path/to/mydata.med")
586 id=0 name = testfield1
587 id=1 name = testfield2
591 f1 (id=0, name=testfield1)
592 f2 (id=1, name=testfield2)
595 f1 (id=0, name=testfield1)
596 f2 (id=1, name=testfield2)
597 r (id=2, name=testfield1+testfield2)
598 >>> r.update(name="toto")
600 f1 (id=0, name=testfield1)
601 f2 (id=1, name=testfield2)
604 >>> save("result.med")
606 The main commands are:
608 * ``load``: load a med file in data base (useful in pure textual mode)::
610 >>> load("/path/to/datafile.med")
612 * ``la``: show the list of all fields loaded in data base ("list all")
613 * ``get``: set a field in workspace from its identifier (useful in pure
614 textual mode ; this operation can be done in GUI selecting a field from data
619 * ``ls``: show the list of fields available in workspace ("list")
620 * ``put``: put a reference to a field in *management space*::
624 * ``save``: save to a med a file all fields referenced in management space::
626 >>> save("/path/to/resultfile.med")
630 * the ``load`` command only loads metadata describing meshes and fields
631 (names, discretization types, list of time steps). Meshes and physical
632 quantities on fields are loaded later (and automatically) as soon as an
633 operation needs them. In all cases med data (mete-information and values)
634 are physically stored in *data base* environment.
635 * the ``get`` command defines a *field handler* in workspace, i.e.
636 a variable that links to the physical field hosted in data base. Physical
637 data never transit between environments but remain centralized in data
640 The following TUI commands need to work in graphical environment:
642 * ``visu``: display a field map for quick visual control (no parametrization
649 .. LocalWords: softwares