.. role:: ts-api-decorator

##############
VectorSettings
##############

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

.. container:: ts-api-section

   .. js:class:: VectorSettings

      Specification of how to render vector arrows for the given result on the model, on cutting planes
      and on isosurfaces.

      Use this object to control the visual appearance of vector arrows in the 3D viewer. With ``colorMode`` you can specify whether 
      vectors should use a ``singleVectorColor``, the color mapping from the object's scalar fringes, or the color mapping from a 
      provided scalar result ID. You can also setup relative or absolute scaling with ``scaleMode`` and perform filtering and clamping 
      of the vector magnitudes (lengths), with ``setFilteringRange`` and ``setClampingRange`` respectively.



.. container:: api-index-section

   .. rubric:: Accessors

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

   * :js:attr:`~cee.ug.VectorSettings.anisotropicScaleFactor`
   * :js:attr:`~cee.ug.VectorSettings.arrowHeadRelativeLength`
   * :js:attr:`~cee.ug.VectorSettings.arrowHeadRelativeRadius`
   * :js:attr:`~cee.ug.VectorSettings.arrowShaftRelativeRadius`
   * :js:attr:`~cee.ug.VectorSettings.clampingRangeMaximum`
   * :js:attr:`~cee.ug.VectorSettings.clampingRangeMinimum`
   * :js:attr:`~cee.ug.VectorSettings.colorMode`
   * :js:attr:`~cee.ug.VectorSettings.drawMaxCount`
   * :js:attr:`~cee.ug.VectorSettings.drawMode`
   * :js:attr:`~cee.ug.VectorSettings.drawSkipBy`
   * :js:attr:`~cee.ug.VectorSettings.dynamicSymmetricArrowsScalarId`
   * :js:attr:`~cee.ug.VectorSettings.filteringRangeMaximum`
   * :js:attr:`~cee.ug.VectorSettings.filteringRangeMinimum`
   * :js:attr:`~cee.ug.VectorSettings.isClampingEnabled`
   * :js:attr:`~cee.ug.VectorSettings.isFilteringEnabled`
   * :js:attr:`~cee.ug.VectorSettings.mapScalarResultId`
   * :js:attr:`~cee.ug.VectorSettings.nodeAveragedValues`
   * :js:attr:`~cee.ug.VectorSettings.projectVectorsOnSurface`
   * :js:attr:`~cee.ug.VectorSettings.resultId`
   * :js:attr:`~cee.ug.VectorSettings.scaleFactor`
   * :js:attr:`~cee.ug.VectorSettings.scaleMode`
   * :js:attr:`~cee.ug.VectorSettings.singleVectorColor`
   * :js:attr:`~cee.ug.VectorSettings.vectorType`



.. container:: api-index-section

   .. rubric:: Methods

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

   * :js:meth:`~cee.ug.VectorSettings.disableClamping`
   * :js:meth:`~cee.ug.VectorSettings.disableFiltering`
   * :js:meth:`~cee.ug.VectorSettings.getAsProperties`
   * :js:meth:`~cee.ug.VectorSettings.setClampingRange`
   * :js:meth:`~cee.ug.VectorSettings.setFilteringRange`
   * :js:meth:`~cee.ug.VectorSettings.setFromProperties`
   * :js:meth:`~cee.ug.VectorSettings.setVectorTypeArrow`
   * :js:meth:`~cee.ug.VectorSettings.setVectorTypeDynamicSymmetricArrow`
   * :js:meth:`~cee.ug.VectorSettings.setVectorTypeReverseSymmetricArrow`
   * :js:meth:`~cee.ug.VectorSettings.setVectorTypeSymmetricArrow`





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

Accessors
=========

.. container:: ts-api-section

   .. js:function:: VectorSettings.anisotropicScaleFactor()



      The anisotropic scaling factor to use for the vector arrows. The provided value will scale each vector 
      result component by the respective scaling factor. This factor is interpreted as either absolute or relative based on
      ``scaleMode``. Returns null if ``scaleFactor`` is set and in use (default).


      :rtype: Vec3Like

   .. js:function:: VectorSettings.anisotropicScaleFactor( anisotropicScaleFactor)

      :param anisotropicScaleFactor: None
      :type anisotropicScaleFactor: Vec3Like


      :rtype: void



.. container:: ts-api-section

   .. js:function:: VectorSettings.arrowHeadRelativeLength()



      The length of the vector arrow head relative to the vector length.


      :rtype: number

   .. js:function:: VectorSettings.arrowHeadRelativeLength( headRelativeLength)

      :param headRelativeLength: None
      :type headRelativeLength: number


      :rtype: void



.. container:: ts-api-section

   .. js:function:: VectorSettings.arrowHeadRelativeRadius()



      The radius of the vector arrow head relative to the vector length.


      :rtype: number

   .. js:function:: VectorSettings.arrowHeadRelativeRadius( headRelativeRadius)

      :param headRelativeRadius: None
      :type headRelativeRadius: number


      :rtype: void



