Use Basemaps in Offline Environments

Provide geographic context for your maps by displaying data over a basemap, also called a base layer. MathWorks^® provides a variety of basemaps, including low-resolution two-tone options created using Natural Earth and high-zoom-level options hosted by Esri^®. For a list of basemap options, see the basemap argument of the geobasemap function.

Most of these basemaps require internet access, including the default basemap. If you do not have reliable access to the internet, you can use strategies such as downloading a selection of basemaps onto your local system or displaying data over the "darkwater" basemap. Some strategies require MATLAB^® to have temporary internet access and other strategies do not require MATLAB to have internet access. Different strategies support different types of map displays.

Internet Access Requirement for MATLAB	Strategy	Supported Map Displays
Temporary Internet Access	Download basemaps onto your local system	Objects with a Basemap property, for example: Geographic axes Geographic globes Site Viewer (Communications Toolbox™, Antenna Toolbox™) Satellite Scenario Viewer (Satellite Communications Toolbox)
	Use cached basemap tiles	Geographic axes Geographic bubble charts
	Use a spatially referenced image from a web source	Axes (mapshow) axesm-based maps (geoshow)
No Internet Access	Create a basemap from an MBTiles file	Objects with a Basemap property
	Create a basemap from an image	Objects with a Basemap property
	Use a basemap installed with MATLAB®	Objects with a Basemap property
	Use a spatially referenced image from a file	Axes (mapshow) axesm-based maps (geoshow)
	Use spatially referenced vector data from a file	Map axes (geoplot) Geographic axes (geoplot) Axes (mapshow) axesm-based maps (geoshow)

Temporary Internet Access

These strategies require MATLAB to temporarily access the internet. When MATLAB is in an online environment, you can save the basemap data to your local system. Then, when MATLAB is in an offline environment, you can load the saved basemap data.

• Download basemaps onto your local system

• Use cached basemap tiles

• Use a spatially referenced image from a web source

Download basemaps onto your local system

When you have internet access, you can download the basemaps created using Natural Earth onto your local system. The basemaps hosted by Esri are not available for download. Then, when you are in an offline environment, you can use the downloaded basemaps.

Download basemaps using the Add-On Explorer.

1. On the MATLAB Home tab, in the Environment section, click Add-Ons and then Get Add-Ons.

2. In the Add-On Explorer, scroll to the MathWorks Optional Features section, and click Show All to find the basemap add-ons. You can also search for the basemap add-ons by name, or click Optional Features in Filter by Type.

3. Select the basemap add-ons that you want to download.

These are the names of the basemap add-ons and their associated basemap argument names.

• MATLAB Basemap Data - bluegreen ("bluegreen")

• MATLAB Basemap Data - grayland ("grayland")

• MATLAB Basemap Data - colorterrain ("colorterrain")

• MATLAB Basemap Data - grayterrain ("grayterrain")

• MATLAB Basemap Data - landcover ("landcover")

Use cached basemap tiles

When you view a basemap over the internet, MATLAB temporarily caches the basemap tiles. If you lose your internet connection, you can still view the cached basemap tiles.

When you are in an offline environment and attempt to view basemap tiles that you have not previously viewed, MATLAB issues a warning and displays different tiles depending on the type of basemap. When you attempt to view tiles created using Natural Earth, MATLAB displays "darkwater" tiles. When you attempt to view tiles from a custom basemap or tiles hosted by Esri, you see missing map tiles.

Cached basemap tiles have these limitations:

• MATLAB stores the cached tiles in a temporary folder. Your operating system can delete the temporary folder.

• The cached tiles can expire.

• MATLAB caches custom basemap tiles for only the current MATLAB session.

Use a spatially referenced image from a web source

When you have internet access, you can read an image from a basemap or a Web Map Service (WMS) server as a spatially referenced image and save the image as a MAT or GeoTIFF file. Then, when you are in an offline environment, you can load the image from the file and use it as a base layer for your data.

Read and save an image from a basemap

Read satellite imagery for Boston into the workspace as an array, a map cells reference object, and an attribution by using the readBasemapImage function.

