# Introduction à ParaView/Quelques exemples simples

Nous étudions ici quelques exemples simples de traitement de données. Cela permet de s'approprier l'interface graphique du logiciel, et de comprendre la logique globale des traitement effectués.
Nous allons utiliser des données que nous créons nous-même. La plupart du temps, les données sont fournies « toutes faites » (résultats d'une mesure ou d'une simulation). Ici, nous allons créer les données sous la forme de fichiers de texte simples, et travailler à partir de ces fichiers. Les exemples sont donc également simples.

## Tracer une fonction réelle

Bien que ParaView soit destiné à afficher des données 3D, nous allons commencer par tracer la courbe représentative d'une fonction d'une variable réelle.
Pour cela, nous allons créer un fichier texte contenant les cordonnées des points. Nous créons un fichier texte (codage ASCII ou Unicode) au format CSV : les nombres sont écrits avec le point comme séparateur décimal, et les champs sont séparés par une virgule.

### Créer le fichier CSV

* Ouvrir un éditeur de texte.
* Copier le texte ci-après.
* Enregistrer le fichier dans un répertoire connu, dans un format texte, et avec le nom trace_parabole.csv.

### Afficher les données dans ParaView

* Ouvrir ParaView.
* Importer les données, soit avec le menu File → Open, soit avec le bouton Open. Naviguer pour sélectionner le fichier trace_parabole.csv puis cliquer sur OK
* Cliquer sur le bouton Apply :
** l'objet trace_parabole.csv apparaît dans l'arborescence de tuyauterie ;
** les données apparaissent dans un tableau dans la fenêtre de visualisation.
* Appuyez sur les touches du clavier [Ctrl]+[Espace] : cela ouvre la boîte de dialogue Filters Search.
* Taper plot : cela affiche les filtres (fonctions) contenant « plot » dans leur nom. Le filtre proposé par défaut est Plot Data : cliquer sur le bouton gris pour valider le choix, puis cliquez sur le bouton Apply. Notez que l'on peut aussi trouver ce filtre dans le menu Filters → Data Analysis, ou bien Filters → Alphabetical.
* Une deuxième fenêtre de visualisation s'affiche à côté de la première ; elle contient deux courbes. Aller dans la boîte Properties située en bas à gauche de la fenêtre ParaView :
** dans la zone X Axis Data, cliquer sur l'option Use Data Array ;
** dans le menu déroulant se trouvant à côté, choisir x ;
** dans le tableau Line Series, décocher toutes les variables sauf y.

### Modifier la mise en page

* Cliquer sur la fenêtre où se trouve le graphique. S'assurer qu'elle est entourée d'un trait bleu : c'est la vue active.
* Aller dans le menu Edit → View Settings ; cela ouvre la boîte de dialogue View Settings.
* Dans l'arborescence de gauche, cliquer sur General. Dans la zone Chart Title → Text, taper Parabole $y = x^2$, et cliquer sur le bouton Apply de la boîte de dialogue. Le titre « Parabole $y=x^{2}$ » s'affiche en haut et au centre de l'image (il s'agit de syntaxe LaTeX, voir LaTeX/Écrire des mathématiques pour plus de détails).
* Dans l'arborescence de gauche, cliquer sur Left axis. Dans la zone Axis Title → Text, taper $y $ ; pensez bien à mettre un espace entre le « $ » et le « y » (avant ou après), sinon ParaView ne comprend pas qu'il s'agit de LaTeX ; cliquer sur le bouton Apply de la boîte de dialogue, l'étiquette « $y$ » s'afficher à côté de l'axe vertical.
* Dans l'arborescence de gauche, cliquer sur Bottom axis. Dans la zone Axis Title → Text, taper $x $ ; pensez bien à mettre un espace entre le « $ » et le « x » (avant ou après), sinon ParaView ne comprend pas qu'il s'agit de LaTeX. Cliquer sur le bouton OK.
* Dans la zone Line Series de la boîte Properties, cliquer sur la ligne y ; cliquer sur le bouton Choose Color… pour changer la couleur de la courbe, et modifier le champ Legend Name pour modifier l'étiquette d'identification de la courbe. Essayer les menu déroulants situés en dessous de cette zone pour voir leur influence.
Notez que dans le cas présent, nous aurions pu simplement taper « x » et « y » pour les titres des axes, sans les encadrer par les signes dollar. Le fait de les encadrer par des « $…$ » permet d'avoir la même mise en forme que pour le titre (même police d'écriture).

