GeographicGlobe

Control geographic globe appearance and behavior

Since R2020a

Description

Use a geographic globe to plot 3-D lines and markers over basemaps and terrain.

Creation

Create a geographic globe object using the geoglobe function.

Properties

Maps

Basemap — Map to plot data on

'satellite' (default) | 'streets' | 'streets-light' | 'streets-dark' | custom basemap | ...

Map on which to plot data, specified as one of the values listed in the table. Six of the basemaps in the table are tiled data sets created using Natural Earth. Five of the basemaps are high-zoom-level maps hosted by Esri^®.

	'satellite' (default) Full global basemap composed of high-resolution satellite imagery. Hosted by Esri.		'streets' General-purpose road map that emphasizes accurate, legible styling of roads and transit networks. Hosted by Esri.
	'streets-light' Map designed to provide geographic context while highlighting user data on a light background. Hosted by Esri.		'streets-dark' Map designed to provide geographic context while highlighting user data on a dark background. Hosted by Esri.
	'topographic' General-purpose map with styling to depict topographic features. Hosted by Esri.		'landcover' Map that combines satellite-derived land cover data, shaded relief, and ocean-bottom relief. The light, natural palette is suitable for thematic and reference maps. Created using Natural Earth.
	'colorterrain' Shaded relief map blended with a land cover palette. Humid lowlands are green and arid lowlands are brown. Created using Natural Earth.		'grayterrain' Terrain map in shades of gray. Shaded relief emphasizes both high mountains and micro-terrain found in lowlands. Created using Natural Earth.
	'bluegreen' Two-tone, land-ocean map with light green land areas and light blue water areas. Created using Natural Earth.		'grayland' Two-tone, land-ocean map with gray land areas and white water areas. Created using Natural Earth.
	'darkwater' Two-tone, land-ocean map with light gray land areas and dark gray water areas. This basemap is installed with MATLAB®. Created using Natural Earth.	Not applicable.	Custom basemap added using the addCustomBasemap function.

All basemaps except 'darkwater' require Internet access. The 'darkwater' basemap is included with MATLAB and Mapping Toolbox™.

If you do not have consistent access to the Internet, you can download the basemaps created using Natural Earth onto your local system by using the Add-On Explorer. The basemaps hosted by Esri are not available for download. For more about downloading basemaps and changing the default basemap on your local system, see Access Basemaps and Terrain for Geographic Globe.

The basemaps hosted by Esri update periodically. As a result, you might see differences in your visualizations over time.

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

Example: g = geoglobe(uifigure,'Basemap','bluegreen')

Example: g.Basemap = 'bluegreen'

Data Types: char | string

Terrain — Terrain data

'gmted2010' (default) | 'none' | string scalar | character vector

Terrain data, specified as one of these values:

• 'gmted2010' – Global terrain derived from the GMTED2010 model created by the U.S. Geological Survey (USGS) and National Geospatial-Intelligence Agency (NGA).

• 'none' - No terrain.

• string scalar or character vector – Name of custom terrain added using the addCustomTerrain function.

Multiple Plots

ColorOrder — Color order

seven predefined colors (default) | three-column matrix of RGB triplets

Color order for lines plotted on the globe, specified as a three-column matrix of RGB triplets. This property defines the palette of colors MATLAB uses to create plot objects such as lines. Each row of the array is an RGB triplet. An RGB triplet is a three-element vector whose elements specify the intensities of the red, green, and blue components of a color. The intensities must be in the range [0, 1]. This table lists the default colors.

Colors	ColorOrder Matrix
	[ 0 0.4470 0.7410 0.8500 0.3250 0.0980 0.9290 0.6940 0.1250 0.4940 0.1840 0.5560 0.4660 0.6740 0.1880 0.3010 0.7450 0.9330 0.6350 0.0780 0.1840]

MATLAB assigns colors to objects according to their order of creation. For example, when plotting lines, the first line uses the first color, the second line uses the second color, and so on. If there are more lines than colors, then the cycle repeats.

Change the color order in either of the following ways:

• Call the colororder function to change the color order for all globe objects in a UI figure. The colors of existing plots in the UI figure update immediately. If you place additional globe objects into the figure, those globe objects also use the new color order. If you continue to call plotting commands, those commands also use the new colors.

