Package com.luciad.view.lightspeed.camera

Class ALspViewXYZWorldTransformation

java.lang.Object
com.luciad.view.lightspeed.camera.ALspViewXYZWorldTransformation
All Implemented Interfaces:
ILcdPropertyChangeSource, Cloneable
Direct Known Subclasses:
TLspViewXYZWorldTransformation2D, TLspViewXYZWorldTransformation3D
public abstract class ALspViewXYZWorldTransformation extends Object implements Cloneable, ILcdPropertyChangeSource
This class defines a transformation between world coordinates and view coordinates. The world-to-view transformation is assumed to be an affine transformation which is performed by the GPU. The apply method in this interface is used to this effect.

2D and 3D views

A view's ALspViewXYZWorldTransformation determines whether that view is a 2D or 3D view. All layers and painters in a view are expected to cope with both scenarios, as well as with runtime switches between the two. Hence, for many application developers the distinction between 2D and 3D should pose no special concern. Implementations of custom layers and/or painters, however, may wish to check the type of the world-to-view transformation if they need separate code paths for 2D and 3D rendering.

The class TLspViewTransformationUtil provides convenience methods for switching a view between 2D and 3D. These methods not only instantiate the appropriate ALspViewXYZWorldTransformation, but also initialize it with sensible default parameters.

View coordinates

All view coordinates follow the Java AWT convention, meaning that the origin is in the upper left corner.

Screen DPI and display scaling

To accurately work with map scales, the view needs the screen's DPI. Refer to TLcdMapScale for more information.

Lightspeed views support high DPI rendering, meaning that map features such as icons, line widths or font sizes will be scaled up in response to the DPI scale settings of the host operating system. This is largely transparent to the user, but some caveats apply when using the methods of this class to transform back and forth between pixel and world coordinates.

When using a DPI scale factor other than 100%, the Java runtime environment essentially creates an additional coordinate system. Let us refer to this system as "toolkit coordinates". Toolkit coordinates correspond to screen pixels that have been scaled by the DPI scaling factor. If the DPI scale is 150%, for instance, then toolkit == screen / 1.5 (for both the X and Y axes). All UI components (both in Swing/AWT and JavaFX) will express their dimensions and locations in toolkit coordinates. This means that the width and height reported by, for instance, a JPanel will be smaller than the panel's size in actual screen pixels.

Lightspeed views will render themselves at full screen resolution, but will use larger icons, fonts, and so on, proportional to the DPI scale factor. The dimensions of a view in toolkit coordinates are simply those reported by the view's host component -- the view itself, as well as its ALspViewXYZWorldTransformation, will always report the actual screen pixel size of the view. The ratio between these two sizes is equal to the DPI scale factor.

This class provides two-way transformation methods between toolkit, view and world coordinates. API users should take care to call the appropriate method for the task at hand. The most common scenario will be to transform between toolkit and world coordinates -- the intermediate view coordinates should only be needed in very advanced use cases such as when implementing a custom painter.

A final note about toolkit coordinates is that, unlike view coordinates, they do not have a third dimension. When transforming between toolkit and view coordinates, therefore, Z is assumed to be zero. This is reflected in method signatures by using java.awt.Point instead of ILcdPoint as the parameter type in places where Z is ignored.

All the above applies both to AWT/Swing and to JavaFX. High DPI rendering can be overridden using the following system properties:

  • -Dsun.java2d.uiScale=1.0 for AWT/Swing (1.0 corresponds to 100%)
  • -Dglass.win.uiScale=100% for JavaFX
In both cases, this sets the DPI scale to 100% (i.e. it switches DPI scaling off). The same properties can also be used to enforce a scale factor other than the one configured in the host operating system.

Thread safety

