jv.viewer

## Class PvCamera

- java.lang.Object
- - jv.object.PsObject
  - - jv.viewer.PvCamera

- All Implemented Interfaces:
    java.io.Serializable, java.lang.Cloneable, PsUpdateIf, PvCameraIf

      public final class PvCamera
      extends PsObject
      implements PvCameraIf

  Camera provides transformation matrices to project a scene into a given target image of given size.

  A camera may be in one of four different projection types, for example, `PvCameraIf.CAMERA_PERSPECTIVE`. The camera compute the transformation matrices based in the mouse pick and drag positions. The size of the picking device and of the target image may differ.

  If the camera info panel is showing, then it is updated when the camera is changed. On slow machines just disable the camera panel to avoid immediate panel updates.

  See Also:
    `PvDisplay`, Serialized Form
  Author:
    Konrad Polthier
  Version:
    28.03.15, 3.60 revised (kp) Initialization of instance variables moved to init().
    01.05.14, 3.50 revised (kp) Changed SIZE to 1 from 10, and simultaneously Z_STRETCH to 10000 from 1000.
    24.09.05, 3.30 revised (kp) Fill display added which 2D-scales the projected data.
    17.08.03, 3.20 revised (kp) New major mode MODE_VERTICAL allows rotation with constant camera roll.
    14.08.03, 3.10 revised (kp) Avoid internal vector allocations.
    17.03.03, 3.00 revised (kp) Bndbox ratio implemented.
    07.12.02, 2.60 revised (kp) Perspectivity implemented.
    01.02.02, 2.50 revised (kp) Distinguish between size if picking device and target image.
    15.03.01, 2.10 revised (kp) Methods for horizontal clipping added.
    27.03.00, 2.02 revised (ep) implements PvCameraIf.
    21.06.99, 2.01 revised (kp) Clipping activated.
    00.00.98, 2.00 revised (kp) Revised.
    00.00.97, 1.00 created (kp)

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `PdMatrix` | `m_defTrans` Default transformation matrix is the product of projection and viewing matrix.
    `PdMatrix` | `m_defTransInv` Default inverse of the transformation matrix.
    `PdMatrix` | `m_defView` Default viewing matrix transforms the scene into normal coordinates.
    `PdMatrix` | `m_defViewInv` Default inverse of the viewing matrix.
    `PdMatrix` | `m_trans` Transformation matrix is the product of projection and viewing matrix.
    `PdMatrix` | `m_transInv` Inverse of the transformation matrix.
    `PdMatrix` | `m_transNon` Non-perspective part of transformation matrix is the product of projection and viewing matrix.
    `PdMatrix` | `m_transNonInv` Non-perspective part of inverse of the transformation matrix.
    `PdMatrix` | `m_view` Viewing matrix transforms the scene into normal coordinates.
    `PdMatrix` | `m_viewInv` Inverse of the viewing matrix.

    - ### Fields inherited from class jv.object.PsObject

      `HAS_BOUNDARY_PANEL, HAS_CONFIG_PANEL, HAS_INFO_PANEL, HAS_LABEL_PANEL, HAS_MATERIAL_PANEL, HAS_TEXTURE_PANEL, HAS_VECTOR_PANEL, INSPECTOR_INFO, INSPECTOR_INFO_EXT, IS_DELETED, IS_FIXED, IS_FOCUSSED, IS_PICKED, IS_SELECTED, IS_USED, NUM_TAGS`

    - ### Fields inherited from interface jv.project.PvCameraIf

      `CAMERA_MODEL, CAMERA_NAME, CAMERA_ORTHO_XY, CAMERA_ORTHO_XZ, CAMERA_ORTHO_YZ, CAMERA_PERSPECTIVE`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `PvCamera(PvDisplay display, int projMode)` Constructor of camera associates the display and initializes the current projection mode.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `fit(double diameter)` Fit object with given diameter into current display window.
    `PdVector[]` | `getBounds()` Get transformed bounding box used in clipping.
    `double` | `getDist()` Get distance of camera position from point of interest in world coordinates.
    `double` | `getFarClip()` Get distance of the far clipping plane.
    `double` | `getFieldOfView()` Get opening angle of camera.
    `PdVector` | `getInterest()` Get position at which camera is directed, i.e. the point of interest.
    `double` | `getNearClip()` Get distance of the near clipping plane.
    `PdVector` | `getPosition()` Get position of camera in world coordinates.
    `int` | `getProjectionMode()` Get projection mode of the camera, for example, perspective, xy-projection etc.
    `double` | `getRoll()` Get angle which camera is rotated around viewing direction against default position.
    `double` | `getScale()` Get zoom factor of camera.
    `PdMatrix` | `getTransMatrix(int type)` Get transformation matrices PV, P, V and their inverses in current camera and display.
    `PdVector` | `getUpVector()` Get up vector as second row of viewing matrix divided by scaling factor.
    `PdVector` | `getViewDir()` Get normalized viewing direction as the vector pointing from the camera to its interest.
    `void` | `init()` Initializes and resets current camera.
    `boolean` | `isEnabledClip()` Determine whether horizontal clipping is enabled.
    `boolean` | `isEnabledSceneRatio()` Check of aspect ratio of scene bounding box is enabled.
    `void` | `reset()` Reset the current transformation matrices to default values.
    `void` | `saveAsDefault()` Save the current transformation matrices as default.
    `void` | `setBoxRatio(PdVector ratio)` Set the scaling factor for all three camera axis to produce a non-square viewing frustum.
    `void` | `setDist(double newDist)` Set distance of camera position from point of interest in world coordinates.
    `void` | `setEnabledBoxRatio(boolean flag)` Enable usage of a variable aspect ratio for the viewing frustum of this camera.
    `void` | `setEnabledClip(boolean flag)` Enable horizontal clipping.
    `void` | `setEnabledSceneRatio(boolean flag)` Set aspect ratio of scene bounding box.
    `void` | `setFarClip(double dist)` Get distance of far clipping plane.
    `void` | `setFieldOfView(double angle)` Set opening angle of camera.
    `void` | `setFullPosition(PdVector interest, PdVector position, PdVector upDir)` Set full orientation and location of camera in world coordinates.
    `void` | `setInterest(PdVector pos)` Set location at which camera is directed, i.e. the point of interest.
    `void` | `setNearClip(double dist)` Get distance of the near clipping plane.
    `void` | `setPosition(PdVector pos)` Set position of camera in world coordinates.
    `void` | `setProjectionMode(int mode)` Set projection mode of the camera, for example, perspective, xy-projection etc.
    `void` | `setRoll(double roll)` Set angle which camera is rotated around viewing direction against default position.
    `void` | `setScale(double newScale)` Set zoom factor of camera.
    `void` | `setTransMatrix(int type, PdMatrix mat)` Set transformation matrices PV, P, V and their inverses in current camera and display.
    `void` | `setUpVector(PdVector up)` Set normalized up vector of camera in world coordinates.
    `void` | `setViewDir(PdVector dir)` Set viewing direction as the vector pointing from the camera to its interest.
    `boolean` | `update(java.lang.Object event)` event == this : geometry has changed by itself without widget event, therefore somewhere in a superclass the infoPanel must be updated.

    - ### Methods inherited from class jv.object.PsObject

      `addInspector, addUpdateListener, assureInspector, clearTag, clone, clone, clone, copy, getFather, getInfoPanel, getInspector, getName, getNumObjects, getSymbol, hasInspector, hasTag, hasUpdateListener, instanceOf, instanceOf, newInspector, newInspector, removeInspector, removeInspector, removeUpdateListener, setName, setParent, setSymbol, setTag, toString, updatePanels`

    - ### Methods inherited from class java.lang.Object

      `equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`

    - ### Methods inherited from interface jv.project.PvCameraIf

      `setName`

    - ### Methods inherited from interface jv.object.PsUpdateIf

      `getFather, getName, setParent`

