.. role:: ts-api-decorator

######
Camera
######

.. js:module:: cee
   :noindex:

.. container:: ts-api-section

   .. js:class:: Camera

      Camera settings (view point and projection) for a View.

      Use this class to get a View's current eye point, view direction and up vector.

      Setup the camera by providing the eye, view reference point (center) and up vector to ``setFromLookAt``.

      You can also use this class to setup the projection and control the front and back clipping planes. 

      You can access a View's camera with the ``View.camera`` property.



.. container:: api-index-section

   .. rubric:: Accessors

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

   * :js:attr:`~cee.Camera.farPlane`
   * :js:attr:`~cee.Camera.fieldOfViewYDeg`
   * :js:attr:`~cee.Camera.frontPlaneFrustumHeight`
   * :js:attr:`~cee.Camera.nearPlane`
   * :js:attr:`~cee.Camera.projectionType`
   * :js:attr:`~cee.Camera.viewMatrix`
   * :js:attr:`~cee.Camera.viewport`



.. container:: api-index-section

   .. rubric:: Methods

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

   * :js:meth:`~cee.Camera.applyCameraConfig`
   * :js:meth:`~cee.Camera.computeFitViewEyePosition`
   * :js:meth:`~cee.Camera.disableAutoClip`
   * :js:meth:`~cee.Camera.enableAutoClipFixedNearDistance`
   * :js:meth:`~cee.Camera.enableAutoClipMinimumNearDistance`
   * :js:meth:`~cee.Camera.fitView`
   * :js:meth:`~cee.Camera.fitViewOrtho`
   * :js:meth:`~cee.Camera.getDirection`
   * :js:meth:`~cee.Camera.getPosition`
   * :js:meth:`~cee.Camera.getUp`
   * :js:meth:`~cee.Camera.project`
   * :js:meth:`~cee.Camera.resetCamera`
   * :js:meth:`~cee.Camera.setClipPlanesFromBoundingBox`
   * :js:meth:`~cee.Camera.setFromLookAt`
   * :js:meth:`~cee.Camera.setProjectionAsOrtho`
   * :js:meth:`~cee.Camera.setProjectionAsPerspective`
   * :js:meth:`~cee.Camera.setViewChangeHandler`
   * :js:meth:`~cee.Camera.setViewMatrix`
   * :js:meth:`~cee.Camera.setViewpoint`
   * :js:meth:`~cee.Camera.unproject`
   * :js:meth:`~cee.Camera.zoomToBoundingBox`





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

Accessors
=========

.. container:: ts-api-section

   .. js:function:: Camera.farPlane()



      Returns the far clipping plane


      :rtype: number



.. container:: ts-api-section

   .. js:function:: Camera.fieldOfViewYDeg()



      Returns the total field of view in the Y direction in degrees.

      Returns undefined if parallel (orthographic) projection


      :rtype: number



.. container:: ts-api-section

   .. js:function:: Camera.frontPlaneFrustumHeight()



      Get height of the view frustum in the front plane in world coordinates.


      :rtype: number



.. container:: ts-api-section

   .. js:function:: Camera.nearPlane()



      Returns the near clipping plane


      :rtype: number



.. container:: ts-api-section

   .. js:function:: Camera.projectionType()



      Returns the current projection type (perspective/ortho)


      :rtype: ProjectionType



.. container:: ts-api-section

   .. js:function:: Camera.viewMatrix()



      Returns the current view matrix


      :rtype: Mat4



.. container:: ts-api-section

   .. js:function:: Camera.viewport()



      Returns the viewport of the camera


      :rtype: function



Methods
=======

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

applyCameraConfig
-----------------

.. js:method:: Camera.applyCameraConfig( config, allowChangeOfProjectionType)

   :param config: None
   :type config: CameraConfig
   :param allowChangeOfProjectionType: None
   :type allowChangeOfProjectionType: boolean


   Helper that applies a camera config to the camera


   :rtype: void

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

