Main Content

siteviewer

Create Site Viewer

Since R2019b

expand all in page

Description

Display transmitter sites, receiver sites, and RF propagation visualizations by using a siteviewer object. By default, Site Viewer displays a 3-D view of the globe. When you display sites on the globe, they are referenced to geographic coordinates. You can customize the globe using custom terrain, high-zoom-level or custom basemaps, and buildings.

You can also import and view 3-D models represented by standard tessellation language (STL) files or triangulation objects. When you display sites on a 3-D model, they are referenced to Cartesian coordinates.

Site Viewer requires hardware graphics support for WebGL™.

Creation

Syntax

viewer = siteviewer
viewer = siteviewer(Name,Value)

Description

example

viewer = siteviewer creates a Site Viewer.

example

viewer = siteviewer(Name,Value) specifies Site Viewer properties using name-value arguments. For example, import and view a 3-D model file by using the SceneModel name-value argument.

Properties

expand all

Site Viewer

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

This property is read-only.

Coordinate reference system, specified as 'geographic' or 'cartesian'. The value of CoordinateSystem depends on how you create the Site Viewer.

  • By default, the value of CoordinateSystem is 'geographic' and visualizations are referenced to the WGS84 reference ellipsoid.

  • When you create the Site Viewer by specifying the SceneModel argument, the value of CoordinateSystem is 'cartesian' and the coordinates are defined by the origin of the 3-D model.

When CoordinateSystem is 'geographic', you can view the latitude and longitude coordinates for a location by right-clicking the map and selecting Show Location. To remove the location, right-click and select Remove Location.

Data Types: char | string

Geographic Coordinate System

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' basemap.

'satellite' (default)

Full global basemap composed of high-resolution satellite imagery.

Hosted by Esri®.

'openstreetmap' basemap.

'openstreetmap'

Street map provided by OpenStreetMap®.

'streets' basemap.

'streets'

General-purpose road map that emphasizes accurate, legible styling of roads and transit networks.

Hosted by Esri.

'streets-light' basemap.

'streets-light'

Map designed to provide geographic context while highlighting user data on a light background.

Hosted by Esri.

'streets-dark' basemap.

'streets-dark'

Map designed to provide geographic context while highlighting user data on a dark background.

Hosted by Esri.

'topographic' basemap.

'topographic'

General-purpose map with styling to depict topographic features.

Hosted by Esri.

'landcover' basemap.

'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' basemap.

'colorterrain'

Shaded relief map blended with a land cover palette. Humid lowlands are green and arid lowlands are brown.

Created using Natural Earth.

'grayterrain' basemap.

'grayterrain'

Terrain map in shades of gray. Shaded relief emphasizes both high mountains and micro-terrain found in lowlands.

Created using Natural Earth.

'bluegreen' basemap.

'bluegreen'

Two-tone, land-ocean map with light green land areas and light blue water areas.

Created using Natural Earth.

'grayland' basemap.

'grayland'

Two-tone, land-ocean map with gray land areas and white water areas.

Created using Natural Earth.

'darkwater' basemap.

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

This property applies only when CoordinateSystem is 'geographic'.

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 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 applies only when CoordinateSystem is 'geographic'.

This property is read-only after you create the Site Viewer.

For limitations, see Limitations.

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 applies only when CoordinateSystem is 'geographic'.

This property is read-only after you create the Site Viewer.

For limitations, see Limitations.

Data Types: char | string

Cartesian Coordinate System

Name of the 3-D model file or triangulation, specified as a string scalar, a character vector, or a triangulation object.

When SceneModel is the name of a 3-D model file, you must specify an STL file with extension .stl. The way you specify the file depends on the location of the file.

  • If the file is in your current folder or in a folder on the MATLAB path, then specify the name of the file, such as 'myFile.stl'.

  • If the file is not in the current folder or in a folder on the MATLAB path, then specify the full or relative path name, such as 'C:\myfolder\myFile.stl' or 'dataDir\myFile.stl'.

