.. _report-page:

#########################################################
Create Interactive Reports Directly from Your Application
#########################################################

With the |FamilyName| Report Component, 3D content can easily be included in MS Office documents. The engineer can 
explore the model and the results in full 3D, providing increased understanding and more data readily available. 
Including 3D content in the report reduces the need for multiple images and videos, adding flexibility and the ability
to answer ad-hoc questions. The |FamilyName| Report Component collects and organizes all data in one place, and 
creates reports in MS Word, MS PowerPoint and HTML from the same source. It can even produce Word/PowerPoint 
reports on Linux.

.. image:: ../../images/rep_word.png
    :height: 400

The Report component uses the :ref:`Envision VTFx format <vtfx-format-page>` and the Ceetron 3D Plugin to embed the 3D 
model directly into the Word document or the PowerPoint presentation. The Ceetron 3D Plugin for Microsoft Office is our 
plugin to the Microsoft Office suite, which enables interactive 3D models with animation embedded into the PowerPoint 
presentation or Word document. 
For a HTML report, the 3D model is rendered directly into the web browser using 
:ref:`Ceetron Cloud <cloud-integration-page>`. 

The main building block of the Report component is a :class:`Snapshot <cee::rep::Snapshot>`. A snapshot is a capture of 
information from your application at a given setup. A snapshot contains either an image (for instance a snapshot of the 
view), a 3D model with results and feature extractions, a 2D plot/graph or a tabular result listing. Each snapshot also 
has a title, a description and a set of :ref:`field values <field-values-page>`. 
A collection of snapshots are stored in a :class:`Repository <cee::rep::Repository>`. 

A creator produces a report based on a repository and a template file. There are creators for 
:class:`Word <cee::rep::ReportCreatorWord>`, :class:`PowerPoint <cee::rep::ReportCreatorPowerPoint>` and for 
:class:`HTML <cee::rep::ReportCreatorHtml>`. 
The creator checks for tagged objects in the template document/presentation and replaces this with snapshot data found 
in the repository when creating the report document/presentation. 

The simple concept behind the Report component is that templates are created using ordinary Word/PowerPoint/HTML 
documents. Insert dummy data and tag these with a snapshot type and a snapshot index. Create a repository of snapshots 
matching the template. Feed both repository and template file to a creator, and it will produce a report for you with 
all the dummy objects replaced with actual data from your simulation. Easy to create, easy to share. 

*******************
Create the Template
*******************

