siteviewer
Create Site Viewer
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
Description
creates a
Site Viewer.viewer
= siteviewer
specifies Site Viewer properties using name-value arguments. For example,
import and view a 3-D model file by using the viewer
= siteviewer(Name,Value
)SceneModel
name-value argument.
Properties
Site Viewer
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
CoordinateSystem
— Coordinate reference system
'geographic'
(default) | 'cartesian'
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 ofCoordinateSystem
is'cartesian'
and coordinates are referenced to Cartesian coordinates.
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
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.
|
Full global basemap composed of high-resolution satellite imagery. Hosted by Esri®. |
|
Street map provided by OpenStreetMap®. |
|
General-purpose road map that emphasizes accurate, legible styling of roads and transit networks. Hosted by Esri. |
|
Map designed to provide geographic context while highlighting user data on a light background. Hosted by Esri. |
|
Map designed to provide geographic context while highlighting user data on a dark background. Hosted by Esri. |
|
General-purpose map with styling to depict topographic features. Hosted by Esri. |
|
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. |
|
Shaded relief map blended with a land cover palette. Humid lowlands are green and arid lowlands are brown. Created using Natural Earth. |
|
Terrain map in shades of gray. Shaded relief emphasizes both high mountains and micro-terrain found in lowlands. Created using Natural Earth. |
|
Two-tone, land-ocean map with light green land areas and light blue water areas. Created using Natural Earth. |
|
Two-tone, land-ocean map with gray land areas and white water areas. Created using Natural Earth. |
|
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
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
or one of the following options:
'none'
— Terrain elevation is0
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
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 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
SceneModel
— Name of 3-D model file or triangulation
character vector | string scalar | triangulation
object
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
form of SceneModel
depends on the location of your 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
— Transparency of model
scalar in the range [0,1]
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
ShowOrigin
— Option to show origin
true
or
1
(default) | false
or 0
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
ShowEdges
— Option to show edges of model
true
or
1
(default) | false
or 0
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
Examples
Default Site Viewer Map Display
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.
Site Viewer with 3-D Model
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.
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 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)
Site Viewer with Buildings
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/.
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 an internet connection. If no internet connection exists, then Site Viewer automatically uses
'none'
in the propertyTerrain
.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
Site Viewer Navigation
You can interactively navigate Site Viewer by using your mouse.
Pan by left-clicking and dragging.
Zoom by scrolling or by right-clicking and dragging.
Tilt and rotate by holding Ctrl and dragging or by middle-clicking and dragging.
When CoordinateSystem
is 'geographic'
, you
can restore the default view by selecting
Restore View from the toolbar.
Dimension Picker
When CoordinateSystem
is
'geographic'
, you can choose between three view options by
using the Dimension Picker in the toolbar.
3-D View — A smooth globe. This is the default view.
2-D View — A flat map in the Mercator projection.
Columbus View — A flat map in the Mercator projection that supports tilt and rotation.
Some interactions are not supported for 2-D View and Columbus View.
Version History
Introduced in R2019b
See Also
Functions
Objects
Open Example
You have a modified version of this example. Do you want to open this example with your edits?
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)