This property applies only when CoordinateSystem is 'cartesian'.

This property is read-only after you create the Site Viewer.

Data Types: char | string

Transparency of the model, specified as a scalar in the range [0,1], where 0 is transparent and 1 is opaque. The default is 0.1 when ShowEdges is 1 (true), and 1 otherwise.

This property applies only when CoordinateSystem is 'cartesian'.

Data Types: double

Option to show the origin of the model, specified as numeric or logical 1 (true) or 0 (false). The x-axis appears in red, the y-axis appears in green, and the z-axis appears in blue. The z-axis of the scene points up.

This property applies only when CoordinateSystem is 'cartesian'.

Data Types: logical

Option to show the edges of the model using black lines, specified as numeric or logical 1 (true) or 0 (false). Site Viewer defines edges as two adjacent facets with normals that differ by more than two degrees.

This property applies only when CoordinateSystem is 'cartesian'.

This property is read-only after you create the Site Viewer.

Data Types: logical

Object Functions

clearMapClear plots
closeClose Site Viewer

Examples

collapse all

Open Live Script

Create a default Site Viewer.

viewer = siteviewer;

Pan by left-clicking and dragging, zoom by right-clicking and dragging or by using the scroll wheel, and rotate the visualization by clicking the middle button and dragging or by pressing Ctrl and left-clicking or dragging. View the coordinates for a location by right-clicking and selecting Show location.

For this example, navigate to a region containing New England and view the coordinates for a location near Cape Cod.

A gray marker appears at the location you selected. Remove the marker by right-clicking the location and selecting Remove location.

Open Live Script

Import and view an STL file. The file models a small conference room with one table and four chairs.

viewer = siteviewer("SceneModel","conferenceroom.stl");

Pan by left-clicking, zoom by right-clicking or by using the scroll wheel, and rotate the visualization by clicking the middle button and dragging or by pressing Ctrl and left-clicking and dragging.

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 and the other window does not use the terrain model.

viewer1 = siteviewer("Terrain","gmted2010","Name","Site Viewer (Using Terrain)");
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)

Open Live Script

Launch Site Viewer with a 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.

Specify values for these arguments:

  • A name that identifies the custom basemap.

  • The URL of the map tiles. For load balancing, this provider has three servers that you can use (a, b, or c).

  • An attribution that gives credit to the provider of the map tiles. When you plot data, this attribution appears at the bottom of the map. Map tile providers can define specific requirements for the attribution.

  • A display name for the custom basemap. This name appears in the Imagery tab of Site Viewer.

name = "opentopomap";
url = "a.tile.opentopomap.org/${z}/${x}/${y}.png";
copyright = char(uint8(169));
attribution = copyright + "OpenStreetMap contributors";
displayName = "Open Topo Map";

Use addCustomBasemap to load the custom basemap, and then create a Site Viewer that uses the custom basemap.

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

Site Viewer with the OpenTopoMap basemap

After you add a custom basemap, the custom map is available in new Site Viewer windows. Note the Open Topo Map basemap icon in the Imagery tab.

siteviewer;

A new Site Viewer. The Imagery tab shows a selection of basemaps, including the OpenTopoMap basemap..

Use removeCustomBasemap to remove the custom basemap. Then, open a new Site Viewer. Note the Open Topo Map basemap option is no longer available in the Imagery tab.

removeCustomBasemap(name)
siteviewer;

The Imagery tab in a new Site Viewer. The tab does not show the OpenTopoMap basemap.

Limitations

Terrain

  • Default terrain access requires an 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 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 you are trying to show a transmitter or receiver site 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 3-D buildings.

MATLAB Online

  • In MATLAB Online™, if you refresh the URL, then the Site Viewer window remains open but the visualizations disappear.

More About

expand all

Version History

Introduced in R2019b

See Also

Functions

Objects

Topics