.. role:: ts-api-decorator

#######
Overlay
#######

.. js:module:: cee
   :noindex:

.. container:: ts-api-section

   .. js:class:: Overlay

      Manages 2d overlay items in a View.

      Overlay items are 2d items drawn in the view together with the 3d model, for example color legends,
      navigation cube, step text and info box.

      You can access the overlay object with the ``View.overlay`` property.



.. container:: api-index-section

   .. rubric:: Accessors

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

   * :js:attr:`~cee.Overlay.autoAppendModelInfoToInfoBox`
   * :js:attr:`~cee.Overlay.infoBoxPosition`
   * :js:attr:`~cee.Overlay.infoBoxVisible`
   * :js:attr:`~cee.Overlay.legendsPosition`
   * :js:attr:`~cee.Overlay.maximumLegendHeight`
   * :js:attr:`~cee.Overlay.modelColorLegendsVisible`
   * :js:attr:`~cee.Overlay.navigationCubeHomeDirection`
   * :js:attr:`~cee.Overlay.navigationCubeHomeEye`
   * :js:attr:`~cee.Overlay.navigationCubeHomeUp`
   * :js:attr:`~cee.Overlay.navigationCubePosition`
   * :js:attr:`~cee.Overlay.navigationCubeVisible`
   * :js:attr:`~cee.Overlay.stepTextVisible`



.. container:: api-index-section

   .. rubric:: Methods

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

   * :js:meth:`~cee.Overlay.addCustomCategoryLegend`
   * :js:meth:`~cee.Overlay.addCustomColorLegend`
   * :js:meth:`~cee.Overlay.addCustomColorLegendForScalarMapper`
   * :js:meth:`~cee.Overlay.configureNavigationCube`
   * :js:meth:`~cee.Overlay.removeAllCustomLegends`
   * :js:meth:`~cee.Overlay.setInfoBoxAppearance`
   * :js:meth:`~cee.Overlay.setInfoBoxContent`
   * :js:meth:`~cee.Overlay.setStepTextContent`
   * :js:meth:`~cee.Overlay.viewConfigurationFromNavigationCubeItem`





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

Accessors
=========

.. container:: ts-api-section

   .. js:function:: Overlay.autoAppendModelInfoToInfoBox()



      Whether information from the models should be appended to the info box


      :rtype: boolean

   .. js:function:: Overlay.autoAppendModelInfoToInfoBox( enable)

      :param enable: None
      :type enable: boolean


      :rtype: void



.. container:: ts-api-section

   .. js:function:: Overlay.infoBoxPosition()



      The position of the info box.


      :rtype: OverlayItemPosition

   .. js:function:: Overlay.infoBoxPosition( position)

      :param position: None
      :type position: OverlayItemPosition


      :rtype: void



.. container:: ts-api-section

   .. js:function:: Overlay.infoBoxVisible()



      The visibility of the info box (the blue box in the bottom right corner) in the view


      :rtype: boolean

   .. js:function:: Overlay.infoBoxVisible( show)

      :param show: None
      :type show: boolean


      :rtype: void



.. container:: ts-api-section

   .. js:function:: Overlay.legendsPosition()



      The position of the legends.


      :rtype: OverlayItemPosition

   .. js:function:: Overlay.legendsPosition( position)

      :param position: None
      :type position: OverlayItemPosition


      :rtype: void



.. container:: ts-api-section

   .. js:function:: Overlay.maximumLegendHeight()



      The maximum height of the legends (color legends and category legends).

      Legends are sized to fit the view, depending on the view height and the number of legends.
      This property controls the maximum height a legend can have.

      The value of this property is in device pixels, so it's multiplied by the display's pixelScaleFactor to give
      the native (full resolution) pixel height.


      :rtype: number

   .. js:function:: Overlay.maximumLegendHeight( height)

      :param height: None
      :type height: number


      :rtype: void



.. container:: ts-api-section

   .. js:function:: Overlay.modelColorLegendsVisible()



      The visibility of the color legend overlay items for models (currently only for RemoteModel).


      :rtype: boolean

   .. js:function:: Overlay.modelColorLegendsVisible( show)

      :param show: None
      :type show: boolean


      :rtype: void



.. container:: ts-api-section

   .. js:function:: Overlay.navigationCubeHomeDirection()



      The view direction to set when the "Home" button on the navigation cube is pressed


      :rtype: Vec3

   .. js:function:: Overlay.navigationCubeHomeDirection( direction)

      :param direction: None
      :type direction: Vec3


      :rtype: void



.. container:: ts-api-section

   .. js:function:: Overlay.navigationCubeHomeEye()



      The view eye position to set when the "Home" button on the navigation cube is pressed
      If undefined then eye position is set automatically to fit view


      :rtype: Vec3

   .. js:function:: Overlay.navigationCubeHomeEye( eye)

      :param eye: None
      :type eye: Vec3


      :rtype: void



.. container:: ts-api-section

   .. js:function:: Overlay.navigationCubeHomeUp()



      The up direction to set when the "Home" button on the navigation cube is pressed


      :rtype: Vec3

   .. js:function:: Overlay.navigationCubeHomeUp( up)

      :param up: None
      :type up: Vec3


      :rtype: void



