Cameras

Updated February 2009: added mention of <gx:altitudeMode>, <gx:TimeStamp>, and <gx:TimeSpan>.

Introduced with KML 2.2, <Camera> provides an additional way to specify the observer's viewpoint and associated view parameters. <Camera> is similar to <LookAt>, since both elements define the placement and orientation of a virtual camera that is viewing the Earth. The difference is that LookAt specifies the view in terms of the point of interest that is being viewed. Camera, in contrast, specifies the view in terms of the viewer's position and orientation.

Both <LookAt> and <Camera> are extended from the <AbstractView> element, which is a base abstract type. <Camera> and <LookAt> are identical in how they are used in a KML file—namely, as a child of any element derived from <Feature> (Placemark, ScreenOverlay, GroundOverlay, PhotoOverlay, Folder, Document, NetworkLink) or as a child of <NetworkLinkControl>. You can use either a <Camera> or a <LookAt> within a Feature, but not both at the same time (that is, only one virtual camera can specify the current viewpoint).

Differences between <Camera> and <LookAt>

The new <Camera> element provides additional flexibility in how you specify the view. Most importantly, you can tilt the camera view so that you're looking above the horizon into the sky. <Camera> provides full six-degrees-of-freedom control over the view, so you can position the Camera in space and then rotate it around the x, y, and z axes. If no rotations are specified, the two elements are equivalent:

The following diagram illustrates how the <LookAt> viewpoint is constructed:

The <LookAt> element specifies answers to the following questions:

Question

Specification in <LookAt>

What point am I looking at?

<longitude>, <latitude>,<altitude>, <altitudeMode>

How far away is the viewpoint from the point of interest?

<range>

Is the view oriented so that due North is at the top of the view?

If Yes, use default <heading> value of 0. If No, specify a <heading> rotation from >0 to 360°

Is the view looking straight down at the Earth?

If Yes, use default<tilt> value. If No, camera is tilted upwards toward the horizon; specify a <tilt> rotation ≤ 90°.
90° is looking straight along the horizon. (You may not see the surface of the Earth at all if you're far away and <tilt> equals 90°.)

Position the camera at the point specified by <longitude>, <latitude>, <altitude>, and <altitudeMode>. In general, it is a poor choice to put a camera on the ground.

Is the camera oriented so that North is at the top of the view?

If Yes, use the default <heading> value of 0. If No, rotate the camera from >0 to 360°, according to points of the compass.

Is the camera looking straight down at the Earth?

If Yes, use the default <tilt> value of 0. If No, rotate the camera from 0 to 180° to specify the angle of rotation around the X axis. (Negative values for <tilt> are allowed, but these result in a view that is upside down.)

Is the camera level as it views the scene?

If Yes, use the default <roll> value of 0. Note: the value for <roll> when it is used as a child of <Camera> is usually 0. You can specify a value between −180 and +180°, but this usage is rare.

The following diagram shows the X, Y, and Z axes, which are attached to the virtual camera.

The X axis points toward the right of the camera and is called the right vector.

The Y axis defines the "up" direction relative to the screen and is called the up vector.

The Z axis points from the center of the screen toward the eye point. The camera looks down the −Z axis, which is called the view vector.

Here is an example of setting up a <Camera> as the starting viewpoint within a <Document>:

Time in AbstractViews

<Camera> and <LookAt> can both contain time information, which affects the historical imagery, sunlight, and any time-tagged objects. <gx:TimeSpan> and <gx:TimeStamp> are used within AbstractViews, and are contained within the Google extension namespace. For more information, please refer to the Time with AbstractViews section of the Time and Animation chapter.

Examples

The following examples illustrate different <Camera> rotations.

Heading

This example shows a <Camera> with a heading of 90 degrees (East) and a tilt of 90 degrees (looking toward the horizon). The Camera is placed at an altitude of 100 meters.

Tilt

The following example uses a <Camera> with a tilt equal to 90 degrees, which is looking toward the horizon. It uses default values for <heading>, <altitude>, <altitudeMode>, and <roll>.

The <Camera> does contain a <gx:TimeStamp> value; this affects historical imagery and sunlight, as well as the display of any time-tagged objects. In the image below, sunlight has been turned on and the <Camera> is viewing the location at 3:29pm, UTC on January 1st, 2009 (7:30am, local time).

Order of Transformations

The order of rotation is important. By default, the camera is looking straight down the −Z axis toward the Earth. Before rotations are performed, the camera is translated along the Z axis to <altitude>. The order of transformations is as follows:

<altitude> - translate along the Z axis to <altitude>

<heading> - rotate around the Z axis.

<tilt> - rotate around the X axis.

<roll> - rotate around the Z axis (again).

Note that each time a rotation is applied, two of the camera axes change their orientation.