computeFitViewEyePosition
-------------------------

.. js:method:: Camera.computeFitViewEyePosition( boundingBox, dir, up, coverageFactor)

   :param boundingBox: None
   :type boundingBox: BoundingBox
   :param dir: None
   :type dir: Vec3
   :param up: None
   :type up: Vec3
   :param coverageFactor: None
   :type coverageFactor: number


   Calculate the camera position required to fit the given bounding box in the view when the camera is orientated with the
   given direction and up vectors.


   :rtype: Vec3

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

disableAutoClip
---------------

.. js:method:: Camera.disableAutoClip()



   Disables the auto clipping feature


   :rtype: void

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

enableAutoClipFixedNearDistance
-------------------------------

.. js:method:: Camera.enableAutoClipFixedNearDistance( fixedNearDistance)

   :param fixedNearDistance: None
   :type fixedNearDistance: number


   Enables the auto clipping feature and sets a fixed near distance


   :rtype: void

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

enableAutoClipMinimumNearDistance
---------------------------------

.. js:method:: Camera.enableAutoClipMinimumNearDistance( minNearDistance)

   :param minNearDistance: None
   :type minNearDistance: number


   Enables the auto clipping feature and sets a minimum near distance


   :rtype: void

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

fitView
-------

.. js:method:: Camera.fitView( boundingBox, dir, up, coverageFactor)

   :param boundingBox: None
   :type boundingBox: BoundingBox
   :param dir: None
   :type dir: Vec3Like
   :param up: None
   :type up: Vec3Like
   :param coverageFactor: None
   :type coverageFactor: number


   Sets up the view to contain the passed bounding box, with the camera looking from the given
   direction (dir) and with the given up vector (up).

   The passed boundingBox should be the bounding box of the object/model you would like to fit
   the view to.

   The relativeDistance parameter specifies the distance from the camera to the
   center of the bounding box.

   Note: This only works for perspective projection. For orthographic (parallel) projections,
   use the fitViewOrtho method.


   :rtype: void

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

fitViewOrtho
------------

.. js:method:: Camera.fitViewOrtho( boundingBox, eyeDist, dir, up, coverageFactor)

   :param boundingBox: None
   :type boundingBox: BoundingBox
   :param eyeDist: None
   :type eyeDist: number
   :param dir: None
   :type dir: Vec3Like
   :param up: None
   :type up: Vec3Like
   :param coverageFactor: None
   :type coverageFactor: number


   Sets up the view to contain the passed bounding box, with the camera looking from the given 
   direction 'dir', at the give distance 'eyeDist' and with the given up vector 'up'.

   We recommend to set the 'eyeDist' to boundingBox.radius()*2.0

   The passed boundingBox should be the bounding box of the object/model you would like to fit
   the view to. 

   Note: This only works for orthographic (parallel) projection. For perspective projections,
   use the fitView method.


   :rtype: void

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

getDirection
------------

.. js:method:: Camera.getDirection()



   Returns camera's forward direction vector. The returned vector is normalized.


   :rtype: Vec3

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

getPosition
-----------

.. js:method:: Camera.getPosition()



   Returns the camera's position (eye point)


   :rtype: Vec3

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

getUp
-----

.. js:method:: Camera.getUp()



   Returns the camera's up vector. The returned vector is normalized.


   :rtype: Vec3

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

project
-------

.. js:method:: Camera.project( point)

   :param point: None
   :type point: Vec3Like


   Maps world (3d) coordinates to window coordinates

   Returns null if the specified point cannot be projected.

   The returned window coordinates 'out' are in WebGL/OpenGL style coordinates, which means a right handed
   coordinate system with the origin in the lower left corner of the window.

   OpenGL like project.


   :rtype: Vec3

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

resetCamera
-----------

.. js:method:: Camera.resetCamera()



   Resets the camera to its initial state as it appeared upon creation of its containing view


   :rtype: void

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

setClipPlanesFromBoundingBox
----------------------------

