.. role:: ts-api-decorator

######
Viewer
######

.. js:module:: cee
   :noindex:

.. container:: ts-api-section

   .. js:class:: Viewer

      The Viewer manages the ``Views`` it contains and handles user interaction (navigation and picking).

      You can add a new view with the ``addView`` function. The Viewer owns and manages the
      View, and you delete the view by using the ``deleteViewAt`` function. 

      A Viewer can have multiple views. A single model can be shared in each view, or multiple different models 
      can be added to specific views. By default, the views are positioned automatically, but you can set the position and size 
      of each view manually using the ``ViewLayoutMode`` accessor. 

      The Viewer handles the interaction with the user, both navigation (pan/rotate/zoom/walk) and
      selection/picking. 

      You can trigger a redraw of the 3D view(s) with the ``requestRedraw`` function. 

      Examples of the different highlight modes (See ``ViewerOptions.highlightMode`` )

      .. image:: ../../images/HighlightMode.png





.. container:: api-index-section

   .. rubric:: Accessors

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

   * :js:attr:`~cee.Viewer.disableContextMenu`
   * :js:attr:`~cee.Viewer.pixelScaleFactor`
   * :js:attr:`~cee.Viewer.viewCount`
   * :js:attr:`~cee.Viewer.viewLayoutMode`



.. container:: api-index-section

   .. rubric:: Methods

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

   * :js:meth:`~cee.Viewer.addView`
   * :js:meth:`~cee.Viewer.deleteAllViews`
   * :js:meth:`~cee.Viewer.deleteViewAt`
   * :js:meth:`~cee.Viewer.enableMouseButtonTracking`
   * :js:meth:`~cee.Viewer.enableNavigationHandling`
   * :js:meth:`~cee.Viewer.flyCameraTo`
   * :js:meth:`~cee.Viewer.getViewArray`
   * :js:meth:`~cee.Viewer.getViewAt`
   * :js:meth:`~cee.Viewer.getViewFromCssCoordinate`
   * :js:meth:`~cee.Viewer.oglWinPosFromClientCoord`
   * :js:meth:`~cee.Viewer.oglWinPosFromCssCoordinate`
   * :js:meth:`~cee.Viewer.rayFromCssCoordinate`
   * :js:meth:`~cee.Viewer.requestRedraw`
   * :js:meth:`~cee.Viewer.resizeViewer`
   * :js:meth:`~cee.Viewer.rubberBandZoom`
   * :js:meth:`~cee.Viewer.setActiveMouseNavigationsChangedHandler`
   * :js:meth:`~cee.Viewer.setCameraAnimation`
   * :js:meth:`~cee.Viewer.setColorLegendClickHandler`
   * :js:meth:`~cee.Viewer.setPickHandler`
   * :js:meth:`~cee.Viewer.setPixelScaleFactor`
   * :js:meth:`~cee.Viewer.setShowDebugWindow`
   * :js:meth:`~cee.Viewer.updatePixelScaleFactor`





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

Accessors
=========

.. container:: ts-api-section

   .. js:function:: Viewer.disableContextMenu()



      Disable the context menu on right click


      :rtype: boolean

   .. js:function:: Viewer.disableContextMenu( disable)

      :param disable: None
      :type disable: boolean


      :rtype: void



.. container:: ts-api-section

   .. js:function:: Viewer.pixelScaleFactor()



      The current pixel scale factor ( > 1 for 'retina'/'high-dpi') screen.


      :rtype: number



.. container:: ts-api-section

   .. js:function:: Viewer.viewCount()



      The number of views in the Viewer


      :rtype: number



.. container:: ts-api-section

   .. js:function:: Viewer.viewLayoutMode()



      The view layout mode for the viewer


      :rtype: ViewLayoutMode

   .. js:function:: Viewer.viewLayoutMode( layoutMode)

      :param layoutMode: None
      :type layoutMode: ViewLayoutMode


      :rtype: void



Methods
=======

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

addView
-------

.. js:method:: Viewer.addView()



   Adds a view to the viewer. 

   This functions creates a view, adds it to the viewer and returns the newly created view.

   You need at least one view in a viewer in order to display a model.


   :rtype: View

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

deleteAllViews
--------------

.. js:method:: Viewer.deleteAllViews()



   Deletes all views from the viewer.


   :rtype: void

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

deleteViewAt
------------

.. js:method:: Viewer.deleteViewAt( viewIndex)

   :param viewIndex: None
   :type viewIndex: number


   Deletes the view at the given index.

   The index must be zero-based and between 0 and viewCount - 1


   :rtype: void

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

