addCustomBasemap

Add custom basemap

Since R2022a

collapse all in page

Syntax

addCustomBasemap(basemapName,URL)
addCustomBasemap(___,Name=Value)

Description

addCustomBasemap(basemapName,URL) adds the custom basemap specified by URL to the list of basemaps available for use with mapping functions. basemapName is the name you choose to call the custom basemap. Added basemaps remain available for use in future MATLAB® sessions.

addCustomBasemap(___,Name=Value) specifies name-value arguments that set additional parameters of the basemap.

Examples

collapse all

Open Live Script

This example shows how to register and switch between custom basemaps in satelliteScenarioViewer while visualizing a satellite scenario.

Register and use NASA VIIRS City Lights Basemap.

addCustomBasemap("viirs", ...
    "https://gitc.earthdata.nasa.gov/wmts/epsg3857/best/VIIRS_CityLights_2012/default/GoogleMapsCompatible_Level8/${z}/${y}/${x}.jpg", ...
    Attribution = "Imagery provided by services from NASA's Global Imagery Browse Services (GIBS)", ...
    MaxZoomLevel = 8);

sc = satelliteScenario;

Re = 6378.137e3; % Earth's radius in meters

perigee = Re + 300e3;    % Perigee altitude: 300 km
apogee  = Re + 16800e3;  % Apogee altitude: 16800 km

a = (perigee + apogee) / 2; % Semi-major axis (meters)
e = (apogee - perigee) / (apogee + perigee); % Eccentricity
inclination = 63.4;    % degrees
raan = 0;              % Right ascension of ascending node, degrees
argPeriapsis = 270;    % Argument of periapsis, degrees
trueAnomaly = 0;       % degrees

sat = satellite(sc, a, e, inclination, raan, argPeriapsis, trueAnomaly);

Add a ground station at Natick, MA.

gs = groundStation(sc, 42.283, -71.35, Name = "Natick, MA");

Add access analysis between satellite and ground station.

ac = access(sat, gs);

Visualize scenario with the NASA VIIRS City Lights basemap.

viewer1 = satelliteScenarioViewer(sc, Basemap = "viirs", Name = "NASA VIIRS City Lights Basemap");

Show ground track for 6 hours.

groundTrack(sat, LeadTime = 3*3600, TrailTime = 3*3600);
play(sc, PlaybackSpeedMultiplier = 1000);

Delete the viewer, remove VIIRS Basemap, and register OpenStreetMap.

delete(viewer1);
removeCustomBasemap("viirs");

addCustomBasemap("osm", ...
    "https://tile.openstreetmap.org/${z}/${x}/${y}.png", ...
    Attribution = "© OpenStreetMap contributors");

viewer2 = satelliteScenarioViewer(sc, Basemap = "osm", Name = "OpenStreetMap Basemap");
play(sc, PlaybackSpeedMultiplier = 1000);

Input Arguments

collapse all

Name used to identify basemap programmatically, specified as a string scalar or character vector.

Example: "opentopomap"

Data Types: string | char

Parameterized map URL, specified as a string scalar or character vector.

The parameterized map URL typically includes:

  • The URL of the basemap tiles.

  • An index of the map tiles, formatted as ${z}/${x}/${y} or ${z}/${y}/${z}, where z is the tile zoom level, x is the tile column index, and y is the tile row index.

  • The file format of the map tiles. The addCustomBasemap function can read tiles in image formats supported by the imread function. Depending on the data provider, map tiles are available in different file formats.

The way you structure this argument can depend on the data provider. For more information about how to structure a URL, see Examples or ask your data provider.

Example: "https://hostname/${z}/${y}/${x}.png"

Example: "https://hostname/${z}/${x}/${y}/png"

Data Types: string | char

Name-Value Arguments

collapse all

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: addCustomBasemap(basemapName,URL,Attribution="My attribution") specifies the attribution for the custom basemap.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: addCustomBasemap(basemapName,URL,"Attribution","My attribution") specifies the attribution for the custom basemap.

Attribution of the custom basemap, specified as a string scalar, string array, character vector, or cell array of character vectors. To create a multiline attribution, specify a string array or a nonscalar cell array of character vectors.

When you create a custom basemap from a URL, the default attribution is 'Tiles courtesy of DOMAIN_NAME_OF_URL', where DOMAIN_NAME_OF_URL is the domain name from the URL input argument. If the host is 'localhost', or if URL contains only IP numbers, specify the attribution as an empty string ("").

Example: "Credit: U.S. Geological Survey"

Data Types: string | char | cell

Display name of the custom basemap, specified as a string scalar or character vector.

Example: "OpenTopoMap"

Data Types: string | char

Maximum zoom level of the basemap, specified as an integer in the range [0, 25].

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

Map is deployable using MATLAB Compiler, specified as a numeric or logical 0 (false) or 1 (true).

Data Types: logical

Tips

  • You can find tiled web maps from various vendors, such as OpenStreetMap®, the USGS National Map, Mapbox, DigitalGlobe, Esri® ArcGIS Online, the Geospatial Information Authority of Japan (GSI), and HERE Technologies. Abide by the map vendors terms-of-service agreement and include accurate attribution with the maps you use.

  • Mapping Toolbox™ enables additional strategies for adding custom basemaps. For example, you can add custom basemaps from vector basemaps hosted by Esri, from MBTiles files, or from georeferenced images. Several of these strategies do not require internet access. For more information, see addCustomBasemap (Mapping Toolbox) and Use Basemaps in Offline Environments (Mapping Toolbox).

  • To access a list of available basemaps, press Tab before specifying the basemap in your plotting function. This image shows a sample list of available basemaps, including several custom basemaps from the USGS National Map.

    Plotting function in Aerospace Toolbox with list of available basemaps to select from

Version History

Introduced in R2022a

See Also

| | (Mapping Toolbox) | (Mapping Toolbox)

Topics