• Set the ColorOrder property on the globe, call the hold function to set the globe hold state to 'on', and then call the desired plotting functions. This is like calling the colororder function, but in this case you are setting the color order for the specific globe, not the entire UI figure. Setting the hold state to 'on' is necessary to ensure that subsequent plotting commands do not reset the globe to use the default color order.

NextSeriesIndex — SeriesIndex value for next object

whole number

This property is read-only.

SeriesIndex value for the next plot object added to the globe, returned as a whole number greater than or equal to 0. This property is useful when you want to track how the objects cycle through the colors in the color order. This property maintains a count of the objects in the globe that have a SeriesIndex property. MATLAB uses it to assign the value of the SeriesIndex property for each new object. The count starts at 1 when you create the globe, and it increases by 1 for each additional object. Thus, the count is typically n+1, where n is the number of objects in the globe.

NextPlot — Properties to reset

'replace' (default) | 'add' | 'replacechildren' | 'replaceall'

Properties to reset when adding a new plot to the globe, specified as one of these values:

• 'add' — Add new plots to the existing globe. Do not delete existing plots or reset globe properties before displaying the new plot.

• 'replacechildren' — Delete existing plots before displaying the new plot. Reset the ColorOrderIndex property to 1, but do not reset other globe properties. The next plot added to the globe uses the first color based on the ColorOrder property.

• 'replace' — Delete existing plots and reset globe properties, except Position, Units, Basemap, and Terrain, to their default values before displaying the new plot.

• 'replaceall' — Delete existing plots and reset globe properties, except Position and Units, to their default values before displaying the new plot.

Position

Position — Size and location

[0 0 1 1] (default) | four-element vector of form [left bottom width height]

Size and location, specified as a four-element vector of the form [left bottom width height]. By default, MATLAB measures the values in units normalized to the container. To change the units, set the Units property.

• The left and bottom elements define the distance from the lower left corner of the container UI figure, panel, or tab to the lower left corner of the position boundary.

• The width and height elements are the position boundary dimensions.

Units — Position units

'normalized' (default) | 'inches' | 'centimeters' | 'points' | 'pixels' | 'characters'

Position units, specified as one of these values.

Units	Description
'normalized' (default)	Units normalized with respect to the container, which is typically the figure or a panel. The lower left corner of the container is (0,0) and the upper right corner is (1,1).
'inches'	Inches.
'centimeters'	Centimeters.
'characters'	Units based on the default uicontrol font of the graphics root object: The character width is the width of the letter x. The character height is the distance between the baselines of two lines of text.
'points'	Typography points. One point equals 1/72 inch.
'pixels'	Pixels. Distances in pixels are independent of your system resolution on Windows® and Macintosh systems. On Windows systems, a pixel is 1/96th of an inch. On Macintosh systems, a pixel is 1/72nd of an inch. On Linux® systems, the size of a pixel is determined by your system resolution.

When specifying the units as a name-value pair during object creation, specify the Units name-value pair before specifying name-value pairs that use those units, for example Position.

Interactivity

Visible — State of visibility

'on' (default) | on/off logical value

State of visibility, specified as 'on' or 'off', or as numeric or logical 1 (true) or 0 (false). A value of 'on' is equivalent to true, and 'off' is equivalent to false. Thus, you can use the value of this property as a logical value. The value is stored as an on/off logical value of type matlab.lang.OnOffSwitchState.

• 'on' — Display the object.

• 'off' — Hide the object without deleting it. You still can access the properties of an invisible object.

Parent/Child

Parent — Parent container

Figure object created using uifigure | Panel object | Tab object

Parent container, specified as a Figure object created using the uifigure function, a Panel object within a UI figure, or a Tab object within a UI figure.

Children — Children

empty GraphicsPlaceholder array | array of Line objects

Children, returned as an array of graphics objects. Use this property to view a list of the children or to reorder the children by setting the property to a permutation of itself.

You cannot add or remove children using the Children property. To add a child to this list, set the Parent property of the child graphics object to the GeographicGlobe object.

HandleVisibility — Visibility of object handle

'on' (default) | 'off' | 'callback'

Visibility of the object handle in the Children property of the parent, specified as one of these values:

• 'on' — Object handle is always visible.

• 'off' — Object handle is invisible at all times. This option is useful for preventing unintended changes by another function. Set the HandleVisibility to 'off' to temporarily hide the handle during the execution of that function.

• 'callback' — Object handle is visible from within callbacks or functions invoked by callbacks, but not from within functions invoked from the command line. This option blocks access to the object at the command line, but permits callback functions to access it.

