The position of a view is often manipulated through a controller. In many cases, however, you need to position the view programmatically, if you want to center the view on a certain object, for instance.
In general, the position of the view is determined by its view-to-world transformation. In LuciadLightspeed, the
ALspViewXYZWorldTransformation
class represents a view-to-world transformation. Among other things, this transformation determines where the eye point of
the view is placed, and how the viewing volume is defined. The class also allows you to link an identifier to transformations.
An identifier is useful to prevent cloning: you can compare transformations, and check whether the transformation stored in
the cache is still valid by looking at the identifier.
The LuciadLightspeed API offers distinct implementations for 2D and 3D views. Each implementation offers different parameters to position the view.
Positioning a 2D view and Positioning a 3D view describe the low-level details of positioning in a 2D and 3D view. You can go straight to Navigating on a Lightspeed view for higher-level abstractions.
See Coordinate systems and transformations for more information.
Positioning a 2D view
For 2D views, the API provides the TLspViewXYZWorldTransformation2D
class. The most important parameters
that this class offers to adjust the position of the view are:
-
The world origin
-
The view origin
-
The scale parameter
The first two parameters are important for the view position. Under the hood, the view configuration is calculated in such a way that the view origin, a point in view space, is mapped to the world origin, a point in the world.
To position your view:
-
Choose a view origin, a point in view space, defined in pixel coordinates.
-
Choose a world origin, a point in world space defined in Cartesian coordinates. This point must map to the view origin.
-
Choose a scale to determine the range of map content shown around the origin, and define it in pixels per world unit.
-
Specify the rotation to apply around the origin, in degrees
The scale parameter is defined in pixels per world reference unit, typically expressed in meters. It determines the distance at which the view is positioned from the world, which gives an indication of how much the view is zoomed in or out. This means that low-scale parameter values specify a zoomed-out view and high values specify a zoomed-in view.
Suppose that you want to use the TLspViewXYZWorldTransformation2D
class to fit and center a map of the entire world in a view of 1000 pixels wide. Then, you need to supply:
-
The center of the view as the view origin: a point with pixel coordinates (500, 500).
-
The center of the world projection on the map as the world origin: a point with the XY coordinates (0,0).
-
The scale parameter is 1.0/40.000, or 1000 pixels of view width for 40000 kilometers of world circumference.
-
The rotation is 0 degrees.
To position a view, it is often easier to use |
Positioning a 3D view
For 3D views, the API provides the TLspViewXYZWorldTransformation3D
class, which makes abstraction of the viewing frustum that defines the view in 3D. This class allows you to position the view point using two similar, but subtly different methods:
lookAt()
and lookFrom()
. These methods take the same arguments:
-
The world reference of the view in which the
TLspViewXYZWorldTransformation3D
is being applied. -
A location in world coordinates.
-
A distance to be maintained between the view point and the reference point.
-
Yaw, pitch and roll angles to determine the orientation of the viewer.
From this parameter input, TLspViewXYZWorldTransformation3D
derives an orthogonal coordinate frame. The frame is defined by three properties:
-
The eye point: the position of the viewer in world coordinates.
-
The reference point: a point towards which the viewer is oriented. When projected, this is a point in the middle of the screen.
-
The up-vector: a vector that indicates, in world coordinates, the direction of the vertical axis of the screen.
The difference between the lookAt()
and lookFrom()
methods resides in the way they derive the eye point, reference point and up-vector from their arguments:
-
lookAt()
places the reference point at the specified location, and then uses the given distance, yaw, pitch and roll to compute the eye point. Use this method to orbit the view around a particular point, by keeping the location constant and varying the yaw and pitch angles. -
lookFrom()
places the eye point at the specified location, and then uses the given distance, yaw, pitch and roll to compute the reference point. Use this method to let the viewer look around freely from a fixed position.
Navigating on a Lightspeed view
Navigation on a Lightspeed view boils down to configuring the ALspViewXYZWorldTransformation
it uses. This is not trivial in most cases, so the LuciadLightspeed API offers several components to help you accomplish
this:
-
Navigation controllers: controllers that interpret input events and adapt the view-to-world transformation accordingly. See Interacting with the view for more information about attaching controllers to the view, and creating or customizing your controllers.
-
On-map navigation controls: a set of GUI components that you can control with the mouse to navigate the view. These are
TLspCompassNavigationControl
,TLspPanNavigationControl
, andTLspZoomNavigationControl
.TLspNavigationControlsBuilder
allows you to construct such navigation control components. -
The class
TLspViewNavigationUtil
: a utility class to navigate programmatically.
TLspViewNavigationUtil
offers various high-level methods for navigation:
-
Panning in the view
-
Zooming the view
-
Rotating the view
-
Fitting the view to an area. See also How to fit a view to focus on specific data.
-
Panning the view to an area
These operations can either be performed immediately, so that the view snaps to the requested state without transition, or as an animation. This allows for a smooth transition from the current state to the new state.