Using ParaViS
--------------
.. include:: ../icons.inc

.. sectionauthor:: Wayne Arter

The initial chapters of the official guide explain basic concepts such as
the graphics pipeline and should be at least skim-read before reading these
SMITER-specific hints. This preliminary should help the user acquire the
necessary familiarity with basic ParaView GUI layout, knowledge of when to
use the :guilabel:`Apply` button, and thereby avoid the commonest mistakes
and sources of confusion.

General points worth noting are that

* SMITER in normal use only generates surface information, so many ParaView
  functions which require volume data are not available or needed.

* ParaView starts counting from zero, whereas SMITER is more conventional,
  so that for example, the first track starts from triangle zero.

* Toggling the gear-wheel symbol gives access to a wider and often useful
  range of extra functionality.

The functionality most often needed for SMITER concerns the making and
saving of selections of the data in the vtk files. A specific example is
the visualisation of fieldlines emanating from part of the geometry. The
selection process is activated by toggling the "Select Cells on" icon
immediately above the main "render" window ("Select Cells With Polygon"
offers finer control). A selection box is defined by the mouse and the
selected cells (triangles) are highlighted. The selection may be inspected
in more detail, by use of the Selection Display Inspector
:menuselection:`View -->Selection Display Inspector`). If satisfactory, the
"Extract Selection" icon which is on the menu bar just above the Select
Cells icons, should be clicked upon. :menuselection:`File --> Save` data
can then be used to save the selection to a Legacy vtk (.vtk) format file,
using the options to save all timesteps to the Ascii file type. The new vtk
file thereby produced can be used as an input to a new SMITER run with
field-line plotting activated in the .ctl file. datvtk preserves block
information from each .dat file when it is converted to .vtk (unfortunately
it is discarded in subsequent processing). If block numbers are known, or
identified from ParaView visulation, their geometry can be selected by
first using :menuselection:`Edit --> Find data`, where "is one of" is the
most flexible selection option. Having created the selection use the
"Extract Selection" icon as above, clicking on "Copy active selection".

Most other functionality is accessed by the Filters menu. Of the myriad
options, the ones most relevant to SMITER are

* Integrate variables, for total power.

* Calculator, operates on fields such as Bcart and Q, to give B.n etc.

* Point data -> Cell data, and vice versa, since Calculator only operates
  on variables of the same data type.

* Cell centres, when producing spread-sheet .csv output.

* Generate Ids, to help locate elements and points on the surface.

* Append attributes, enables data from different vtk files with same
  geometry to be combined.

* Plot on intersection curves, for line plots of data as functions of
  arclength on surface, see "Line plots" below.

Views in the render window may be saved to .png file for plotting using
:menuselection:`File --> Save Screenshot`. The same view may be applied to
a separate session by using :menuselection:`File --> Save State`, then
:menuselection:`File --> Load State` in the new ParaView session (same
release required).

Spread-sheets may be produced using :menuselection:`File --> Save Data`,
for which CSV is the default option. For point data this is straighforward,
as the position is saved with the data (consistent with ParaView usage, the
first vector component is zero). Cell centre points need to be explicitly
defined by the user with the Cell centre filter before using File->Save
Data with cell data such as Q.

Line plots using ParaView
~~~~~~~~~~~~~~~~~~~~~~~~~

In ParaView notation, SMITER calculates Q values at cell centres, but
ParaView only plots point values, so it interpolates in a manner than does
not seem to be documented officially. Checks indicate that the point value is
an average over cell-centred values for all triangles meeting at the point
(probably area-weighted), hence shadow edges get blurred since typically
only 2 cells out of 6 or 8 have non-zero Q. The intersection curve is
likely to be generated by the intersection of a plane and the surface, and
when generically the intersection between the plotting plane does not align
with the surface triangulation points, there is a further interpolation to
points on the intersection. The intersection curve is not sampled uniformly
but at points which seem to correspond to the projections of the vertices
of intersected triangles.

Hints for line plots
~~~~~~~~~~~~~~~~~~~~

It is often easier to reduce the size of the geometry in the window by
using "select cells through" icon just above followed by