If the object is not listed in the Children property of the parent, then functions that obtain object handles by searching the object hierarchy or querying handle properties cannot return it. Examples of such functions include the get, findobj, gca, gcf, gco, newplot, cla, clf, and close functions.

Hidden object handles are still valid. Set the root ShowHiddenHandles property to 'on' to list all object handles regardless of their HandleVisibility property setting.

Identifiers

Type — Type of graphics object

'globe'

This property is read-only.

Type of graphics object returned as 'globe'.

Tag — Object identifier

'' (default) | character vector | string scalar

Object identifier, specified as a character vector or string scalar. You can specify a unique Tag value to serve as an identifier for an object. When you need access to the object elsewhere in your code, you can use the findobj function to search for the object based on the Tag value.

UserData — User data

[] (default) | array

User data, specified as any MATLAB array. For example, you can specify a scalar, vector, matrix, cell array, character array, table, or structure. Use this property to store arbitrary data on an object.

If you are working in App Designer, create public or private properties in the app to share data instead of using the UserData property. For more information, see Share Data Within App Designer Apps.

Object Functions

Change Hold State and Basemap

hold

These hold syntaxes are supported for geographic globe objects: hold(g,'on') retains plots in the globe g so that new plots do not delete existing plots. New plots use the next color based on the ColorOrder property of the globe. MATLAB adjusts the camera line of sight to display the full range of data. hold(g,'off') sets the hold state to off so that new plots added to the globe clear existing plots and reset all globe properties, excluding terrain and basemaps, to their default values. The next plot added to the globe uses the first color based on the ColorOrder property of the globe. This option is the default behavior. hold(g) toggles the hold state between on and off.

geobasemap

This geobasemap syntax is supported for geographic globe objects: geobasemap(g,basemap) sets the basemap for the globe specified by g. For example, geobasemap(g,'topographic') sets the basemap to a general-purpose map with styling to depict topographic features. For a list of basemaps, see the Basemap property.

Change View

campos	Set or query position of camera for geographic globe
camheight	Set or query height of camera for geographic globe
camheading	Set or query heading angle of camera for geographic globe
campitch	Set or query pitch angle of camera for geographic globe
camroll	Set or query roll angle of camera for geographic globe

Examples

Display Geographic Globe

Display a geographic globe in a figure created using the uifigure function.

uif = uifigure;
g = geoglobe(uif);

Version History

Introduced in R2020a

R2023b: Some basemaps have improved appearance at high zoom levels

The "streets-light", "streets-dark", "streets", and "topographic" basemaps hosted by Esri have an improved visual appearance at high zoom levels. For example, this image compares a basemap at zoom level 21 in R2023a with the same basemap and zoom level in R2023b.

The basemaps can also have different appearances at other zoom levels. For example, this image compares a basemap at zoom level 15 in R2023a with the same basemap and zoom level in R2023b.

R2022b: When NextPlot is 'replace', adding new plots to geographic globe does not reset basemap or terrain

When the value of the NextPlot property is 'replace', adding new plots does not reset the Basemap or Terrain properties. As a result, when you add a plot to a geographic globe by using the geoplot3 function, MATLAB does not reset the basemap or terrain. In R2022a and earlier releases, the basemap and terrain reset when you add new plots.

As a result, you can specify the basemap or terrain and then visualize data without using the hold function. For example, this code creates a globe using the "streets" basemap and no terrain data. Then, it displays a plot and adjusts the camera view. In R2022b, the basemap and terrain do not reset. In R2022a and earlier releases, the basemap reset to the default "satellite" and the terrain reset to the default "gmted2010".

lat = [42.3501 42.3515 42.3598 42.3584 42.3529 42.3626];
lon = [-71.0870 -71.0926 -71.0662 -71.0598 -71.0662 -71.0789];

uif = uifigure;
g = geoglobe(uif,Basemap="streets",Terrain="none");

p = geoplot3(g,lat,lon,0,"ro",LineWidth=3);
campos(g,42.33,-71.0756,2113)
campitch(g,-42.2458)

This change does not affect existing code that sets the hold state to "on" between commands.

To reset the basemap and terrain, set the Basemap and Terrain properties to the defaults after you create the plot.

g.Basemap = "satellite";
g.Terrain = "gmted2010";

For more information about changing the basemap and terrain of geographic globes, see Access Basemaps and Terrain for Geographic Globe.