.. _intro_vtfx_page:

###################
Writing VTFx Files
###################

First one creates a :class:`File <cee::vtfx::File>` object. Call the :func:`File::create() <cee::vtfx::File::create>` 
method to create the new VTFx file, specifying the file name and file settings using 
:class:`FileSettings <cee::vtfx::FileSettings>`:

-   **binary** - true for binary data files or false for text data files. Text files are good for debugging while binary 
    files highly increases the file load time.
-   **createDigitalSignature** - true to store a digital signature in the VTFx file. The signature allows to detect and 
    thus avoid changes made to the VTFx file by third parties.
-   **compressionLevel** - 0: no compression, 1..9: minimal to maximal compression, default is 5.
-   **vendorName** - Vendor name, typically your company name.
-   **applicationName** - Application name.
-   **password** - Optional password for the VTFx file, digits and latin characters are allowed, encryption method is 
    AES-256, supply NULL to disable encryption.

.. image:: ../../../images/vtfx/uml_vtfx_minimal.png
    :height: 480px


At least one database is required for a VTFx file. The class :class:`Database <cee::vtfx::Database>` abstracts databases 
and its instances are used to register databases in the supplied :class:`File <cee::vtfx::File>` object. Note that every 
database within a VTFx file requires a unique id.
To define the geometry data in a database you need to create at least one node block 
(:class:`NodeBlock <cee::vtfx::NodeBlock>`), one element block (:class:`ElementBlock <cee::vtfx::ElementBlock>`), and a 
geometry block (:class:`GeometryBlock <cee::vtfx::GeometryBlock>`) with a corresponding info block 
(:class:`GeometryInfoBlock <cee::vtfx::GeometryInfoBlock>`). 

An example for handling a node block: you add nodes to the node block and after the node block is complete, you write 
the node block to a database using :func:`Database::writeBlock() <cee::vtfx::Database::writeBlock>`. Only write a block 
once to a database, and do not reuse the block for additional 
writing operations. Similar approach for the element block: reference the node block, add elements, and write the block 
to the database. 
Then, create a geometry block referring the element block and write it to the database. The methods of 
:class:`GeometryBlock <cee::vtfx::GeometryBlock>` either use no state id parameter to define static geometry, or use a 
state id parameter to define adaptive geometry. If no state id is used, then the default state id is 1. The 
:class:`GeometryInfoBlock <cee::vtfx::GeometryBlock>` contains part info for element blocks used in the 
:class:`GeometryBlock <cee::vtfx::GeometryBlock>`.

The last block type needed for a minimal database is :class:`StateInfoBlock <cee::vtfx::StateInfoBlock>`. Every state 
needs a unique state id, and for every state id one has to add a corresponding entry to this block. The state info block 
allows defining state meta data, such as name, state type, time, frequency, and so forth. This depends on the type of 
simulation results one writes to the database, i.e. load cases, modal frequencies, time steps, etc.

Once the database is fully specified, one creates a case (:class:`Case <cee::vtfx::Case>`), which is the second 
important element of a VTFx file. A case defines a visualization configuration of database contents. The visualization 
configuration is defined by adding :ref:`properties <VTFx-prop-page>` to the case. Every property block defines a 
specific aspect of the visualization, such as states shown for an animation, part colors, mapped scalars and vectors, 
part draw styles, and much more. It is best practice to have a look at the 
:ref:`examples provided with VTFx Component <tutorials-page>`) to see the potential and use of properties. 
Note that properties must be written to cases, not to databases.

A VTFx file may contain many cases, thus you may define several visualization configurations of one database within a 
single VTFx file.

Most methods return true/false to indicate success or failure. If an error occurred, a message will be logged to the 
|ProductName| :ref:`logging system <logging-page>`. Enabling logging is good practice and a great help
identifying problems.

Once the databases and cases are finished, one closes the VTFx file using :func:`File::close() <cee::vtfx::File::close>`. 

The file is now ready to be opened in any of Envisions's products. You can install our free viewers, for instance; 
HOOPS Envision Demo. The generated VTFx file can also be added to the Ceetron Cloud 
(https://cloud.ceetron.com) for easily sharing it without the need for installed software. See 
:ref:`cloud-integration-vtfx-page`.

Since a VTFx file may contain several databases and cases, one can open and append databases, cases or blocks to an 
existing VTFx file. 
To open a VTFx file for appending, use :func:`File::openForAppend() <cee::vtfx::File::openForAppend>` and proceed as 
usual to add new databases, cases or blocks. 

**Minimal Example** 

.. |img| image:: ../../../images/vtfx/tut_vtfxwriter.png
   :width: 150
   :target: examples/my-first-vtfx.html

+-----------------------+------------------------------------------------------------------------------------+
| |img|                 | :ref:`vtfx-writer-tutorial`     |br|                                               |
|                       | This example shows how to create a minimal VTFx file with a simple part |br|       |
|                       | consisting of just one hexahedron element. The VTFx file has only one state, |br|  |
|                       | no results of any kind nor any properties.                                         |
+-----------------------+------------------------------------------------------------------------------------+
