# Documentation

## Working with the Globe Display

### What Is the Globe Display?

The Globe display is a three-dimensional view of geospatial data capable of mapping terrain relief or other data for an entire planet viewed from space. Its underlying transformation maps latitude, longitude, and elevation to a three-dimensional Cartesian frame. All Mapping Toolbox™ projections transform latitudes and longitudes to map x- and y-coordinates. The `globe` function is special because it can render relative relief of elevations above, below, or on a sphere. In Earth-centered Cartesian (x,y,z) coordinates, z is not an optional elevation; rather, it is an axis in Cartesian three-space. `globe` is useful for geospatial applications that require three-dimensional relationships between objects to be maintained, such as when one simulates flybys, and/or views planets as they rotate.

The Globe display is based on a coordinate transformation, and is not a map projection. While it has none of the distortions inherent in planar projections, it is a three-dimensional model of a planet that cannot be displayed without distortion or in its entirety. That is, in order to render the globe in a figure window, either a perspective or orthographic transformation must be applied, both of which necessarily involve setting a viewpoint, hiding the back side and distortions of shape, scale, and angles.

### The Globe Display Compared with the Orthographic Projection

The following example illustrates the differences between the two-dimensional orthographic projection, which looks spherical but is really flat, and the three-dimensional Globe display. Use the Rotate 3D tool to manipulate the display.

1. Load the `topo` data set and render it with an orthographic map projection:

```load topo axesm ortho; framem meshm(topo,topolegend);demcmap(topo)```
2. View the map obliquely:

`view(3); daspectm('m',1)`
3. You can view it in 3-D from any perspective, even from underneath. To visualize this, define a geolocated data grid with `meshgrat`, populate it with a constant z-value, and render it as a stem plot with `stem3m`:

```[latgrat,longrat] = meshgrat(topo,topolegend,[20 20]); stem3m(latgrat,longrat,500000*ones(size(latgrat)),'r') ```

Use the Rotate 3D tool on the figure window toolbar to change your viewpoint. No matter how you position the view, you are looking at a disc with stems protruding perpendicularly.

4. Create another figure using the Globe transform rather than orthographic projection:

```figure axesm('globe','Geoid',earthRadius)```
5. Display the `topo` surface in this figure and view it in 3-D:

```meshm(topo,topolegend); demcmap(topo) view(3)```
6. Include the stem plot to visualize the difference in surface normals on a sphere:

`stem3m(latgrat,longrat,500000*ones(size(latgrat)),'r')`
7. You can apply lighting to the display, but its location is fixed, and does not move as the camera position is shifted:

`camlight('headlight','infinite')`
8. If you prefer a more unobstructed view, hide the 3-D axes:

`set(gca,'Box','off')`

Here is a representative view using the Globe display with the headlight.

You can use the `LabelRotation` property when you use the Orthographic or any other Mapping Toolbox projection to align meridian and parallel labels with the graticule. Because the Globe display is not a true map projection and is handled differently internally, `LabelRotation` does not work with it.

For additional information on functions used in this example, see the reference pages for `view`, `camlight`, `meshgrat`, and `stem3m`.

### Using Opacity and Transparency in Globe Displays

Because Globe displays depict 3-D objects, you can see into and through them as long as no opaque surfaces (e.g., patches or surfaces) obscure your view. This can be particularly disorienting for point and line data, because features on the back side of the world are reversed and can overlay features on the front side.

Here is one way to create an opaque surface over which you can display line and point data:

1. Create a figure and set up a Globe display:

`figure; axesm('globe')`
2. Draw a graticule in a light color, slightly raised from the surface:

`gridm('GLineStyle','-','Gcolor',[.8 .7 .6],'Galtitude', .02)`
3. Load and plot the coast data in black, and set up a 3-D perspective:

```load coast plot3m(lat,long,.01,'k') view(3) axis off; zoom(2)```

4. Use the Rotate 3D tool on the figure's toolbar to rotate the view. Note how confusing the display is because of its transparency.

5. Make a uniform 1-by-1-degree grid and a referencing matrix for it:

```base = zeros(180,360); baseR = makerefmat('RasterSize', size(base), ... 'Latlim',[-90 90],'Lonlim',[0 360]); ```
6. Render the grid onto the globe, color it copper, light it from camera right, and make the surface reflect more light:

```hs = meshm(base,baseR,size(base)); colormap copper camlight right material([.8 .9 .4])```
 Note   Another way to make the surface of the globe one color is to change the `FaceColor` property of a displayed surface mesh (e.g., `topo`).

If you haven't rotated it, the display looks like this.

When you manually rotate this map, its movement can be jerky due to the number of vectors that must be redisplayed. In any position, however, the copper surface effectively hides all lines on the back side of the globe.

 Note   The technique of using a uniform surface to hide rear-facing lines has limitations for the display of patch symbolism (filled polygons). As patch polygons are represented as planar, in three-space the interiors of large patches can intersect the spherical surface mesh, allowing its symbolism to show through.

### Over-the-Horizon 3-D Views Using Camera Positioning Functions

You can create dramatic 3-D views using the Globe display. The `camtargm` and `camposm` functions (Mapping Toolbox functions corresponding to `camtarget` and `campos`) enable you to position focal point and a viewpoint, respectively, in geographic coordinates, so you do not need to deal with 3-D Cartesian figure coordinates.