Extract selection, (on bar just above) then :menuselection:`Cell data -->
point data`.

The filter is "Plot on intersection curves", when the menu brought up is
comprehensive if the gear-wheel is clicked. However it will often be found
helpful to save the data to a .csv file for graphing using gnuplot (comment
out first line with leading "#", replace commas with spaces) or spreadsheet
software.

.. sectionauthor:: Leon Kos

Using IOR in ParaViS plugins
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To show geometry and meshes with Interoperable Object Reference (IOR)
inside ParaViS one can to use 
:menuselection:`Source --> Para Geometry Corba Plugin Source`
and :menuselection:`Source --> Para Mesh Corba Plugin Source`.
However, one firstly needs to provide IOR value of the selected object 
within the study. To get this value for properties using Python console::

   >>> import salome
   >>> o = salome.myStudy.FindObjectID(salome.sg.getSelected(0))
   >>> o.GetIOR()

Then the IOR value starting with ``IOR:0100...`` can be cut and pasted into
plugin properties.

Better option is to use SMITER dialog which displays IOR value that
can the be copied into appropriate *CORBA* plugin. To activate this
dialog click on |ior_icon| icon. Then select desired object in Object
Browser and then click button ``Get IOR``.

.. figure:: ../intro/images/GetIORdialog.png
    :align: center

    Get IOR dialog.

Desired IOR object will be transfered and displayed in Paraview module.

Writing filters in ParaVis
~~~~~~~~~~~~~~~~~~~~~~~~~~

.. sectionauthor:: Matic Brank
                   
In *ParaViS* you can write a ``filter``, a python plugin script, which you
can then apply to any data source that is in the *Pipeline Browser* in
*ParaViS*.

The goal here is to write a script in which we will calculate the total heat
power from a vtk file we got from ``POWCAL``.

First we need the *ParaViS* module activated and a vtk file loaded to the
*Pipeline Browser*.


.. image:: paravisFilter_1.*
   :align: center

Then we will apply a ``Programmable Filter``, by first clicking on the
*VTK* file in the *Pipeline Browser* to highlight it and then clicking on
the menu :menuselection:`&Sources --> Search`. In the **Search** window
that pops up, write ``Programmable Filter`` and click on it when it appears
in the *results*.

.. image:: paravisFilter_2.*
   :align: center

In the left *docking* area, beneath the *Pipeline Browser* a new window will
appear. In this window there will be an input area, in which you will be able
to write the ``filter`` script.

.. image:: paravisFilter_3.*
   :align: center

In the case of integrating the **Heat Flux** on the wall, you have to multiply
the ``area`` and the ``heat flux`` for each cell and then sum it all up. In
python code it will look like:

.. code-block:: python

   # Get the VTK data from input
   data = self.GetInput()
   Q = data.GetCellData().GetArray('Q')
   sumPow = 0.0
   # Integrate the values.
   for i in range(data.GetNumberOfCells()):
       area = data.GetCell(i).ComputeArea()
       powDen = Q.GetValue(i)
       sumPow += powDen * area
   # Note that the cells coordinates are in milimeters.
   sumPow *= 1e-6

   # Put the output value in a cell array and name it 'Power'
   out = self.GetOutput()
   import vtk
   ar = vtk.vtkDoubleArray()
   ar.SetName('Power')
   ar.InsertNextTuple((sumPow,))
   out.GetCellData().AddArray(ar)

This code will perform the integration on the *highlighted VTK file* in
*Pipeline Browser*. After you paste the code into the ``Script`` area, click
the button :guilabel:`Apply` and the script will run.

By default, you will see in the *display* window the same object as it was in
the highlighted *VTK file*. But to see the calculated ``Power`` you will have
to open a **Spreadsheet View** for the **ProgrammableFilter1** object that is
shown in the **Pipeline Browser**.

In the **Spreadsheet View** you will see under Cell data one ``Power`` entry,
having the calculated value from the ``Filter``.

To see how to get the **Spreadsheet View**, check :ref:`SpreadsheetView`.

.. image:: paravisFilter_4.*
   :align: center

