.. role:: ts-api-decorator

##########
PartLabels
##########

.. js:module:: cee.mrk
   :noindex:

.. container:: ts-api-section

   .. js:class:: PartLabels

      Defines positioned text labels that can be shown in a ``MarkupModel``.

      Use ``MarkupModel.addLabelsPart`` to create a new instance of this class.

      **Some examples of different label styles:**
      .. image:: ../../images/MrkLabels.png





.. container:: api-index-section

   .. rubric:: Accessors

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

   * :js:attr:`~cee.mrk.PartLabels.attachmentAppearance`
   * :js:attr:`~cee.mrk.PartLabels.customData`
   * :js:attr:`~cee.mrk.PartLabels.drawMode`
   * :js:attr:`~cee.mrk.PartLabels.labelAppearance`
   * :js:attr:`~cee.mrk.PartLabels.labelAttachmentPoint`
   * :js:attr:`~cee.mrk.PartLabels.labelCount`



.. container:: api-index-section

   .. rubric:: Methods

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

   * :js:meth:`~cee.mrk.PartLabels.add`
   * :js:meth:`~cee.mrk.PartLabels.addWithOffsetDirection`
   * :js:meth:`~cee.mrk.PartLabels.addWithOffsetDirectionFlipTowardEye`
   * :js:meth:`~cee.mrk.PartLabels.addWithOffsetPosition`
   * :js:meth:`~cee.mrk.PartLabels.deleteAll`
   * :js:meth:`~cee.mrk.PartLabels.deleteLabelAt`
   * :js:meth:`~cee.mrk.PartLabels.getLabelOffsetDirection`
   * :js:meth:`~cee.mrk.PartLabels.getLabelOffsetPosition`
   * :js:meth:`~cee.mrk.PartLabels.getLabelPosition`
   * :js:meth:`~cee.mrk.PartLabels.getLabelText`
   * :js:meth:`~cee.mrk.PartLabels.rayIntersect`
   * :js:meth:`~cee.mrk.PartLabels.setCustomDrawOntoCanvasCallback`
   * :js:meth:`~cee.mrk.PartLabels.setLabelOffsetDirection`
   * :js:meth:`~cee.mrk.PartLabels.setLabelOffsetPosition`
   * :js:meth:`~cee.mrk.PartLabels.setLabelPosition`
   * :js:meth:`~cee.mrk.PartLabels.setLabelText`
   * :js:meth:`~cee.mrk.PartLabels.setOccluderTriMesh`





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

Accessors
=========

.. container:: ts-api-section

   .. js:function:: PartLabels.attachmentAppearance()



      Returns an active reference to the attachment appearance settings for this part.


      :rtype: LabelAttachmentAppearance



.. container:: ts-api-section

   .. js:function:: PartLabels.customData()



      Custom data for the part. This field is not used by EnvisionWeb.


      :rtype: any

   .. js:function:: PartLabels.customData( data)

      :param data: None
      :type data: any


      :rtype: void



.. container:: ts-api-section

   .. js:function:: PartLabels.drawMode()



      Draw mode for the labels in this part


      :rtype: LabelDrawMode

   .. js:function:: PartLabels.drawMode( mode)

      :param mode: None
      :type mode: LabelDrawMode


      :rtype: void



.. container:: ts-api-section

   .. js:function:: PartLabels.labelAppearance()



      Returns an active reference to the appearance settings for the labels in this part.


      :rtype: LabelAppearance



.. container:: ts-api-section

   .. js:function:: PartLabels.labelAttachmentPoint()



      Point where the attachment line meets the label


      :rtype: LabelAttachmentPoint

   .. js:function:: PartLabels.labelAttachmentPoint( attachmentPoint)

      :param attachmentPoint: None
      :type attachmentPoint: LabelAttachmentPoint


      :rtype: void



.. container:: ts-api-section

   .. js:function:: PartLabels.labelCount()



      The number of labels in the part.


      :rtype: number



Methods
=======

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

add
---

.. js:method:: PartLabels.add( text, pos)

   :param text: None
   :type text: string
   :param pos: None
   :type pos: Vec3


   Adds the given text to the part, placing it at the given position. Returns the index of the
   new label.


   :rtype: number

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

addWithOffsetDirection
----------------------

.. js:method:: PartLabels.addWithOffsetDirection( text, pos, offsetDirection)

   :param text: None
   :type text: string
   :param pos: None
   :type pos: Vec3
   :param offsetDirection: None
   :type offsetDirection: Vec3


   Adds text label with offset direction. Returns the index of the new label.


   :rtype: number

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

addWithOffsetDirectionFlipTowardEye
-----------------------------------

.. js:method:: PartLabels.addWithOffsetDirectionFlipTowardEye( text, pos, offsetDirection)

   :param text: None
   :type text: string
   :param pos: None
   :type pos: Vec3
   :param offsetDirection: None
   :type offsetDirection: Vec3


   Adds text with offset direction where the offset direction will be flipped so that it always 
   points towards the viewpoint. Returns the index of the new label.


   :rtype: number

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

