classdef siteviewer< handle & matlab.mixin.CustomDisplay
%siteviewer   Create Site Viewer
%   VIEWER = siteviewer creates a Site Viewer for visualizing transmitter
%   or receiver sites.
%
%   VIEWER = siteviewer(Name,Value) creates a Site Viewer with properties
%   specified by one or more Name-Value pairs. Properties you do not
%   specify retain their default values.
%
%   siteviewer properties:
%
%      Name             - Caption to display on the map viewer window
%      Position         - Map viewer window position in pixels
%      CoordinateSystem - Coordinate system of map viewer
%      Materials        - Table of imported materials and matched materials
%
%   Geographic coordinate system properties
%      Basemap   - Basemap on which to visualize sites
%      Terrain   - Terrain data on which to visualize sites
%      Buildings - Buildings
%
%   Cartesian coordinate system properties
%      SceneModel            - 3-D model file or triangulation
%      SceneModelScale       - Scale of the 3-D scene
%      Transparency          - Transparency of the 3-D model
%      ShowOrigin            - Determines if origin is shown
%      ShowEdges             - Determines if edges are highlighted
%
%   siteviewer methods:
%
%      clearMap - Clear plots
%      close    - Close Site Viewer
%
%   % Examples
%
%   % Example 1: Launch siteviewer with buildings
%
%   % Launch siteviewer map window with basemap and buildings file
%   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)
%
%   % Close the map
%   close(viewer)
%
%   % Example 2: Compare coverage maps
%
%   % Launch two siteviewer windows, with and without terrain
%   viewer1 = siteviewer("Terrain","gmted2010",...
%      "Name","Site Viewer (Using Terrain)");
%   viewer2 = siteviewer("Terrain","none",...
%      "Name","Site Viewer (No Terrain)");
%
%   % Generate a coverage map on each window. The map with terrain uses the
%   % Longley-Rice propagation model by default, whereas the map without
%   % terrain used the free-space model by default.
%   tx = txsite;
%   coverage(tx,"Map",viewer1)
%   coverage(tx,"Map",viewer2)
%
%   % Example 3: Visualize indoor propagation
%
%   % Launch a cartesian Site Viewer using an STL file containing a conference
%   % room with four chairs and a table.
%   viewer = siteviewer("SceneModel", "conferenceroom.stl");
%   
%   % Define a transmitter site close to the wall and a receiver site on
%   % the table. Show them in the Site Viewer. 
%   tx = txsite("cartesian", ...
%     "AntennaPosition",[-1.45; -1.4; 1.5], ...
%     "TransmitterFrequency",2.8e9);
%   rx = rxsite("cartesian", ...
%     "AntennaPosition",[0.3; 0.2; 0.9]);
%   show(tx)
%   show(rx)
% 
%   % Visualize propagation paths using the raytrace function
%   raytrace(tx, rx)
%
%  See also txsite, rxsite, addCustomTerrain, addCustomBasemap

 
    %   Copyright 2018-2023 The MathWorks, Inc.

    methods
        function out=siteviewer
            % Only allow running on MATLAB Desktop, not MATLAB Online or
            % any other environments.
        end

        function out=clearMap(~) %#ok<STOUT>
            %clearMap   Clear plots
            %   clearMap(VIEWER) removes all plots from Site Viewer.
            %
            %   See also close
        end

        function out=close(~) %#ok<STOUT>
            %close   Close Site Viewer
            %   close(VIEWER) closes Site Viewer and deletes the handle.
            %
            %   See also clearMap
        end

        function out=delete(~) %#ok<STOUT>
        end

        function out=getPropertyGroups(~) %#ok<STOUT>
        end

    end
    properties
        %Basemap   Basemap on which to visualize sites
        %   Basemap imagery on which to visualize sites, specified as a character
        %   vector or string scalar matching the name of a custom basemap
        %   added by the function addCustomBasemap, or matching one of the
        %   following options:
        %      'satellite'     - Satellite imagery provided by ESRI
        %      'topographic'   - Topographic imagery provided by ESRI
        %      'streets'       - Street maps provided by ESRI
        %      'streets-light' - Light street maps provided by ESRI
        %      'streets-dark'  - Dark street maps provided by ESRI
        %      'openstreetmap' - Street maps provided by OpenStreetMap
        %      'darkwater'     - Two-tone map with light gray for land and dark gray for water
        %      'grayland'      - Two-tone map with gray for land and white for water
        %      'bluegreen'     - Two-tone map with green for land and blue for water
        %      'colorterrain'  - Shaded relief map derived from elevation and climate
        %      'grayterrain'   - Shaded relief map in shades of gray
        %      'landcover'     - Shaded relief map derived from satellite data
        %   The default value is 'satellite'.
        Basemap;

        %Buildings   Buildings file
        %   Name of an OpenStreetMap (.osm) file or geospatial table of
        %   buildings to use as the source of buildings data.
        %   If you specify the name of an OpenStreetMap file, the
        %   file must be specified as a string scalar or character vector
        %   and must be in the current directory, in a directory on the
        %   MATLAB path, or include a full or relative path to a file. A
        %   geospatial table must contain a Shape variable. You can read
        %   data from a file into a geospatial table by using the
        %   readgeotable function (requires Mapping Toolbox (TM)). The
        %   default value is empty. This property is read-only after the
        %   siteviewer is created.
        Buildings;

        %CoordinateSystem   Coordinate System
        %   Coordinate System used by the viewer, determined by the way the
        %   viewer is constructed. The value is set to "cartesian" if the
        %   viewer is opened with the "SceneModel" name-value pair, and is
        %   "geographic" by default. This property is read-only after the
        %   siteviewer is created.
        CoordinateSystem;

        %Materials  Table of imported materials and matched materials
        %   Table containing imported materials data from either the
        %   SceneModel or Buildings name-value argument. The first column
        %   contains the imported materials. The second column contains the
        %   closest match between the imported material and the materials
        %   supported by the ray tracing propagation model. When Site
        %   Viewer does not find a match, the value of the matched material
        %   is "", and is set by the ray tracing propagation model.
        %   This property is read-only after the Site Viewer is created.
        Materials;

        %Name   Caption to display on the map viewer window
        %   Caption to display on the map viewer window, specified as a character
        %   vector or string scalar. The default value is 'Site Viewer'.
        Name;

        %Position   Map window position in pixels
        %   Size and location of the map window in pixels, specified as a
        %   four-element double vector of the form [left bottom width height]. The
        %   default value is dependent on the screen resolution such that the
        %   window is positioned in the center of the screen, with a width and
        %   height of 800 and 600 pixels respectively.
        Position;

        %SceneModel   3-D model file or triangulation
        %   Name of 3-D model file or triangulation object to display. When specified, the
        %   CoordinateSystem property is set to 'cartesian'. If a file is specified,
        %   it must be a string scalar or character vector and must be in the current
        %   directory, in a directory on the MATLAB path, or include a full
        %   or relative path to the file. The file must have the extension
        %   ".stl", ".glb", or ".gltf". The default value is "none". This property
        %    is read-only after the siteviewer is created, and is only applicable to
        %   siteviewers with CoordinateSystem equal to 'cartesian'.
        SceneModel;

        %SceneModelScale    Scale of the 3-D scene
        %   The scale of the 3-D scene, specified as a positive scalar. This value changes
        %   the size of the 3-D scene specified by SceneModel by multiplying the
        %   distances between the vertices in the scene by the SceneModelScale value.
        %   For example, when the distance between two points in the model is 10 units,
        %   specifying this value as 2 increases the distance to 20 units. The
        %   default value is 1. This property only applies to Site Viewers with CoordinateSystem
        %   set to 'cartesian'.
        SceneModelScale;

        %ShowEdges   Determines if edges are highlighted
        %   Determines whether or not edges of a 3-D model are highlighted
        %   using black lines, specified as a scalar logical. The default
        %   value is true.
        ShowEdges;

        %ShowOrigin   Determines if origin is shown
        %   Determines if origin is shown in a siteviewer with
        %   CoordinateSystem set to 'cartesian', specified as a scalar
        %   logical. The default value is true.
        ShowOrigin;

        %Terrain   Terrain data on which to visualize sites
        %   Terrain data on which to visualize sites and perform terrain
        %   calculations, specified as a character vector or string scalar matching
        %   the name of custom terrain data previously added using addCustomTerrain
        %   or one of the following options:
        %      'none'      - Terrain elevation is 0 everywhere
        %      'gmted2010' - Global terrain derived from USGS GMTED2010 (Internet required)
        %   The default value is 'gmted2010'. This property is read-only after the
        %   siteviewer is created.
        Terrain;

        %Transparency   Transparency of the 3-D model
        %   Transparency of the 3-D model specified as a scalar double in
        %   range 0 to 1, where 0 is completely transparent, and 1 is
        %   opaque. The default value is 0.1 if ShowEdges is true, and 1 if
        %   ShowEdges is false or if a glTF model is specified as the
        %   SceneModel.
        Transparency;

    end
end
