function addCustomBasemap(basemapName, url, varargin)
%addCustomBasemap Add use of custom basemap
% 
%   addCustomBasemap(basemapName,URL) adds the basemap specified by
%   basemapName and URL for use in geographic axes and charts and webmap.
% 
%   addCustomBasemap(__,Name,Value) specifies name-value pairs that set
%   additional parameters of the basemap.
% 
%
%   Input Arguments
%   ---------------
%
%   Name          Data Type                       Description                
%   ----          ---------          --------------------------------------
%   BasemapName   String scalar, or  Name of custom basemap. Utilized by
%                 character vector   specific geographic functions to
%                                    identify the custom basemap.
%
%   URL           String scalar, or  Parameterized URL to access map tiles. 
%                 character vector   Parameterized index of the map tiles
%                                    specified as either:
%                                    ${x} or {x} for tile column index, 
%                                    ${y} or {y} for tile row index, and 
%                                    ${z} or {z} for tile zoom level.
%                                    URL may be a hostname if the
%                                    parameterized url is:
%                                    'https://hostname/${z}/${x}/${y}.png'
%
%
%   Name-Value Pair Arguments
%   -------------------------
%
%   Name          Data Type                       Description                
%   ----          ---------          --------------------------------------
%   DisplayName   String scalar, or  Display name of custom basemap.                                  
%                 character vector   Used by webmap in the layer manager.
%
%   Attribution   String,            Attribution of custom basemap.
%                 character vector,  The value can be empty if the host is
%                 or cellstr         'localhost' or URL contains only IP
%                                    numbers. If the value is a string
%                                    array or non-scalar cellstr, the
%                                    attribution is displayed on multiple
%                                    lines. The default value is:
%                                    'Tiles courtesy of DOMAIN_NAME_OF_URL'
% 
%   MaxZoomLevel  Numeric scalar     Maximum zoom level of the basemap in
%                                    the integer-valued range of 0 to 25. 
%                                    The default value is 18.
% 
%   IsDeployable  Logical scalar     True if the basemap is deployable.
%                                    The default value is false. Set to
%                                    true if you are deploying a map
%                                    application and you want your users to
%                                    have access to this basemap.
%
%   Example 1
%   ---------
%   % View locations of placenames as bubbles on the OpenStreetMap basemap.
%   name = 'openstreetmap';
%   url = 'a.tile.openstreetmap.org';
%   copyright = char(uint8(169));
%   attribution = copyright + "OpenStreetMap contributors";
%   displayName = 'Open Street Map';
%   addCustomBasemap(name,url,'Attribution',attribution, ...
%      'DisplayName',displayName)
%
%   pts = gpxread('boston_placenames');
%   gb = geobubble(pts.Latitude,pts.Longitude,'Basemap','openstreetmap');
%   gb.BubbleWidthRange = 25;
%   gb.MapLayout = 'maximized';
%   gb.ZoomLevel = 14;
%
%   Example 2
%   ---------
%   % View glider path on the OpenTopoMap using webmap.
%   trk = gpxread('sample_mixed.gpx','FeatureType','track');
%   name = 'opentopomap';
%   url = 'a.tile.opentopomap.org';
%   copyright = char(uint8(169));
%   attribution = [ ...
%     "map data:  " + copyright + "OpenStreetMap contributors,SRTM", ...
%     "map style: " + copyright + "OpenTopoMap (CC-BY-SA)"];
%   displayName = 'Open Topo Map';
%   addCustomBasemap(name,url,'Attribution',attribution,'DisplayName',displayName)
%   webmap opentopomap
%   wmline(trk,'LineWidth',2)
%
%   Example 3
%   ---------
%   % View glider path on basemaps from the USGS National Map.
%   % The USGS National Map has several tiled web maps. Construct basemap
%   % URLs by replacing BASEMAP with the name of the USGS basemap.
%   % Use a DisplayName the same as webmap so that webmap does not contain
%   % duplicate maps.
%   trk = gpxread('sample_mixed','FeatureType','track');
%   baseURL = "https://basemap.nationalmap.gov/ArcGIS/rest/services";
%   usgsURL = baseURL + "/BASEMAP/MapServer/tile/${z}/${y}/${x}";
%
%   % Add basemaps from the USGS National Map.
%   attribution = 'Credit: U.S. Geological Survey';
%   basemaps = ["USGSImageryOnly" "USGSImageryTopo" ...
%      "USGSTopo" "USGSShadedReliefOnly" "USGSHydroCached"];
%   displayNames = ["USGS Imagery" "USGS Topographic Imagery" ...
%      "USGS Shaded Topographic Map" "USGS Shaded Relief" ...
%      "USGS Hydrography"];
%   maxZoomLevel = 16;
%   for k =1:length(basemaps)
%      basemap = basemaps(k);
%      name = lower(basemap);
%      url = replace(usgsURL,"BASEMAP",basemap);
%      displayName = displayNames(k);
%      addCustomBasemap(name,url,'Attribution',attribution, ...
%        'DisplayName',displayName,'MaxZoomLevel',maxZoomLevel)
%      figure
%      geoplot(trk.Latitude,trk.Longitude,'r','LineWidth',5);
%      geobasemap(basemap)
%      title(displayName)
%   end
%   
%   See also GEOAXES, GEOBASEMAP, GEOBUBBLE, GEODENSITYPLOT, GEOPLOT, GEOSCATTER, removeCustomBasemap, WEBMAP

% Copyright 2018 The MathWorks, Inc.

    narginchk(2,inf)
    try
        addCustomBasemapImpl(basemapName, url, varargin{:})
    catch e
        throwAsCaller(e)
    end
end