.. js:method:: Camera.setClipPlanesFromBoundingBox( boundingBox, minNearPlaneDistance)

   :param boundingBox: None
   :type boundingBox: BoundingBox
   :param minNearPlaneDistance: None
   :type minNearPlaneDistance: number


   Sets the front and back clipping planes close to the given bounding box


   :rtype: void

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

setFromLookAt
-------------

.. js:method:: Camera.setFromLookAt( eye, center, up)

   :param eye: None
   :type eye: Vec3Like
   :param center: None
   :type center: Vec3Like
   :param up: None
   :type up: Vec3Like


   Sets the view matrix from the standard OpenGL 'lookat' (eye, center, vup) specification.

   View direction will be (center - eye). Center is not stored in this class.


   :rtype: void

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

setProjectionAsOrtho
--------------------

.. js:method:: Camera.setProjectionAsOrtho( height, nearPlane, farPlane)

   :param height: None
   :type height: number
   :param nearPlane: None
   :type nearPlane: number
   :param farPlane: None
   :type farPlane: number


   Sets up an orthographic (parallel) projection.

   The height parameter is the height of the frustum. A good default is the length of the extent
   of the current bounding box.


   :rtype: void

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

setProjectionAsPerspective
--------------------------

.. js:method:: Camera.setProjectionAsPerspective( fieldOfViewYDeg, nearPlane, farPlane)

   :param fieldOfViewYDeg: None
   :type fieldOfViewYDeg: number
   :param nearPlane: None
   :type nearPlane: number
   :param farPlane: None
   :type farPlane: number


   Sets up a perspective projection.

   The fieldOfViewYDeg parameter is the total field of view angle (in degrees) in the Y direction.
   Works similar to gluPerspective().


   :rtype: void

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

setViewChangeHandler
--------------------

.. js:method:: Camera.setViewChangeHandler( handler, waitForIdle)

   :param handler: The handler to invoke on change
   :type handler: CameraViewChangeHandler
   :param waitForIdle: If true, the handler will only be invoked after any ongoing mouse operations or camera animations have completed. Note that setting this to false will result in a large number of handler invocations, while setting this to true and then starting a never-ending camera animation will result in no invocations.
   :type waitForIdle: boolean


   Sets a handler to be invoked each time the camera view changes


   :rtype: void

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

setViewMatrix
-------------

.. js:method:: Camera.setViewMatrix( viewMatrix)

   :param viewMatrix: None
   :type viewMatrix: Mat4


   Sets the view matrix of the camera.


   :rtype: void

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

setViewpoint
------------

.. js:method:: Camera.setViewpoint( eye, direction, up)

   :param eye: None
   :type eye: Vec3Like
   :param direction: None
   :type direction: Vec3Like
   :param up: None
   :type up: Vec3Like


   Sets the viewpoint from the eye point position, direction and up vectors.


   :rtype: void

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

unproject
---------

.. js:method:: Camera.unproject( coord)

   :param coord: None
   :type coord: Vec3Like


   Maps window coordinates to world (3d) coordinates

   Returns null if the specified coordinate cannot be unprojected.

   The input (window) coordinates 'coord' must be specified in WebGL/OpenGL style coordinates, which means
   a right handed coordinate system with the origin in the lower left corner of the window.

   OpenGL like unproject.

   Use ``Viewer.oglWinPosFromClientCoord`` to convert client coordinates into WebGL style coordinates


   :rtype: Vec3

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

zoomToBoundingBox
-----------------

.. js:method:: Camera.zoomToBoundingBox( boundingBox)

   :param boundingBox: None
   :type boundingBox: BoundingBox


   Zoom in/out so the given bounding box will fill the view.

   This is done without changing the current camera position. It works for both for PERSPECTIVE and
   ORTHO projection types.

   Note: Works best with ZOOM navigation. Combining zoom (changing FOV) and walk navigation can give
   distorted views.


   :rtype: void

