.. role:: ts-api-decorator

##################
ParticleTraceGroup
##################

.. js:module:: cee.ug
   :noindex:

.. container:: ts-api-section

   .. js:class:: ParticleTraceGroup

      Specification of a particle trace group (both parameters and attributes) in a ``RemoteModel``.

      To visualize features of a vector field, it is possible to define streamlines: the paths of massless 
      particles through the flow. Streamlines can be computed based on the specification of single points. 
      Animating the movement of particles along these streamlines gives a powerful and direct tool for visualizing
      the features of a flow.

      Particle traces are defined by a vector result specifying the vector field and an array of trace seed points.
      The particles traces use 3D primitives such as cylinders, spheres, or comets to visualize the traces. 
      A scalar result can be mapped as fringes onto these primitives.

      Particle traces can be animated. All particle trace groups must have the same number of animation steps.
      You specify this with ``Animation.particleTraceAnimationStepCount``. You can start the animation with 
      ``Animation.runParticleTraceAnimation``.
 
      To create a particle trace group, use ``RemoteModel.addParticleTraceGroup``.

      **Example:** Show a grid of traces


      .. code-block:: javascript

         var modelDir = myModel.modelDirectory;

         // Create a grid of 10x10 points to use a seed points
         var center = new cee.Vec3(-0.017, -0.00726, 0.0016);
         var seedPoints = cee.ug.ParticleTraceUtils.computeGridPoints(center, 
                          new cee.Vec3(1,0,0), 10, 10, 0.0005);

         // Create the particle trace group
         var ptGroup = myModel.addParticleTraceGroup();
         ptGroup.seedPointArray = seedPoints;       
         ptGroup.vectorResultId = modelDir.vectorResultArray[0].id;
         ptGroup.mapScalarResultId = modelDir.scalarResultArray[0].id;
         ptGroup.radius = 0.00015;

         // Set model to outline to show the cutting planes
         myModel.setDrawStyleAllParts(cee.ug.DrawStyle.OUTLINE);

 
      This code sample produces the following image in the 3D Viewer:

      .. image:: /images/ParticleTraceGroup.png





.. container:: api-index-section

   .. rubric:: Accessors

   .. rst-class:: api-index-list-item api-kind-accessor api-parent-kind-class

   * :js:attr:`~cee.ug.ParticleTraceGroup.color`
   * :js:attr:`~cee.ug.ParticleTraceGroup.extrapolateRatioLength`
   * :js:attr:`~cee.ug.ParticleTraceGroup.id`
   * :js:attr:`~cee.ug.ParticleTraceGroup.ignoreClipping`
   * :js:attr:`~cee.ug.ParticleTraceGroup.isPrecomputed`
   * :js:attr:`~cee.ug.ParticleTraceGroup.mapScalarResultId`
   * :js:attr:`~cee.ug.ParticleTraceGroup.massedParticleParameters`
   * :js:attr:`~cee.ug.ParticleTraceGroup.maximumNumberOfPointsToCompute`
   * :js:attr:`~cee.ug.ParticleTraceGroup.pointSamplingPulseCount`
   * :js:attr:`~cee.ug.ParticleTraceGroup.radius`
   * :js:attr:`~cee.ug.ParticleTraceGroup.relativeCometLength`
   * :js:attr:`~cee.ug.ParticleTraceGroup.seedPointArray`
   * :js:attr:`~cee.ug.ParticleTraceGroup.traceBothDirections`
   * :js:attr:`~cee.ug.ParticleTraceGroup.vectorResultId`
   * :js:attr:`~cee.ug.ParticleTraceGroup.visible`
   * :js:attr:`~cee.ug.ParticleTraceGroup.visualizationStyle`



.. container:: api-index-section

   .. rubric:: Methods

   .. rst-class:: api-index-list-item api-kind-method api-parent-kind-class

   * :js:meth:`~cee.ug.ParticleTraceGroup.getAsProperties`
   * :js:meth:`~cee.ug.ParticleTraceGroup.setFromProperties`





------------

Accessors
=========

.. container:: ts-api-section

   .. js:function:: ParticleTraceGroup.color()



      The color of the particle traces. This property only applies if ``mapScalarResultId`` is set to -1.

      The default is white (1,1,1)


      :rtype: Color3Like

   .. js:function:: ParticleTraceGroup.color( clr)

      :param clr: None
      :type clr: Color3Like


      :rtype: void



.. container:: ts-api-section

   .. js:function:: ParticleTraceGroup.extrapolateRatioLength()



      The ratio length relative to the frame bounding box to test when moving out of the part

      This controls how far to extrapolate the particle trace when leaving a part and entering another part
      The Ratio is given as a fraction of the bounding box of the current frame.


      :rtype: number

   .. js:function:: ParticleTraceGroup.extrapolateRatioLength( ratio)

      :param ratio: None
      :type ratio: number


      :rtype: void



.. container:: ts-api-section

   .. js:function:: ParticleTraceGroup.id()



      The id of the particle trace group. This is assigned by the system when you call ``RemoteModel.addParticleTraceGroup``
      and is used to identify the group.


      :rtype: number



.. container:: ts-api-section

   .. js:function:: ParticleTraceGroup.ignoreClipping()



      Set whether the particle traces in this group should ignore clipping.

      The default is false, which means that the traces will be clipped.


      :rtype: boolean

   .. js:function:: ParticleTraceGroup.ignoreClipping( ignore)

      :param ignore: None
      :type ignore: boolean


      :rtype: void



.. container:: ts-api-section

   .. js:function:: ParticleTraceGroup.isPrecomputed()



      Is true if the particle trace group is precomputed and cannot be changed


      :rtype: boolean



