
.. _data-element-sets-tutorial:

########################################################
UnstructGrid: Using DataElementSets to Filter the Model 
########################################################

.. image:: ../images/tut_dataelementsets.png
    :height: 300
    :align: center
    
Element sets can be used to specify which elements that should be visible at any given time in a data source within an 
unstruct grid model.

By creating a :class:`DataElementSet <cee::ug::DataElementSet>` and adding 
:class:`DataElementSetItems <cee::ug::DataElementSetItem>` to this you can filter the model based on any custom
property, spacial position in world or window coordinates or any other criteria.

This tutorial shows how to create element sets and how to use the filtering to control which elements to show.

The demo file (30x30x30.vtf) contains a single part geometry with a synthetic scalar result. 

Load the file and setup the model specification to show the result. For a more thorough 
explanation on creating a data source from a file interface and setup the model specification,
see the Load VFT tutorial:
:ref:`simple-load-vtf-tutorial`

.. note::
    This tutorial expect the application to have a correctly configured :class:`cee::vis::View`
    in place. See the demo applications on how to set up a :class:`cee::vis::View` in your application.

**Load model**

Create the model and a VTF file interface data source. Open the file and set the created data
source in the model.

.. literalinclude:: ../../../../EnvisionDesktop/Tutorials/DataElementSets.cpp
    :language: cpp
    :lines: 50-51,54-58,61

Set the first state as current in the model specification.

.. literalinclude:: ../../../../EnvisionDesktop/Tutorials/DataElementSets.cpp
    :language: cpp
    :lines: 64-66

Find the id of the first scalar result from the data source's directory.

.. literalinclude:: ../../../../EnvisionDesktop/Tutorials/DataElementSets.cpp
    :language: cpp
    :lines: 69-72,73-74


**Create the sets**

We use the :class:`DataElementSetGenerator <cee::ug::DataElementSetGenerator>` class to create the sets. This class 
provides methods for creating sets from an :class:`UnstructGridModel <cee::ug::UnstructGridModel>`,
either by world coordinates (as in this example) or in screen coordinates (with the 
:func:`createFromRegion() <cee::ug::DataElementSetGenerator::createFromRegion>`) method.

First, create a set with all elements above the first plane. We use the FRONT and ON criteria so we will add any element 
that is either intersected by the plane or in front of the plane.

.. literalinclude:: ../../../../EnvisionDesktop/Tutorials/DataElementSets.cpp
    :language: cpp
    :lines: 77-79

Then, create a second set with all elements below the second plane. We use the same criteria here.

.. literalinclude:: ../../../../EnvisionDesktop/Tutorials/DataElementSets.cpp
    :language: cpp
    :lines: 82-83

Do an intersection of the two sets to get the elements that are between the two planes (the elements presents in both 
sets).

.. literalinclude:: ../../../../EnvisionDesktop/Tutorials/DataElementSets.cpp
    :language: cpp
    :lines: 86

Now, add the complete DataElementSet to the DataSource of the UnstructGridModel.

.. literalinclude:: ../../../../EnvisionDesktop/Tutorials/DataElementSets.cpp
    :language: cpp
    :lines: 89


Specify to use this set (with id = 1) as our visible set in the :class:`ModelSpec <cee::ug::ModelSpec>` of the 
:class:`UnstructGridModel <cee::ug::UnstructGridModel>`. This will filter the model so only the elements in the set will 
be visible. When we specify one or more set ids as visible sets, the element filtering will be enabled.

.. literalinclude:: ../../../../EnvisionDesktop/Tutorials/DataElementSets.cpp
    :language: cpp
    :lines: 92


**Set up the created model**

Show all parts as surface mesh so we can see the elements.
 
.. literalinclude:: ../../../../EnvisionDesktop/Tutorials/DataElementSets.cpp
    :language: cpp
    :lines: 95-100


The model is ready to use and can be added to the view. Exactly where the view exists
depends on the platform and solution. These examples uses Qt and the view is set up 
in a :class:`cee::qt::ViewerWidget`.

.. literalinclude:: ../../../../EnvisionDesktop/Tutorials/DataElementSets.cpp
    :language: cpp
    :lines: 103-113


**See the complete source code here:**

:ref:`data-element-sets-example`

