siteviewer

Create Site Viewer

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.

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.

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

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

Since R2023b

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.

Site Viewer with 3-D Model from STL File

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.

Site Viewer with Buildings

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

Site Viewer with Customized Buildings

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

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"          

[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 and Remove a Custom Basemap

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

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;

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;

Compare Coverage Maps

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

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 R2019a

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.