The transformation implementations are not thread-safe and should only be accessed from the painting thread. An immutable clone can be obtained to be used for asynchronous tasks.
Since:
2012.0

  • Method Details

    • getView

      public ILspView getView()
      Returns the registered view, or null if no view was registered.
      Returns:
      the registered view, or null if no view was registered.

    • apply

      public abstract void apply(ILcdGLDrawable aGLDrawable)
      Applies the current world-to-view transformation to the specified ILcdGLDrawable. This method sets the OpenGL modelview and projection matrices as appropriate.
      Parameters:
      aGLDrawable - the ILcdGLDrawable to be configured

    • applyLocalOrigin

      public abstract void applyLocalOrigin(ILcdGLDrawable aGLDrawable, ILcdPoint aOrigin)
      Modifies the OpenGL MODELVIEW matrix so that the given point is the origin.

      This method does not modify this transformation object.

      Parameters:
      aGLDrawable - the drawable that is painted on. Shall not be null.
      aOrigin - the new origin. Shall not be null.

    • restoreLocalOrigin

      public abstract void restoreLocalOrigin(ILcdGLDrawable aGLDrawable)
      Undoes a previously applied local coordinate origin.
      Parameters:
      aGLDrawable - the access point to OpenGL

    • set

      public abstract 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 viewing properties such as origin or eye location, scale, and so on. 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).
      Parameters:
      aOther - the transformation to copy the properties from
      Throws:
      IllegalArgumentException - if aOther is not a compatible transformation (i.e., when trying to set the properties of a 3D transformation to a 2D transformation and vice versa)
      See Also:

    • getFrustum

      public abstract TLspFrustum getFrustum()
      Returns the current view frustum.
      Returns:
      the current view frustum.

    • worldPoint2ViewSFCT

      public abstract void worldPoint2ViewSFCT(ILcdPoint aWorldPoint, ILcd3DEditablePoint aViewPointSFCT)
      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.

      Parameters:
      aWorldPoint - the world point to transform
      aViewPointSFCT - the point to be set
      Throws:
      NullPointerException - if either parameter is null

    • viewPoint2WorldSFCT

      public abstract void viewPoint2WorldSFCT(ILcdPoint aViewPoint, ILcd3DEditablePoint aWorldPointSFCT)

      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 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.

      Parameters:
      aViewPoint - the view point to transform to world coordinates
      aWorldPointSFCT - the point to set
      Throws:
      NullPointerException - if either parameter is null

    • worldBounds2viewSFCT

      public void worldBounds2viewSFCT(ILcdBounds aWorldBounds, ILcd3DEditableBounds aViewBoundsSFCT)
      Transforms a bounds in world coordinates to a bounds in view coordinates. The result of the transformation is stored in the second bounds parameter.

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

      Parameters:
      aWorldBounds - the world bounds to transform
      aViewBoundsSFCT - the bounds to be set
      Throws:
      NullPointerException - if either parameter is null

    • viewBounds2worldSFCT

      public void viewBounds2worldSFCT(ILcdBounds aViewBounds, ILcd3DEditableBounds aWorldBoundsSFCT)
      Transforms a bounds in view coordinates to a bounds in world coordinates. The result of the transformation is stored in the second bounds parameter.

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

      Parameters:
      aViewBounds - the view bounds to transform
      aWorldBoundsSFCT - the bounds to be set
      Throws:
      NullPointerException - if either parameter is null

    • setSize

      public abstract void setSize(int aWidth, int aHeight)
      Sets the size of the viewport.
      Parameters:
      aWidth - the new width of the viewport
      aHeight - the new height of the viewport

    • getWidth

      public abstract int getWidth()
      Returns the width of the viewport in pixels.
      Returns:
      the width of the viewport

    • getHeight

      public abstract int getHeight()
      Returns the height of the viewport in pixels.
      Returns:
      the height of the viewport

    • clone

      public ALspViewXYZWorldTransformation clone()
      Returns a deep clone of this transformation.
      Overrides:
      clone in class Object
      Returns:
      a deep clone of this transformation

    • getImmutableClone

      public abstract ALspViewXYZWorldTransformation getImmutableClone()
      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.

      Returns:
      an immutable deep clone of this transformation

    • getIdentifier

      public abstract Object getIdentifier()
      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);

      Returns:
      an object that can be used to compare transformations as described above

    • getScale

      public double getScale()
      Returns the scale for which to paint objects. The scale corresponds to the number of physical screen 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.

      If you need to calculate the scale with respect to toolkit coordinates, divide this value by the dpi scale.

      Returns:
      the scale of this transformation, in screen pixels per world unit

    • getMapScale

      public TLcdMapScale getMapScale(TLcdMapScale.ScaleLocation aScaleLocation)
      Returns the unitless map scale ratio for which to paint the view contents.
      Returns:
      the scale of this view
      Since:
      2021.0
      See Also:

    • getScaleX

      public abstract double getScaleX()
      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.
      Returns:
      the scale of this transformation.

    • getScaleY

      public abstract double getScaleY()
      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.
      Returns:
      the scale of this transformation.

    • viewAWTPoint2worldSFCT

      public void viewAWTPoint2worldSFCT(Point aViewPoint, ALspViewXYZWorldTransformation.LocationMode aLocationMode, ILcd3DEditablePoint aWorldPointSFCT) throws TLcdOutOfBoundsException
      Deprecated.
      Use viewPoint2WorldSFCT(Point, LocationMode, ILcd3DEditablePoint) or toolkitPoint2WorldSFCT(Point, LocationMode, ILcd3DEditablePoint) instead.
      Throws:
      TLcdOutOfBoundsException

    • getFeatureScale

      public double getFeatureScale()
      Returns a scale factor which changes the relative size of features (such as icons, labels or line widths) in a view. The default value is 1. Lower values will make features proportionally smaller (allowing, for instance, more labels to be placed). Higher values will make features proportionally larger (for instance, to make text more readable on very high-resolution displays). Feature scale may also affect level-of-detail decisions, e.g. for raster layers. Lower feature scales may cause higher detail levels to be shown (and vice versa).

    • getClip

      public Rectangle2D getClip()
      Returns the clipping rectangle which identifies the portion of the view that is currently being rendered. The clip is typically used when printing, because the view is usually not able to generate the entire print resolution image in a single pass. By default, the clip is null.
      Returns:
      the current clip

    • getOutputDevice

      public ALspViewXYZWorldTransformation.OutputDevice getOutputDevice()
      Returns the type of output device to which a view is being rendered. By default, this is ALspViewXYZWorldTransformation.OutputDevice.DISPLAY. This method can be used by layers and painters to tell whether the view is being printed, in which case the getClip() and getFeatureScale() properties of this transformation should be taken into account where appropriate.
      Returns:
      an OutputDevice

    • getGeodeticVisibleArea

      public abstract ILcdComplexPolygon getGeodeticVisibleArea()
      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.

      Returns:
      a polygon which bounds the currently visible area of the world

    • toolkitPoint2ViewSFCT

      public void toolkitPoint2ViewSFCT(Point aToolkitPoint, ILcd3DEditablePoint aViewPointSFCT)

      Transforms a point from toolkit coordinates to view coordinates. The result is stored in the aViewPointSFCT parameter. The Z coordinate of the output is always set to zero.

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

      Parameters:
      aToolkitPoint - a point in toolkit coordinates
      aViewPointSFCT - will be set to the corresponding point in view coordinates
      Since:
      2019.0

    • toolkitPoint2WorldSFCT

      public void toolkitPoint2WorldSFCT(Point aToolkitPoint, ILcd3DEditablePoint aWorldPointSFCT)

      Transforms a point from toolkit coordinates to world coordinates. This is equivalent to transforming from toolkit to view and then from view to world coordinates. The result is stored in the aWorldPointSFCT parameter. The Z coordinate of the input is assumed to be zero, therefore the output point is always located on the near plane.

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

      Parameters:
      aToolkitPoint - a point in toolkit coordinates
      aWorldPointSFCT - will be set to the corresponding point in world coordinates
      Since:
      2019.0

    • viewPoint2ToolkitSFCT

      public void viewPoint2ToolkitSFCT(ILcdPoint aViewPoint, Point aToolkitPointSFCT)

      Transforms a point from view coordinates to toolkit coordinates. The result is stored in the aToolkitPointSFCT parameter. The Z coordinate of the input is discarded.

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

      Parameters:
      aViewPoint - a point in view coordinates
      aToolkitPointSFCT - will be set to the corresponding point in toolkit coordinates
      Since:
      2019.0

    • worldPoint2ToolkitSFCT

      public void worldPoint2ToolkitSFCT(ILcdPoint aWorldPoint, Point aToolkitPointSFCT)

      Transforms a point from world coordinates to toolkit coordinates. This is equivalent to transforming from world to view and then from view to toolkit coordinates. The result is stored in the aToolkitPointSFCT parameter. The Z coordinate of the intermediate view point is discarded.

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

      Parameters:
      aWorldPoint - a point in world coordinates
      aToolkitPointSFCT - will be set to the corresponding point in toolkit coordinates
      Since:
      2019.0

    • viewPoint2WorldSFCT

      public void viewPoint2WorldSFCT(Point aViewPoint, ALspViewXYZWorldTransformation.LocationMode aLocationMode, ILcd3DEditablePoint aWorldPointSFCT) throws TLcdOutOfBoundsException

      Returns the location, in world coordinates, of the point currently located under aViewPoint, with the latter being a point in view coordinates.

      aLocationMode indicates whether the returned point should be at sea level or on the surface closest to the viewer. The Z coordinate of the view point is therefore irrelevant. Hence, this method accepts a java.awt.Point rather than an ILcdPoint.

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

      Parameters:
      aViewPoint - X and Y view coordinates of the point of which the location should be determined
      aLocationMode - specifies how the location should be determined
      aWorldPointSFCT - receives the world coordinates corresponding to aViewPoint
      Throws:
      TLcdOutOfBoundsException - if aViewPoint is not over the surface of the Earth in the current view
      Since:
      2019.0
      See Also:

    • toolkitPoint2WorldSFCT

      public void toolkitPoint2WorldSFCT(Point aToolkitPoint, ALspViewXYZWorldTransformation.LocationMode aLocationMode, ILcd3DEditablePoint aWorldPointSFCT) throws TLcdOutOfBoundsException

      Returns the location, in world coordinates, of the point currently located under aViewPoint, with the latter being a point in toolkit coordinates.

      aLocationMode indicates whether the returned point should be at sea level or on the surface closest to the viewer.

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

      Parameters:
      aToolkitPoint - toolkit coordinates of the point of which the location should be determined
      aLocationMode - specifies how the location should be determined
      aWorldPointSFCT - receives the world coordinates corresponding to aViewPoint
      Throws:
      TLcdOutOfBoundsException - if aToolkitPoint is not over the surface of the Earth in the current view
      Since:
      2019.0
      See Also: