Package com.luciad.view.lightspeed.camera

Class TLspViewXYZWorldTransformation3D

java.lang.Object
com.luciad.view.lightspeed.camera.ALspViewXYZWorldTransformation
com.luciad.view.lightspeed.camera.TLspViewXYZWorldTransformation3D
All Implemented Interfaces:
ILcdPropertyChangeSource, Cloneable
public class TLspViewXYZWorldTransformation3D extends ALspViewXYZWorldTransformation

An ALspViewXYZWorldTransformation which provides 3D perspective projection for an ILspView. This transformation is defined by an orthogonal coordinate frame which is in turn specified by an "eye point", a "reference point" and an "up vector". The eye point is the location of the viewpoint in the 3D world; the reference point is a point in the world towards which the viewer is oriented, and the up vector is a normalized vector, relative to the eye point, which defines the "up" direction of the viewer.

The eye point, reference point and up vector cannot be manipulated directly. Instead, the viewer can be positioned using the more intuitive lookAt(com.luciad.shape.ILcdPoint, double, double, double, double) and lookFrom(com.luciad.shape.ILcdPoint, double, double, double, double) methods, both of which express the orientation of the viewer in terms of yaw, pitch and roll angles. The definition of these angles is as follows:

  • Yaw: orientation (or "heading") of the viewer in the ground plane. A value of 0 points the viewer towards the North pole; the angle increases in clockwise direction.
  • Pitch: the viewer's "tilt" angle. A value of 0 points the viewer towards the horizon (i.e. horizontally); -90 points straight down towards the ground and +90 points straight up.
  • Roll: the "bank" angle or rotation of the viewer around the axis from the eye point to the reference point. Negative angles bank the view to the left; positive angles turn to the right.
All angles are specified in degrees.

This transformation is not thread-safe for writing and should only be modified from the painting thread. The transformation is thread-safe for reading. However, to obtain consistent results on asynchronous tasks, an immutable clone should be used.