[A1,R1,attrib1] = readBasemapImage("satellite",[42.3453 42.3711],[-71.099 -71.0454]);

Save the imagery as a GeoTIFF file by using the geotiffwrite function.

• The readBasemapImage function spatially references the image using the Web Mercator projected coordinate reference system (CRS) with EPSG code 3857. Specify the CRS code by using the CoordRefSysCode name-value argument.

• Include the attribution by specifying the ImageDescription TIFF tag.

tag = struct("ImageDescription",attrib1);
geotiffwrite("satelliteBoston.tif",A1,R1,CoordRefSysCode=3857,TiffTags=tag)

To use the basemap data, load the GeoTIFF file and attribution.

[A2,R2] = readgeoraster("satelliteBoston.tif");
info = imfinfo("satelliteBoston.tif");
attrib2 = info.ImageDescription;

Display the data on a map. Use the mapshow function when the reference object is a map reference object and use the geoshow function when the reference object is a geographic reference object.

figure
mapshow(A2,R2)
title("Boston Imagery from Basemap")
subtitle("Attribution: " + attrib2)
axis off

For more information about displaying data over basemaps images in offline environments, see Display Data over Basemaps When Internet Access Is Intermittent.

Read and save an image from a WMS server

WMS servers provide publicly accessible geospatial data from web-based sources. Search the WMS Database for orthoimagery from the USGS National Map.

usgs = wmsfind("basemap.nationalmap",SearchFields="ServerURL");
imagery = refine(usgs,"USGSImageryOnly",SearchFields="ServerURL");
imagery = wmsupdate(imagery);

Read orthoimagery for an area in Boston and save it as a GeoTIFF file.

[A3,R3] = wmsread(imagery,Latlim=[42.3453 42.3711],Lonlim=[-71.099 -71.0454]);
geotiffwrite("usgsImageryLayer.tif",A3,R3)

To use the WMS orthoimagery, load the GeoTIFF file and display it on a map.

[A4,R4] = readgeoraster("usgsImageryLayer.tif");
figure
usamap(A4,R4)
geoshow(A4,R4)
title("Boston Imagery from WMS Server")
subtitle("Attribution: USGS National Map")

For more information about creating WMS maps in offline environments, see Create WMS Maps When Internet Access Is Intermittent.

No Internet Access

These strategies do not require MATLAB to access the internet.

• Create a basemap from an MBTiles file

• Create a basemap from an image

• Use "darkwater" basemap installed with MATLAB

• Use a spatially referenced image from a file

• Use spatially referenced vector data from a file

Create a basemap from an MBTiles file

When you are in an offline environment, you can use the addCustomBasemap function to create a custom basemap from an MBTiles file.

MBTiles files can contain raster or vector map tiles. If you do not know whether your MBTiles file contains raster or vector map tiles, check with your data provider.

• Raster map tiles are useful for displaying satellite imagery and orthoimagery. You can write raster data to an MBTiles file by using the mbtileswrite function.

• Vector map tiles enable you to customize the appearance of the basemap and typically include higher zoom levels than raster map tiles. For information about customizing the appearance of vector basemaps, see Customize Appearance of Vector Basemaps.

Create a basemap from a raster MBTiles file

Mapping Toolbox™ includes a raster MBTiles file with low-resolution USGS imagery called usgsimagery.mbtiles. Create a custom basemap from the file and display it using a geographic globe. Position the camera 3200 kilometers above Boston.

addCustomBasemap("usgsimagery","usgsimagery.mbtiles")

uif = uifigure;
g = geoglobe(uif);
geobasemap(g,"usgsimagery")
campos(g,42.3582,-71.0722,3200000) 

Create a basemap from a vector MBTiles file

(Since R2023a)

Mapping Toolbox includes a vector MBTiles file, naturalearth.mbtiles, with low-zoom levels of region and land boundaries. Create a custom basemap from the file. Specify the appearance of the basemap, including the colors and fonts, using a predefined topographic style. Predefined styles do not require internet access. For information about vector basemap styles, including limitations in offline environments, see the Style argument on the addCustomBasemap reference page.

addCustomBasemap("naturalearth","naturalearth.mbtiles",Style="topographic")

