siteviewer

Create Site Viewer map display for visualizing sites

Description

Use the siteviewer object to create a map viewer for visualizing transmitter and receiver sites.

Note

• Site Viewer is a 3-D map display and requires hardware graphics support for WebGL™.

• This object only supports antenna sites with CoordinateSystem property set to 'geographic'.

Creation

Syntax

viewer = siteviewer

viewer = siteviewer(Name,Value)

Description

viewer = siteviewer creates a Site Viewer map display for visualizing transmitter or receiver sites.

viewer = siteviewer(Name,Value) creates a Site Viewer map display with properties specified by one or more name-value pairs. Properties you do not specify retain their default values.

Properties

Name — Caption to display on map viewer window

'Site Viewer' (default) | character vector | string scalar

Caption to display on map viewer window, specified as a character vector or a string scalar.

Data Types: char | string

Position — Size and location of map viewer window in pixels

four-element integer-valued vector

Size and location of map viewer window in pixels, specified as a four-element integer-valued vector in the form [left bottom width height]. The default value depends on the screen resolution such that the window lies in the center of the screen with a width of 800 pixels and a height of 600 pixels.

Data Types: double

Basemap — Map imagery used to visualize sites

'satellite' (default) | 'openstreetmap' | 'streets' | 'streets-light' | 'streets-dark' | 'topographic' | ...

Map imagery used to visualize sites, specified as one of the basemap names in this table or as a custom basemap defined using the addCustomBasemap function.

	'satellite' (default) Full global basemap composed of high-resolution satellite imagery. Hosted by Esri®.		'openstreetmap' Street map provided by OpenStreetMap®.
	'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.

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^®.

Data Types: char | string

Terrain — Data on which to visualize sites and perform terrain calculations

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

Data on which to visualize sites and perform terrain calculations, specified as a character vector or a scalar previously added using addCustomTerrain (Antenna Toolbox) or one of the following options:

• 'none' - Terrain elevation is 0 everywhere.

• 'gmted2010' - USGS GMTED2010 terrain data. This option requires an internet connection.

This property is read-only once the Site Viewer is created.

For limitations, see Limitations (Antenna Toolbox).

Data Types: char | string

Buildings — Name of OpenStreetMap (.osm) file to use as buildings data

string scalar | character vector

Name of the OpenStreetMap (.osm) file to use as buildings data, specified as a string scalar or a character vector. The file must be in the current directory, in a directory on the MATLAB path. You can also use a full or relative path to the file to specify the data. By default, this value is empty.

This property is read-only once the Site Viewer is created.

For limitations, see Limitations (Antenna Toolbox).

Data Types: char | string

Object Functions

clearMap	Clear map visualizations
close	Close map viewer window

Examples

Default Site Viewer Map Display

Create a default Site Viewer map display.

viewer = siteviewer;

View Transmitter Site On Site Viewer

Launch a Site Viewer with streets basemap.

viewer = siteviewer("Basemap","streets");

View a transmitter site on this map.

tx = txsite;
show(tx)

Compare Coverage Maps

Launch two Site Viewer windows.

One Site Viewer window uses the terrain model.

viewer1 = siteviewer("Terrain","gmted2010","Name","Site Viewer (Using Terrain)");

The second Site Viewer window does not use the terrain model.

viewer2 = siteviewer("Terrain","none","Name","Site Viewer (No Terrain)");

Create a transmitter site.

tx = txsite;

Generate a coverage map on each window. The map with terrain uses the Longley-Rice propagation model by default.

coverage(tx,"Map",viewer1)

The map without terrain uses the free-space model by default.

coverage(tx,"Map",viewer2)

Close the maps.

close(viewer1)
close(viewer2)

Site Viewer with Buildings

Launch siteviewer map window with basemap and buildings file for Manhattan. For more information about the osm file, see [1].

viewer = siteviewer("Basemap","openstreetmap",...
       "Buildings","manhattan.osm");

Show a transmitter site on a building.

tx = txsite("Latitude",40.7107,...
       "Longitude",-74.0114,...
       "AntennaHeight",50);
show(tx) 

Appendix

[1] The osm file is downloaded from https://www.openstreetmap.org, which provides access to crowd-sourced map data all over the world. The data is licensed under the Open Data Commons Open Database License (ODbL), https://opendatacommons.org/licenses/odbl/.

Add and Remove a Custom Basemap

Add a custom basemap to view locations on an OpenTopoMap® basemap, then remove the custom basemap from siteviewer.

Initialize simulation variables to:

• Define the name that you will use to specify your custom basemap.

• Specify the website that provides the map data. The first character of the URL indicates which server to use to get the data. For load balancing, the provider has three servers that you can use: a, b, or c.

• Create an attribution to display on the map that gives credit to the provider of the map data. Web map providers might define specific requirements for the attribution.

• Define a display name for the custom map.

name = 'opentopomap';
url = 'a.tile.opentopomap.org';
copyright = char(uint8(169));
attribution = copyright + "OpenStreetMap contributors";
displayName = 'Open Topo Map';

Use addCustomBasemap to load the custom basemap, and then create a siteviewer object that loads the custom basemap.

addCustomBasemap(name,url,'Attribution',attribution','DisplayName',displayName)
viewer = siteviewer('Basemap',name);

After a custom basemap is added to siteviewer, the custom map is available for future calls to siteviewer. Note the 'Open Topo Map' icon in the Imagery tab.

siteviewer;

Use removeCustomBasemap to remove the custom basemap from future calls to siteviewer. Note the 'Open Topo Map' icon is no longer available in the Imagery tab.

removeCustomBasemap(name)
siteviewer;

Limitations

Terrain

• Default terrain access requires Internet connection. If no internet connection exists, then Site Viewer automatically uses 'none' in the property Terrain.

• Custom DTED terrain files for use with addCustomTerrain (Antenna Toolbox) must be acquired outside of MATLAB for example by using USGS EarthExplorer.

• When using custom terrain, analysis is restricted to the terrain region. For example, an error occurs if trying to show a txsite or rxsite outside of the region.

Buildings

• OpenStreetMap files obtained from https://www.openstreetmap.org represent crowd-sourced map data, and the completeness and accuracy of the buildings data may vary depending on the map location.

• When downloading data from https://www.openstreetmap.org, select an export area larger than the desired area to ensure that all expected building features are fully captured. Building features at the edge of the selected export area may be missing.

• Building geometry and features are interpreted from the file according to the recommendations of OpenStreetMap for 3D buildings.