### Enregistrer le résultat

Pour créer une image matricielle contenant le graphe :
* S'assurer que la fenêtre de visualisation active est celle contenant le graphe, sinon, cliquer sur cette fenêtre.
* Cliquer sur le menu File → Save Screenshot.
* Dans la boîte de dialogue Save Snapshot resolution qui apparaît, modifier le cas échant les dimensions de l'image, puis cliquer sur OK.
* Dans la boîte de dialogue Save Screenshot: qui apparaît, choisir le format de l'image dans le menu Files of type (fichier PNG par défaut), puis définir l'emplacement et le nom du fichier. Cliquer sur OK.
Pour créer une image vectorielle contenant le graphe :
* S'assurer que la fenêtre de visualisation active est celle contenant le graphe, sinon, cliquer sur cette fenêtre.
* Cliquer sur le menu File → Export Scene.
* Dans la boîte de dialogue Export View: qui apparaît, choisir le format de l'image dans le menu Files of type (fichier EPS par défaut, préférer le format SVG si vous voulez retravailler l'image), puis définir l'emplacement et le nom du fichier. Cliquer sur OK.
Pour enregistrer le projet :
* Cliquer sur le menu File → Save State.
* Dans la boîte de dialogue Save State File qui apparaît, définir l'emplacement et le nom du fichier. Cliquer sur OK.

## Manipuler une image matricielle

ParaView peut servir à manipuler une image matricielle (bitmap), de type PNG, JPEG, GIF, TIFF, … Nous allons commencer par enregistrer une image localement ; prenons par exemple l'image File:Land ocean ice 2048.jpg :
* Dans la page Wikimedia Commons ci-dessus, cliquer avec le bouton secondaire (clic droit pour un droitier) sur le lien Fichier d'origine/Original file, puis dans le menu déroulant qui apparaît, choisir Enregistrer la cible du lien sous…
* Enregistrer le fichier dans un répertoire (dossier) local que vous retrouverez facilement.
Puis :
* Ouvrir ParaView.
* Cliquer sur le bouton Open, et ouvrir le fichier Land ocean ice 2048.jpg ; cliquer sur Apply.
* Faire bouger l'image avec la souris. On remarque que l'on ne peut pas la faire tourner, le mode par défaut étant « 2D ». Cliquer sur le bouton 2D en haut de la fenêtre de visualisation pour changer l'état de l'affichage en 3D, et faire bouger l'image. Revenir en mode « 2D ».
* Cliquer sur le bouton Split vertical (en haut à droite de la fenêtre de visualisation) pour créer une nouvelle fenêtre de visualisation. Dans la fenêtre Create View qui apparaît, cliquer sur le bouton 3D View.
* Sélectionner le menu Sources → Sphere. Cliquer sur Apply. Changer les valeurs Theta resollution et Phi resolution sur 16 et cliquer sur Apply ; constater que la sphère est moins anguleuse.
* Sélectionner le menu Filters → Alphabetical → Texture Map to Sphere. Cliquer sur Apply.
* Dans la boîte Properties, cliquer sur l'engrenage Toogle advanced properties. Dans la zone Miscelaneous qui apparaît (tout en bas), cliquer sur le menu Texture et choisir l'option Load…
* Dans la fenêtre Open texture qui apparaît, aller chercher le fichier Land ocean ice 2048.jpg et cliquer sur OK. Cela drape l'image sur la sphère.
* Dans la boîte Properties, décocher l'option Prevent seam et cliquer sur Apply.
On remarque que le résultat est imparfait :
* sur une petite portion de la sphère : une tranche de la sphère est occupée par une réplique en miroir de la carte ; On peut réduire cette portion en augmentant le paramètre Theta Resolution de la source Sphere, par exemple en le mettant sur 128 ;
* la carte est inversée est-ouest ; ceci est dû au fait que l'origine d'une image matricielle est en haut à gauche, tandis que l'origine géométrique habituelle est en bas à droite ; on résoud ce problème en créant une version miroir de la carte, par exemple avec The Gimp (menu Image → Transformer → Miroir horizontal).

