X-Git-Url: http://git.salome-platform.org/gitweb/?a=blobdiff_plain;f=src%2FMEDOP%2Fdoc%2Fsphinx%2Fmedop-userguide-gui.rst;h=3494402c5b2b0b7fc574487613a72039e2dd57f0;hb=56fddf07c0b7170f79791d38e2b909a8a5b0b872;hp=f09404a6498c5620a95106d4bc478d64c5ace580;hpb=8f90826e49c2b5b497cd594db02f761f7cd3dda8;p=tools%2Fmedcoupling.git diff --git a/src/MEDOP/doc/sphinx/medop-userguide-gui.rst b/src/MEDOP/doc/sphinx/medop-userguide-gui.rst index f09404a64..3494402c5 100644 --- a/src/MEDOP/doc/sphinx/medop-userguide-gui.rst +++ b/src/MEDOP/doc/sphinx/medop-userguide-gui.rst @@ -1,93 +1,83 @@ .. 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`, 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` (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 @@ -101,34 +91,30 @@ Exemple 1: Explorer des sources de données .. |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 @@ -141,537 +127,459 @@ itérations du champ ``Pulse`` peut être consultée. | |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 ```` est créée -automatiquement dans la console de travail pour désigner le -champ. Dans cet exemple, ```` 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 +```` is automatically created in the TUI to designate the field. In +this example, ```` 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`): - >>> 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`). 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`). 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` 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` 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`). -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()`` (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()`` (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`:: +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`:: >>> 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):: $ /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:: $ /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 @@ -679,7 +587,7 @@ suivantes:: 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 @@ -695,54 +603,47 @@ suivantes:: >>> 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