camheading

Set or query heading angle of camera for geographic globe

collapse all in page

Syntax

camheading(g,heading)
camheading(g,'auto')
camheading(g,'manual')
outHeading = camheading(g)
outHeading = camheading(___)

Description

Set Heading and Mode

example

camheading(g,heading) sets the heading angle of the camera for the specified geographic globe. Setting the heading angle shifts the camera left or right. For more information about how camera rotations affect your view of the globe, see How Camera Orientation Affects Globe View.

Camera with double-headed arrow in front of lens, pointing left and right

camheading(g,'auto') sets the camera heading to automatic mode, enabling the geographic globe to determine the heading angle based on plotted data. The mode defaults to automatic when you create a geographic globe. If you interact with the globe using your mouse, then the mode switches to automatic.

example

camheading(g,'manual') sets the camera heading to manual mode, specifying that the geographic globe preserve the heading angle when the plotted data changes. If you change the heading angle using the camheading function, then the mode switches to manual.

Query Heading

example

outHeading = camheading(g) returns the heading angle of the camera.

outHeading = camheading(___) sets the heading angle or mode and then returns the heading angle of the camera. You can return the heading angle using any combination of input arguments from the previous syntaxes.

Examples

collapse all

Open Live Script

Create a geographic globe. Position the camera near Mount Kilimanjaro by specifying a latitude, longitude, and ellipsoidal height. Set the pitch angle to 0 degrees, so that the camera points across the summit.

uif = uifigure;
g = geoglobe(uif);
campos(g,-3.1519,37.3561,5500)
campitch(g,0)

By default, the heading angle is 360 degrees, which is equivalent to a heading angle of 0 degrees. Shift the camera to the right by changing the heading angle to 15 degrees.

camheading(g,15)

Open Live Script

Create a geographic globe. Position the camera at the top of Mount Washington by specifying a latitude, longitude, and ellipsoidal height. Change the pitch angle so that the camera faces the horizon instead straight down.

uif = uifigure;
g = geoglobe(uif);
campos(g,44.2700,-71.3038,2000)
campitch(g,0)

Animate the view by incrementally changing the heading angle. As the heading angle increases, the camera view shifts to the right.

for heading = 0:5:180
    camheading(g,heading)
    drawnow
end

Get the position and the heading, pitch, and roll angles of the camera. Use this information to control the view of a different geographic globe or to automate navigation.

Create a geographic globe. Navigate to an area of interest using your mouse or gestures. For this example, navigate to an area around Hawaii.

uif = uifigure;
g = geoglobe(uif);

Bird's-eye view of Hawaii

Query the latitude, longitude, and ellipsoidal height of the camera, and assign each to a variable.

[camlat,camlon,camh] = campos(g)

camlat =

   18.1781


camlon =

 -155.9297


camh =

   6.6664e+04

Query the heading, pitch, and roll angles of the camera, and assign each to a variable.

heading = camheading(g)
pitch = campitch(g)
roll = camroll(g)
heading =

   16.7613


pitch =

  -24.1507


roll =

  359.9977

Use these values to control the view of a different geographic globe. For example, create a new geographic globe and programmatically set the view.

uif2 = uifigure;
g2 = geoglobe(uif2);
campos(g2,camlat,camlon,camh)
camheading(g2,heading)
campitch(g2,pitch)
camroll(g2,roll)

Preserve the position and the heading, pitch, and roll angles of the camera by setting the camera modes to manual. If you do not set the camera modes to manual, then the camera view resets when you plot new data.

Import a sample route along roads in Massachusetts using the gpxread function. Create a geographic globe with a road map and no terrain data. Preserve the basemap and terrain settings by using the hold function. Then, navigate to an area near Eastern Massachusetts using your mouse.

track = gpxread('sample_tracks.gpx','Index',2);
lat = track.Latitude;
lon = track.Longitude;
height = track.Elevation;

uif = uifigure;
g = geoglobe(uif,'Basemap','streets','Terrain','none');
hold(g,'on')

Map of an area around Eastern Massachusetts with labeled cities and roads

Set the camera modes to manual and plot the data. Note that the camera position does not change.

campos(g,'manual')
camheight(g,'manual')
camheading(g,'manual')
campitch(g,'manual')
camroll(g,'manual')
geoplot3(g,lat,lon,height,'LineWidth',3)

The same map with a blue line plotted along several roads

Input Arguments

collapse all

Geographic globe, specified as a GeographicGlobe object.[1]

Heading angle of the camera, specified as a scalar value in the range [–360, 360] degrees.

More About

collapse all

How Camera Orientation Affects Globe View

The values of the camera heading, pitch, and roll angles affect your view of a geographic globe. Mapping Toolbox™ references these values to the globe using a north-east-down (NED) coordinate system. As a result, when the heading, pitch, and roll angles of the camera are zero, the camera sits on a plane that is parallel to the tangent plane of the globe at the current latitude and longitude. For more information about NED coordinate systems, see Choose a 3-D Coordinate System.

A camera positioned far above the Earth. The camera has three axes labeled xNorth, yEast, and zDown.

Change your view of a geographic globe by changing the heading, pitch, and roll angles of the camera:

  • Heading — Rotate the camera about its z-axis, which shifts the view left or right. Move the view to the right by increasing the heading angle.

  • Pitch — Rotate the camera about its y-axis, which tilts the view up or down. Tilt the view up by increasing the pitch angle.

  • Roll — Rotate the camera about its x-axis, which spins the camera around its lens. Spin the view counterclockwise by increasing the roll angle.

A camera with three axes labeled x, y, and z. The origin sits at the center of the camera lens.

Tips

  • When the pitch angle is near –90 (the default) or 90 degrees, the camera loses one rotational degree of freedom. As a result, when you change the roll angle, the heading angle may change instead. This phenomenon is called gimbal lock. To avoid the effects of gimbal lock, use the camheading function instead of the camroll function.

See Also

Functions

Topics

Introduced in R2020b

[1] Alignment of boundaries and region labels are a presentation of the feature provided by the data vendors and do not imply endorsement by MathWorks®.

Mapping Toolbox Documentation

Support