## Associer des valeurs à des points et obtenir une représentation

Nous allons partir d'un fichier de coordonnées de points, disposés aux sommet d'un cube pour simplifier. Une valeur arbitraire A est associée à chaque point.

### Créer le fichier CSV

* Ouvrir un éditeur de texte.
* Copier le texte ci-après.
* Enregistrer le fichier dans un répertoire connu, dans un format texte, et avec le nom sommets_cube.csv.

### Afficher la géométrie et les valeurs dans ParaView

* Ouvrir ParaView et importer les données du fichier sommets_cube.csv.
* Cliquer sur le bouton Apply : l'objet sommets_cube.csv apparaît dans l'arborescence de tuyauterie, et les données apparaissent dans un tableau dans la fenêtre de visualisation.
* Sélectionner le menu Filters → Alphabetical → Table to Points. Cliquer sur Apply : cela affiche une nouvelle table.
* Dans la boîte Properties, les menus déroulants X, Y et Z affichent par défaut x. Cliquer sur les menus Y et Z pour sélectionner respectivement y et z, puis cliquer sur Apply.
* Cliquer sur le bouton Split Horizontal (le premier du groupe de quatre boutons situé en haut à droite de la fenêtre de visualisation). Dans la fenêtre Create View qui apparaît, cliquer sur 3D View. Cliquer sur l'œil situé à côté du filtre TableToPoints1 dans la tuyauterie ; cela affiche les huit points dans la fenêtre de visualisation.
* Sélectionner le menu Filters → Alphabetical → Delaunay 3D. Cliquer sur Apply : cela affiche un cube « plein » à la place des points.
* Faire varier l'affichage du cube :
** Cliquer dans la fenêtre de visualisation, et bouger la souris en maintenant le clic enfoncé : cela fait tourner le cube.
** Cliquer avec le bouton secondaire de la souris (bouton droit pour les droitiers), et faire monter ou descendre la souris ; cela fait un gros plan (zoom) ou un plan éloigné (dézoomage). Faire tourner la molette centrale pour zoomer/dézoomer.
** Cliquer avec la molette, et bouger la souris en maintenant le clic enfoncé : cela déplace le cube (translation). Cliquer sur le bouton Reset dans la barre d'outils pour ramener le cube au centre.
** Dans la barre d'outils, cliquer sur Surface, et dans le menu déroulant qui apparaît, choisir Wireframe pour afficher le maillage. Revenir sur l'option Surface
* Dans la zone Coloring de la boîte Properties, cliquer sur Surface, et choisir l'option A. Cela affiche des couleurs en correspondance avec la valeur de A ; les valeurs sont interpolées entre les nœuds, ce qui crée un dégradé.
* Modifier l'affichage :
** Cliquer sur le bouton Show pour afficher l'échelle de correspondance entre la valeur de A et les couleurs.
** Cliquer sur le bouton Edit pour modifier l'échelle des couleurs. Cela affiche la boîte de dialogue Color Map Editor. L'échelle figure dans la zone Mapping Data : les cercles sur la barre de dégradé en bas désignent les couleurs associées à certaines valeurs de A, double-cliquer dessus pour modifier une couleur. La ligne noire oblique indique que l'échelle est linéaire ; on peut modifier cette ligne en cliquant dessus, ou bien utiliser l'option Use log scale when mapping data to colors pour avoir une échelle logarithmique.
Voir aussi : Triangulation de Delaunay sur Wikipédia

### Faire des calculs sur les données