- - ### Field Detail

    - #### m_defView

          public PdMatrix m_defView

      Default viewing matrix transforms the scene into normal coordinates.

    - #### m_defViewInv

          public PdMatrix m_defViewInv

      Default inverse of the viewing matrix.

    - #### m_defTrans

          public PdMatrix m_defTrans

      Default transformation matrix is the product of projection and viewing matrix.

    - #### m_defTransInv

          public PdMatrix m_defTransInv

      Default inverse of the transformation matrix.

    - #### m_transNon

          public PdMatrix m_transNon

      Non-perspective part of transformation matrix is the product of projection and viewing matrix.

    - #### m_transNonInv

          public PdMatrix m_transNonInv

      Non-perspective part of inverse of the transformation matrix.

    - #### m_view

          public PdMatrix m_view

      Viewing matrix transforms the scene into normal coordinates.

    - #### m_viewInv

          public PdMatrix m_viewInv

      Inverse of the viewing matrix.

    - #### m_trans

          public PdMatrix m_trans

      Transformation matrix is the product of projection and viewing matrix.

    - #### m_transInv

          public PdMatrix m_transInv

      Inverse of the transformation matrix.

  - ### Constructor Detail

    - #### PvCamera

          public PvCamera(PvDisplay display,
                          int projMode)

      Constructor of camera associates the display and initializes the current projection mode. The available projection modes are listed in PvDisplayIf, for example, `PvCameraIf.CAMERA_PERSPECTIVE`.
      Parameters:
        `display` - associate display
        `projMode` - current projection mode of this camera

  - ### Method Detail

    - #### init

          public void init()

      Initializes and resets current camera.
      Overrides:
        `init` in class `PsObject`

    - #### saveAsDefault

          public void saveAsDefault()

      Save the current transformation matrices as default.
      Specified by:
        `saveAsDefault` in interface `PvCameraIf`
      Since:
        JavaView 2.47
      See Also:
        `reset()`
      Version:
        28.11.02, 1.00 created (kp)

    - #### reset

          public void reset()

      Reset the current transformation matrices to default values.
      Since:
        JavaView 2.47
      See Also:
        `saveAsDefault()`
      Version:
        28.11.02, 1.00 created (kp)

    - #### update

          public boolean update(java.lang.Object event)

      event == this : geometry has changed by itself without widget event, therefore somewhere in a superclass the infoPanel must be updated. call: super.update(event, e.g. this) event == null : geometry has change by widget event which has been handled call: super.update(null) event == else : we must handle the event here or pass it to superclass. If no superclass can handle this event, then error. call: super.update(event)
      Specified by:
        `update` in interface `PsUpdateIf`
      Overrides:
        `update` in class `PsObject`
      Parameters:
        `event` - carries a lot of information
      Returns:
        true if event has been handled, otherwise false
      See Also:
        `PsObject.setParent(PsUpdateIf)`, `PsObject.getFather()`, `PsObject.addUpdateListener(PsUpdateIf)`
      Version:
        01.01.01, 1.10 revised (kp) Adjust clip sliders if other clip slider exceeds range.

    - #### getProjectionMode

          public int getProjectionMode()

      Get projection mode of the camera, for example, perspective, xy-projection etc. For a list of possible type see `PvCameraIf#CAMERA_ORTHO_XY`.
      Specified by:
        `getProjectionMode` in interface `PvCameraIf`
      Returns:
        current projection mode
      See Also:
        `PvDisplayIf`

    - #### setProjectionMode

          public void setProjectionMode(int mode)

      Set projection mode of the camera, for example, perspective, xy-projection etc. For a list of possible type see `PvCameraIf#CAMERA_ORTHO_XY`.
      Specified by:
        `setProjectionMode` in interface `PvCameraIf`
      Parameters:
        `mode` - new projection mode
      See Also:
        `PvDisplayIf`

    - #### isEnabledClip

          public boolean isEnabledClip()

      Determine whether horizontal clipping is enabled.
      Specified by:
        `isEnabledClip` in interface `PvCameraIf`

    - #### setEnabledClip

          public void setEnabledClip(boolean flag)

      Enable horizontal clipping.
      Specified by:
        `setEnabledClip` in interface `PvCameraIf`

    - #### getNearClip

          public double getNearClip()

      Get distance of the near clipping plane. The near and far clipping planes of a camera are orthogonal to the viewing direction at a positive distance. The near clip plane is closer to the camera than the far clip plane, and this order is not allowed to change.
      Specified by:
        `getNearClip` in interface `PvCameraIf`
      Returns:
        positive distance of the near clip plane

    - #### setNearClip

          public void setNearClip(double dist)

      Get distance of the near clipping plane. The near and far clipping planes of a camera are orthogonal to the viewing direction at a positive distance. The near clip plane is closer to the camera than the far clip plane, and this order is not allowed to change.
      Specified by:
        `setNearClip` in interface `PvCameraIf`
      Parameters:
        `dist` - positive distance of the near clip plane

    - #### getFarClip

          public double getFarClip()

      Get distance of the far clipping plane. The near and far clipping planes of a camera are orthogonal to the viewing direction at a positive distance. The near clip plane is closer to the camera than the far clip plane, and this order is not allowed to change.
      Specified by:
        `getFarClip` in interface `PvCameraIf`
      Returns:
        positive distance of the far clip plane

    - #### setFarClip

          public void setFarClip(double dist)

      Get distance of far clipping plane. The near and far clipping planes of a camera are orthogonal to the viewing direction at a positive distance. The near clip plane is closer to the camera than the far clip plane, and this order is not allowed to change.
      Specified by:
        `setFarClip` in interface `PvCameraIf`
      Parameters:
        `dist` - positive distance of the far clip plane

    - #### getViewDir

          public PdVector getViewDir()

      Get normalized viewing direction as the vector pointing from the camera to its interest.

      Internally the viewing direction is the negative of third row of the viewing matrix divided by the scaling factor.

          viewDir = -view[2][.] / getScale()

      .
      Specified by:
        `getViewDir` in interface `PvCameraIf`
      Returns:
        normalized viewing direction in world coordinates
      Version:
        11.01.05, 2.00 revised (kp) BoxRatio scaling corrected with new m_viewDirOut.

    - #### setViewDir

          public void setViewDir(PdVector dir)

      Set viewing direction as the vector pointing from the camera to its interest. Length of vector is irrelevant.
      Specified by:
        `setViewDir` in interface `PvCameraIf`
      Parameters:
        `dir` - viewing direction in world coordinates

    - #### getDist

          public double getDist()

      Get distance of camera position from point of interest in world coordinates. Distance is inverse to scaling factor of viewing matrix.
      Specified by:
        `getDist` in interface `PvCameraIf`
      Returns:
        distance of camera to interest in world coordinates.
      See Also:
        `getScale()`

    - #### setDist

          public void setDist(double newDist)

      Set distance of camera position from point of interest in world coordinates. Scale view matrix with `factor=newDist/currDist`.
      Specified by:
        `setDist` in interface `PvCameraIf`
      Parameters:
        `newDist` - distance of camera to interest in world coordinates.
      See Also:
        `setScale(double)`

    - #### getScale

          public double getScale()

      Get zoom factor of camera.
      Specified by:
        `getScale` in interface `PvCameraIf`
      Returns:
        zoom factor of camera.
      See Also:
        `getDist()`

    - #### setScale

          public void setScale(double newScale)

      Set zoom factor of camera.
      Specified by:
        `setScale` in interface `PvCameraIf`
      Parameters:
        `newScale` - zoom factor of camera.
      See Also:
        `setDist(double)`

    - #### getFieldOfView

          public double getFieldOfView()

      Get opening angle of camera.
      Specified by:
        `getFieldOfView` in interface `PvCameraIf`
      Returns:
        angle in (0,180)
      See Also:
        `setFieldOfView(double)`

    - #### setFieldOfView

          public void setFieldOfView(double angle)

      Set opening angle of camera.
      Specified by:
        `setFieldOfView` in interface `PvCameraIf`
      Parameters:
        `angle` - angle in (0,180)
      See Also:
        `getFieldOfView()`

    - #### getRoll

          public double getRoll()

      Get angle which camera is rotated around viewing direction against default position. The default position depends on the projection mode of the camera.

      Mathematically, the roll is the angle between the two planes p1=(viewDir, defaultUpVector) and p2=(viewDir, upVector). The defaultUpVector depends on the projection mode, in xy-projection mode we have defaultUpVector=(0,1,0) since camera looks down the negative z-axis and the positive y-axis is showing upward.

      Specified by:
        `getRoll` in interface `PvCameraIf`
      Returns:
        angle in (-180, 180)
      See Also:
        `setRoll(double)`

    - #### setRoll

          public void setRoll(double roll)

      Set angle which camera is rotated around viewing direction against default position. The default position depends on the projection mode of the camera.
      Specified by:
        `setRoll` in interface `PvCameraIf`
      Parameters:
        `roll` - angle in (-180, 180)
      See Also:
        `getRoll()`

    - #### getInterest

          public PdVector getInterest()

      Get position at which camera is directed, i.e. the point of interest. Interest is implicitly stored as the 4th column of the inverse viewing matrix.

          interest = viewInv[.][3]

      Specified by:
        `getInterest` in interface `PvCameraIf`
      Returns:
        3d-coordinates of interest in world coordinates.

    - #### setInterest

          public void setInterest(PdVector pos)

      Set location at which camera is directed, i.e. the point of interest. This method does not change the viewing direction, that means, implicitly the camera position is moved parallel in order to keep the same viewing direction.

      This behaviour results from the steering inside the camera panel where a user may change the interest, viewing direction and distance. Users who want to set camera position and interest are advised either to first set the interest and then the position, or to set the viewing direction and then the interest.

      Specified by:
        `setInterest` in interface `PvCameraIf`
      Parameters:
        `pos` - 3d-coordinates of interest in world coordinates.

    - #### getPosition

          public PdVector getPosition()

      Get position of camera in world coordinates. The camera position is implicitly stored and computed from

          position = interest - dist*viewDir

      .
      Specified by:
        `getPosition` in interface `PvCameraIf`
      Returns:
        3d-position of camera in world coordinates.
      Version:
        25.07.00, 1.10 revised (kp) Bug removed, did not use interest correctly.

    - #### setPosition

          public void setPosition(PdVector pos)

      Set position of camera in world coordinates. The camera position is implicitly stored by equation

          position = interest - dist*viewDir

      .
      Specified by:
        `setPosition` in interface `PvCameraIf`
      Parameters:
        `pos` - 3d-position of camera in world coordinates.

    - #### getUpVector

          public PdVector getUpVector()

      Get up vector as second row of viewing matrix divided by scaling factor.

          upDir = -view[1][.] / getScale()

      .
      Specified by:
        `getUpVector` in interface `PvCameraIf`
      Returns:
        normalized up vector of camera in world coordinates.

    - #### setUpVector

          public void setUpVector(PdVector up)

      Set normalized up vector of camera in world coordinates.
      Specified by:
        `setUpVector` in interface `PvCameraIf`
      Parameters:
        `up` - normalized up vector of camera in world coordinates.

    - #### setFullPosition

          public void setFullPosition(PdVector interest,
                                      PdVector position,
                                      PdVector upDir)

      Set full orientation and location of camera in world coordinates. The camera position and interest are related by the formula

          position = interest - dist*viewDir

      .

      UpDir must be orthogonal to the vector interest-position.

      Specified by:
        `setFullPosition` in interface `PvCameraIf`
      Parameters:
        `interest` - 3d-coordinates of point of interest in world coordinates.
        `position` - 3d-coordinates of position of camera in world coordinates.
        `upDir` - normalized up vector of camera in world coordinates.
      Since:
        JavaView 3.03.002
      Version:
        14.12.03, 1.00 created (kp)

    - #### fit

          public void fit(double diameter)

      Fit object with given diameter into current display window. Compute scaling factor such that diameter (in world coordinates) corresponds to width of image.
      Version:
        15.03.01, 1.10 revised (kp) Reduce size of scene to factor 1.1 from 1.2.

    - #### isEnabledSceneRatio

          public boolean isEnabledSceneRatio()

      Check of aspect ratio of scene bounding box is enabled.
      Specified by:
        `isEnabledSceneRatio` in interface `PvCameraIf`

    - #### setEnabledSceneRatio

          public void setEnabledSceneRatio(boolean flag)

      Set aspect ratio of scene bounding box.
      Specified by:
        `setEnabledSceneRatio` in interface `PvCameraIf`

    - #### setEnabledBoxRatio

          public void setEnabledBoxRatio(boolean flag)

      Enable usage of a variable aspect ratio for the viewing frustum of this camera.
      Specified by:
        `setEnabledBoxRatio` in interface `PvCameraIf`

    - #### setBoxRatio

          public void setBoxRatio(PdVector ratio)

      Set the scaling factor for all three camera axis to produce a non-square viewing frustum.
      Specified by:
        `setBoxRatio` in interface `PvCameraIf`
      Parameters:
        `ratio` - three scaling factors, default square has (1.,1.,1.).

    - #### getBounds

          public PdVector[] getBounds()

      Get transformed bounding box used in clipping. Method returns the bounding box of the transformed bounding box of the scene, that means, the returned bounding box is in screen coordinates where the third component points towards the observer.
      Version:
        02.08.03, 1.10 revised (kp) Transform and handle all eight vertices of the bndBox.

    - #### getTransMatrix

          public PdMatrix getTransMatrix(int type)

      Get transformation matrices PV, P, V and their inverses in current camera and display. Allows to transform world coordinates into screen coordinates [0,0]*[width-1,height-1] of display.

      Modeling matrix should be set in original geometry model.

      Specified by:
        `getTransMatrix` in interface `PvCameraIf`
      Parameters:
        `type` - type of transformation matrix, see `PvDisplay.MATRIX_`
      Returns:
        pointer to transformation matrix
      Since:
        JavaView 2.99.016
      Version:
        26.09.03, 1.00 created (kp)

    - #### setTransMatrix

          public void setTransMatrix(int type,
                                     PdMatrix mat)

      Set transformation matrices PV, P, V and their inverses in current camera and display. Allows to transform world coordinates into screen coordinates [0,0]*[width-1,height-1] of display.

      Modeling matrix should be set in original geometry model.

      Specified by:
        `setTransMatrix` in interface `PvCameraIf`
      Parameters:
        `type` - type of transformation matrix, see `PvDisplay.MATRIX_`
        `mat` - new transformation matrix
      Since:
        JavaView 2.47
      Version:
        28.11.02, 1.00 created (kp) Body moved from PvDisplay#setTransMatrix().

"

The software JavaView? is copyright protected. All Rights Reserved.
"