In the screenshots below, you can see very simple Word and PowerPoint templates with the tagged objects showing. (Please 
note that these tag names are invisible for normal view and usage and is only shown when you open the 'Selection and 
Visibility' pane in PowerPoint or toggle the 'Design Mode' button in Word.)
All tags can be set using native Word/PowerPoint, but to simplify the template creation, Envision provides a Report Addin 
for Microsoft Office.

Read more about creating your own templates and the Report Addin in the topic: :ref:`addin-page`

The naming scheme for tags are the same for all report types. See more information on this in the topic: :ref:`tags-page`.

*********************
Create the Repository
*********************

A repository consists of one or more snapshots. Each snapshot contains a title, a description, field values and a media 
object (image, VTFx model or tabular data).

Read more about snapshot types at: :ref:`snapshot-page`

First, create the Repository object:

.. code-block:: cpp

    cee::PtrRef<cee::rep::Repository> repository = new cee::rep::Repository();


Example on creating and adding an image snapshot:

.. code-block:: cpp

    cee::PtrRef<cee::Image> image = new cee::Image();
    m_viewer->view()->renderToImage(image.get());

    cee::PtrRef<cee::rep::Snapshot> snapshot = new cee::rep::Snapshot(cee::rep::Snapshot::OBJECT_IMAGE);
    snapshot->setImage(image.get());
    snapshot->setTitle("My Image Title");

    repository->addSnapshot(snapshot.get());

Example on creating and adding a table snapshot:
(In this example, we're getting the name, mapping type and minimum/maximum scalar values from the currently showing 
scalar result.)

.. code-block:: cpp

    const cee::ug::DataSourceDirectory* directory = m_unstructModel->dataSource()->directory();

    int currentResultId = m_unstructModel->modelSpec().fringesResultId();
    const cee::ug::ResultInfo scalarInfo = directory->findScalarResultInfo(currentResultId);

    cee::PtrRef<cee::rep::Table> table = new cee::rep::Table(5, 2);
    // First row
    table->setValue(0, 1, "Values");
    
    // Second row
    table->setValue(1, 0, "Scalar name: ");
    table->setValue(1, 1, scalarInfo.name());
    
    // Third row
    table->setValue(2, 0, "Mapping:");
    switch (scalarInfo.resultMapping())
    {
        case cee::ug::PER_ELEMENT:          table->setValue(2, 1, "Per element"); break;
        case cee::ug::PER_ELEMENT_NODE:     table->setValue(2, 1, "Per element node"); break;
        case cee::ug::PER_ELEMENT_SURFACE:  table->setValue(2, 1, "Per element surface"); break;
        case cee::ug::PER_NODE:             table->setValue(2, 1, "Per element node"); break;
        default:                            table->setValue(2, 1, "Unknown"); break;
    }
    
    // Fourth row
    double minimum, maximum;
    m_unstructModel->scalarRange(currentResultId, &minimum, &maximum);
    table->setValue(3, 0, "Minimum: ");
    table->setValue(3, 1, cee::Str::number(minimum));
    table->setValue(4, 0, "Maximum: ");
    table->setValue(4, 1, cee::Str::number(maximum));

    cee::PtrRef<cee::rep::Snapshot> snapshot = new cee::rep::Snapshot(cee::rep::Snapshot::OBJECT_TABLE);
    snapshot->setTitle("My Table Title");
    snapshot->setTable(table.get());

    repository->addSnapshot(snapshot.get());


Example on creating and add a VTFx snapshot:

.. code-block:: cpp

    cee::exp::ExportVTFx exporter(cee::exp::ExportVTFx::DISPLAY_MODEL_ONLY, m_unstructModel.get());

    // Add properties and resources from model and view
    cee::PtrRef<cee::PropertySetCollection> propColl = new cee::PropertySetCollection;
    cee::PtrRef<cee::ImageResources> resources = new cee::ImageResources;
    cee::exp::PropertyBuilderVTFx propBuilder(propColl.get(), resources.get());
    propBuilder.addFromModel(*m_unstructModel.get());
    propBuilder.addFromView(*m_viewer->view());
    exporter.addProperties(*propColl);
    exporter.addResources(*resources);

    cee::PtrRef<cee::ug::VTFxMemoryFile> memoryFile = new cee::ug::VTFxMemoryFile();
    exporter.saveCase(memoryFile.get());

    cee::PtrRef<cee::rep::Snapshot> snapshot = new cee::rep::Snapshot(cee::rep::Snapshot::OBJECT_VTFX);
    snapshot->setModelVTFx(memoryFile.get());
    snapshot->setTitle("My VTFx Model Title");

    repository->addSnapshot(snapshot.get());


*****************
Create the Report
*****************

The report is created based on a repository of snapshots and a template file (which is an ordinary MSOffice file/HTML 
file containing tags for the Report component to interpret.)

See :ref:`addin-page`

Create a creator and let it produce your report:

.. code-block:: cpp

    cee::rep::ReportCreatorPowerPoint creator(repository.get(), "MyTemplate.pptx");

    if (!creator.generate("MyReport.pptx"))
    {
        // Error
        return;
    }

This figure shows a simple template presentation containing three slides, one with an image, one with a table and one 
with a plugin. 
And below is the resulting report presentation based on the repository created in the examples above:

.. image:: ../../images/rep_gen.png
    :height: 550


********
Examples
********

For more code examples, please check the example applications includes in the distribution under the **Examples** folder. 

**QtReport**

.. |img_report| image:: ../../images/rep_qtreport.png
   :width: 150

+-----------------------+------------------------------------------------------------------------------------+
| |img_report|          | **Location**\ : Examples/Qt/QtReport |br|                                          |
|                       | The QtReport example creates reports using the model in the view and simple |br|   |
|                       | included templates. This example describes creating all three snapshots types |br| |
|                       | (image, VTFx, and table) for Word, PowerPoint and HTML. It also shows how to |br|  |
|                       | use generic snapshot tags and field values.                                        |
+-----------------------+------------------------------------------------------------------------------------+


**WinFormsReport**

.. |img_wf| image:: ../../images/rep_winformsreport.png
   :width: 150

+-----------------------+------------------------------------------------------------------------------------+
| |img_wf|              | **Location**\ : Examples/WinForms/WinFormsReport |br|                              |
|                       | The WinFormsReport example creates reports using the model in the view and |br|    |
|                       | simple included templates. This example describes creating all three |br|          |
|                       | snapshots types (image, VTFx, and table) for Word, PowerPoint and HTML. |br|       |
|                       | It also shows how to use generic snapshot tags and field values. The WinForms |br| |
|                       | example also shows how to integrate your reports directly to Ceetron Cloud.        |
+-----------------------+------------------------------------------------------------------------------------+


**QtRepositoryManager**

.. |img_repman| image:: ../../images/rep_manager_example.png
   :width: 150

+-----------------------+------------------------------------------------------------------------------------+
| |img_repman|          | **Location**\ : Examples/Qt/QtRepositoryManager |br|                               |
|                       | In addition, there's a QtRepositoryManager example which is a simple manager |br|  |
|                       | for a repository file. This allows you to open a repository file and |br|          |
|                       | view the actual snapshot content. (There is an example repository in the |br|      |
|                       | **Examples/ReportTemplates** folder in the distribution.) You can add |br|         |
|                       | individual snapshots and save the new repository. The QtRepositoryManager |br|     |
|                       | example lets you select your own template file (or use one of the predefined |br|  |
|                       | found in the Examples/ReportTemplates folder). |br|                                |
|                       | |br|                                                                               |
|                       | The QtRepositoryManager example also allows you to integrate your reports |br|     |
|                       | directly to Ceetron Cloud.                                                         |
+-----------------------+------------------------------------------------------------------------------------+


*****************
Tutorials
*****************


.. |img_r| image:: ../../images/tut_report.png
   :width: 150
   :target: ../../tutorials/report.html

+-----------------------+------------------------------------------------------------------------------------+
| |img_r|               | :ref:`report-tutorial`     |br|                                                    |
|                       | Shows how to create a Word report where the 3D model from your view is |br|        |
|                       | inserted (and embedded) into the Word document along with some metadata.           |
+-----------------------+------------------------------------------------------------------------------------+


