
.. _getting-started-page:

##########
Quickstart
##########

This guide outlines the steps to kickstart your journey with |ProductName|. It begins with instructions on 
installing and configuring your license. Next, you'll learn how to seamlessly integrate the viewer into your preferred 
UI toolkit, creating a basic application. We'll then walk you through importing your data into |ProductName| and 
progressing to implement additional features.

***************************
Installing |FamilyName|
***************************

|ProductName| is packaged as a .zip archive for Windows and a .tar.gz archive for Linux.

After unzipping the compressed files, you will get the following structure in the installation folder:

-   **DotNetLibraries:** Libraries for the .NET version of |FamilyName| (debug and release).
-   **Examples:** Example programs for Qt, wxWidgets, WinForms, WPF, MFC and Win32.
-   **include:** Include files for C++ users.
-   **lib:**  Libs and DLLs for C++ users (debug and release).
-   **PlatformIntegration:** Source code (C++) helper classes for Qt and wxWidgets users.
-   **Tutorials:** Tutorials presented in this documentation with Tutorial Runners for Qt, MFC and wxWidgets.
-   **License:** Dummy license files. Replace with your own.
-   **Python:** Python modules and example scripts.
-   **ThirdParty:** Third party dependencies.
-   **DataProviderFramework:** Framework for writing data providers
-   **ResultCalculatorFramework:** Framework for writing result calculators
-   **DataProviderPlugins:** Ready to use data provider plugins


**************
License System
**************

|ProductName| is a licensed software system. In order to use |ProductName| within your
application you will need a valid license. See :ref:`license-system-page` for more information.

*************************************
How to Integrate into Your UI Toolkit
*************************************

**For C++ Users:**

In order to render with OpenGL and |ProductName| in your application, you will have to provide a Viewer that derives from 
:class:`cee::vis::ViewerUIFramework`. If you are using Qt or wxWidgets, we have provided examples on how to do this. See :ref:`qt-page` and 
:ref:`wxwidgets-page` for more information.

If you are using MFC or native Win32, you can use the built-in Viewers in the :class:`cee::win::WinComponent`.  
See :ref:`mfc-page` and :ref:`win32-page` for more information.

If you are using any other UI toolkit, please see the documentation of :class:`cee::vis::ViewerUIFramework` in order to create your own wrapper. 
If you have any problems with this, do not hesitate to contact :ref:`contact-us-page`.

**For .NET Users:** 

For Windows Forms, you need to use the :class:`cee::win::WinComponent` (CeetronEnvision.Win) and create a user control for the 3D rendering. 
Examples on how to do this are provided in the **WinFormsMinimal** and **WinFormsDemoApp**. See :ref:`winforms-page` for more information.

The Windows Presentation Foundation can also integrate towards this user control. See :ref:`wpf-page` for more information. A couple of minimal apps 
for this support is provided (**WpfMinimal/WpfWindowsFormsHostMinimal**).

**********************************
Getting Data into |FamilyName|
**********************************

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


There are many ways to get your data into |ProductName| depending on the nature of the data and the need for your application.

FEA and CFD Data
================

If you have analysis data (FEA, CFD, etc. with elements and results) you should use the :class:`cee::ug::UnstructGridModel`. Here there are many 
ways of getting your data into |ProductName|.

-   **Use the Import CAE 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`. Please note that this component requires a separate feature in the license 
    key and has additional cost of use.

-   **Create Your Own Data Reader** |br|
    By deriving from :class:`cee::ug::DataReader` and using the :class:`cee::ug::DataSourceReader` you can easily create a 
    data source that supports your own data. You will then leverage the advanced data management and just-in-time 
    loading of your data, so you can just focus on creating the user interface. See the tutorial 
    :ref:`custom-datareader-tutorial` for an example on how to do this.

-   **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 a Data Provider** |br|
    A Data Provider is a plugin for providing CAE data to applications built with Envision SDKs. Use an existing Data 
    Provider to get your data into HOOPS Envision, see :ref:`data-providers-page`. To create a new Data Provider, see 
    the topic :ref:`data-provider-framework-page`.

-   **Create by Hand** |br|
    Finally, you can always build the data model by hand, adding the parts, elements, nodes, results etc. 
    using code. You will then need to make sure that the required data is present before it can be visualized. See the 
    :ref:`two-triangles-tutorial` and :ref:`triangle-with-results-tutorial` tutorials for examples on how to do this.



Geometry Data
=============

.. image:: ../images/getting_started_geo1.png
    :height: 186
    :align: right

If you have geometry based data, you should use the :class:`cee::geo::GeometryModel`. The Geometry model offers a data 
model for geometries containing a large number of parts (grouping of elements, typically with different attributes). 
The Geometry model is specifically designed for efficient handling of complex geometries. Here you will need to populate 
the model with data and effects manually.

We provide several tutorial for creating geometries:

-   :ref:`geometry-tutorial`
-   :ref:`geometry-texture-tutorial`
-   :ref:`geometry-primitives-tutorial`

Finally, please note that you can combine the different models in a view to create a rich visualization. A view can have as 
many models as you like of any type.

**********************************
Sharing Data from |FamilyName|
**********************************

Based the Envision VTFx file format, your simulation data can be easily shared using Ceetron Cloud, the Report component and
our free viewers.

Ceetron Cloud
=============

With Envision it is easy to add cloud export support to your application. With a single click of a button the users 
can share the 3D model they are currently showing in your app with the rest of the world. The model can be shown in any modern web 
browser without installing any software or plug-in. 

See :ref:`cloud-integration-page` 

Envision Viewers
================

The Export component adds easy sharing of simulation results using the Envision VTFx format. With a few lines of code, you can export 
exactly what you have on the screen to a compact file that can be shown on almost any platform. 

See :ref:`vtfx-page`

Report Component
================

With the Report Component, 3D content, images and other simulation data 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. Or just create a hyperlinked image in your report and go to the model in the cloud with one click. 
The HOOPS Envision Report Component collects and organizes all data in one place, and creates reports in MS Word, MS PowerPoint and HTML from the same source.

See :ref:`report-page`

***********************************
Adding Features to Your Application
***********************************

The :ref:`tutorials-page` and :ref:`topics-page` are good places to look for specific information on how to implement a given feature. The Examples entry gives more direct 
access to the code for easy overview and copy/paste. 

A good starting point for FEA type data is the DemoApps provided for Qt and .NET. These are more complete apps that 
showcase one way of using |ProductName|. 

You find these in the **Examples/Qt/QtDemoApp** and **Examples/WinForms/WinFormsDemoApp** folders in the distribution.