.. container:: ts-api-section

   .. js:function:: VectorSettings.arrowShaftRelativeRadius()



      The radius of the vector arrow shaft relative to the vector length.


      :rtype: number

   .. js:function:: VectorSettings.arrowShaftRelativeRadius( shaftRelativeRadius)

      :param shaftRelativeRadius: None
      :type shaftRelativeRadius: number


      :rtype: void



.. container:: ts-api-section

   .. js:function:: VectorSettings.clampingRangeMaximum()



      The maximum length the vectors will have if clamping is enabled. This will be undefined if clamping is disabled.


      :rtype: number



.. container:: ts-api-section

   .. js:function:: VectorSettings.clampingRangeMinimum()



      The minimum length the vectors will have if clamping is enabled. This will be undefined if clamping is disabled.


      :rtype: number



.. container:: ts-api-section

   .. js:function:: VectorSettings.colorMode()



      The coloring mode of the vector arrows. This can be either single color, as specified by ``singleVectorColor``,
      color by fringes, where the color is taken from the scalar result in the object on which the vector arrows are mapped,
      or color by a given result ID, where the color is taken from the scalar results referenced by ``mapScalarResultId``.


      :rtype: VectorColorMode

   .. js:function:: VectorSettings.colorMode( colorMode)

      :param colorMode: None
      :type colorMode: VectorColorMode


      :rtype: void



.. container:: ts-api-section

   .. js:function:: VectorSettings.drawMaxCount()



      If there are more vectors than specified with setDrawMaximumCount(), every n'th vector arrow will 
      be skipped to reduce the number of arrows to within maximum count.

      When set to 0, all vectors will be drawn

      Note! If drawSkipBy is set to value other than 0, this skip by value will be used and 
      maximum count ignored!


      :rtype: number

   .. js:function:: VectorSettings.drawMaxCount( skipBy)

      :param skipBy: None
      :type skipBy: number


      :rtype: void



.. container:: ts-api-section

   .. js:function:: VectorSettings.drawMode()



      The rendering mode for the vector result. 

      Vectors can either be drawn as 3D arrows (default) or a simplified version


      :rtype: VectorDrawMode

   .. js:function:: VectorSettings.drawMode( drawMode)

      :param drawMode: None
      :type drawMode: VectorDrawMode


      :rtype: void



.. container:: ts-api-section

   .. js:function:: VectorSettings.drawSkipBy()



      Get number of vectors to skip between each vector that is drawn. Default 0.

      If set > 0, will draw every n'th vector. No guarantee of an even distribution.


      :rtype: number

   .. js:function:: VectorSettings.drawSkipBy( skipBy)

      :param skipBy: None
      :type skipBy: number


      :rtype: void



.. container:: ts-api-section

   .. js:function:: VectorSettings.dynamicSymmetricArrowsScalarId()



      The id of the scalar result used to determine directions of dynamic symmetric arrows. Use
      ``setVectorTypeDynamicSymmetricArrow`` to set this value.


      :rtype: number



.. container:: ts-api-section

   .. js:function:: VectorSettings.filteringRangeMaximum()



      The maximum length the vectors need to have to be visible when filtering is enabled. This will be undefined if filtering is disabled.


      :rtype: number



.. container:: ts-api-section

   .. js:function:: VectorSettings.filteringRangeMinimum()



      The minimum length the vectors need to have to be visible when filtering is enabled. This will be undefined if filtering is disabled.


      :rtype: number



.. container:: ts-api-section

   .. js:function:: VectorSettings.isClampingEnabled()



      Whether clamping of this vector result is enabled.


      :rtype: boolean



.. container:: ts-api-section

   .. js:function:: VectorSettings.isFilteringEnabled()



      Whether filtering of this vector result is enabled.


      :rtype: boolean



.. container:: ts-api-section

   .. js:function:: VectorSettings.mapScalarResultId()



      The scalar results ID to reference for coloring vectors if ``colorMode`` is COLOR_BY_MAP_SCALAR.


      :rtype: number

   .. js:function:: VectorSettings.mapScalarResultId( scalarResultId)

      :param scalarResultId: None
      :type scalarResultId: number


      :rtype: void



.. container:: ts-api-section

   .. js:function:: VectorSettings.nodeAveragedValues()



      Specify if the vector result should be shown as a node averaged result or not. 

      If false (default) the result is shown as is computed. If true, a node averaged result will be shown
      that is derived from the original result.


      :rtype: boolean

   .. js:function:: VectorSettings.nodeAveragedValues( useNodeAveraging)

      :param useNodeAveraging: None
      :type useNodeAveraging: boolean


      :rtype: void



.. container:: ts-api-section

   .. js:function:: VectorSettings.projectVectorsOnSurface()



      Set if the vectors should be projected onto the model surface or not (default is false)

      If set to true, all vectors are projected onto the surface using the surface normal in that point
      to define the plane to project onto.

      This works in the similar way to the CuttingPlane::setProjectVectorsOnPlane() method.

      NOTE: It is only in effect when having PER_NODE and PER_ELEMENT_NODE vector results


      :rtype: boolean

   .. js:function:: VectorSettings.projectVectorsOnSurface( project)

      :param project: None
      :type project: boolean


      :rtype: void



