Viewing

By default, the 3D control automatically provides rotating and zooming in a 3D scene using the mouse.

• Hold down the left mouse button and move the mouse to rotate.

• Hold down the right mouse button and move to zoom in and out. Zooming uses a logarithmic scale; as the camera approaches the viewed object, the zooming speed slows down.

• Hold down the shift key and the left mouse button and move to change the view direction without changing the camera position.

• Hold down control and the left mouse button and move to lock horizontal movement so you can rotate vertically without accidentally changing your horizontal axis.

• Hold down alt and the left mouse button and move to lock vertical movement.

The 3D control also provides the Zooming (get / set) property. When this property is set to true, the next time the user drags using the left mouse button, a box will be drawn on the screen. When complete, the camera will then zoom to the rectangular extent on the globe under the box.

Camera provides full control over the camera's position and orientation. These are defined by three primary parameters:

• Camera Position – The position of the virtual camera in the 3D scene.

• Direction – A unit length vector indicating the direction the camera is looking.

• Up Vector – A unit length vector indicating the orientation of the camera. Informally, this can be thought of as how the camera's head is tilted.

The camera's position can be retrieved using the camera's Position (get / set) property. The position is defined in the PositionReferenceFrame (get). Similarly, the direction and up vectors can be retrieved using Direction (get / set) and UpVector (get / set) properties. They are returned in the camera's Axes (get / set). The following example converts the position to the Earth's fixed frame and rotates the direction and up vectors to the Earth's fixed axes:

Camera camera = getScene().getCamera();
CentralBody earth = CentralBodiesFacet.getFromContext().getEarth();

// Create ReferenceFrameEvaluator that converts a Cartesian from the
// Camera's reference frame to Earth's Fixed Frame
ReferenceFrameEvaluator evaluator = GeometryTransformer.getReferenceFrameTransformation(camera.getPositionReferenceFrame(), earth.getFixedFrame());

// Convert the position to Earth's Fixed Frame
Cartesian positionInFixed = evaluator.evaluate(SceneManager.getTime()).transform(camera.getPosition());

// Get the UnitQuaternion that rotates the Camera's Axes to Earth's Fixed Axes.
UnitQuaternion rotation = GeometryTransformer.getAxesTransformation(camera.getAxes(), earth.getFixedFrame().getAxes()).evaluate(SceneManager.getTime());

// Rotate the Direction and UpVector to Earth's Fixed Axes
UnitCartesian direction = camera.getDirection().rotate(rotation);
UnitCartesian up = camera.getUpVector().rotate(rotation);

The viewCentralBody method sets the camera's position and direction so an entire central body is visible, with the camera looking toward the center of the central body. This method is commonly used as a default view or to switch between different central bodies, as shown below:

CentralBody moon = CentralBodiesFacet.getFromContext().getMoon();
getScene().getCamera().viewCentralBody(moon, moon.getInertialFrame().getAxes());
getScene().render();

The second parameter defines the axes of rotation. When the user holds down the left mouse button and moves, this is the axes the camera is rotated around.

The viewExtent method zooms to a rectangular extent on the globe. In the HowTo, this is used to set the camera such that an entire image overlay is visible. After calling viewExtent, the camera is in an east-north-up axes: X points toward local east, Y points toward local north, and Z points along the surface normal. The camera is looking straight down at the extent; the camera's up vector is local north (Y) and the camera's direction is opposite of the surface normal (-Z).

Camera camera = getScene().getCamera();
camera.viewExtent(CentralBodiesFacet.getFromContext().getEarth(), new CartographicExtent(0.0, 0.0, Trig.degreesToRadians(1.0), Trig.degreesToRadians(1.0)));
Cartesian offset = new Cartesian(new AzimuthElevationRange(Trig.degreesToRadians(45.0), Trig.degreesToRadians(-25.0), camera.getDistance()));
camera.setPosition(camera.getReferencePoint().add(offset));
getScene().render();

Azimuth is an angle from the positive X axis (in this case, local east) to rotate around Z. Elevation is an angle to rotate from the XY plane toward Z.

In the rotation axes used by the camera after viewing an extent, an azimuth of 90 degrees is looking south, and an azimuth of 0 is looking west. An elevation of 90 degrees is looking straight down, and an elevation of 0 is looking toward the horizon.

The view and viewDirection methods are used for general purpose viewing. They provide direct control over the camera's position, direction, and up vector, unlike viewCentralBody and viewExtent, which set these parameters implicitly. The following example views one Point from another Point.

EarthCentralBody earth = CentralBodiesFacet.getFromContext().getEarth();
PointCartographic viewerPosition = new PointCartographic(earth, new Cartographic(Trig.degreesToRadians(-77.04), Trig.degreesToRadians(36.85), 100000.0));
PointCartographic referencePoint = new PointCartographic(earth, new Cartographic(Trig.degreesToRadians(-77.04), Trig.degreesToRadians(38.85), 0.0));
Axes axes = new AxesEastNorthUp(earth, referencePoint);

UnitCartesian up = new UnitCartesian(0.0, 1.0, 0.0);

getScene().getCamera().setConstrainedUpAxis(ConstrainedUpAxis.NEGATIVE_Z);
getScene().getCamera().view(axes, viewerPosition, referencePoint, up);
getScene().render();

We create a viewer position and a reference point – the point the camera will look at. Next, an axes of rotation is created using east-north-up axes, similar to the axes created by viewExtent. The camera will evaluate the points at the current Time (get / set) and position the Camera accordingly. To improve efficiency, the camera caches the evaluator for each point. If the evaluator becomes invalid, for example, if the definition of a point changes, then refreshEvaluators must be called.