.. container:: ts-api-section

   .. js:function:: Overlay.navigationCubePosition()



      The position of the navigation cube.


      :rtype: OverlayItemPosition

   .. js:function:: Overlay.navigationCubePosition( position)

      :param position: None
      :type position: OverlayItemPosition


      :rtype: void



.. container:: ts-api-section

   .. js:function:: Overlay.navigationCubeVisible()



      The visibility of the navigation cube in the view


      :rtype: boolean

   .. js:function:: Overlay.navigationCubeVisible( show)

      :param show: None
      :type show: boolean


      :rtype: void



.. container:: ts-api-section

   .. js:function:: Overlay.stepTextVisible()



      The visibility of the step text (the text at the bottom of the view displaying the current step for RemoteModels)


      :rtype: boolean

   .. js:function:: Overlay.stepTextVisible( show)

      :param show: None
      :type show: boolean


      :rtype: void



Methods
=======

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

addCustomCategoryLegend
-----------------------

.. js:method:: Overlay.addCustomCategoryLegend( categories, colors, legendTitle, resultId)

   :param categories: None
   :type categories: [string]
   :param colors: None
   :type colors: ArrayLike <Color3Like>
   :param legendTitle: None
   :type legendTitle: string
   :param resultId: None
   :type resultId: number


   Adds a category legend to the view.

   The category legend shows each color with its corresponding descriptive text.

   Note that the categories and colors arrays must have the same length.

   Legends can be removed with the ``removeAllCustomLegends`` method.


   :rtype: void

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

addCustomColorLegend
--------------------

.. js:method:: Overlay.addCustomColorLegend( legend)

   :param legend: None
   :type legend: OverlayColorLegendContinuousDomain


   Adds a color legend displaying the settings of the given scalar mapper.

   Legends can be removed with the ``removeAllCustomLegends`` method.


   :rtype: void

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

addCustomColorLegendForScalarMapper
-----------------------------------

.. js:method:: Overlay.addCustomColorLegendForScalarMapper( scalarMapper, legendTitle, resultId)

   :param scalarMapper: None
   :type scalarMapper: ScalarMapperContinuousDomain
   :param legendTitle: None
   :type legendTitle: string
   :param resultId: None
   :type resultId: number


   Adds a color legend displaying the settings of the given scalar mapper.

   Legends can be removed with the ``removeAllCustomLegends`` method.

   The resultId parameter is an optional user defined id identifying the scalar mapper. This id will be passed to the
   legend picked handler when the user clicks on the color legend. See ``Viewer.setColorLegendClickHandler`` and
   ``ColorLegendClickedHandler`` for more information.


   :rtype: void

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

configureNavigationCube
-----------------------

.. js:method:: Overlay.configureNavigationCube( faceNames[, faceColors[, axisLabels]])

   :param faceNames: None
   :type faceNames: [string]
   :param faceColors: :ts-api-decorator:`optional` None
   :type faceColors: [Color3Like]
   :param axisLabels: :ts-api-decorator:`optional` None
   :type axisLabels: [string]


   Configure the navigation cube

   - faceNames: Must contain 6 values, names for: Pos_X, Neg_X, Pos_Y, Neg_Y, Pos_Z, Neg_Z
   - faceColors: null or 6 values, colors for: Pos_X, Neg_X, Pos_Y, Neg_Y, Pos_Z, Neg_Z
   axisLabels: null (defaults to x,y,z) or 3 values, names for X_AXIS, Y_AXIS, Z_AXIS


   :rtype: void

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

removeAllCustomLegends
----------------------

.. js:method:: Overlay.removeAllCustomLegends()



   Removes all custom legends from the view.

   This method will remove all legends added with the ``addCustomColorLegendForScalarMapper`` and 
   ``addCustomCategoryLegend`` methods.


   :rtype: void

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

setInfoBoxAppearance
--------------------

.. js:method:: Overlay.setInfoBoxAppearance([ backgroundColor[, textColor[, borderColor]]])

   :param backgroundColor: :ts-api-decorator:`optional` None
   :type backgroundColor: Color4Like
   :param textColor: :ts-api-decorator:`optional` None
   :type textColor: Color3Like
   :param borderColor: :ts-api-decorator:`optional` None
   :type borderColor: Color3Like


   Sets the appearance of the info box.


   :rtype: void

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

setInfoBoxContent
-----------------

.. js:method:: Overlay.setInfoBoxContent( content)

   :param content: None
   :type content: string


   Sets the text to show in the info box. 

   Note that any information from the models will be appended to the given string unless ``autoAppendModelInfoToInfoBox`` is set to false.


   :rtype: void

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

setStepTextContent
------------------

.. js:method:: Overlay.setStepTextContent( content)

   :param content: None
   :type content: string


   Sets the text to show in as the step info.

   This will remove any automatic step info from the Remote Model.


   :rtype: void

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

viewConfigurationFromNavigationCubeItem
---------------------------------------

.. js:method:: Overlay.viewConfigurationFromNavigationCubeItem( item)

   :param item: None
   :type item: NavigationCubeItem


   Get the view direction and up vector based on the navigation cube item


   :rtype: NavigationCubeViewConfiguration

