.. meta::
- :keywords: maillage, champ, manipulation, guide utilisateur
+ :keywords: mesh, field, manipulation, user guide
:author: Guillaume Boulant
.. include:: medop-definitions.rst
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-Module MED: Guide d'utilisation de l'interface graphique
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+MED module: User guide for graphical interface
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-Ce document est un guide rapide pour l'utilisation de l'interface
-graphique du module MED. Il montre comment utiliser le module sur la
-base de quelques exemples de référence, inspirés des cas d'utilisation
-identifiés lors de l'analyse des besoins en matière de manipulation de
-champs.
+This document is a quick guide for Graphical User Interface of MED module. It
+shows how to use this module on the basis of a few reference examples, built
+from use cases identified during requirement analysis stage.
-.. warning:: Le document est autonome, mais il est vivement conseillé
- de parcourir au préalable (ou en parallèle) :doc:`le document de
- spécifications<medop-specifications>`, au moins pour fixer les
- concepts et la terminologie.
+.. warning:: This document is self-contained, but it is strongly advised to
+ read :doc:`the specification document<medop-specifications>` (in
+ french), at least to clarify concepts and terminology.
-.. contents:: Sommaire
+.. contents:: Contents
:local:
:backlinks: none
-Présentation générale du module MED
-===================================
-
-L'ergonomie générale d'utilisation du module de manipulation de champs
-est inspirée des logiciels comme octave ou scilab. Elle associe une
-interface graphique, pour sélectionner et préparer les données, avec
-une interface texte (la console python) pour le travail effectif sur
-les données.
-
-Pour cela, le module propose deux espaces utilisateurs qui sont
-symbolisés par les rectangles rouges et vert sur la capture d'écran
-ci-dessous:
-
-* **l'espace des données** (*dataspace*), dans lequel l'utilisateur
- définit les sources de données med (*datasource*), c'est-à-dire les
- fichiers med dans lesquels sont lus les champs et maillages. Cet
- espace permet l'exploration des maillages et des champs fournis par
- les différentes sources de données.
-* **l'espace de travail** (*workspace*), dans lequel l'utilisateur
- peut déposer des champs sélectionnées dans l'espace source, pour
- ensuite les travailler par exemple pour produire des nouveaux champs
- au moyen des fonctions de manipulation fournies par l'interface
- textuelle (console python TUI).
+.. warning:: Screenshots are not up-to-date. They were extracted from SALOME
+ 6 with data visualization achieved using VISU module. In SALOME
+ 7, VISU module has been replaced by PARAVIS module. The
+ look-and-feel may thus be slightly different.
+
+General presentation of MED module
+==================================
+
+The overall ergonomics of MED module for field manipulation is inspired by
+softwares such as octave or scilab. It combines a graphical interface (GUI) to
+select and prepare data, with a textual interface (the python console, TUI)
+for actual work on data.
+
+This module provides two user environments that are marked by the red and
+green rectangles on the screenshot below:
+
+* **The data space** (*dataspace*), in which user defines the MED data sources
+ (*datasource*), that is to say the med files from which meshes and fields
+ are read. This data space allows for the exploration of meshes and fields
+ provided by the different data sources.
+* **The workspace** (*workspace*), in which user may drop fields selected in
+ the source space, and then use them for example to produce new fields using
+ the operations on fields provided by the TUI.
.. image:: images/xmed-gui-withframe.png
:align: center
-L'utilisation type des fonctions de manipulation de champs suit un
-processus de la forme suivante:
+A typical use of field manipulation functions is:
-1. Chargement d'un fichier med dans l'espace de données (dataspace) et
- exploration du contenu, composé de maillages et de champs définis
- sur ces maillages et pouvant contenir un ou plusieurs pas de temps.
-2. Sélection (graphique) des champs à manipuler dans l'espace de
- travail (workspace), avec la possibilité de préciser des
- restrictions d'utilisation (pas de temps, composantes, groupe de
- maille).
-3. Création de nouveaux champs par l'exécution d'opérations
- algébriques (+,-,*,/) entre champs, l'application de fonctions
- mathématiques standard (pow, sqrt, abs), ou encore l'initialisation
- "from scratch" sur un maillage support.
-4. Contrôle visuel rapide des champs produits (avec les modules VISU
- et/ou PARAVIS de SALOME, pilotés automatiquement depuis l'interface
- utilisateur)
-5. Enregistrement d'une partie des champs produits dans un fichier med
+1. Load a med file in the data space and explore its contents: meshes and
+ fields defined on these meshes, defined for one or several time steps.
+2. Select (using GUI) fields to be manipulated in workspace ; it is possible
+ to introduce restrictions on time steps, components or groups of cells.
+3. Create new fields executing algebraic operations (+,-,*,/) on fields,
+ applying simple mathematical functions (pow, sqrt, abs), or initializing
+ them "from scratch" on a support mesh.
+4. Visually control produced fields, using PARAVIS module in SALOME,
+ automatically controlled from user interface.
+5. Save (parts of) produced fields to a med file.
-Tour rapide des fonctions du module MED
-=======================================
+Quick tour on functions available in MED module
+===============================================
-Cette section présente des exemples d'utilisation du module XMED sous
-la forme de "storyboard", et illustre au passage les fonctions mises à
-disposition par le module.
+This section presents some use examples of MED module like a "storyboard",
+illustrating the functions proposed by the module.
-.. warning:: Cette section est en travaux. Tant que cet avis n'aura
- pas disparu, veuillez en considérer le plan et le contenu encore
- incomplets, temporaires et sujets à caution.
+.. warning:: This section is under construction. Please consider that its
+ contents and organization are still incomplete and may change
+ until this warning is removed.
-Exemple 1: Explorer des sources de données
-------------------------------------------
+Example 1: Explore data sources
+-------------------------------
-.. note:: Cet exemple présente les fonctions:
+.. note:: This example illustrates the following functions:
- * ajouter une source de données
- * fonctions "Extends field series", "Visualize"
+ * add a data source
+ * "Extends field series" and "Visualize" functions
.. |ICO_DATASOURCE_ADD| image:: images/ico_datasource_add.png
:height: 16px
.. |ICO_DATASOURCE_VIEW| image:: images/ico_datasource_view.png
:height: 16px
-Au démarrage, le module de manipulation de champs, identifié par
-l'icône |ICO_XMED|, présente une interface vierge:
+At startup the field manipulation module, identified by icon |ICO_XMED|, shows
+an empty interface:
.. image:: images/xmed-gui-start.png
:align: center
:width: 800px
-La première étape consiste à ajouter une ou plusieurs source de
-données med dans le "dataspace". Pour cela, on clique sur l'icône "Add
-datasource" |ICO_DATASOURCE_ADD| qui propose de sélectionner un
-fichier med:
+The first step consists in adding one or several med data sources in
+"dataspace". For this, user clicks on icon "Add datasource"
+|ICO_DATASOURCE_ADD| to select a med file:
.. image:: images/xmed-gui-datasource-selectfile.png
:align: center
:width: 800px
-L'opération ajoute une nouvelle entrée (datasource) dans l'espace de
-données (dataspace). Le contenu peut être exploré en parcourant
-l'arborescence. La figure ci-dessous (image de gauche) montre le
-résultat du chargement du fichier ``timeseries.med`` contenant un
-maillage de nom ``Grid_80x80`` sur lequel est défini un champ au noeud
-de nom ``Pulse``. Par défaut, la composition du champs (en terme de
-pas de temps et de composantes) n'est pas affichée pour éviter
-l'encombrement visuel de l'arbre. On doit faire la demande explicite
-au moyen de la commande "Expand field timeseries"
-|ICO_DATASOURCE_EXPAND| disponible dans le menu contextuel associé aux
-champs. Le résultat est affiché sur l'image centrale. La liste des
-itérations du champ ``Pulse`` peut être consultée.
+This operation adds a new entry (datasource) in data space. The contents can
+be explored using the data tree. The figure below (left image) shows the
+result of loading the file ``timeseries.med`` containing a mesh named
+``Grid_80x80`` on which a field on nodes named ``Pulse`` is defined. By
+default, the field composition (in terms of time steps and components) is not
+displayed to avoid visual congestion of data tree. User must explicitly ask
+for visualization using the command "Expand field timeseries"
+|ICO_DATASOURCE_EXPAND| available in the field contextual menu. The result is
+displayed on center image. The list of field ``Pulse`` iterations can be advised.
.. |IMG_DATASOURCE_EXPLORE| image:: images/xmed-gui-datasource-explore-zoom.png
:height: 340px
| |IMG_DATASOURCE_EXPLORE| | |IMG_DATASOURCE_MENUCON| | |IMG_DATASOURCE_EXPANDF| |
+--------------------------+--------------------------+--------------------------+
-.. note:: En toute rigueur, le concept de *champ* dans le modèle MED
- désigne une itération donnée. Un ensemble d'itérations est désigné
- par le terme *série temporelle de champs*. Par abus de langage, et
- s'il n'y a pas ambiguité, on utilisera le nom du champ pour
- désigner à la fois le champs proprement dit ou la série temporelle
- à laquelle il appartient.
+.. note:: Strictly speaking, the *field* concept in MED model corresponds to
+ a given iteration. A set of iterations is identified by the term
+ *field time series*. If there is no ambiguity, the field name will
+ refer to both the field itself or the time series it belongs to.
-Enfin, il est possible au niveau du dataspace de visualiser la forme
-générale du champ au moyen d'une carte scalaire affichée dans le
-viewer de SALOME. Pour cela, on sélectionne le pas de temps à
-visualiser et on utilise la commande "Visualize" |ICO_DATASOURCE_VIEW|
-disponible dans le menu contextuel associé:
+Finally, it is possible from dataspace to visualize the field general shape
+using a scalar map displayed in SALOME viewer. For this, user selects the time step to
+display then uses the command "Visualize" |ICO_DATASOURCE_VIEW| available in
+the associated contextual menu:
.. image:: images/xmed-gui-datasource-visualize-zoom.png
:align: center
:width: 800px
-.. note:: Cette représentation graphique a pour objectif le contrôle
- visuel rapide. Aussi, les fonctions du module VISU sont employées
- par défaut, mais il est possible de faire l'affichage des cartes
- scalaires au moyen du module PARAVIS (choix de préférence non
- implémenté pour le moment, mais techniquement réalisable).
+.. note:: This graphical representation aims at providing a quick visual
+ control. Scalar maps are displayed using the PARAVIS module.
-Exemple 2: Rassembler des champs issus de différentes sources
--------------------------------------------------------------
+Example 2: Combine fields from different sources
+------------------------------------------------
-.. note:: Cet exemple présente les fonctions:
+.. note:: This example illustrates the following functions:
- * fonction "Use in workspace"
- * fonction "Save"
+ * function "Use in workspace"
+ * function "Save"
.. |ICO_DATASOURCE_USE| image:: images/ico_datasource_use.png
:height: 16px
.. |ICO_WORKSPACE_SAVE| image:: images/ico_workspace_save.png
:height: 16px
-L'objectif est de récupérer des données issues de différents fichiers
-med, puis de les rassembler dans un même fichier en sortie.
+The objective is to access data contained in several med files, then to
+combine them in the same output file.
-On commence par ajouter les sources de données med dans l'espace de
-données (dataspace). Dans l'exemple ci-dessous, l'espace de données
-contient deux sources de nom ``parametric_01.med`` et
-``smallmesh_varfiled.med``. La première source contient le maillage
-``Grid_80x80_01`` sur lequel est défini le champ ``StiffExp_01``. La
-deuxième source contient le maillage ``My2DMesh`` sur lequel sont
-définis deux champs de noms respectifs ``testfield1`` et
-``testfield2``:
+User starts by adding med data sources in dataspace. In the example below,
+dataspace contains two sources names ``parametric_01.med`` and
+``smallmesh_varfiled.med``. The first one contains the mesh ``Grid_80x80_01``
+on which the field ``StiffExp_01`` is defined. The second source contains the
+mesh ``My2DMesh`` on which the two fields ``testfield1`` are ``testfield2``
+are defined:
.. image:: images/xmed-userguide-example2-datasource.png
:align: center
:width: 800px
-Pour l'exemple, on souhaite rassembler les champs ``StiffExp_01`` et
-``testfield2`` dans un fichier de nom ``result.med``. La procédure
-consiste à importer les deux champs dans l'espace de travail
-(workspace), puis à sauvegarder l'espace de travail. Pour cela, on
-sélectionne les champs et on utilise la commande "Use in workspace"
-|ICO_DATASOURCE_USE| disponible dans le menu contextuel. Les deux
-champs sélectionnés apparaissent dans l'arborescence de l'espace de
-travail:
+In this example, ``StiffExp_01`` and ``testfield2`` are combined then saved to
+``result.med`` file. The procedure consists in importing the two fields in
+workspace, then to save the workspace. For this user selects the fields and
+uses the command "Use in workspace" |ICO_DATASOURCE_USE| available in the
+contextual menu. Both selected fields appear in the workspace tree:
.. image:: images/xmed-userguide-example2-workspace.png
:align: center
:width: 800px
-La sauvegarde de l'espace de travail est faite au moyen de la commande
-"Save workspace" |ICO_WORKSPACE_SAVE| disponible dans la barre
-d'outils du module. Une fenêtre de dialogue invite l'utilisateur à
-spécifier le nom du fichier de sauvegarde:
+Workspace is saved using the command "Save workspace" |ICO_WORKSPACE_SAVE|
+available in the module toolbar. A dialog window lets user set the save
+file name:
.. image:: images/xmed-userguide-example2-workspace-save.png
:align: center
:width: 800px
-Ce fichier ``result.med`` peut ensuite être rechargé dans le module
-XMED (ou les modules VISU ou PARAVIS) pour vérifier la présence des
-champs sauvegardés.
+The file ``result.med`` can then be reloaded in MED module (or PARAVIS module)
+to check the presence of saved fields.
.. BUG: plantage à l'utilsation dans XMED d'un fichier rechargé
.. (invalid mesh on field)
.. _xmed.userguide.exemple3:
-Exemple 3: Appliquer une opération mathématique sur des champs
---------------------------------------------------------------
+Example 3: Apply a formula on fields
+------------------------------------
-.. note:: Cet exemple présente les fonctions:
+.. note:: This example illustrates the following functions:
- * exécution d'opérations mathématiques dans la console TUI
- * fonction "put" pour référencer un champ de travail dans la liste
- des champs persistant.
- * fonction "Visualize" depuis le TUI.
+ * execute mathematical operations in TUI console
+ * function "put" to refer to a work field in the list of persisting fields.
+ * function "Visualize" from TUI.
-L'usage le plus courant du module de manipulation de champs est
-d'exécuter des opérations mathématiques dont les opérandes sont des
-champs ou des composantes de ces champs.
+The most common usage of field manipulation module is to execute mathematical
+operations on fields or on their components.
-On se place dans une situation où les sources de données sont définies
-dans le "dataspace" (dans l'exemple ci-après, une série temporelle de
-nom ``Pulse``, contenant 10 pas de temps, définis sur un maillage de
-nom ``Grid_80x80``, le tout issu du datasource ``timeseries.med``).
+Assume data sources are already defined in dataspace (in the following example
+a temporal series named ``Pulse`` contains 10 time steps defined on a mesh
+named ``Grid_80x80``, all read from ``timeseries.med`` data source).
-Comme vu précedemment, pour manoeuvrer un champ dans l'espace de
-travail, on sélectionne ce champ, puis on exécute la commande "Use in
-workspace" |ICO_DATASOURCE_USE| du menu contextuel. Dans le cas
-présent, un seul champ est sélectionné (contre deux dans l'exemple
-précédent) et la commande ouvre alors une fenêtre de dialogue qui
-permet de préciser les données sur lesquelles on souhaite
-effectivement travailler et comment on veut les manoeuvrer:
+As previously seen, a field can be manipulated in workspace after selecting
+the field and applying the command "Use in
+workspace" |ICO_DATASOURCE_USE| from contextual menu. Here only one file is
+selected (two in the previous example) and the command then opens a dialog
+window to select data to work on and the way they will be manipulated:
.. image:: images/xmed-gui-datasource-useinworkspace-alias.png
:align: center
:width: 800px
-.. note:: En l'état actuel du développement, l'interface propose
- uniquement de définir le nom de la variable sous laquelle doit être
- manoeuvré le champ dans la console de travail (TUI). Dans une
- version ultérieure, il est prévue de pouvoir préciser la ou les
- composante du champs à utiliser et un groupe de maille pour définir
- une restriction géométrique. Inversement, il sera également
- possible de choisir une série temporelle complète pour faire des
- opérations globales sur l'ensemble des pas de temps.
-
-Aprés validation, le champ est placé dans l'arborescence du
-"workspace" et une variable de nom ``<alias>`` est créée
-automatiquement dans la console de travail pour désigner le
-champ. Dans cet exemple, ``<alias>`` vaut ``f3``, positionné ainsi par
-l'utilisateur pour rappeler que la variable correspond au pas de temps
-n°3:
+.. note:: In the current state of development, the interface only propose to
+ define the name of a variable representing the field in TUI. In
+ a next version, user will have the possibility to specify the field
+ component(s) to be used and a group of cells to introduce
+ a geometrical restriction. Conversely it will be possible to select
+ a complete time series to apply global operations on all time steps.
+
+After validation, the field if put in workspace tree and a variable
+``<alias>`` is automatically created in the TUI to designate the field. In
+this example, ``<alias>`` is ``f3``, as set by user to recall that variable
+corresponds to the third time step:
.. image:: images/xmed-gui-workspace.png
:align: center
:width: 800px
-La manipulation peut commencer. Dans l'exemple ci-dessous, on crée le
-champ ``r`` comme le résultat d'une transformation afine du champ
-``f3`` (multiplication du champ par le facteur 2.7 auquel on ajoute
-l'offset 5.2)::
+Field manipulation can start. In the example below, use creates the field``r``
+as the result of an affine transformation of field ``f3`` (multiplication of
+field by a scale factor 2.7 then addition of offset 5.2)::
>>> r=2.7*f3+5.2
-On peut poursuivre la manipulation du champs avec une variété
-d'opérations qui sont détaillées dans les spécifications du module
+Other operations can be applied, as detailed in module specifications
(cf. :ref:`Spécification des opérations<xmed-specifications>`):
- >>> r=f3/1000 # les valeurs de r sont celles du champ f3 réduites d'un facteur 1000
- >>> r=1/f3 # les valeurs de r sont les inverses des valeurs de f3
- >>> r=f3*f3 # les valeurs de r sont celles du champ f3 élevées au carré
- >>> r=pow(f3,2) # même résultat
- >>> r=abs(f3) # valeur absolue du champ f3
+ >>> r=f3/1000 # the values of r are the ones of f3 reduced by a factor 1000
+ >>> r=1/f3 # the values of r are the inverted values of f3
+ >>> r=f3*f3 # the values of r are the squared values of f3
+ >>> r=pow(f3,2) # same result
+ >>> r=abs(f3) # absolute value of field f3
>>> ...
-Les opérations peuvent utiliser plusieurs opérandes de type champs. Si
-``f4`` désigne le pas de temps n°4 du champ ``Pulse``, alors on peut
-calculer toute combinaison algébrique des deux champs::
+The two operands can be fields. If ``f4`` is the fourth time step of field
+``Pulse``, then algebraic combinations of fields can be computed::
>>> r=f3+f4
>>> r=f3-f4
>>> r=f3/f4
>>> r=f3*f4
-Avec au besoin l'utilisation de variables scalaires::
+Scalar variables can be used if needed::
>>> r=4*f3-f4/1000
>>> ...
-Dans ces exemples, la variable ``r`` désigne un champ de travail qui
-contient le résultat de l'opération. Par défaut, ce champ de travail
-n'est pas référencé dans l'arborescence du workspace. Si on souhaite
-tout de même le référencer, par exemple pour qu'il soit pris en compte
-dans la sauvegarde, alors on tape la commande::
+In theses examples, the variable ``r`` corresponds to a work field containing
+the operation result. By default the field is nor referenced in workspace
+tree. If user wants to add it, for example to make it considered when saving,
+then the following command is used::
>>> put(r)
-La fonction ``put`` a pour but de marquer le champ en argument comme
-persistent, puis de le ranger dans l'arborescence du "workspace" afin
-qu'il soit visible et sélectionnable. En effet, parmi tous les champs
-qui pourront être créés dans la console pendant la session de travail,
-tous n'ont pas besoin d'être sauvegardés. Certains sont même des
-variables temporaires qui servent à la construction des champs
-résultats finaux. C'est pourquoi, seuls les champs rangés dans
-l'arborescence du workspace sont enregistrés lors de la demande de
-sauvegarde du workspace.
-
-Les variables définies dans la console ont d'autres utilités. Tout
-d'abord, elles permettent d'imprimer les informations concernant le
-champ manoeuvré. Pour cela, on tape simplement le nom de la variable
-puis retour::
+The function ``put`` aims at tagging the field as persisting, the to store it
+in the workspace tree to make it visible and selectable. Among all fields that
+could be created in console during the work session, all do not need to be
+saved. Some may only be temporary variables used in the construction of final
+fields. That is why only fields in workspace tree are saved when saving the
+workspace.
+
+Variables defined in console have other uses. First they allow for printing
+information relative to the manipulated field. For this one enters the
+variable name then validates::
>>> f3
- field name (id) = Pulse (3)
- mesh name (id) = Grid_80x80 (0)
- discretization = ON_NODES
- (iter, order) = (3,-1)
- data source = file:///home/gboulant/development/projets/salome/MEDOP/XMED/xmed/resources/datafiles/timeseries.med
-
-Elle peut également être utilisée comme argument des commandes de
-gestion disponibles dans l'interface textuelle (dont la liste
-détaillée est décrite à la section :ref:`Documentation de l'interface
-textuelle<xmed.userguide.tui>`). Par exemple, la fonction ``view``
-permet d'afficher la carte scalaire du champ dans le viewer::
+ field name (id) = Pulse (3)
+ mesh name (id) = Grid_80x80 (0)
+ discretization = ON_NODES
+ (iter, order) = (3,-1)
+ data source = file:///home/gboulant/development/projets/salome/MEDOP/XMED/xmed/resources/datafiles/timeseries.med
+
+Second, variables can be used as command arguments (the list of commands
+available in TUI is described in section :ref:`Documentation of textual
+interface<xmed.userguide.tui>`). For example the function ``view`` displays
+the field scalar map in the viewer::
>>> view(f3)
-Donne:
+Results in:
.. image:: images/xmed-gui-workspace-view.png
:align: center
:width: 800px
-.. note:: On remarquera ici qu'il est facile de comparer deux pas de
- temps d'un champ, par exemple en calculant la différence ``f3-f4``,
- puis en affichant un aperçu de la carte scalaire résultat au moyen
- de la fonction ``view``::
+.. note:: It is easy to compare two time steps of a field, computing the
+ difference ``f3-f4``, then producing a scalar map preview using the
+ function ``view``::
>>> view(f3-f4)
-On peut enfin tout simplement afficher les données du champs par la
-commande ``print``::
+Finally the field data can be displayed using the command``print``::
>>> print f3
Data content :
- Tuple #0 : -0.6
- Tuple #1 : -0.1
- Tuple #2 : 0.4
- Tuple #3 : -0.1
- Tuple #4 : 0.4
+ Tuple #0 : -0.6
+ Tuple #1 : -0.1
+ Tuple #2 : 0.4
+ Tuple #3 : -0.1
+ Tuple #4 : 0.4
...
- Tuple #6556 : 3.5
- Tuple #6557 : 3.3
- Tuple #6558 : 1.5
- Tuple #6559 : 0.3
+ Tuple #6556 : 3.5
+ Tuple #6557 : 3.3
+ Tuple #6558 : 1.5
+ Tuple #6559 : 0.3
Tuple #6560 : 0.2
-Il est important de noter que les opérations entre champs ne peuvent
-être faites qu'entre champs définis sur le même maillage. Il s'agit là
-d'une spécification du modèle MED qui interdit d'envisager les
-opérations entre champs définis sur des maillages géométriquement
-différents. Techniquement, cela se traduit par l'obligation pour les
-objets informatique *champs* de partager le même objet informatique
-*maillage*.
-
-Dans l'hypothèse où on souhaite utiliser des champs définis sur des
-maillages différents, par exemple pour manoeuvrer les valeurs des
-champs à l'interface de deux maillages partageant une zone géométrique
-2D, il faut d'abord ramener tous les champs sur le même maillage de
-surface par une opération de projection.
-
-.. note:: Même si ceci est techniquement possible avec la bibliothèque
- MEDCoupling, cet type d'opération de projection n'est pas encore
- disponible dans le module de manipulation de champs (prévu en
- 2012).
-
-Un autre besoin plus classique est l'utilisation de champs définis sur
-des maillages géométriquement identiques, mais techniquement
-différents, par exemple lorsqu'ils sont chargés de fichiers med
-différents. Pour traiter ce cas de figure, la bibliothèque MEDCoupling
-prévoit une fonction de "Changement du maillage support", dont
-l'utilisation au niveau du module de manipulation de champs est
-illustrée dans :ref:`l'exemple 4<xmed.userguide.exemple4>` ci-après.
+It is important to note that operations between fields can only be applied if
+fields are defined on the same mesh. It corresponds to a specification of MED
+model that forbids operations between fields defined on meshes geometrically
+different. Technically it means that the conceptual objects *fields* must share
+the same conceptual object *mesh*.
+
+If user do want to use fields defined on different meshes, for example to
+manipulate the field values at the interface of two meshes sharing a 2D
+geometrical area, it is necessary first to make all fields be defined on the
+same surface mesh using a projection operation.
+
+.. note:: Such projection operations are available in the MEDCoupling library.
+
+Another classical need is using fields defined on meshes geometrically
+identical, but technically different for example when they are loaded from
+different med files. For such a case, the MEDCoupling library proposes
+a function "Change support mesh" ; its use in field manipulation module is
+illustrated in :ref:`example 4<xmed.userguide.exemple4>` described hereafter.
.. _xmed.userguide.exemple4:
-Exemple 4: Comparer des champs issues de différentes sources
-------------------------------------------------------------
+Example 4: Compare fields derived from different sources
+--------------------------------------------------------
-.. note:: Cet exemple présente les fonctions:
+.. note:: This example illustrates the following function:
- * Changement du maillage support "change underlying mesh"
+ * Change the underlying (support) mesh
-On se place ici dans le cas de figure où des champs ont été produits
-sur le même maillage, au sens géométrique, mais enregistrés dans des
-fichiers med différents. C'est le cas par exemple d'une étude
-paramétrique où plusieurs calculs sont effectués avec des variantes
-sur certains paramètres du modèle simulé, chaque calcul produisant un
-fichier med.
+Assume here that fields have been defined on same mesh, geometrically
+speaking, but saved in different med files. This occurs for example for
+a parametric study in which several computations are achieved with variants on
+some parameters of the simulated model, each computation producing a med file.
-Soit ``parametric_01.med`` et ``parametric_02.med`` deux fichiers med
-contenant les champs que l'on souhaite comparer, par exemple en
-calculant la différence des valeurs et en visualisant le résultat.
+Let ``parametric_01.med`` and ``parametric_02.med`` be two med files
+containing the fields to compare, for example computing the difference of
+their values and visualizing the result.
-Aprés le chargement des sources de données dans le module XMED,
-l'utilisateur se trouve en présence de deux maillages, au sens
-technique du terme cette fois-ci, c'est-à-dire que les champs sont
-associées à des objets informatiques maillage différents, bien que
-géométriquement identiques.
+After loading data sources user sees two meshes, this time from the technical
+point of view, that is to say fields are associated to different conceptual
+mesh objects, while geometrically identical.
-Or, les fonctions de manipulation de champs ne permettent pas les
-opérations sur des champs dont les maillages supports sont différents
-(voir la remarque à la fin de :ref:`l'exemple
+However field manipulation functions do not allow operations on fields lying
+on different support meshes (see remark at the end of :ref:`example
3<xmed.userguide.exemple3>`).
-Pour résoudre ce cas de figure, le module de manipulation de champs
-met à disposition la fonction "Change underlying mesh" qui permet de
-remplacer le maillage support d'un champ par un autre à partir du
-moment où les deux maillages sont géométriquement identiques,
-c'est-à-dire que les noeuds ont les mêmes coordonnées spatiales.
+To circumvent this issue, the module offers the function "Change underlying
+mesh" to replace a field mesh support by another, provided that the two meshes
+are geometrically identical, that is to say nodes have the same spatial
+coordinates.
.. |ICO_DATASOURCE_CHG| image:: images/ico_datasource_changeUnderlyingMesh.png
:height: 16px
-Dans l'exemple proposé, l'utilisateur sélectionne le premier pas de
-temps du champ ``StiffExp_01`` du "datasource" ``parametric_01.med``,
-puis l'importe dans l'espace de travail au moyen de la commande "Use
-in workspace" |ICO_DATASOURCE_USE|. Il sélectionne ensuite le premier
-pas de temps du champs ``StiffExp_02`` du "datasource"
-``parametric_02.med``, mais l'importe dans l'espace de travail au
-moyen de la commande "Change underlying mesh" |ICO_DATASOURCE_CHG|. La
-fenêtre de dialogue ci-dessous s'affiche et invite l'utilisateur à
-choisir le nouveau maillage support par sélection dans l'arborescence
-du "dataspace":
+In the proposed example, user selects the first time step of field
+``StiffExp_01`` in data source ``parametric_01.med``, and imports it in
+workspace using the command "Use in workspace" |ICO_DATASOURCE_USE|. User then
+selects the first time step of field ``StiffExp_02`` in data source
+``parametric_02.med``, but imports it in workspace using the command "Change
+underlying mesh" |ICO_DATASOURCE_CHG|. The following dialog window appears to
+let user select the new support mesh in dataspace tree:
.. image:: images/xmed-gui-datasource-changeUnderlyingMesh.png
:align: center
-Dans cet exemple, on sélectionne le maillage ``Grid_80x80_01`` support
-du champ ``StiffExp_01``, avec lequel on souhaite faire la
-comparaison. Après validation, l'arborescence du workspace contient le
-champ ``StiffExp_02`` défini sur le maillage ``Grid_80x80_01``:
+In this example, the support mesh ``Grid_80x80_01`` of field ``StiffExp_01``
+to compare with is selected. After validation the workspace tree contains the
+field ``StiffExp_02`` defined on mesh ``Grid_80x80_01``:
.. image:: images/xmed-gui-datasource-changeUnderlyingMesh_wsview.png
:align: center
-.. note:: La fonction "Change underlying mesh" ne modifie pas le champ
- sélectionné dans le "dataspace" (principe de base de fonctionnement
- du dataspace), mais crée une copie du champ dans l'espace de travail
- pour ensuite remplacer le maillage support. D'où le nom par défaut
- pour le champ ``dup(<nom du champ sélectionné>)`` (dup pour
- "duplicate").
+.. note:: The function "Change underlying mesh" does not modify the field
+ selected in dataspace (basic running principle of dataspace), but
+ creates a field copy in workspace to then change support mesh. This
+ explains the default name for field ``dup(<name of selected
+ field>)`` (dup stands for "duplicate").
-Il reste à associer une variable à ce champ pour le manipuler dans la
-console. Ceci peut être fait au moyen de la commande "Use in console",
-disponible dans le menu contextuel du workspace.
+All we have to do now is to associate a variable to this field, in order to
+manipulate it in TUI. This can be done using the command "Use in console"
+available in workspace contextual menu.
-En définitif, si ``f1`` désigne le champ issu du datasource
-``parametric_01.med`` et ``f2`` le champ issu du datasource
-``parametric_02.med`` par la procédure décrite ci-dessus, alors la
-comparaison des deux grandeurs peut être faite comme pour le cas de
-:ref:`l'exemple 3<xmed.userguide.exemple3>`::
+Finally, if ``f1`` is a field from datasource ``parametric_01.med`` and ``f2``
+is a field from datasource
+``parametric_02.med`` according to the above procedure, then comparison values
+can be achieved as explained in :ref:`example 3<xmed.userguide.exemple3>`::
>>> r=f1-f2
>>> view(r)
-.. note:: En remarque générale sur cet exemple, il convient de noter
- les points suivants:
-
- * l'égalité géométrique de deux maillages est établie à une marge
- d'erreur prés qu'il est possible de définir techniquement, mais
- qui n'est pas ajustable au niveau de l'interface du module de
- manipulation de champs. Elle est fixée à une valeur standard qui
- permet de traiter la plupart des cas utilisateur. On verra à
- l'usage s'il est nécessaire de remonter ce paramètre au niveau de
- l'interface.
- * L'utilisateur doit faire la démande explicite de changer le
- maillage support d'un champ, en prévision de la comparaison de
- champs issus de datasource différentes. Il s'agit là d'un choix
- fonctionnel délibéré pour que l'utilisateur garde trace des
- modifications faites sur les données (pas de modification
- automatiques à l'insu de l'utilisateur, même sous prétexte
- d'amélioration de l'ergonomie).
-
-
-Exemple 5: Créer un champ sur un domaine spatial
-------------------------------------------------
+.. note:: As a general remark concerning this example, one may note:
+
+ * the geometrical equality of two meshes is constrained to a numerical
+ error that can be technically set, but not through the module interface.
+ This tolerance is empirically set to a standard value regarding to
+ success of most of the use cases. The usefulness of setting this value in
+ the interface could be later investigated.
+
+ * User must explicitly ask for changing a field support mesh, in order to
+ compare fields coming from different data sources. This choice has been
+ made to keep trace of modifications made on data (no modification is made
+ without user knowing, even to improve ergonomics).
+
-.. note:: Cet exemple présente les fonctions:
+Example 5: Create a field on a spatial domain
+---------------------------------------------
- * initialisation par une fonction de la position spatiale
- * initialisation sur un groupe de maille
+.. note:: This example illustrates the following functions:
-Le domaine géométrique de définition du champs à créer est spécifié
-ici par la donnée d'un groupe de mailles. Ce cas d'usage est
-typiquement prévu pour produire les conditions de chargement initial
-d'une structure, par exemple en définissant un champ sur une surface
-de la géométrie, identifiée par un nom de groupe de mailles.
+ * initialize with function of spatial position
+ * initialize on a group of cells
-.. warning:: DEVELOPPEMENT EN COURS
+The geometrical domain on which the field to create is defined is here given
+by cell group data. This use case is provided for producing initial load
+conditions of a structure, for example defining a field on a geometry surface
+identified by a group of cells.
-Exemple 6: Extraire une partie d'un champ
------------------------------------------
+.. warning:: DEVELOPMENT IN PROGRESS
-.. note:: Cet exemple présente les fonctions:
+Example 6: Extract a field part
+-------------------------------
- * extraire une composante (ou un sous-ensemble des composantes)
- * extraire un domaine géométrique (valeurs sur un groupe de maille)
- * extraire un ou plusieurs pas de temps.
+.. note:: This example illustrates the following functions:
-.. warning:: DEVELOPPEMENT EN COURS
+ * extract a component (or a subset of components)
+ * extract a geometrical domain (values on a group of cells)
+ * extract one or several time steps
- On doit illustrer ici les fonctions de restriction, qui
- permettraient de récupérer certaines composantes uniquement. Le
- principe est qu'on crée un nouveau champ qui est une restriction du
- champ argument à une liste de composantes à spécifier (utiliser la
- fonction __call__ des fieldproxy).
+.. warning:: DEVELOPMENT IN PROGRESS
-Pour l'extraction des pas de temps, on peut se ramener au cas de
-l'exemple 2 avec une seule source de donnée.
+ Here the restriction functions that allow to get some components only, have
+ to be illustrated. The principle is creating a new field that is
+ a restriction of input field to a list of given components (use the
+ function __call__ of fieldproxy).
-Exemple 7: Créer un champ à partir d'une image to[mp]ographique
----------------------------------------------------------------
+For time step extraction, we can reduce to the case of example 2 with a single
+data source.
-.. note:: Cet exemple présente les fonctions:
+Example 7: Create a field from a to[mp]ographic image
+-----------------------------------------------------
- * Création d'un champ sans datasource (ni maillage, ni champs), à
- partir d'un fichier image
+.. note:: This example illustrates the following function:
-En tomographie ou en topographie, les appareils de mesure produisent
-des images qui représentent une grandeur physique en niveaux de gris
-sur un plan de coupe donné. L'image ci-dessous représente par exemple
-une vue interne du corps humain faite par IRM:
+ * Create a field without data source (neither mesh nor field), from an
+ image file
+
+In tomography or topography studies, measurement devices produce images that
+represent a physical quantity using gray levels on a given cutting plane. The
+following image represents for example a internal view of human body obtained
+by MRI:
.. image:: images/xmed-irm.png
:align: center
:width: 600px
-Cette image est un ensemble de pixels organisés sur une grille
-cartesienne. Elle peut donc être modélisée sous la forme d'un champ
-scalaire dont les valeurs sont définies aux cellules d'un maillage
-réglés de même taille que l'image (en nombre de pixels):
+This image is a subset of pixels organized on a Cartesian grid. It can thus be
+represented as a scalar field whose values are defined on cells of a mesh
+having the same dimension as the image (number of pixels):
.. image:: images/xmed-irm-field.png
:align: center
:width: 600px
-Le module de manipulation de champ fournit un utilitaire appelé
-``image2med.py`` qui permet d'appliquer ce principe à la conversion
-d'un fichier image en fichier med contenant la représentation de
-l'image sous forme d'un champ scalaire (seul le niveau de gris est
-conservé)::
+The field manipulation module provides a tool named ``image2med.py`` to
+convert a file image to a med file containing the image representation as
+a scalar field (only the gray level is kept)::
$ <xmed_root_dir>/bin/salome/xmed/image2med.py -i myimage.png -m myfield.med
.. |ICO_IMAGESOURCE| image:: images/ico_imagesource.png
:height: 16px
-Cette opération de conversion peut être faite automatiquement dans
-l'interface graphique du module au moyen de la commande "Add Image
-Source" |ICO_IMAGESOURCE| disponible dans la barre d'outils. Cette
-commande ouvre la fenêtre suivante pour inviter l'utilisateur à
-choisir un fichier image:
+This conversion operation can be automatically achieved using the command "Add
+Image Source" |ICO_IMAGESOURCE| available in GUI toolbar. This command opens
+the following window to let user select a file image:
.. image:: images/medop_image2med_dialog.png
:align: center
-Le nom du fichier med résultat est proposé par défaut (changement de
-l'extention en ``*.med``) mais il peut être modifié. Enfin, on peut
-demander le chargement automatique du fichier med produit pour ajout
-dans l'espace de donnée. Les champs peuvent alors être manipulés comme
-dans les cas d'utilisation standard.
+The name of result med file is set by default (changing file extension to
+``*.med``) but can be modified. Finally user can ask for automatic load of
+this med file in data space. Fields can then be manipulated like presented in
+the standard use cases.
-Par exemple, l'image ci-dessous affiche le résultat de la différence
-entre deux images, ajoutée à l'image de référence: si i1 et i2
-désignent les champs créés à partir des deux images, on représente ``r
-= i1 + 5*(i2-i1)`` où le facteur 5 est arbitraire et sert à amplifier
-la zone d'intérêt (en haut de l'oeil gauche):
+For example, the image below depicts the result of the difference between two
+images, added to the reference image: if i1 and i2 are the fields created from
+these two images, then ``r = i1 + 5*(i2-i1)`` with 5 an arbitrary factor to
+amplify the region of interest (above the left eye):
.. image:: images/xmed-irm-diff.png
:align: center
:width: 600px
-L'exemple ci-dessous est le résultat du chargement d'une image
-tomographique issue du projet MAP (Charles Toulemonde,
-EDF/R&D/MMC). L'image tomographique:
+The example below is the result of loading a tomographic image courtesy of MAP
+project (Charles Toulemonde, EDF/R&D/MMC). The tomographic image:
.. image:: images/champ_altitude_MAP.png
:align: center
:width: 600px
-Le résultat du chargement:
+The result of loading:
.. image:: images/medop_image2med_tomographie.png
:align: center
:width: 800px
-Exemple 8: Continuer l'analyse dans PARAVIS
--------------------------------------------
+Example 8: Continue analysis in PARAVIS
+---------------------------------------
-.. note:: Cet exemple présente les fonctions:
+.. note:: This example illustrates the following functio:
- * Export de champs vers le module PARAVIS.
+ * Export fields to PARAVIS module
-Les possibilités de représentation graphique des champs fournies par
-le module MED ont pour seul objectif le contrôle visuel rapide. Par
-défaut, le viewer de VISU est employé.
+The solutions for field representation in MED module aims at proposing a quick
+visual control.
-Pour une analyse plus détaillées des champs, il est nécessaire de
-poursuivre le travail dans PARAVIS. Le module de manipulation de
-champs offre une fonction qui simplifie ce passage, en faisant le
-chargement automatique dans PARAVIS et en proposant une visualisation
-par défaut (carte de champs scalaire).
+For a detailed analysis of fields, user shall switch to PARAVIS. The field
+manipulation module has a function to facilitate this transition, with
+automatic load in PARAVIS and proposing a default visualization (scalar map).
-Pour cela, il faut sélectionner dans l'espace de travail les champs à
-exporter, puis déclencher la fonction d'export depuis le menu
-contextuel associé:
+For this user selects in workspace the fields to export, then call the export
+function from contextual menu:
.. image:: images/medop_exportparavis.png
:align: center
-Les champs sélectionnés sont regroupés dans une entrée MED du
-navigateur PARAVIS, et le premier champ est affiché sous forme de
-carte de champ:
+Selected fields are grouped in a single MED entry in PARAVIS, and the first
+field is depicted as a scalar map:
.. image:: images/medop_exportparavis_result.png
:align: center
:width: 800px
-.. note:: La fonction d'export est une fonction de confort. La même
- opération peut être faite manuellement en procédant d'abord à
- l'enregistrement des champs sous forme de fichier MED, puis en
- chargeant le fichier généré dans le module PARAVIS pour
- visualisation.
+.. note:: The export function is a convenience function. The same operation
+ can be manually achieved, first saving fields to a med file then
+ loading the created file in PARAVIS module for visualization.
.. _xmed.userguide.tui:
-Utilisation de l'interface textuelle du module MED (TUI)
-========================================================
+Using the textual interface (TUI)
+=================================
-Toutes les opérations menées au moyen de l'interface graphique peuvent
-être réalisées (avec plus ou moins de facilité) avec l'interface
-textuelle. Le module de manipulation de champs peut même être utilisé
-exclusivement en mode texte. Pour cela, on lance la commande::
+All operations driven through GUI can be done (more or less easily) using TUI.
+The field manipulation module can even be used exclusively in textual mode.
+For this run the command::
$ <path/to/appli>/medop.sh
-Cette commande ouvre une console de commandes ``medop>``. Un fichier
-med peut être chargé et travaillé, par exemple pour créer des champs à
-partir des données du fichier.
+This command opens a command console ``medop>``. A med file can be loaded and
+manipulated, for example to create fields from file data.
-Que l'on soit en mode texte pur ou en mode graphique, un séquence de
-travail type dans la console peut ressembler au jeu d'instructions
-suivantes::
+Whatever textual or graphical mode is used, a typical workflow in console
+looks like the following instructions::
>>> load("/path/to/mydata.med")
>>> la
id=1 name = testfield2
>>> f1=get(0)
>>> f2=get(1)
- >>> ls
+ >>> ls
f1 (id=0, name=testfield1)
f2 (id=1, name=testfield2)
>>> r=f1+f2
>>> put(r)
>>> save("result.med")
-Les commandes principales sont:
+The main commands are:
-* ``load``: charge un fichier med dans la base de données (utile
- uniquement en mode texte pur)::
+* ``load``: load a med file in data base (useful in pure textual mode)::
>>> load("/path/to/datafile.med")
-* ``la``: affiche la liste de tous les champs chargés en base de données ("list all")
-* ``get``: définit un champ dans l'espace de travail à partir de son
- identifiant (utile plutôt en mode texte pur car l'interface
- graphique permet de faire cette opération par sélection d'un champ
- dans le dataspace)::
+* ``la``: show the list of all fields loaded in data base ("list all")
+* ``get``: set a field in workspace from its identifier (useful in pure
+ textual mode ; this operation can be done in GUI selecting a field from data
+ space).::
>>> f=get(fieldId)
-* ``ls``: affiche la liste des champs présent dans l'espace de travail ("list")
-* ``put``: met un champ en référence dans l'*espace de gestion*::
+* ``ls``: show the list of fields available in workspace ("list")
+* ``put``: put a reference to a field in *management space*::
>>> put(f)
-* ``save``: sauvegarde tous les champs référencés dans l'espace de
- gestion dans un fichier med::
+* ``save``: save to a med a file all fields referenced in management space::
>>> save("/path/to/resultfile.med")
-.. note:: On peut faire à ce stade plusieurs remarques:
-
- * la commande ``load`` charge uniquement les méta-informations
- décrivant les maillage et les champs (noms, type de
- discrétisation, liste des pas de temps). Les maillages et les
- valeurs physiques des champs sont chargées ultérieurement (et
- automatiquement) dés lors qu'elles sont requises par une
- opération. Dans tous les cas, les données med (méta-informations
- et valeurs) sont physiquement stockées au niveau de l'espace
- *base de données*.
- * la commande ``get`` définit en réalité un *manipulateur de champ*
- dans l'espace de travail, c'est-à-dire une variable qui fait la
- liaison avec le champ physique hébergé dans la base de
- données. Les données physiques ne circulent jamais entre les
- espaces, mais restent centralisées au niveau de la base de
- données.
-
-Les commandes TUI suivantes nécessitent de travailler dans
-l'environnement graphique:
-
-* ``visu``: afficher une carte de champ pour contrôle visuel rapide
- (pas de paramettrage possible)
+.. note::
+
+ * the ``load`` command only loads metadata describing meshes and fields
+ (names, discretization types, list of time steps). Meshes and physical
+ quantities on fields are loaded later (and automatically) as soon as an
+ operation needs them. In all cases med data (mete-information and values)
+ are physically stored in *data base* environment.
+ * the ``get`` command defines a *field handler* in workspace, i.e.
+ a variable that links to the physical field hosted in data base. Physical
+ data never transit between environments but remain centralized in data
+ base.
+
+The following TUI commands need to work in graphical environment:
+
+* ``visu``: display a field map for quick visual control (no parametrization
+ is possible)
>>> view(f)
+
+.. LocalWords: softwares