In this exercise, you display coastlines from the `landareas` shapefile over topographic relief, and then view the globe from above Washington, D.C., looking toward Moscow, Russia.

1. Set up a Globe display and obtain topographic data for the map:

```figure axesm globe load topo```
2. Display `topo` without the vertical component (by omitting the fourth argument to `meshm`):

`meshm(topo, topolegend, size(topo)); demcmap(topo);`

The default view is from above the North Pole with the central meridian running parallel to the x-axis.

3. Add world coastlines from the global `landareas` shapefile and plot them in light gray:

```coastlines = shaperead('landareas',... 'UseGeoCoords', true, 'Attributes', {}); plotm([coastlines.Lat], [coastlines.Lon], 'Color', [.7 .7 .7])```
4. Read the coordinate locations for Moscow and Washington from the `worldcities` shapefile:

```moscow = shaperead('worldcities',... 'UseGeoCoords', true,... 'Selector',{@(name) strcmpi(name,'Moscow'), 'Name'}); washington = shaperead('worldcities',... 'UseGeoCoords', true,... 'Selector',{@(name) strcmpi(name,'Washington D.C.'),... 'Name'});```
5. Create a great circle track to connect Washington with Moscow and plot it in red:

```[latc,lonc] = track2('gc',... moscow.Lat, moscow.Lon, washington.Lat, washington.Lon); plotm(latc,lonc,'r')```
6. Point the camera at Moscow. Wherever the camera is subsequently moved, it always looks toward ```[moscow.Lat moscow.Lon]```:

`camtargm(moscow.Lat, moscow.Lon, 0)`
7. Station the camera above Washington. The third argument is an altitude in Earth radii:

`camposm(washington.Lat, washington.Lon, 3)`
8. Establish the camera up vector with the camera target's coordinates. The great circle joining Washington and Moscow now runs vertically:

`camupm(moscow.Lat, moscow.Lon)`
9. Set the field of view for the camera to 20º for the final view:

`camva(20)`
10. Add a light, specify a relatively nonreflective surface material, and hide the map background:

```camlight; material(0.6*[ 1 1 1]) hidem(gca)```

Here is the final view.

For additional information, see the reference pages for `extractm`, `camtargm`, `camposm`, `camupm`, `Globe`, and `camlight`.

### Displaying a Rotating Globe

Because the Globe display can be viewed from any angle without the need to recompute a projection, you can easily animate it to produce a rotating globe. If the displayed data is simple enough, such animations can be redrawn at relatively fast rates. In this exercise, you progressively add or replace features on a Globe display and rotate it under the control of a MATLAB® program that resets the view to rotate the globe from west to east in one-degree increments.

1. In the Mapping Toolbox editor, create a MATLAB program file containing the following code:

```% spin.m: Rotates a view around the equator one revolution % in 5-degree steps. Negative step makes it rotate normally % (west-to-east). for i=360:-5:0 view(i,23.5); % Earth's axis tilts by 23.5 degrees drawnow end```

Save this as `spin.m` in your current folder or on the Mapping Toolbox path. Note that the azimuth parameter for the figure does not have the same origin as geographic azimuth: it is 90 degrees to the west.

2. Set up a Globe display with a graticule, as follows:

`axesm('globe','Grid','on','Gcolor',[.7 .8 .9],'GlineStyle','-')`

The view is from above the North Pole.

3. Show the axes, but hide the edges of the figure's box, and view it in perspective rather than orthographically (the default perspective):

`set(gca, 'Box','off', 'Projection','perspective')`
4. Spin the globe one revolution:

`spin`

The globe spins rapidly. The last position looks like this.

5. To make the globe opaque, create a sea-level data grid as you did for the previous exercise, Using Opacity and Transparency in Globe Displays:

```base = zeros(180,360); baseref = [1 90 0]; hs = meshm(base,baseref,size(base)); colormap copper ```

The globe now is a uniform dark copper color with the grid overlaid.

6. Pop up the grid so it appears to float 2.5% above the surface. Prevent the display from stretching to fit the window with the `axis vis3d` command:

```setm(gca, 'Galtitude',0.025); axis vis3d```
7. Spin the globe again:

`spin`

The motion is slower, due to the need to rerender the 180-by-360 mesh: The last frame looks like this.

8. Get ready to replace the uniform sphere with topographic relief by deleting the copper mesh:

```clmo(hs) load topo```
9. Scale the elevations to have an exaggeration of 50 (in units of Earth radii) and plot the surface:

```topo = topo / (earthRadius('km')* 20); hs = meshm(topo,topolegend,size(topo),topo); demcmap(topo) ```
10. Show the Earth in space; blacken the figure background, turn off the three axes, and spin again:

```set(gcf,'color','black'); axis off; spin```

Here is a representative view, showing the Himalayas rising on the Eastern limb of the planet and the Andes on the Western limb.

11. You can apply lighting as well, which shifts as the planet rotates. Try the following settings, or experiment with others:

```camlight right lighting Gouraud; material ([.7, .9, .8])```

Here is the illuminated version of the preceding view:

For additional information, see the `globe`, `camlight`, and `view` reference pages.