.. container:: ts-api-section

   .. js:function:: VectorSettings.resultId()



      The id (>=0) of the vector result. This id corresponds to the id in ``ModelDirectory.vectorResultArray``.


      :rtype: number



.. container:: ts-api-section

   .. js:function:: VectorSettings.scaleFactor()



      The scaling factor to use for the vector arrows. This factor is interpreted as either absolute or relative based on
      ``scaleMode``. Returns undefined if ``anisotropicScaleFactor`` is set and in use.


      :rtype: number

   .. js:function:: VectorSettings.scaleFactor( scaleFactor)

      :param scaleFactor: None
      :type scaleFactor: number


      :rtype: void



.. container:: ts-api-section

   .. js:function:: VectorSettings.scaleMode()



      The scaling mode to use for the vector arrows (absolute or relative).


      :rtype: VectorScaleMode

   .. js:function:: VectorSettings.scaleMode( scaleMode)

      :param scaleMode: None
      :type scaleMode: VectorScaleMode


      :rtype: void



.. container:: ts-api-section

   .. js:function:: VectorSettings.singleVectorColor()



      The color to use for the vectors if ``colorMode`` is SINGLE.


      :rtype: Color3Like

   .. js:function:: VectorSettings.singleVectorColor( singleColor)

      :param singleColor: None
      :type singleColor: Color3Like


      :rtype: void



.. container:: ts-api-section

   .. js:function:: VectorSettings.vectorType()



      The visualization type for the vector result. Use the methods ``setVectorTypeArrow``, ``setVectorTypeSymmetricArrow``
      etc to set this property.


      :rtype: VectorType



Methods
=======

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

disableClamping
---------------

.. js:method:: VectorSettings.disableClamping()



   Disables any clamping of the vectors. They will be rendered with the length specified by the vector result and scaling.


   :rtype: void

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

disableFiltering
----------------

.. js:method:: VectorSettings.disableFiltering()



   Disables any filtering of the vectors. They will be rendered with the length specified by the vector result and scaling.


   :rtype: void

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

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

.. js:method:: VectorSettings.getAsProperties()



   Gets the settings for this object as a Plain Old JavaScript Object (POJO).


   :rtype: VectorSettingsProperties

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

setClampingRange
----------------

.. js:method:: VectorSettings.setClampingRange( clampMinLength, clampMaxLength)

   :param clampMinLength: None
   :type clampMinLength: number
   :param clampMaxLength: None
   :type clampMaxLength: number


   Specifies to clamp all vectors between the given min and max length.

   When enabled, all vectors will be clamped into the given <clampMinLength, clampMaxLength> range. So if clampMinLength = clampMaxLength, all
   vectors will be drawn with the same length, regardless of the magnitude of the vector.

   Note: The clamping is done before any scaling.


   :rtype: void

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

setFilteringRange
-----------------

.. js:method:: VectorSettings.setFilteringRange( minLength, maxLength)

   :param minLength: None
   :type minLength: number
   :param maxLength: None
   :type maxLength: number


   Specifies to show only the vectors whose length lies within the given range.

   When enabled, only vectors whose length is within the given filter range <filterMinLength, filterMaxLength> will be drawn. 
   All other vectors will be discarded and not drawn.

   Note: The filtering is done before any scaling.


   :rtype: void

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

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

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

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


   Applies the settings in the given properties object to this vector settings


   :rtype: void

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

setVectorTypeArrow
------------------

.. js:method:: VectorSettings.setVectorTypeArrow()



   Set the visualization type to ARROW - normal arrows.


   :rtype: void

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

setVectorTypeDynamicSymmetricArrow
----------------------------------

.. js:method:: VectorSettings.setVectorTypeDynamicSymmetricArrow( scalarId)

   :param scalarId: The id of the scalar to use to determine arrow directions.
   :type scalarId: number


   Set the visualization type to DYNAMIC_SYMMETRIC_ARROW - arrows centered on the node/vertex, with arrow head directions
   determined by the sign of the scalar value at that point.

   Note that for mapped vectors on cutting planes, isosurfaces and isovolumes, if dynamicSymmetricArrows scalar does not
   match the scalar mapped to the cutting plane/isosurface/isovolume, then the vectors will not be displayed.


   :rtype: void

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

setVectorTypeReverseSymmetricArrow
----------------------------------

.. js:method:: VectorSettings.setVectorTypeReverseSymmetricArrow()



   Set the visualization type to REVERSE_SYMMETRIC_ARROW - arrows centered on the node/vertex, with arrow heads
   pointing inward in both directions


   :rtype: void

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

setVectorTypeSymmetricArrow
---------------------------

.. js:method:: VectorSettings.setVectorTypeSymmetricArrow()



   Set the visualization type to SYMMETRIC_ARROW - arrows centered on the node/vertex, with arrow heads pointing
   outwards in both directions


   :rtype: void