enableMouseButtonTracking
-------------------------

.. js:method:: Viewer.enableMouseButtonTracking( enable)

   :param enable: None
   :type enable: boolean




   :deprecated:


   :rtype: void

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

enableNavigationHandling
------------------------

.. js:method:: Viewer.enableNavigationHandling( enable)

   :param enable: None
   :type enable: boolean




   :deprecated:


   :rtype: void

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

flyCameraTo
-----------

.. js:method:: Viewer.flyCameraTo( cameraPos, viewDir, upVec, fieldOfViewYDegOrFrontPlaneFrustumHight, animDuration[, view])

   :param cameraPos: None
   :type cameraPos: Vec3Like
   :param viewDir: None
   :type viewDir: Vec3Like
   :param upVec: None
   :type upVec: Vec3Like
   :param fieldOfViewYDegOrFrontPlaneFrustumHight: None
   :type fieldOfViewYDegOrFrontPlaneFrustumHight: number
   :param animDuration: None
   :type animDuration: number
   :param view: :ts-api-decorator:`optional` None
   :type view: View


   Flies the camera from the current position to the specified new position in the given view.

   If the current projection in the active View camera is perspective, 
   the fieldOfViewYDegOrFrontPlaneFrustumHight parameter is the final field of view in Y direction in degrees
   (as passed to Camera.setProjectionAsPerspective()).

   If the current projection is ortho, the fieldOfViewYDegOrFrontPlaneFrustumHight parameter is the final 
   front plane frustum height (as passed to Camera.setProjectionAsOrtho()).
 
   If view is not specified then the operation is performed on the first view.


   :rtype: void

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

getViewArray
------------

.. js:method:: Viewer.getViewArray()



   Returns a read only array with all views in the viewer


   :rtype: unknown

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

getViewAt
---------

.. js:method:: Viewer.getViewAt( viewIndex)

   :param viewIndex: None
   :type viewIndex: number


   Returns the view at the given index.

   The index must be zero-based and between 0 and viewCount - 1


   :rtype: View

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

getViewFromCssCoordinate
------------------------

.. js:method:: Viewer.getViewFromCssCoordinate( offsetX, offsetY)

   :param offsetX: The x coordinate in css pixel coordinates. This is relative to the top left corner of the Viewer's Canvas element.
   :type offsetX: number
   :param offsetY: The y coordinate in css pixel coordinates. This is relative to the top left corner of the Viewer's Canvas element.
   :type offsetY: number


   Get the view containing the given Canvas/Viewer local CSS coordinate. This coordinate
   is relative to the top left corner of the canvas/viewer element in css pixels.

   The input coordinates can be set from MouseEvent.offsetX/offsetY.

   :returns: The View containing the given coordinate, or null if no view contains the coordinate.


   :rtype: View

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

oglWinPosFromClientCoord
------------------------

.. js:method:: Viewer.oglWinPosFromClientCoord( clientX, clientY)

   :param clientX: The X coordinate of the mouse pointer in local (DOM content) coordinates.
   :type clientX: number
   :param clientY: The Y coordinate of the mouse pointer in local (DOM content) coordinates.
   :type clientY: number


   Convert from client (DOM content) coordinates to WebGL style coordinates

   :returns: The WebGL style <x,y> coordinate for the given client coordinate in the viewer.


   :rtype: Vec2

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

oglWinPosFromCssCoordinate
--------------------------

.. js:method:: Viewer.oglWinPosFromCssCoordinate( cssPixCoordX, cssPixCoordY)

   :param cssPixCoordX: The x coordinate in css pixel coordinates. This is relative to the top left corner of the Viewer's Canvas element.
   :type cssPixCoordX: number
   :param cssPixCoordY: The y coordinate in css pixel coordinates. This is relative to the top left corner of the Viewer's Canvas element.
   :type cssPixCoordY: number


   Convert from canvas local css (DOM content) coordinates to WebGL style coordinates, similar to 
   offsetX/Y in in MouseEvent.

   The cssX/Y coordinates local Canvas coordinates in css (DOM content) coordinates. They are 
   local to the Canvas element, so 0,0 is the top left corner of the Canvas element. 
   The coordinates are in css pixels, so they are  not affected by the device pixel ratio or 
   any zoom in the browser. These coordinates are related to the MouseEvent.offsetX/Y coordinates.

   See https://developer.mozilla.org/en-US/docs/Web/CSS/CSSOM_View/Coordinate_systems for more on 
   CSS coordinate systems. They correspond to the "Offset" system.

   :returns: The WebGL style <x,y> coordinate for the given css coordinate in the viewer.


   :rtype: Vec2

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