Display the custom basemap using a geographic axes.

figure
geobasemap naturalearth
geolimits([40.1951 47.8433],[-77.5238 -64.0377])
title("Northeast United States with Vector MBTiles Basemap")
subtitle("Attribution: Natural Earth")

Create a basemap from an image

When you are in an offline environment, you can use the addCustomBasemap function to create a custom basemap from a spatially referenced raster image. The function you use to read the image into the workspace depends on the file format.

• Read images in formats such as GeoTIFF by using the readgeoraster function.

• Read images in formats that are associated with a world file, such as TIFF, JPEG, or PNG, by using the imread and worldfileread functions.

Read a GeoTIFF image of Boston into the workspace as an array and a map cells reference object. The array is a grid of cells referenced to projected coordinates.

[A5,R5] = readgeoraster("boston.tif");

Add a custom basemap from the array and reference object. The addCustomBasemap function issues a warning because the array and reference object do not specify global data for zoom level 0.

addCustomBasemap("bostonBasemap",A5,R5)

Warning: File does not contain global data for zoom level 0.

Create a map using the limits of the imagery. Calculate the latitude and longitude limits by unprojecting the xy-limits that are stored in the reference object.

xlimits = R5.XWorldLimits;
ylimits = R5.YWorldLimits;
projcrs = R5.ProjectedCRS;
[latlim,lonlim] = projinv(projcrs,xlimits,ylimits);

figure
geolimits(latlim,lonlim)

Change the basemap to the custom basemap. The black background indicates areas where the basemap tile contains no data.

geobasemap bostonBasemap

Use "darkwater" basemap installed with MATLAB

MATLAB includes the "darkwater" basemap, a two-tone land-ocean map with light gray land areas and dark grey water areas. Using the "darkwater" basemap does not require internet access.

Display the "darkwater" basemap using a geographic axes. Center the map over the northeast United States.

figure
geobasemap darkwater
geolimits([40.1951 47.8433],[-77.5238 -64.0377])
title("Northeast United States with Darkwater Basemap")
subtitle("Attribution: Natural Earth")

Use a spatially referenced image from a file

When you are in an offline environment, you can read a spatially referenced raster image from a file and then use it as a base layer for your data. The function you use to read the data depends on the file format.

• Read images in formats such as GeoTIFF by using the readgeoraster function.

• Read images in formats that are associated with a world file, such as TIFF, JPEG, or PNG, by using the imread and worldfileread functions.

Read a GeoTIFF image of Boston into the workspace as an array and a map cells reference object. Then, display the image on a map. Use the mapshow function when the reference object is a map reference object and use the geoshow function when the reference object is a geographic reference object.

[A6,R6] = readgeoraster("boston.tif");
figure
mapshow(A6,R6)
title("Boston Imagery from GeoTIFF File")
subtitle("Attribution: GeoEye")

Use spatially referenced vector data from a file

When you are in an offline environment, you can read spatially referenced vector data from a file and then use it as a base layer for your data. Read vector data in formats such as shapefile by using the readgeotable function.

Mapping Toolbox™ includes a shapefile with world land areas called landareas.shp. Read the land areas into the workspace as a geospatial table. Then, display the land areas on a world map.

GT = readgeotable("landareas.shp");

figure
worldmap world
geoshow(GT)
title("World Land Areas from Shapefile")

Mapping Toolbox™ includes shapefiles with high- and low-resolution US state boundaries called usastatehi.shp and usastatelo.shp, respectively. Read the high-resolution state boundaries into the workspace as a geospatial table. Clip the boundaries to include only the northeast states.

GT = readgeotable("usastatehi.shp");
ne = geoclip(GT.Shape,[40.1951 47.8433],[-77.5238 -64.0377]);

Display the boundaries using a geographic axes. To prevent MATLAB from using the basemaps provided by MathWorks, set the basemap to "none".

figure
geobasemap none
hold on
geoplot(ne)
title("Northeast United States from Shapefile")

For an example that shows how to create a base layer from data stored in an OpenStreetMap® file, see Create Base Layer from OpenStreetMap Data.