.. role:: ts-api-decorator

############
CuttingPlane
############

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

.. container:: ts-api-section

   .. js:class:: CuttingPlane

      Specification of a cutting plane (both parameters and attributes) in a ``RemoteModel``.

      Use this object to control the position, settings and visual attributes of a cutting plane. The 
      position of the cutting plane is defined with ``point`` and ``normal``. You can map a 
      scalar result onto the cutting plane with ``mapScalarResultId``, and show vectors sampled in a regular 
      grid with ``mapVectorResultId``. The spacing of this regular grid is defined with ``vectorGridSpacing``.

      You can specify whether to clip the model in the cutting plane's plane with ``clipping``, show the 
      intersected element mesh with ``showElementMesh`` and set its ``opacity``.

      Please note that cutting planes are more that just geometric clipping planes. They intersect the volume
      elements and produce a surface onto which results can be mapped.  
 
      To create a cutting plane, use ``RemoteModel.addCuttingPlane``.

      **Example:** Create two cutting planes:


      .. code-block:: javascript

         var modelDir = myModel.modelDirectory;

         // Find basis for position and map scalar result
         var bb = myModel.getBoundingBox();
         var halfExtent = bb.getExtent().x/2;
         var mapScalarId = -1;
    
         if (modelDir.scalarResultArray.length > 0) {
             mapScalarId = modelDir.scalarResultArray[0].id;
         }

         // Create plane 1
         var plane1 = myModel.addCuttingPlane();
         plane1.point = cee.Vec3.add(bb.getCenter(), new cee.Vec3(0.5*halfExtent, 0, 0));
         plane1.normal = new cee.Vec3(1,0,0);
         plane1.mapScalarResultId = mapScalarId;

         // Create plane 2
         var plane2 = myModel.addCuttingPlane();
         plane2.point = bb.getCenter();
         plane2.point = cee.Vec3.sub(bb.getCenter(), new cee.Vec3(0.5*halfExtent, 0, 0));
         plane2.normal = new cee.Vec3(1,0,0);
         plane2.mapScalarResultId = mapScalarId;
         plane2.showElementMesh = true;

         // 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/CuttingPlane.png





.. container:: api-index-section

   .. rubric:: Accessors

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

   * :js:attr:`~cee.ug.CuttingPlane.clipping`
   * :js:attr:`~cee.ug.CuttingPlane.computeFromVisibleParts`
   * :js:attr:`~cee.ug.CuttingPlane.crinkleCutSurface`
   * :js:attr:`~cee.ug.CuttingPlane.eyeLift`
   * :js:attr:`~cee.ug.CuttingPlane.filterScalarRangeMaximum`
   * :js:attr:`~cee.ug.CuttingPlane.filterScalarRangeMinimum`
   * :js:attr:`~cee.ug.CuttingPlane.filterScalarResultId`
   * :js:attr:`~cee.ug.CuttingPlane.highlight`
   * :js:attr:`~cee.ug.CuttingPlane.id`
   * :js:attr:`~cee.ug.CuttingPlane.isPrecomputed`
   * :js:attr:`~cee.ug.CuttingPlane.lighting`
   * :js:attr:`~cee.ug.CuttingPlane.mapContourLinesResultId`
   * :js:attr:`~cee.ug.CuttingPlane.mapScalarResultId`
   * :js:attr:`~cee.ug.CuttingPlane.mapVectorResultId`
   * :js:attr:`~cee.ug.CuttingPlane.normal`
   * :js:attr:`~cee.ug.CuttingPlane.opacity`
   * :js:attr:`~cee.ug.CuttingPlane.point`
   * :js:attr:`~cee.ug.CuttingPlane.projectVectorsOnPlane`
   * :js:attr:`~cee.ug.CuttingPlane.showElementMesh`
   * :js:attr:`~cee.ug.CuttingPlane.showSurface`
   * :js:attr:`~cee.ug.CuttingPlane.surfaceColor`
   * :js:attr:`~cee.ug.CuttingPlane.useSourcePartColor`
   * :js:attr:`~cee.ug.CuttingPlane.vectorGridSpacing`
   * :js:attr:`~cee.ug.CuttingPlane.visible`



.. container:: api-index-section

   .. rubric:: Methods

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

   * :js:meth:`~cee.ug.CuttingPlane.getAsProperties`
   * :js:meth:`~cee.ug.CuttingPlane.setFromProperties`
   * :js:meth:`~cee.ug.CuttingPlane.setScalarFilteringVisibleRange`





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

Accessors
=========

.. container:: ts-api-section

   .. js:function:: CuttingPlane.clipping()



      Whether the model should be clipped. If true, the model will be clipped at the 
      cutting plane position


      :rtype: boolean

   .. js:function:: CuttingPlane.clipping( clipping)

      :param clipping: None
      :type clipping: boolean


      :rtype: void



