
.. _input-ug-page:

####################################
Getting Data into UnstructGridModel 
####################################

|ProductName| offers several approaches to getting data into the UnstructGridModel. This page outlines 
the different way of populating the model with elements and results. 

If you only have geometry data, the :class:`Geometry Model <cee::geo::GeometryModel>` might be a better choice.

**Unstructured Grid Model**

:class:`UnstructGridModel <cee::ug::UnstructGridModel>` defines a specific model structure and 
functionality for representing scientific and engineering models, e.g. finite element data. 
Essential to :class:`UnstructGridModel <cee::ug::UnstructGridModel>` is a :class:`DataSource <cee::ug::DataSource>`
which represents the actual source of model information. Subclasses to DataSource distinguish 
between :class:`interface/file based <cee::ug::DataSourceInterface>` and 
:class:`programmatic input <cee::ug::DataSourceMemory>` of model information. 

**Getting Data into the DataSource**

There are five different ways of getting your own data into a DataSource:

-   **Create your own data reader** |br|
    By deriving from cee::ug::DataReader and using the :class:`cee::ug::DataSourceReader` you can easily create a 
    data source that supports your own data.

-   **Use VTFx files** |br| 
    If you are able to save your data to VTFx (Envision file format) you can use the built-in data source 
    :class:`cee::ug::DataSourceVTFx` to read your data.

-   **Use the ImportCae Component** |br|
    If you want to load files from commercial FEA and CFD simulation software systems you can use the 
    :class:`cee::imp::cae::DataSourceCae`. 

-   **Use a DataProvider** |br|
    A Data Provider is a plugin for providing CAE data to applications built with |FamilyName| SDKs, both Desktop and Web. 
    Use an existing plugin or create your own Data Provider plugin to get your data into |FamilyName|. 

-   **Manually populate the DataSource** |br|
    Finally, you can always build the data model by hand, adding the parts, elements, nodes, results etc. 
    using code. 
 
Each of these five methods are described below.

1: Create Your Own Data Reader
==============================

Creating your own data reader is usually the recommended way of getting your data into |FamilyName|. By using a 
:class:`DataSourceInterface <cee::ug::DataSourceInterface>` derived class you will leverage the advanced data management 
capabilities of |ProductName|. After completing the data reader, you can just specify what you would
like to visualize, and the reader will be used to load data (element and results) whenever needed.

Please see the documentation of :class:`DataReader <cee::ug::DataReader>` and the 
:ref:`Create a custom DataReader <simple-load-vtf-tutorial>` tutorial for a detailed description on how to create your 
own reader.

.. |img| image:: ../../images/tut_custom_datareader.png
   :width: 150
   :target: ../../tutorials/custom-datareader.html

+-----------------------+------------------------------------------------------------------------------------+
| |img|                 | :ref:`custom-datareader-tutorial`     |br|                                         |
|                       | Shows how to get your own analysis results into the UnstructGridModel by |br|      |
|                       | creating a DataReader. It is a very simple reader that returns one hexahedron |br| |
|                       | element with one scalar, one vector, one displacement and one transformation |br|  |
|                       | result, but it will work as a starting point for building your own file reader.    |
+-----------------------+------------------------------------------------------------------------------------+

2: Using VTFx Files
===================

|ProductName| contains readers for the Envision file formats VTF and VTFx, 
:class:`DataSourceVTF <cee::ug::DataSourceVTF>` and :class:`DataSourceVTFx <cee::ug::DataSourceVTFx>`

The VTF and VTFx file formats are Envision's own formats tailored specifically to carry structural 
mechanics and fluid dynamics data in a very compact form. 
VTFx and VTF files can be viewed in several products from Envision. For instance the free viewers, Ceetron Cloud,
and HOOPS Envision VTFx Viewer. By utilizing XML and zip compression, the VTFx format expands 
the functionality and usefulness of the well established VTF format by adding features for 
security, adaptability and the ability to carry multiple cases in one file - without compromising on the file size. 


.. |img_vtf| image:: ../../images/tut_loadvtf.png
   :width: 150
   :target: ../../tutorials/simple-load-vtf.html

+-----------------------+------------------------------------------------------------------------------------+
| |img_vtf|             | :ref:`simple-load-vtf-tutorial`     |br|                                           |
|                       | Shows how to create a data source by loading a VTFx file and how to setup a |br|   |
|                       | model specification                                                                |
+-----------------------+------------------------------------------------------------------------------------+

3: Use the ImportCae Component
==============================

The :class:`Import CAE Data Source <cee::imp::cae::DataSourceCae>` supports most commercial FEA and CFD formats. Please 
note that this component requires a separate feature in the license key and has additional cost of use.

Simulation data from external commercial CAE formats are stored in the 
:class:`DataSourceCae <cee::imp::cae::DataSourceCae>` data source. 
See topic: :ref:`Use Import CAE Component <import-cae-page>`.

4: Use a Data Provider
======================

A Data Provider is a plugin for providing CAE data to applications built with |FamilyName| SDKs, both Desktop and Web. 
The Data Provider Framework is free to use. Use an existing plugin or create your own Data Provider plugin to get your 
data into |ProductName|. 

See topic :ref:`data-provider-framework-page` and :ref:`data-providers-page` for more information.

5: Manually Populate the DataSource
===================================

By using a :class:`memory data source <cee::ug::DataSourceMemory>` to create a data source "by hand". All states, 
geometries and results are added manually. By entering the data manually into the DataSource, you will have full control
over the current contents. You also then have the responsibility to provide the needed data before calling 
:func:`updateVisualization() <cee::ug::UnstructGridModel::updateVisualization>` on the 
:class:`model <cee::ug::UnstructGridModel>`.

See :class:`DataSourceMemory <cee::ug::DataSourceMemory>`


.. |img_tt| image:: ../../images/tut_twotriangles.png
   :width: 150
   :target: ../../tutorials/two-triangles.html

.. |img_twr| image:: ../../images/tut_triangle_with_results.png
   :width: 150
   :target: ../../tutorials/triangle-with-results.html

+-----------------------+------------------------------------------------------------------------------------+
| |img_tt|              | :ref:`two-triangles-tutorial`     |br|                                             |
|                       | Shows how to create your own part and to use it in a model.                   |br| |
|                       | The geometry is a very simple structure containing two triangles only.             |
+-----------------------+------------------------------------------------------------------------------------+
| |img_twr|             | :ref:`triangle-with-results-tutorial`     |br|                                     |
|                       | Shows how to build an UnstructGridModel geometry, part and results.           |br| |
|                       | The geometry is a very simple structure containing a single triangle and |br|      |
|                       | a scalar result mapped as fringes, a vector result and a displacement result.      |
+-----------------------+------------------------------------------------------------------------------------+


.. seealso::

    -   :class:`DataSourceMemory <cee::ug::DataSourceMemory>`
    -   :class:`DataSourceVTF <cee::ug::DataSourceVTF>`
    -   :class:`DataSourceVTFx <cee::ug::DataSourceVTFx>`
    -   :class:`DataSourceReader <cee::ug::DataSourceReader>`
    -   :class:`DataSourceCae <cee::imp::cae::DataSourceCae>`
