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:

  1. Choose a view origin, a point in view space, defined in pixel coordinates.

  2. Choose a world origin, a point in world space defined in Cartesian coordinates. This point must map to the view origin.

  3. Choose a scale to determine the range of map content shown around the origin, and define it in pixels per world unit.

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

worldvieworigin
Figure 1. Positioning a world map in your view

To position a view, it is often easier to use TLspViewNavigationUtil instead of writing the code to manipulate the view yourself. TLspViewNavigationUtil allows you to set the view so that to the data in a specific layer fits into it. You can also fit or center a view to specific bounds. For more information, see How to fit a view to focus on specific data.

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.

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:

TLspViewNavigationUtil offers various high-level methods for navigation:

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.