.. container:: ts-api-section

   .. js:function:: ParticleTraceGroup.mapScalarResultId()



      The id of the scalar result to show on the particle traces.

      This id must refer to one of the scalar results in ``ModelDirectory.scalarResultArray``.
      You can change the settings for the scalar with the ``ScalarSettings`` object. 

      Set to -1 to show no scalars on the traces. In this case the value of ``color`` will be applied.


      :rtype: number

   .. js:function:: ParticleTraceGroup.mapScalarResultId( resultId)

      :param resultId: None
      :type resultId: number


      :rtype: void



.. container:: ts-api-section

   .. js:function:: ParticleTraceGroup.massedParticleParameters()



      Massed particle trace parameters. 

      If these paramers are set (not undefined), the particle traces will be computed based on 
      massed particles with the given properties.


      :rtype: MassedParticleParameters

   .. js:function:: ParticleTraceGroup.massedParticleParameters( params)

      :param params: None
      :type params: MassedParticleParameters


      :rtype: void



.. container:: ts-api-section

   .. js:function:: ParticleTraceGroup.maximumNumberOfPointsToCompute()



      Sets the maximum number of points to compute for this group

      This controls the maximum number of increments that will be computed for each trace in this group.


      :rtype: number

   .. js:function:: ParticleTraceGroup.maximumNumberOfPointsToCompute( ratio)

      :param ratio: None
      :type ratio: number


      :rtype: void



.. container:: ts-api-section

   .. js:function:: ParticleTraceGroup.pointSamplingPulseCount()



      Spheres and comets are emitted at regular intervals. This value specifies how many pulses there should be 
      in the model.

      The default is 5.


      :rtype: number

   .. js:function:: ParticleTraceGroup.pointSamplingPulseCount( numPulses)

      :param numPulses: None
      :type numPulses: number


      :rtype: void



.. container:: ts-api-section

   .. js:function:: ParticleTraceGroup.radius()



      The radius of the particle trace geometry (cylinder, sphere, comet), in world coordinates.

      The default is 0.005 of the extent of the bounding box.


      :rtype: number

   .. js:function:: ParticleTraceGroup.radius( radius)

      :param radius: None
      :type radius: number


      :rtype: void



.. container:: ts-api-section

   .. js:function:: ParticleTraceGroup.relativeCometLength()



      The length of the tail of the comets. It is specified in time and is a fraction of the global
      total time range for all particles in this group. 

      For example, if the total trace time is 2, and the relativeCometLength is 0.01, then the length of the tail will be 
      0.02. 

      The default is 0.1


      :rtype: number

   .. js:function:: ParticleTraceGroup.relativeCometLength( relLength)

      :param relLength: None
      :type relLength: number


      :rtype: void



.. container:: ts-api-section

   .. js:function:: ParticleTraceGroup.seedPointArray()



      An array of seed points. Each point will result in a particle trace going through the point. If ``traceBothDirections``
      is set to true, the trace will be computed both forwards and backwards from this point. If it set to false, only the forward
      computation will be done. All traces share the same settings, as defined by other properties of the ``ParticleTraceGroup``.

      You can use the ``ParticleTraceUtils.computeGridPoints`` static function to generate a grid of points based on a point and normal.


      :rtype: unknown

   .. js:function:: ParticleTraceGroup.seedPointArray( pointArr)

      :param pointArr: None
      :type pointArr: unknown


      :rtype: void



.. container:: ts-api-section

   .. js:function:: ParticleTraceGroup.traceBothDirections()



      If set to true, the trace will be computed both forwards and backwards from the seed point(s).

      If set to false, the trace will only be computed forwards from the seed point(s).


      :rtype: boolean

   .. js:function:: ParticleTraceGroup.traceBothDirections( bothDirections)

      :param bothDirections: None
      :type bothDirections: boolean


      :rtype: void



.. container:: ts-api-section

   .. js:function:: ParticleTraceGroup.vectorResultId()



      The vector result to compute the traces in. This property is mandatory and must refer to one of the vector 
      results in ``ModelDirectory.vectorResultArray``.


      :rtype: number

   .. js:function:: ParticleTraceGroup.vectorResultId( resultId)

      :param resultId: None
      :type resultId: number


      :rtype: void



.. container:: ts-api-section

   .. js:function:: ParticleTraceGroup.visible()



      Visibility of the particle trace group. Use this to show or hide a particle trace group in the 3D Viewer.


      :rtype: boolean

   .. js:function:: ParticleTraceGroup.visible( visible)

      :param visible: None
      :type visible: boolean


      :rtype: void



.. container:: ts-api-section

   .. js:function:: ParticleTraceGroup.visualizationStyle()



      The visualization type to use for the particle traces. This can be set to cylinders, spheres or comets.


      :rtype: ParticleTraceVisualizationStyle

   .. js:function:: ParticleTraceGroup.visualizationStyle( style)

      :param style: None
      :type style: ParticleTraceVisualizationStyle


      :rtype: void



Methods
=======

.. rst-class:: ts-api-section

getAsProperties
---------------

.. js:method:: ParticleTraceGroup.getAsProperties()



   Gets the settings for this particle trace group as a Plain Old JavaScript Object (POJO).


   :rtype: ParticleTraceGroupProperties

.. rst-class:: ts-api-section

setFromProperties
-----------------

.. js:method:: ParticleTraceGroup.setFromProperties( props)

   :param props: None
   :type props: Partial <ParticleTraceGroupProperties>


   Applies the settings in the given properties object to this particle trace group


   :rtype: void

