Main Content

siteviewer

Create Site Viewer

Since R2019b

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 glTF™ files (since R2023b), 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

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

Since R2023b

This property is read-only.

Scene materials, returned as a table. When you create a scene from a glTF file, an OpenStreetMap® file, or a geospatial table, Site Viewer assigns materials to the surfaces in the scene by matching each material name stored in the file or table with the name of a supported material. By default, when you perform ray tracing analysis by using a function such as raytrace or coverage, the function uses the matched material names.

For each material stored in the file or geospatial table, the scene materials table contains these variables:

  • Material — Name of the material stored in the file or geospatial table, returned as a string scalar.

  • MatchedCatalogMaterial — Matched material name, returned as one of these values:

    • "perfect-reflector" — Perfect electrical conductor

    • "concrete" — Concrete

    • "plasterboard" — Plasterboard

    • "ceilingboard" — Ceiling board

    • "chipboard" — Chipboard

    • "floorboard" — Floorboard

    • "brick" — Brick

    • "wood" — Wood

    • "glass" — Glass

    • "metal" — Metal

    • "water" — Water

    • "vegetation" — Vegetation

    • "loam" — Loam

    • "" — Material is not supported. By default, the ray tracing analysis functions use concrete for materials that are not supported.

Data Types: table

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

Buildings data, specified as one of these options:

  • A string scalar or character vector that specifies the name of an OpenStreetMap file (.osm).

  • A geospatial table. A geospatial table is a table or timetable with a Shape table variable and attribute table variables. The Shape table variable must contain geopolyshape (Mapping Toolbox) objects. This option requires Mapping Toolbox™.

If you specify the name of an OpenStreetMap file, 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.osm".

  • 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.osm" or "dataDir\myFile.osm".

This property applies only when the CoordinateSystem property is set to "geographic".

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

For limitations, see Limitations.

Data Types: char | string | table

Cartesian Coordinate System

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

Site Viewer supports these 3-D model file formats:

  • glTF (.gltf, .glb) (since R2023b)

  • STL (.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 the CoordinateSystem property is set to "cartesian".

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

Data Types: char | string

Since R2023b

Scale of the 3-D model, specified as a positive scalar. When you import a 3-D model from a glTF file, an STL file, or a triangulation object, Site Viewer creates the scene by multiplying this value by the linear distances stored in the model. For example, when the distance between two vertices in the model is 10 units, specifying this value as 2 increases the distance to 20 units.

By default, Site Viewer interprets scene models using units of meters with a 1:1 scale.

This property applies only when the CoordinateSystem property is set to "cartesian".

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

Transparency of the model, specified as a scalar in the range [0,1], where 0 is transparent and 1 is opaque.

The default value depends on the values of the ShowEdges and SceneModel properties.

  • When ShowEdges is 1 (true), the default value is 0.1. When ShowEdges is 0 (false), the default value is 1.

  • When SceneModel contains the name of a glTF file, the default is 1.

This property applies only when the CoordinateSystem property is set to "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

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.

Since R2023b

Suppose you have a glTF file "samplecity.gltf" that models a sample city with several buildings and road intersections. Import and view the glTF file.

viewer = siteviewer(SceneModel="samplecity.gltf",ShowEdges=false);

Site Viewer displays the model using the colors and textures stored in the file. Pan by left-clicking and dragging, zoom by right-clicking or by using the scroll wheel, and rotate the visualization by clicking the middle button and dragging or by holding Ctrl and left-clicking and dragging.

A city intersection with buildings, labeled roads, foliage, and road signs

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.

Launch Site Viewer with a basemap and buildings file for Manhattan. Site Viewer displays the buildings using the colors stored in the file. For more information about the OpenStreetMap® 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 OpenStreetMap 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/.

Customize the buildings stored in an OpenStreetMap® file by reading the buildings into a geospatial table, editing the geospatial table, and importing the geospatial table into Site Viewer.

Read building parts from an OpenStreetMap file [1] by using the readgeotable (Mapping Toolbox) function. The function derives information about the buildings from the file and stores the result in a geospatial table. The Shape table variable represents the buildings using polygon shapes in geographic coordinates.

buildings = readgeotable("manhattan.osm",Layer="buildingparts");
buildings.Shape

Find the unique building materials reported by the OpenStreetMap file.

uniqueMaterials = unique(buildings.Material)
uniqueMaterials = 8×1 string
    ""
    "brick"
    "concrete"
    "copper"
    "glass"
    "metal"
    "plaster"
    "stone"

Create a dictionary that associates each material with a color. Specify the colors using hexadecimal color codes. Use gray for unspecified materials and concrete, red for brick, orange for copper, blue for glass, black for metal, white for plaster, and purple for stone.

materials = ["","brick","concrete","copper","glass","metal","plaster","stone"]; 
colors = ["#D3D3D3","#AA4A44","#D3D3D3","#B87333","#35707E","#151513","#FFFFFF","#301934"];
dict = dictionary(materials,colors)
dict =

  dictionary (string ⟼ string) with 8 entries:

    ""         ⟼ "#D3D3D3"
    "brick"    ⟼ "#AA4A44"
    "concrete" ⟼ "#D3D3D3"
    "copper"   ⟼ "#B87333"
    "glass"    ⟼ "#35707E"
    "metal"    ⟼ "#151513"
    "plaster"  ⟼ "#FFFFFF"
    "stone"    ⟼ "#301934"

For each building in the table, set the color of the building based on the building material.

numBuildings = height(buildings);
for n = 1:numBuildings
    material = buildings.Material(n);
    buildings.Color(n) = dict(material);
end

Display the buildings in Site Viewer. Navigate to an area that shows several building colors.

viewer = siteviewer(Buildings=buildings);

Site Viewer with buildings in gray, red, blue, and purple colors

View the building materials stored in the Site Viewer by querying the Materials property of the Site Viewer object. By default, ray tracing analysis functions use the materials stored in the MatchedCatalogMaterial table variable.

viewer.Materials
ans=7×2 table
     Material     MatchedCatalogMaterial
    __________    ______________________

    "brick"           "brick"           
    "concrete"        "concrete"        
    "copper"          "metal"           
    "glass"           "glass"           
    "metal"           "metal"           
    "plaster"         "plasterboard"    
    "stone"           ""                

[1] The OpenStreetMap 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 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";
attribution = "©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.

Launch two Site Viewer windows: one that uses terrain data derived from the GMTED2010 model by the USGS and NGA, and one without terrain data.

viewer1 = siteviewer(Terrain="gmted2010",Name="Site Viewer (GMTED2010)");
viewer2 = siteviewer(Terrain="none",Name="Site Viewer (No Terrain Data)");

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)

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

expand all