siteviewer

Create Site Viewer

expand all in page

Description

Display transmitter sites, receiver sites, and RF propagation visualizations by using a siteviewer object.

Site Viewer has two visualization modes:

3-D globe — Display sites that are referenced to geographic coordinates. You can customize the globe using custom terrain, high-zoom-level or custom basemaps, and buildings. This is the default visualization mode.
3-D model — Display sites that are referenced to Cartesian coordinates. You can import and view 3-D models represented by glTF™ files (since R2023b), standard tessellation language (STL) files, or triangulation objects. Specify the name of the 3-D model by using the SceneModel name-value argument.

Site Viewer requires hardware graphics support for WebGL™.

Creation

Syntax

viewer = siteviewer

viewer = siteviewer(Name=Value)

Description

viewer = siteviewer creates a Site Viewer.

example

viewer = siteviewer(Name=Value) uses name-value arguments to set one or more properties, except CoordinateSystem and Materials. For example, you can import and view a 3-D model file by using the SceneModel name-value argument.

example

Properties

expand all

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

`Materials` — Scene materials
table

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
- "marble" — Marble (since R2024a)
- "plywood" — Plywood (since R2024a)
- "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

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

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 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` — Buildings data
string scalar | character vector | geospatial table

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

`SceneModel` — Name of 3-D model file or triangulation
string scalar | character vector | `triangulation` object

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

`SceneModelScale` — Scale of 3-D model
`1` (default) | positive scalar

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` — Transparency of model
scalar in 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 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

`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

Object Functions

`clearMap`	Clear plots
`close`	Close Site Viewer

Examples

collapse all

Default Site Viewer Map Display

Open Live Script

Create a default Site Viewer.

viewer = siteviewer;

Satellite imagery of Earth

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.

Satellite imagery of a region in the northeast United States

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 from glTF File

Since R2023b

Open Live Script

View a 3-D model from a glTF file created using RoadRunner. RoadRunner is an interactive editor that lets you design 3-D scenes for simulating and testing automated driving systems.

Create a temporary folder to store a sample glTF file. Download the file into the folder by using the downloadGLTFFile helper function. The helper function is attached to the example as a supporting file.

dataDir = fullfile(tempdir,"IntersectionAndBuildings");
if ~exist(dataDir,"dir")
    mkdir(dataDir)
end
downloadGLTFFile(dataDir)

The glTF file consists of one main file that defines the structure of the model and multiple image files that define the colors and textures of the model. Specify the name of the main file. Then, import and view the glTF file using Site Viewer.

filename = fullfile(dataDir,"IntersectionAndBuildings.glb");
viewer = siteviewer(SceneModel=filename,ShowEdges=false,ShowOrigin=false);

Site Viewer displays the model using the colors and textures stored with 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 brick and concrete buildings

Site Viewer with 3-D Model from STL File

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.

3-D model of a table and four chairs

Site Viewer with Buildings

Open Live Script

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");

3-D buildings displayed over an OpenStreetMap basemap

Show a transmitter site on a building.

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

Transmitter site on a building

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

Site Viewer with Customized Buildings

This example uses:

Mapping Toolbox Mapping Toolbox

Open Live Script

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

ans=2821×1 object
  16×1 geopolyshape array with properties:

              NumRegions: [16×1 double]
                NumHoles: [16×1 double]
                Geometry: "polygon"
    CoordinateSystemType: "geographic"
           GeographicCRS: [1×1 geocrs]
      ⋮

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"           "marble"

Add and Remove a Custom Basemap

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";
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.

Compare Coverage Maps

Open Live Script

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

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

expand all

R2024a: Import marble and plywood scene materials

Site Viewer supports marble and plywood materials for scenes created from glTF files, OpenStreetMap files, and geospatial tables.

R2023b: Import glTF files and scale the size of 3-D models

Read a scene model from a glTF file with the .gltf or .glb extension. Specify the name of the model by using the SceneModel name-value argument.

Change the scale of scene models created from glTF files, STL files, and triangulation objects by specifying the SceneModelScale name-value argument.

R2023b: Display buildings using colors from OpenStreetMap files

When you read buildings data from an OpenStreetMap file into Site Viewer, Site Viewer displays the buildings using the colors stored in the file.

R2023b: Import customized buildings data

Import customized buildings data into Site Viewer by using geospatial tables that contain buildings data. Specify the geospatial table by using the Buildings name-value argument. This capability requires Mapping Toolbox.

siteviewer

Description

Creation

Syntax

Description

Properties

Site Viewer

Name — Caption to display on map viewer window 'Site Viewer' (default) | character vector | string scalar

Position — Size and location of map viewer window in pixels four-element integer-valued vector

CoordinateSystem — Coordinate reference system 'geographic' (default) | 'cartesian'

Materials — Scene materials table

Geographic Coordinate System

Basemap — Map imagery used to visualize sites 'satellite' (default) | 'openstreetmap' | 'streets' | 'streets-light' | 'streets-dark' | 'topographic' | ...

Terrain — Data on which to visualize sites and perform terrain calculations 'gmted2010' (default) | 'none' | character vector | scalar

Buildings — Buildings data string scalar | character vector | geospatial table

Cartesian Coordinate System

SceneModel — Name of 3-D model file or triangulation string scalar | character vector | triangulation object

SceneModelScale — Scale of 3-D model 1 (default) | positive scalar

Transparency — Transparency of model scalar in range [0,1]

ShowOrigin — Option to show origin true or 1 (default) | false or 0

ShowEdges — Option to show edges of model true or 1 (default) | false or 0

Object Functions

Examples

Default Site Viewer Map Display

Site Viewer with 3-D Model from glTF File

Site Viewer with 3-D Model from STL File

Site Viewer with Buildings

Site Viewer with Customized Buildings

Add and Remove a Custom Basemap

Compare Coverage Maps

Limitations

More About

Site Viewer Navigation

Dimension Picker

Version History

R2024a: Import marble and plywood scene materials

R2023b: Import glTF files and scale the size of 3-D models

R2023b: Display buildings using colors from OpenStreetMap files

R2023b: Import customized buildings data

See Also

Functions

Objects

Topics

`Name` — Caption to display on map viewer window
`'Site Viewer'` (default) | character vector | string scalar

`Position` — Size and location of map viewer window in pixels
four-element integer-valued vector

`CoordinateSystem` — Coordinate reference system
`'geographic'` (default) | `'cartesian'`

`Materials` — Scene materials
table

`Basemap` — Map imagery used to visualize sites
`'satellite'` (default) | `'openstreetmap'` | `'streets'` | `'streets-light'` | `'streets-dark'` | `'topographic'` | ...

`Terrain` — Data on which to visualize sites and perform terrain calculations
`'gmted2010'` (default) | `'none'` | character vector | scalar

`Buildings` — Buildings data
string scalar | character vector | geospatial table

`SceneModel` — Name of 3-D model file or triangulation
string scalar | character vector | `triangulation` object

`SceneModelScale` — Scale of 3-D model
`1` (default) | positive scalar

`Transparency` — Transparency of model
scalar in range `[0,1]`

`ShowOrigin` — Option to show origin
`true` or `1` (default) | `false` or `0`

`ShowEdges` — Option to show edges of model
`true` or `1` (default) | `false` or `0`