rayFromCssCoordinate
--------------------

.. js:method:: Viewer.rayFromCssCoordinate( view, cssPixCoordX, cssPixCoordY)

   :param view: None
   :type view: View
   :param cssPixCoordX: The x coordinate in css pixel coordinates. This is relative to the top left corner of the Viewer's Canvas element.
   :type cssPixCoordX: number
   :param cssPixCoordY: The y coordinate in css pixel coordinates. This is relative to the top left corner of the Viewer's Canvas element.
   :type cssPixCoordY: number


   Get a ray from the given Canvas/Viewer local CSS coordinate. This coordinate
   is relative to the top left corner of the canvas/viewer element in css pixels.

   :returns: A Ray than can be used for rayIntersect() on the various models. Returns null if               a ray could not be created.  The input coordinates can be set from MouseEvent.offsetX/offsetY.


   :rtype: Ray

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

requestRedraw
-------------

.. js:method:: Viewer.requestRedraw()



   Notifies that this viewer needs a redraw. This will schedule a redraw on the next timer event. 

   Use this method to force a redraw if you have changed something that does not update the viewer.
   This is not usually needed.


   :rtype: void

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

resizeViewer
------------

.. js:method:: Viewer.resizeViewer( canvasDisplayWidthCSSPixels, canvasDisplayHeightCSSPixels)

   :param canvasDisplayWidthCSSPixels: None
   :type canvasDisplayWidthCSSPixels: number
   :param canvasDisplayHeightCSSPixels: None
   :type canvasDisplayHeightCSSPixels: number


   Sets the display size of the viewer's canvas in CSS pixels. 

   Note that the input width and height is in CSS pixels which. This means that the resulting size of the 
   canvas in physical pixels may end up being larger than the specified size depending on the currently 
   set pixel scale factor (devicePixelRatio)


   :rtype: void

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

rubberBandZoom
--------------

.. js:method:: Viewer.rubberBandZoom( view, clientX, clientY, width, height)

   :param view: None
   :type view: View
   :param clientX: None
   :type clientX: number
   :param clientY: None
   :type clientY: number
   :param width: None
   :type width: number
   :param height: None
   :type height: number


   Zooms in or out in the view by the given rubber band rectangle.

   clientX and clientY are the Top Left corner of the rectangle, specified in client coordinates 
   (HTML window coordinates) (from e.g. a MouseEvent.clientX/Y)

   NOTE: This is the only method using client coordinates. All other relevant methods use 
   Canvas/Viewer local CSS coordinates. This behavior will change in an upcoming major release.


   :rtype: void

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

setActiveMouseNavigationsChangedHandler
---------------------------------------

.. js:method:: Viewer.setActiveMouseNavigationsChangedHandler( navigationHandler)

   :param navigationHandler: None
   :type navigationHandler: MouseNavigationChangedHandler




   :deprecated:


   :rtype: void

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

setCameraAnimation
------------------

.. js:method:: Viewer.setCameraAnimation( cameraAnimation)

   :param cameraAnimation: None
   :type cameraAnimation: CameraAnimation


   Sets a camera animation that will be run for this viewer


   :rtype: void

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

setColorLegendClickHandler
--------------------------

.. js:method:: Viewer.setColorLegendClickHandler( legendClickHandler)

   :param legendClickHandler: None
   :type legendClickHandler: ColorLegendClickedHandler


   Sets the handler function to be called whenever the user clicks on a color legend.

   The handler function will be passed the id of the scalar result.


   :rtype: void

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

setPickHandler
--------------

.. js:method:: Viewer.setPickHandler( pickHandler)

   :param pickHandler: None
   :type pickHandler: PickHandler




   :deprecated:


   :rtype: void

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

setPixelScaleFactor
-------------------

.. js:method:: Viewer.setPixelScaleFactor( pixelScaleFactor)

   :param pixelScaleFactor: None
   :type pixelScaleFactor: number


   Set pixel scale factor.


   :rtype: void

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

setShowDebugWindow
------------------

.. js:method:: Viewer.setShowDebugWindow( show)

   :param show: None
   :type show: boolean


   Specifies if the debug overlay info window should be shown or not


   :rtype: void

.. todo:: Implement None cee.Viewer.updatePixelScaleFactor (int() argument must be a string, a bytes-like object or a real number, not 'dict')