Since:
2012.0
See Also:

  • Constructor Details

  • Method Details

    • getImmutableClone

      public TLspViewXYZWorldTransformation3D getImmutableClone()
      Description copied from class: ALspViewXYZWorldTransformation
      Returns an immutable deep clone of this transformation

      Use this clone for example to pass the view-to-world transformation to another thread than the painting thread.

      Specified by:
      getImmutableClone in class ALspViewXYZWorldTransformation
      Returns:
      an immutable deep clone of this transformation

    • isAdjustDepthRange

      public boolean isAdjustDepthRange()
      This method returns true when the near and far plane are automatically adjusted each time lookAt(com.luciad.shape.ILcdPoint, double, double, double, double) or lookFrom(com.luciad.shape.ILcdPoint, double, double, double, double) is called.
      Returns:
      true if the depth range is adjusted automatically, false otherwise.

    • setAdjustDepthRange

      public void setAdjustDepthRange(boolean aAdjustDepthRange)
      Enables or disables automatically adjusting depth ranges. Set this to false if you want to manually manage the values for the near and far plane using setNear(double) and setFar(double). The default value is true.
      Parameters:
      aAdjustDepthRange - true to enable and false to disable automatically adjusting the depth range.

    • addConstraint

      public void addConstraint(ALspCameraConstraint<? extends TLspViewXYZWorldTransformation3D> aConstraint)
      Adds a new constraint. The order in which constraints are added is important. Constraints that are added first are executed last. This means that when there are conflicts between constraints, the firstly added takes precedence.
      Parameters:
      aConstraint - a constraint.

    • removeConstraint

      public void removeConstraint(ALspCameraConstraint<? extends TLspViewXYZWorldTransformation3D> aConstraint)
      Removes the given constraint.
      Parameters:
      aConstraint - a constraint.

    • getConstraints

      public Iterable<ALspCameraConstraint<TLspViewXYZWorldTransformation3D>> getConstraints()
      Returns an (unmodifiable) Iterable containing all the constraints currently set on this TLspViewXYZWorldTransformation3D.
      Returns:
      an unmodifiable iterable over the current constraints.

    • lookAt

      public void lookAt(ILcdPoint aLookAt, double aDistance, double aYaw, double aPitch, double aRoll)
      Orients the viewer towards a given reference point. The eye point and up vector are derived from the reference point based on the given distance, yaw, pitch and roll parameters. This method can be used to "orbit" the viewer around a certain point in the world, by keeping the look-at point constant and varying the yaw and/or pitch angles.
      Parameters:
      aLookAt - the point (in world coordinates) at which to put the viewer's reference point
      aDistance - the distance from the reference point at which to put the eye point
      aYaw - the desired yaw angle from the eye point to the reference point (in degrees)
      aPitch - the desired pitch angle from the eye point to the reference point (in degrees)
      aRoll - the desired roll angle of the viewer around its line-of-sight axis (in degrees)
      See Also:

    • lookFrom

      public void lookFrom(ILcdPoint aLookFrom, double aDistance, double aYaw, double aPitch, double aRoll)
      Positions the viewer at a given eye point. The reference point is derived from the eye point based on the given distance, yaw, pitch and roll parameters. This method can be used to look around freely from a fixed position.
      Parameters:
      aLookFrom - the point (in world coordinates) at which to put the eye point
      aDistance - the distance from the eye point at which to put the viewer's reference point
      aYaw - the desired yaw angle from the eye point to the reference point (in degrees)
      aPitch - the desired pitch angle from the eye point to the reference point (in degrees)
      aRoll - the desired roll angle of the viewer around its line-of-sight axis (in degrees)
      See Also:

    • set

      public void set(ALspViewXYZWorldTransformation aOther)
      Sets this view transformation's properties to be equal to the other one. This does not consider any transformation constraints or the width and height of the view. This method only considers: This method can be useful to keep two transformations in sync (e.g., when having two views that need to exactly use the same camera properties).
      Specified by:
      set in class ALspViewXYZWorldTransformation
      Parameters:
      aOther - the transformation to copy the properties from
      Throws:
      IllegalArgumentException - if aOther is not a TLspViewXYZWorldTransformation3D
      See Also:

    • getDistance

      public double getDistance()
      Returns the distance from the eye point to the reference point.
      Returns:
      the distance from the eye point to the reference point

    • getYaw

      public double getYaw()
      Returns the yaw angle of the viewer. The angle is measured in degrees and specifies the clockwise orientation of the viewer relative to the North.
      Returns:
      the yaw angle of the viewer in degrees

    • getPitch

      public double getPitch()
      Returns the pitch angle of the viewer. The angle is measured in degrees. A value of zero represents a horizontal viewer (i.e. looking towards the horizon). Positive angles look up and negative angles look down.
      Returns:
      the pitch angle of the viewer in degrees

    • getRoll

      public double getRoll()
      Returns the roll angle of the viewer. The angle is measured in degrees. Positive angles bank the viewer to the right; negative angles bank to the left.
      Returns:
      the roll angle of the viewer in degrees

    • clone

      public TLspViewXYZWorldTransformation3D clone()
      Returns a deep clone of this transformation.

      Note: this method doesn't copy over or clone the added constraints.

      Overrides:
      clone in class ALspViewXYZWorldTransformation
      Returns:
      a deep clone of this transformation

    • apply

      public void apply(ILcdGLDrawable aGLDrawable)
      Description copied from class: ALspViewXYZWorldTransformation
      Applies the current world-to-view transformation to the specified ILcdGLDrawable. This method sets the OpenGL modelview and projection matrices as appropriate.
      Specified by:
      apply in class ALspViewXYZWorldTransformation
      Parameters:
      aGLDrawable - the ILcdGLDrawable to be configured

    • getFrustum

      public TLspFrustum getFrustum()
      Description copied from class: ALspViewXYZWorldTransformation
      Returns the current view frustum.
      Specified by:
      getFrustum in class ALspViewXYZWorldTransformation
      Returns:
      the current view frustum.

    • worldPoint2ViewSFCT

      public void worldPoint2ViewSFCT(ILcdPoint aWorldPoint, ILcd3DEditablePoint aViewPointSFCT)
      Description copied from class: ALspViewXYZWorldTransformation
      Transforms a point in world coordinates to a point in view coordinates. The result of the transformation is stored in the second point parameter.

      See the class documentation for important information about view coordinates and DPI scaling.

      Specified by:
      worldPoint2ViewSFCT in class ALspViewXYZWorldTransformation
      Parameters:
      aWorldPoint - the world point to transform
      aViewPointSFCT - the point to be set

    • viewPoint2WorldSFCT

      public void viewPoint2WorldSFCT(ILcdPoint aViewPoint, ILcd3DEditablePoint aWorldPointSFCT)
      Description copied from class: ALspViewXYZWorldTransformation

      Transforms a point in view coordinates to a point in world coordinates. The result of the transformation is stored in the second point parameter.

      Note: this method interprets the z value ([0,1]) of the given point as the depth value in view space. If you are using 2D view points (e.g. the x and y coordinates of the mouse), it is advised to use ALspViewXYZWorldTransformation.viewPoint2WorldSFCT(Point, LocationMode, ILcd3DEditablePoint), which can calculate the world point at sea level or on the surface closest to the viewer.

      See the class documentation for important information about view coordinates and DPI scaling.

      Specified by:
      viewPoint2WorldSFCT in class ALspViewXYZWorldTransformation
      Parameters:
      aViewPoint - the view point to transform to world coordinates
      aWorldPointSFCT - the point to set

    • setSize

      public void setSize(int aWidth, int aHeight)
      Description copied from class: ALspViewXYZWorldTransformation
      Sets the size of the viewport.
      Specified by:
      setSize in class ALspViewXYZWorldTransformation
      Parameters:
      aWidth - the new width of the viewport
      aHeight - the new height of the viewport

    • getWidth

      public int getWidth()
      Description copied from class: ALspViewXYZWorldTransformation
      Returns the width of the viewport in pixels.
      Specified by:
      getWidth in class ALspViewXYZWorldTransformation
      Returns:
      the width of the viewport

    • getHeight

      public int getHeight()
      Description copied from class: ALspViewXYZWorldTransformation
      Returns the height of the viewport in pixels.
      Specified by:
      getHeight in class ALspViewXYZWorldTransformation
      Returns:
      the height of the viewport

    • getIdentifier

      public Object getIdentifier()
      Description copied from class: ALspViewXYZWorldTransformation
      Returns an identifier object that can be used to efficiently compare transformations. If a transformation changes, the identifier should be a new object, i.e., a reference comparison should fail. This allows caches to store the identifier to associate a particular transformation state with certain data (e.g., a discretized shape).

      Testing whether a view-to-world transformation is still valid should then follow these lines of code:

      Object yourIdentifier = ...;
      ALspViewXYZWorldTransformation v2w = ...;
      Object myIdentifier = v2w.getIdentifier();
      boolean transformationValid = yourIdentifier.equals(myIdentifier);

      Specified by:
      getIdentifier in class ALspViewXYZWorldTransformation
      Returns:
      an object that can be used to compare transformations as described above

    • addPropertyChangeListener

      public void addPropertyChangeListener(PropertyChangeListener aListener)
      Description copied from interface: ILcdPropertyChangeSource

      Registers the given PropertyChangeListener to be notified when this object's properties change.

      In case you need to register a listener which keeps a reference to an object with a shorter life-time than this change source, you can use a ALcdWeakPropertyChangeListener instance as property change listener.

      Parameters:
      aListener - The listener to be notified
      See Also:

    • removePropertyChangeListener

      public void removePropertyChangeListener(PropertyChangeListener aListener)
      Description copied from interface: ILcdPropertyChangeSource

      De-registers the given PropertyChangeListener from receiving property change events for this object.

      If the listener was added more than once, it will be notified one less time after being removed. If the listener is null, or was never added, no exception is thrown and no action is taken.

      Parameters:
      aListener - the listener that should no longer be notified of changes of this object's properties
      See Also:

    • getEyePoint

      public ILcdPoint getEyePoint()
      Returns the position of the viewer in world coordinates.
      Returns:
      the position of the viewer in world coordinates

    • getReferencePoint

      public ILcdPoint getReferencePoint()
      Returns the reference point of the viewer in world coordinates. The reference point is a point towards which the viewer is oriented.
      Returns:
      the reference point of the viewer in world coordinates

    • getUpVector

      public ILcdPoint getUpVector()
      Returns the up vector of the viewer. This normalized vector indicates the direction in world coordinates that corresponds to the vertical axis of the screen after the world-to-view transformation.
      Returns:
      the up vector of the viewer

    • getFieldOfView

      public double getFieldOfView()
      Returns the vertical field-of-view angle of the viewer in degrees.
      Returns:
      the vertical field-of-view angle of the viewer in degrees

    • setFieldOfView

      public void setFieldOfView(double aFieldOfView)
      Sets the vertical field-of-view angle of the viewer.
      Parameters:
      aFieldOfView - the desired vertical field-of-view angle in degrees

    • getNear

      public double getNear()
      Returns the near clipping plane distance of the frustum.
      Returns:
      the near clipping plane distance of the frustum

    • setNear

      public void setNear(double aNear)
      Sets the near clipping plane distance of the frustum.
      Parameters:
      aNear - the desired near clipping plane distance, in world units

    • getFar

      public double getFar()
      Returns the far clipping plane distance of the frustum.
      Returns:
      the far clipping plane distance of the frustum

    • setFar

      public void setFar(double aFar)
      Sets the far clipping plane distance of the frustum.
      Parameters:
      aFar - the desired far clipping plane distance, in world units

    • getAspectRatio

      public double getAspectRatio()
      Returns the aspect ratio of the view's width and height.
      Returns:
      the aspect ratio of the view's width and height

    • applyLocalOrigin

      public void applyLocalOrigin(ILcdGLDrawable aGLDrawable, ILcdPoint aOrigin)
      Applies a local coordinate origin to the viewer. The origin is subtracted from the eye point and reference point to create a new local coordinate frame. If the same transformation is applied to the data being rendered in the view, the visual end result is the same as it would be without the local origin. However, this method may be used to move data closer to the origin, avoiding loss of accuracy due to conversion from double to single precision floating point while transferring coordinates to the GPU.
      Specified by:
      applyLocalOrigin in class ALspViewXYZWorldTransformation
      Parameters:
      aGLDrawable - the access point to OpenGL
      aOrigin - the local origin to apply

    • restoreLocalOrigin

      public void restoreLocalOrigin(ILcdGLDrawable aGLDrawable)
      Undoes a previously applied local coordinate origin.
      Specified by:
      restoreLocalOrigin in class ALspViewXYZWorldTransformation
      Parameters:
      aGLDrawable - the access point to OpenGL

    • getModelViewMatrix

      public double[] getModelViewMatrix()
      Gets the model-view matrix.

      The array is a linearized 4x4 matrix where result[0] corresponds to row=0 and column=0, result[1] corresponds to row=1, column=0, etc. Note that this corresponds to how OpenGL expects matrices to be linearized.

      Returns:
      a 16 element matrix representing the model-view transformation

    • getProjectionMatrix

      public double[] getProjectionMatrix()
      Gets the projection matrix.

      The array is a linearized 4x4 matrix where result[0] corresponds to row=0 and column=0, result[1] corresponds to row=1, column=0, etc. Note that this corresponds to how OpenGL expects matrices to be linearized.

      Returns:
      a 16 element matrix representing the perspective transformation

    • worldPoint2ClipSFCT

      public double worldPoint2ClipSFCT(ILcdPoint aWorldPoint, ILcd3DEditablePoint aClipPointSFCT)
      Transforms the given point in world coordinates to a point in clip coordinates. This method returns the homogeneous coordinate of the result.

      Clip coordinates are often useful such as for example to perform perspective-correct interpolation.

      Transforming a point from world to clip coordinates and from clip to view coordinates yields the same result as transforming the point directly from world to view coordinates.

      Parameters:
      aWorldPoint - the point in world coordinates
      aClipPointSFCT - the resulting clip point's XYZ coordinates
      Returns:
      the resulting clip point's homogeneous W coordinate
      See Also:

    • clip2viewSFCT

      public void clip2viewSFCT(ILcdPoint aClipPoint, double aW, ILcd3DEditablePoint aViewPointSFCT)
      Transforms the given point in clip coordinates to a point in view coordinates.
      Parameters:
      aClipPoint - the XYZ coordinates of the point in clip coordinates
      aW - the W coordinate of the point in clip coordinates
      aViewPointSFCT - the resulting view point
      See Also:

    • getScaleX

      public double getScaleX()
      Description copied from class: ALspViewXYZWorldTransformation
      Returns the horizontal scale for which to paint objects. The scale corresponds to the number of pixels per world unit, as determined by the ILcdXYWorldReference of the registered view. For example, a view displaying geographical data could use a scale in pixels per meter.
      Specified by:
      getScaleX in class ALspViewXYZWorldTransformation
      Returns:
      the scale of this transformation.

    • getScaleY

      public double getScaleY()
      Description copied from class: ALspViewXYZWorldTransformation
      Returns the vertical scale for which to paint objects. The scale corresponds to the number of pixels per world unit, as determined by the ILcdXYWorldReference of the registered view. For example, a view displaying geographical data could use a scale in pixels per meter.
      Specified by:
      getScaleY in class ALspViewXYZWorldTransformation
      Returns:
      the scale of this transformation.

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • getGeodeticVisibleArea

      public ILcdComplexPolygon getGeodeticVisibleArea()
      Description copied from class: ALspViewXYZWorldTransformation
      Returns a polygon which approximates the area of the globe which is visible in the current view. The polygon is expressed in geodetic coordinates using a standard WGS84 datum (i.e. the reference created by the default constructor of TLcdGeodeticReference). In some 2D map projections, the visible part of the map may consist of multiple disjoint areas. For this reason, this method returns a complex polygon.

      The computation does not take terrain into account: it is essentially the intersection of the frustum with the surface of the ellipsoid as seen in the current world reference.

      If the world is entirely outside of the view, this method returns null.

      Specified by:
      getGeodeticVisibleArea in class ALspViewXYZWorldTransformation
      Returns:
      a polygon which bounds the currently visible area of the world

    • getStereoTransformation

      public TLspViewXYZWorldTransformation3D getStereoTransformation(TLspPaintPhase.PaintStereo aStereoPhase)
      Returns a view-to-world transformation that corresponds with the eye position for the provided stereo phase.
      Parameters:
      aStereoPhase - the stereo phase
      Returns:
      the transformation for the corresponding stereo phase