siteviewer

Create Site Viewer map display for visualizing sites

expand all in page

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

example

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

example

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

expand all

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

Data Types: char | string

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

Map imagery used to visualize sites, specified as a one of the following:

  • 'satellite' - Satellite imagery provided by ESRI

  • 'streets' - Street maps provided by ESRI.

  • 'openstreetmap' - Street maps provided by OpenStreetMap.

  • 'darkwater' - Two-tone map with light gray for land and dark gray for water.

  • 'grayland' - Two-tone map with gray for land and white for water.

  • 'bluegreen' - Two-tone map with green for land and blue for water.

  • 'colorterrain' - Shaded relief map derived from elevation and climate.

  • 'grayterrain' - Shaded relief map in shades of gray.

  • 'landcover' - Shaded relief map derived from satellite data.

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

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

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

clearMapClear map visualizations
closeClose map viewer window

Examples

collapse all

Open Live Script

Create a default Site Viewer map display.

viewer = siteviewer;

Open Live Script

Launch a Site Viewer with streets basemap.

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

View a transmitter site on this map.

tx = txsite;
show(tx)

Open Live Script

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)
Open Live Script

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/.

Open Live Script

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.

See Also

| | | | |

Topics

Introduced in R2019b

Communications Toolbox Documentation

Support