.. note::

   This little example only show the heat power for the target tile and not
   the whole wall. This can be changed by multiplying the python variable
   ``sumPow`` with the necessary value.

Using a single programmable filter to multiple pipeline objects
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The process is the same as in the previous section, except first highlight all
the objects you want to filter and then apply the filter the same way as you
would do to a single pipeline object.

Then the only difference is, that the data from different pipeline objects are
accessed with ``inputs``.

A simple script integrating the **heat flux** on multiple pipeline objects:

.. code-block:: python

   print(len(inputs))
   sumPow = 0.0
   for i in range(len(inputs)):
       # Get the VTK data from input
       data = self.GetInput()
       Q = data.GetCellData().GetArray('Q')
       # Integrate the values.
       for i in range(data.GetNumberOfCells()):
           area = data.GetCell(i).ComputeArea()
           powDen = Q.GetValue(i)
           sumPow += powDen * area
           # Note that the cells coordinates are in milimeters.
   sumPow *= 1e-6

   # Put the output value in a cell array and name it 'Power'
   out = self.GetOutput()
   import vtk
   ar = vtk.vtkDoubleArray()
   ar.SetName('Power')
   ar.InsertNextTuple((sumPow,))
   out.GetCellData().AddArray(ar)

.. _SpreadsheetView:

Extracting data from *VTK file* 
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. sectionauthor:: Gregor Simic

To extract data from the ``VTK`` file, *ParaViS* can be used to export selected
data in ``CSV`` files. To do this you have to activate the *ParaViS* module
inside *SMITER*. Then you have to open a ``VTK`` file, typically the output
file from *powcal*.

.. note::

   The geoq output file :file:`*_geoqx.vtk` file contains values useful 
   for analysis such as *B* and *n* on the surface.   

Then you click on the ``Split Horizontal`` button, situated on the right end
of the `Layout` bar.

.. image:: vtk_1.*
   :align: center

The `Layout` will split into two. On the right you will have a group of buttons
for creating a new `View`. Click the last one that says **SpreadSheet View**.

You will get a `spreadsheet representation` of the data inside the ``VTK``
file.

In the `toolbar` of the `View` you see multiple controls to edit the
spreadsheet. The important parts of the `toolbar` are visible on the next
image.

.. image:: vtk_2.*
   :align: center

With the **Attribute** you select which type of data to show in the
spreadsheet, i.e. `Point Data` or `Cell Data`.

With the **Column selection** you toggle the visibility of columns. That means
you only select the columns you wish to extract and save to a ``CSV`` file.

The **Show ID nodes in Cell Data** shows the columns with the node ``IDs`` for
each cell in **Attribute: Cell Data**.

With the last one you export or save the selected data into a ``CSV`` file.

For example if you wish to get the data for `power` deposition on `cells` in
the output ``VTK`` file from *powcal*:

1. Select the ``Attribute:`` **Point Data**.
2. Save to ``CSV`` file.

With this you get the **NODES** of the geometry, the ``XYZ`` position and its
``ID``. This is important since the `Cell Data` contains the ``ID`` of the
nodes the cells contain. Next you do:

1. Select the ``Attribute:`` **Cell Data**.
2. Click on **Show ID nodes in Cell Data**.
3. Select the ``Column selection``
4. Deselect all but the following things: ``Point Index 0``, ``Point Index 1``,
   ``Point Index 3`` and ``Q``.
5. Save to ``CSV`` file.

With this you get the information from which points the cells are made and the
power deposition value ``Q`` in units of Watts.

Activating ParaViS module with python in GUI mode
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. sectionauthor:: Gregor Simič
                   
The following lines activates the ParaViS module in python::

   import salome
   ParaViScomponent = salome.myStudy.FindComponent('PARAVIS')
   if ParaViScomponent and ParaViScomponent.GetObject():
       # Check if ParaViS module is activated by checking if GetObject()
       # returns a non-None value.
       pass
   else:
       # ParaViS can be activated through SalomePyQt module.
       import SalomePyQt
       sg = SalomePyQt.SalomePyQt()
       sg.activateModule('ParaViS')
   # Now ParaViS interface can be used
   import pvsimple
   ...