.. _report-tutorial:

###################################################
Report: Create a Simple Word Report with a 3D Model
###################################################

.. image:: ../images/tut_report_template.png
    :width: 45%

.. image:: ../images/tut_report.png
    :width: 45%

The Report component enables the user to create highly customizable reports in PowerPoint,
Word and HTML containing interactive 3D models. 

The report is generated from on a template file which is a normal PowerPoint presentation, Word 
document or HTML text file. Using tags, we mark the parts of the template which should be replaced 
with data from our simulation. To help you add these tags, we have provided a MS Office add in, but 
you can create your templates using just your installed Office products.

This tutorial shows how to create a Word report where the 3D model from your view is inserted (and
embedded) into the Word document along with some metadata.

Figure below are showing the template Word document on the left and the generated report on the right:

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 VFTx tutorial:
:ref:`simple-load-vtf-tutorial`

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

**Load model**

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

.. literalinclude:: ../../../../EnvisionDesktop/Tutorials/Report.cpp
    :language: cpp
    :lines: 56-74

**Apply properties**

Read model and view properties from the VTFx file and apply these to the current 
model and active view. We make sure to set some default view settings in advance 
in case the VTFx file does not contain any view properties.

.. literalinclude:: ../../../../EnvisionDesktop/Tutorials/Report.cpp
    :language: cpp
    :lines: 82-100

**Create a 3D snapshot**

Using :class:`ExportVTFx <cee::exp::ExportVTFx>` we can create a VTFx file (either on disk or
just in memory) for the current model with all applied properties and the active view setup. 
Properties are, for instance, current fringes scalar result or vector results visualized on the model, or 
draw style/color for parts, or advanced features like isosurfaces and cutting planes. The
Image Resources object contains textures and overlay images if such are used.

.. literalinclude:: ../../../../EnvisionDesktop/Tutorials/Report.cpp
    :language: cpp
    :lines: 109-120

In this tutorial we are using a memory file. This file will be embedded into the Word document 
and the user don't need to worry about the path to the VTFx file being broken. It's all there inside 
the Word document. Just share it!

.. literalinclude:: ../../../../EnvisionDesktop/Tutorials/Report.cpp
    :language: cpp
    :lines: 123-128

**Create snapshot and repository**

To create a report, we need to create a repository. A repository is a collection of
snapshots, each snapshot being a "snapshot" of the model at a given setup. The snapshot
can either be a 3D model, an image or tabular data (for plot or just a list of data).

In this tutorial we will create one snapshot containing a 3D model. 

First, we
create a repository. Then we create a 3D snapshot and add the 3D model we created above using 
:func:`Snapshot::setModelVTFx() <cee::rep::Snapshot::setModelVTFx>`. In addition, each snapshot can have a name, a 
description and a set of field values. Field values are name and value pairs containing data from you model. 
Using a field value tag in your template, the report generation will replace it with the matching value
from your model. The Report component provides some basic field values that are populated using
:func:`cee::rep::FieldValueSet::fromModel()`. In addition to these, you can add your own field values. See 
:ref:`field-values-page` for more information.

When the snapshot is created, we add it to the repository. In this tutorial, the repository
only contains one snapshot.

.. literalinclude:: ../../../../EnvisionDesktop/Tutorials/Report.cpp
    :language: cpp
    :lines: 131-139

**Generate Report**

Once we have the repository, we just need the path to the template file. The template file is
an ordinary Word document with text and objects tagged to be replaced with the matching snapshot data
in the repository. Read more about templates and tagging in the topic: :ref:`tags-page`

Create a creator (Word, PowerPoint or HTML) and pass along the repository and the path to the template file.

Call :func:`generate() <cee::rep::ReportCreatorWord::generate>` to create and save the report to the 
specified file name. The generator will create a copy of the template file, search through
it and replace all tagged objects with the corresponding data found in the snapshots in the repository.

You can now open the generated Word report and verify that the 3D model along with its title and
some selected field values were inserted.

.. note::
    To get the interactive 3D model into your MS Office documents, you will need the 3D Plugin.

.. literalinclude:: ../../../../EnvisionDesktop/Tutorials/Report.cpp
    :language: cpp
    :lines: 142-148

**See the complete source code here:**

:ref:`report-example`