* Sélectionner le menu Filters → Common → Calculator → . Cliquer sur Apply.
* Dans la boîte Properties, cliquer dans la zone d'édition située au-dessus de la calculatrice, et entrer sqrt(coordsX^2 + coordsY^2 + coordsZ^2). Les signes et opérateurs « sqrt ( ^ + ) » peuvent s'obtenir en cliquant sur les boutons de la calculatrice. Les noms des champs « coordsX coordsY coordsZ » peuvent s'obtenir à l'aide du bouton Scalar situé sous la calculatrice.
* Cliquer sur Apply : cela crée un nouveau champ de données appelé Result (nom défini dans la zone d'édition Result Array Name), qui contient les valeurs ${\sqrt {x^{2}+y^{2}+z^{2}}}$, c'est-à-dire la distance des points par rapport à l'origine. Le dégradé de couleur correspond alors à cette valeur.
* Cliquer sur l'onglet Information. On constate que les données Result sont des nombres réels (double désignant un nombre codé en double précision), et dont les valeurs s'échelonnent de 0 à 1 732,05 (${\sqrt {3}}$, longueur de la grande diagonale d'un cube d'arête 1).

### Autres représentations des données

Les filtres suivants correspondant à des méthodes de représentation souvent utilisées :
* Clip : coupe selon un plan ; ce plan est défini par sa normale, que l'on fait tourner avec la souris, et par l'intersection avec sa normale, que l'on modifie en cliquant sur les bords rouges figurant l'intersection du plan avec la boîte englobant la figure ; dans la boîte Properties, on peut également entrer les coordonnées d'un point du plan ainsi que les composantes du vecteur normal ;
* Slice : section (idem) ;
* Contour : trace les surfaces iso-valeurs, pour les niveaux définis dans une liste ; dans la zone stying de la boîte properties, il peut être utile de diminuer l'opacité en utilisant le curseur Opacity, pour voir les surfaces les unes derrière les autres en transparence.
* Threshold : affiche les mailles (cellules) possédant des valeurs scalaires comprises dans un intervalle donné. Il ne s'agit pas d'une affichage des zones de l'espace en fonction des valeurs interpolées, mais bien d'un affichage de mailles en fonction des valeurs aux nœuds ;
* Plot Over Line : affiche l'évolution des valeurs scalaires le long d'une ligne ; la ligne est modifiée en cliquant sur ses extrémités. Pour les options du tracé, voir la section Tracer une fonction réelle ci-dessus.
On fera attention à bien recliquer sur Delaunay3D1 ou bien Calculator1 avant d'appliquer chaque filtre, afin de ne pas les combiner.
* Choix d'un plan de coupe ou de section (Clip ou Slice)
* Coupe (Clip)
* Section (Slice)
* Utilisation de trois sections orthogonales (Slice, coordonnées des plans entrées manuellement)
* Surfaces iso-valeur (Contour)
* Valeur le long d'une ligne (Plot Over Line)

## Fichier VTK simple

Comme précisé en introduction, ParaView s'appuie sur la bibliothèque VTK (visualization toolkit). Les formats natifs de la bibliothèque VTK sont donc des formats d'échange privilégiés avec ParaView. Si ParaView peut lire de nombreux formats de fichiers (créés en général par des logiciels de calcul ou d'acquisition), si vous devez créer vos fichiers (par exemple à partir de vos propres programmes de calcul), il est intéressant de connaître ces formats natifs.
La bibliothèque VTK gère deux formats de fichiers natifs : un format XML, et un format « héritage » (legacy). Le format XML permet de faire plus de choses, mais est plus complexe. Le format héritage peut être ASCII (caractères alphanumériques) ou bien binaire.
Nous allons donner ici un exemple simple de fichier héritage ASCII.

### Créer le fichier VTK

* Ouvrir un éditeur de texte.
* Copier le texte ci-après.
* Enregistrer le fichier dans un répertoire connu, dans un format texte, et avec le nom cube_structure.vtk.
La première ligne # vtk DataFile Version 2.0 est l'en-tête normalisé du fichier. Le seconde ligne est un titre d'au plus 256 caractères, et se terminant par un retour à la ligne. La troisième ligne indique qu'il s'agit d'un fichier ASCII.
Le bloc suivant décrit le maillage :
* DATASET STRUCTURED_POINTS indique qu'il s'agit d'un maillage parallélépipède uniforme (l'espacement entre les nœuds est le même le long de chaque axe, les mailles sont des parallélépipèdes rectangles tous identiques) ;
* DIMENSIONS 3 3 3 indique qu'il s'agit d'une structure de 3×3×3 nœuds ;
* ORIGIN -1 -1 -1 indique que l'origine du maillage se trouve aux coordonnées (-1 ; -1 ; -1) ;
* SPACING 1 1 1 indique que l'espacement est de 1 dans les direction x, y et z.
Cela crée donc un maillage de 27 nœuds sous la forme d'un cube dont l'arête a une longueur de 3.
Le dernier bloc crée le champ de données :
* POINT_DATA 27 indique que le champ contient 27 données ;
* SCALARS ma_variable float 1 indique que le champ s'appelle « ma_variable », qu'il s'agit de nombre réels (à virgule flottante, simple précision), le dernier paramètre est laissé par défaut à « 1 » ;
* LOOKUP_TABLE default indique que la correspondance valeurs-couleurs utilise la table par défaut ;
* suivent les valeurs associées aux nœuds, l'ordre étant le suivant :
** la première valeur est associée à l'origine ;
** y et z étant fixés, on incrémente x ; on parcourt donc l'axe des x dans le sens croissant ;
** arrivé au bout de la rangée, on incrémente y (en gardant z constant), puis on parcourt x de la valeur minimale à la valeur maximale ;
** une fois la valeur maximale de y atteinte, on incrémente la valeur de z, on remet les valeurs de x et de y à l'origine, et on continue.
Nous avons ici choisi comme données les distances par rapport à l'origine, qui prennent donc des valeurs dans $\{0;1;{\sqrt {2}};{\sqrt {3}}\}$.

### Afficher les données dans ParaView

* Ouvrir ParaView.
* Ouvrir le fichier cube_structure.vtk (menu Open → View). Cliquer sur Apply.
* Changer la représentation de Outline à Volume (dans la barre d'outils, ou bien dans la boîte Properties, menu Representation). Automatiquement, ParaView utilise le champ de valeurs ma_variable pour le rendu de couleurs.
* Dans la boîte Properties, zone Volume Rendering, menu Volume Rendering Mode, choisir l'option Ray Cast Only.
La fenêtre de visualisation affiche le cube en transparence, la densité dépendant de la valeur scalaire interpolée à partir des valeurs définies aux nœuds.

## Fichier VTK avec maille non structurée et données vectorielles

Nous allons créer un fichier VTK « héritage » ASCII contenant un maillage non structuré. La description du maillage est pleinement explicite : il faut préciser les coordonnées de chaque point, ainsi que les points appartenant à chaque maille. Nous nous contentons ici d'une seule maille tétraédrique, et donc de quatre nœud. Nous créons également un champ vectoriel, en associant un vecteur à chaque nœud.
Le fichier tetraedre_vecteurs.vtk est le suivant :
Les commandes notables sont les suivantes :
* DATASET UNSTRUCTURED_GRID : maillage non structuré ;
* POINTS 4 float : quatre points, les coordonnées étant des réels (virgule flottante en simple précision) ; suivent les coordonnées des quatre points (définissant ici un tétraèdre régulier centré sur l'origine) ;
* CELLS 1 5 : indique qu'il n'y a qu'une seule cellule, et que la description du maillage nécessite cinq valeurs : la ligne suivante 4 0 1 2 3 indique que la première (et unique) maille possède quatre nœuds, et que ce sont les points {0 ; 1 ; 2 ; 3} (les points sont désignés par leur ordre de définition ci-dessus, en commençant par zéro) ;
* CELL_TYPES 1 indique que nous allons définir un type de cellule ; le type 10 sur la ligne suivante correspond au tétraèdre ;
* POINT_DATA 4 indique que nous allons définir un champ de 4 données ; VECTORS mes_vecteurs float indique que ce sont des vecteurs de réels (donc trois réels par donnée), et que le nom du champ est mes_vecteurs ; suit la liste des vecteurs, dans l'ordre des indices des points.
Donc :
* le point d'indice i = 0 est le premier point défini ; il a pour coordonnées (0,67 ; 0 ; -0,33), et le vecteur associé a pour composantes (2 ; 0 ; -1) ;
* le point d'indice i = 1 a pour coordonnées (-0,33 ; 0,67 ; -0,33), et le vecteur associé a pour composantes (-1 ; 2 ; -1) ;
Pour représenter les données :
* Ouvrir ParaView, charger le fichier tetraedre_vecteurs.vtk et cliquer sur Apply.
* Sélectionner le filtre Filters → Common → Glyph et cliquer sur Apply.
* Dans la boîte Properties, paramètre Set Scale Factor, cocher la case Edit et dans le zone de texte, entrer la valeur 0.07. Cliquer sur Apply.
* Dans la zone Coloring, cliquer sur Edit. Dans la boîte de dialogue Select Color qui apparaît, sélectionner le rouge et cliquer sur OK.
* Dans l'arborescence de tuyauterie, cliquer sur la source tetraedre_vecteurs.vtk, puis, sélectionner le filtre du menu Filters → Common → Warp By Vector. Cliquer sur Apply.
* Dans la boîte Propereties, fixer la valeur du champ Scale Factor à 0.2 et cliquer sur Apply. Réduire l'opacité, puis dans l'arborescence de tuyauterie, cliquer sur l'œil situé à côté de la source tetraedre_vecteurs.vtk pour la faire réapparaître.
Ce dernier filtre est utile pour afficher la déformée d'une géométrie, par exemple lorsque le champ vectoriel est un champ de déplacement.
Nous modifions ci-dessous l'exemple pour rajouter un cinquième point, et une seconde maille construite.
Fichier deux_tetraedres_vecteurs.vtk :

## Données ponctuelles ou données cellulaires ?

Nous avons ci-dessus défini des données ponctuelles (POINT_DATA), c'est-à-dire des valeurs attachées aux nœuds du maillage. Il est également possible de définir des données attachées aux cellules (CELL_DATA), aux mailles. Outre l'emplacement géométrique des valeurs, il existe une différence fondamentale :
    Dans le cas d'une valeur cellulaire, la valeur est uniforme au sein de la cellule. Il n'est donc pas possible d'interpoler ou de dériver le champ (ni par exemple d'en tirer des lignes de champ). À l'inverse, dans le cas de valeurs ponctuelles, ParaView considère qu'il s'agit d'un champ continu et interpole la valeur entre les nœuds.
Il est possible de transformer des valeurs cellulaires en valeurs ponctuelles avec le filtre Cell Data to Point Data, et vice versa avec le filtre Point Data to Cell Data.

## Annexe
### Fichiers au format VTK XML

Pour information, nous donnons ici la version VTK XML des fichiers VTK « héritage » ASCII utilisés. On peut les générer avec le menu File → Save Data.
Fichier cube_structure.vti :
Pour la balise VTKFile, le type ImageData correspond à un volume parallélépipédique uniforme ; la propriété byte_order désigne la manière dont l'ordinateur code les nombres.
Pour la balise ImageData, la propriété WholeExtent donne les indices minimaux et maximaux pour les coordonnées x, y et z ; nous avons donc ici dans les trois cas des indices allant de 0 à 2 (donc trois points par axe). Les autres paramètres sont explicites.
Fichier deux_tetraedres_vecteurs.vtu :

## Notes et références

* ↑ voir « Menu Transformer », sur docs.gimp.org
* ↑ dans le sens « héritage du passé » ; c'est un format développé pour des anciennes versions de VTK, et qui est toujours lisible pour des raisons de compatibilité et de simplicité de la syntaxe
* ↑ en particulier, il peut gérer le parallélisme des calculs

## Voir aussi
### Livres connexes

* Programmation XML

### Liens externes

* (en) « ParaView Data formats », sur Kitware Public Wiki
* [pdf] (en) « File formats for VTK 4.2 » [PDF], sur vtk.org