.. _particle-trace-page:

###############
Particle Traces
###############

To visualize features of a vector field, it is possible to define streamlines; the paths of 
mass less particles through the flow. Streamlines are computed based on specification of single 
points. Animated display of movement along the streamlines is a powerful and direct way to show 
the features of the flow.

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

A particle trace group is defined by an array of seed positions 
(:func:`ParticleTraceGroup::setSeedPoints <cee::ug::ParticleTraceGroup::setSeedPoints>` and a vector result defining the 
vector field (:func:`ParticleTraceGroup::setVectorResultId <cee::ug::ParticleTraceGroup::setVectorResultId>`). 

The particles trace uses 3D primitives such as cylinders, spheres, ribbons, comets or just lines. Set which 
type to use with the :func:`ParticleTraceGroup::setVisualizationStyle <cee::ug::ParticleTraceGroup::setVisualizationStyle>` 
property. A scalar result can be mapped onto these primitives 
(:func:`ParticleTraceGroup::setMapScalarResultId <cee::ug::ParticleTraceGroup::setMapScalarResultId>`).

See the class documentation (:class:`ParticleTraceGroup <cee::ug::ParticleTraceGroup>`) for a full list of display 
attributes.

Particle traces are created and accessed from :class:`UnstructGridModel <cee::ug::UnstructGridModel>`.


.. code-block:: cpp

    cee::ug::ParticleTraceGroup* group = new cee::ug::ParticleTraceGroup();
    ugModel->addParticleTraceGroup(new cee::ug::ParticleTraceGroup());

    std::vector<cee::ug::ResultInfo> results = ugModel->dataSource()->directory()->vectorResultInfos();
    if (results.size() > 0)
    {
        group->setVectorResultId(results[0].id());
    }

    std::vector<cee::Vec3d> seedPoints;
    seedPoints.push_back(cee::Vec3d(100, 100, 10));
    seedPoints.push_back(cee::Vec3d(100, 100, 15));
    seedPoints.push_back(cee::Vec3d(100, 100, 20));
    group->setSeedPoints(seedPoints);

    ugModel->updateVisualization();

The Qt DemoApp and the WinForms DemoApp both contains example code for creating and manage particle traces. The demo 
apps also shows how to set up particle trace animation.
See the **Examples** folder in the distribution.

.. seealso::

    -   :class:`UnstructGridModel <cee::ug::UnstructGridModel>`
    -   :class:`ParticleTraceGroup <cee::ug::ParticleTraceGroup>`