.. container:: ts-api-section

   .. js:function:: CuttingPlane.computeFromVisibleParts()



      If set to true, the cutting plane will be computed from only the visible parts. Any part that
      is not visible will not contribute to the cutting plane.


      :rtype: boolean

   .. js:function:: CuttingPlane.computeFromVisibleParts( visiblePartsOnly)

      :param visiblePartsOnly: None
      :type visiblePartsOnly: boolean


      :rtype: void



.. container:: ts-api-section

   .. js:function:: CuttingPlane.crinkleCutSurface()



      Specify if the cutting plane should show a crinkle cut surface.

      If enabled, the cutting plane surface will be the combined surface of all elements intersected
      by the cutting plane. So the cutting plane will show the tesselation of all intersected elements.

      This is useful for inspecting and visualizing the mesh of a volume element model.

      The default is false.


      :rtype: boolean

   .. js:function:: CuttingPlane.crinkleCutSurface( show)

      :param show: None
      :type show: boolean


      :rtype: void



.. container:: ts-api-section

   .. js:function:: CuttingPlane.eyeLift()



      The eye lift mode to use for this cutting plane.

      Eye lift can be used when facing z fighting issues (triangles rendered in the same plane). 
      By applying eye lift to one part, it will be moved slightly towards the eye, resolving the 
      z fighting issues. The current version offers 3 eye lift factors to choose from.


      :rtype: EyeLift

   .. js:function:: CuttingPlane.eyeLift( mode)

      :param mode: None
      :type mode: EyeLift


      :rtype: void



.. container:: ts-api-section

   .. js:function:: CuttingPlane.filterScalarRangeMaximum()



      The maximum range of the scalar result used for filtering visibility of the cutting plane

      To set a filtering range, use the ``setScalarFilteringVisibleRange`` function.


      :rtype: number



.. container:: ts-api-section

   .. js:function:: CuttingPlane.filterScalarRangeMinimum()



      The minimum range of the scalar result used for filtering visibility of the cutting plane

      To set a filtering range, use the ``setScalarFilteringVisibleRange`` function.


      :rtype: number



.. container:: ts-api-section

   .. js:function:: CuttingPlane.filterScalarResultId()



      The id of the scalar result used filter on the cutting plane.
      This id must refer to one of the scalar results in ``ModelDirectory.scalarResultArray``.

      Set to -1 to turn off scalar filtering on the cutting plane.


      :rtype: number



.. container:: ts-api-section

   .. js:function:: CuttingPlane.highlight()



      Whether the cutting plane should be highlighted.


      :rtype: boolean

   .. js:function:: CuttingPlane.highlight( highlight)

      :param highlight: None
      :type highlight: boolean


      :rtype: void



.. container:: ts-api-section

   .. js:function:: CuttingPlane.id()



      The id of the cutting plane. This is assigned by the system when you call ``RemoteModel.addCuttingPlane``
      and is used to identify the cutting plane.


      :rtype: number



.. container:: ts-api-section

   .. js:function:: CuttingPlane.isPrecomputed()



      Is true if the cutting plane is precomputed and cannot be changed


      :rtype: boolean



.. container:: ts-api-section

   .. js:function:: CuttingPlane.lighting()



      Toggle lighting of the cutting plane on/off.


      :rtype: boolean

   .. js:function:: CuttingPlane.lighting( lighting)

      :param lighting: None
      :type lighting: boolean


      :rtype: void



.. todo:: Implement None cee.ug.CuttingPlane.mapContourLinesResultId ('target')

.. container:: ts-api-section

   .. js:function:: CuttingPlane.mapScalarResultId()



      The id of the scalar result to show on the cutting plane.
      This id must refer to one of the scalar results in ``ModelDirectory.scalarResultArray``.
      You can change the settings for the scalar in the ``ScalarSettings`` object. 

      Set to -1 to show no scalars on the cutting plane.


      :rtype: number

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

      :param resultId: None
      :type resultId: number


      :rtype: void



.. container:: ts-api-section

   .. js:function:: CuttingPlane.mapVectorResultId()



      The id of the vector result to show on the cutting plane.
      This id must refer to one of the vector results in ``ModelDirectory.vectorResultArray``.
      The vectors are shown in a regular grid. The spacing of this grid can be set with ``vectorGridSpacing``.
      The settings for the vector arrows can be changed with the ``VectorSettings`` object.

      Set to -1 to show no vectors on the cutting plane.


      :rtype: number

   .. js:function:: CuttingPlane.mapVectorResultId( resultId)

      :param resultId: None
      :type resultId: number


      :rtype: void



.. container:: ts-api-section

   .. js:function:: CuttingPlane.normal()



      The normal of the cutting plane. Defines its orientation.


      :rtype: Vec3Like

   .. js:function:: CuttingPlane.normal( normal)

      :param normal: None
      :type normal: Vec3Like


      :rtype: void