addWithOffsetPosition
---------------------

.. js:method:: PartLabels.addWithOffsetPosition( text, pos, offsetPosition)

   :param text: None
   :type text: string
   :param pos: None
   :type pos: Vec3
   :param offsetPosition: None
   :type offsetPosition: Vec3


   Adds text label with offset position. Returns the index of the new label.


   :rtype: number

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

deleteAll
---------

.. js:method:: PartLabels.deleteAll()



   Deletes all text labels from the part.


   :rtype: void

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

deleteLabelAt
-------------

.. js:method:: PartLabels.deleteLabelAt( index)

   :param index: None
   :type index: number


   Deletes the text label at the given index.


   :rtype: void

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

getLabelOffsetDirection
-----------------------

.. js:method:: PartLabels.getLabelOffsetDirection( index)

   :param index: None
   :type index: number


   Gets the offset direction of the label at the given index.


   :rtype: Vec3

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

getLabelOffsetPosition
----------------------

.. js:method:: PartLabels.getLabelOffsetPosition( index)

   :param index: None
   :type index: number


   Gets the offset position of the label at the given index.


   :rtype: Vec3

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

getLabelPosition
----------------

.. js:method:: PartLabels.getLabelPosition( index)

   :param index: None
   :type index: number


   Gets the position of the label at the given index.


   :rtype: Vec3

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

getLabelText
------------

.. js:method:: PartLabels.getLabelText( index)

   :param index: None
   :type index: number


   Gets the text of the label at the given index.


   :rtype: string

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

rayIntersect
------------

.. js:method:: PartLabels.rayIntersect( ray, hitItem)

   :param ray: None
   :type ray: Ray
   :param hitItem: None
   :type hitItem: PartHitItem


   Picking


   :rtype: boolean

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

setCustomDrawOntoCanvasCallback
-------------------------------

.. js:method:: PartLabels.setCustomDrawOntoCanvasCallback( callback)

   :param callback: None
   :type callback: CustomDrawOntoCanvasCallback


   Specify a custom label drawing callback. 

   The callback will be called for each label in the part, and can be used to draw the label in a custom way.

   Note that this callback does not consider the label appearance settings. The callback will only receive 
   the text to draw. If you return false from the callback, the label will be drawn as default.


   :rtype: void

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

setLabelOffsetDirection
-----------------------

.. js:method:: PartLabels.setLabelOffsetDirection( index, offsetDirection, flipTowardsEye)

   :param index: None
   :type index: number
   :param offsetDirection: None
   :type offsetDirection: Vec3
   :param flipTowardsEye: None
   :type flipTowardsEye: boolean


   Sets the offset direction of the label at the given index.


   :rtype: void

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

setLabelOffsetPosition
----------------------

.. js:method:: PartLabels.setLabelOffsetPosition( index, offsetPosition)

   :param index: None
   :type index: number
   :param offsetPosition: None
   :type offsetPosition: Vec3


   Sets the offset position of the label at the given index.

   **Example:** Move a label with the mouse


   .. code-block:: javascript

      private onMouseMove(event: MouseEvent) {
        const label = this.m_pickingLabelPart;

        if (label && event.ctrlKey) {
          const view = this.m_viewer.getViewAt(0);
          const labelPos = label.getLabelPosition(0);

          // Keep label in the same distance from the camera
          const labelDepth = view.camera.project(labelPos).z;
          const oglWinPos = this.m_viewer.oglWinPosFromClientCoord(event.x, event.y);
          const labelOffsetPos = view.camera.unproject(
                    {x: oglWinPos.x, y: oglWinPos.y, z: labelDepth});
    
          label.setLabelOffsetPosition(0, labelOffsetPos);
        }
      }



   :rtype: void

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

setLabelPosition
----------------

.. js:method:: PartLabels.setLabelPosition( index, position)

   :param index: None
   :type index: number
   :param position: None
   :type position: Vec3


   Sets the position of the label at the given index.


   :rtype: void

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

setLabelText
------------

.. js:method:: PartLabels.setLabelText( index, text)

   :param index: None
   :type index: number
   :param text: None
   :type text: string


   Sets the text of the label at the given index.


   :rtype: void

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

setOccluderTriMesh
------------------

.. js:method:: PartLabels.setOccluderTriMesh( labelIndex, vertices, indices[, options])

   :param labelIndex: None
   :type labelIndex: number
   :param vertices: None
   :type vertices: ArrayLike <number>
   :param indices: None
   :type indices: ArrayLike <number>
   :param options: :ts-api-decorator:`optional` None
   :type options: OccluderOptions


   Sets the occluder tri-mesh to use for testing the visibility of the label at the specified index.

   The specified occluder mesh is used to test if the label should be visible or not. If the mesh is
   visible, the label will be visible. If the mesh is occluded, the label will be hidden.


   :rtype: void