.. container:: ts-api-section

   .. js:function:: CuttingPlane.opacity()



      Opacity of the cutting plane. 0.0 means fully transparent (invisible), 1.0 means fully opaque.


      :rtype: number

   .. js:function:: CuttingPlane.opacity( opacity)

      :param opacity: None
      :type opacity: number


      :rtype: void



.. container:: ts-api-section

   .. js:function:: CuttingPlane.point()



      A point in the plane. Together with the normal property this defines the plane that the cutting plane is in.


      :rtype: Vec3Like

   .. js:function:: CuttingPlane.point( point)

      :param point: None
      :type point: Vec3Like


      :rtype: void



.. container:: ts-api-section

   .. js:function:: CuttingPlane.projectVectorsOnPlane()



      If true, the regular grid vectors are projected onto the cutting plane, making all the vectors
      parallel to the cutting plane surface.

      The default is false.


      :rtype: boolean

   .. js:function:: CuttingPlane.projectVectorsOnPlane( project)

      :param project: None
      :type project: boolean


      :rtype: void



.. container:: ts-api-section

   .. js:function:: CuttingPlane.showElementMesh()



      Whether the intersected element mesh should be rendered. If true, the mesh resulting from the intersection
      of the cutting plane with the element model will be overlaid on the cutting plane.


      :rtype: boolean

   .. js:function:: CuttingPlane.showElementMesh( show)

      :param show: None
      :type show: boolean


      :rtype: void



.. container:: ts-api-section

   .. js:function:: CuttingPlane.showSurface()



      Whether the surface of the cutting plane should be visible.

      The default is true.


      :rtype: boolean

   .. js:function:: CuttingPlane.showSurface( show)

      :param show: None
      :type show: boolean


      :rtype: void



.. container:: ts-api-section

   .. js:function:: CuttingPlane.surfaceColor()



      The color of the cutting plane surface if not showing a result and useSourcePartColor is false


      :rtype: Color3Like

   .. js:function:: CuttingPlane.surfaceColor( clr)

      :param clr: None
      :type clr: Color3Like


      :rtype: void



.. container:: ts-api-section

   .. js:function:: CuttingPlane.useSourcePartColor()



      If set to true, the cutting plane will be colored by the source part, so this plane will end
      up with different colors based on the color of the parts the cutting plane intersects


      :rtype: boolean

   .. js:function:: CuttingPlane.useSourcePartColor( use)

      :param use: None
      :type use: boolean


      :rtype: void



.. container:: ts-api-section

   .. js:function:: CuttingPlane.vectorGridSpacing()



      The spacing of the vectors shown on the cutting plane. The vector arrows are resampled into a regular grid
      before being rendered on the cutting plane. This property defines the spacing between each vector arrow
      on the cutting plane. The value is relative to the current extent of the model.

      The default is 0.02


      :rtype: number

   .. js:function:: CuttingPlane.vectorGridSpacing( spacing)

      :param spacing: None
      :type spacing: number


      :rtype: void



.. container:: ts-api-section

   .. js:function:: CuttingPlane.visible()



      Visibility of the cutting plane. Use this to show or hide a cutting plane in the 3D Viewer.


      :rtype: boolean

   .. js:function:: CuttingPlane.visible( visible)

      :param visible: None
      :type visible: boolean


      :rtype: void



Methods
=======

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

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

.. js:method:: CuttingPlane.getAsProperties()



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


   :rtype: CuttingPlaneProperties

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

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

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

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


   Applies the settings in the given properties object to this cutting plane


   :rtype: void

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

setScalarFilteringVisibleRange
------------------------------

.. js:method:: CuttingPlane.setScalarFilteringVisibleRange( resultId, min, max)

   :param resultId: The id for the result to which this filter should be applied.
   :type resultId: number
   :param min: The minimum scalar value for filtering. Areas with scalar values below this threshold will be set invisible.
   :type min: number
   :param max: The maximum scalar value for filtering. Areas with scalar values above this threshold will be set invisible.
   :type max: number


   Sets the scalar filtering visibility range for cutting plane 

   Specify a filter for a cutting plane by defining a specific result id (resultId) and a scalar 
   range from minimum to maximum.
   The filter allows you to control the visibility of areas on the cutting plane based on scalar values, 
   making areas outside the specified range invisible.

   A common use case for this functionality is to restrict the visibility of a cutting plane to a 
   specific isovolume. By configuring the cutting plane filter with the same result id and scalar range 
   as the isovolume, you can ensure that the cutting plane surface is only visible within the isovolume.

   For a visual representation and example scenarios regarding isovolumes and cutting planes with and 
   without scalar filtering, please refer to the images below.

   .. image:: /images/cuttingplane_nofilter.png

 
   .. image:: /images/cuttingplane_filter.png




   :rtype: void

