function addCustomBasemap(basemapName, url, varargin)
%

%addCustomBasemap Add use of custom basemap
% 
%   addCustomBasemap(basemapName,URL) adds the custom basemap specified by
%   URL to the list of basemaps available for use with mapping functions.
%   basemapName is the name you choose to call the custom basemap.
%
%   addCustomBasemap(basemapName,mbtilesFilename) adds the custom basemap
%   specified by mbtilesFilename to the list of basemaps available for use
%   with mapping functions. The added basemap remains available for use in
%   future MATLAB(R) sessions, provided the MBTiles file is available on
%   the same path as when added. Web maps created using the webmap function
%   are not supported. Adding a custom basemap from an MBTiles file is
%   useful when you do not have internet access. This syntax requires
%   Mapping Toolbox(TM).
% 
%   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'
%
%   mbtilesFilename 
%                 String scalar, or  Name of MBTiles file containing raster
%                 character vector   map tiles with case-insensitive
%                                    extension ".mbtiles". Default values
%                                    for MaxZoomLevel and Attribution are
%                                    obtained from the metadata in the
%                                    file, if available.
%
%
%   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.
%   basemap = "openstreetmap";
%   url = "a.tile.openstreetmap.org";
%   copyright = char(uint8(169));
%   attribution = copyright + "OpenStreetMap contributors";
%   displayName = "Open Street Map";
%   addCustomBasemap(basemap,url,"Attribution",attribution, ...
%      "DisplayName",displayName)
%
%   lat = [42.3501 42.3515 42.3598 42.3584 42.3529];
%   lon = [-71.0870 -71.0926 -71.0662 -71.0598 -71.0662];
%   gb = geobubble(lat,lon,"Basemap",basemap);
%   gb.BubbleWidthRange = 25;
%   gb.MapLayout = "maximized";
%   gb.ZoomLevel = 15;
%
%   Example 2
%   ---------
%   % View glider path on the OpenTopoMap using webmap.
%   % (Requires Mapping Toolbox(TM))
%   basemap = "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(basemap,url,"Attribution",attribution, ...
%      "DisplayName",displayName)
%
%   trk = readgeotable("sample_mixed.gpx","Layer","tracks");
%   webmap(basemap)
%   wmline(trk,"LineWidth",2)
%
%   Example 3
%   ---------
%   % View GPX route data 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.
%   % (Requires Mapping Toolbox(TM))
%
%   % Add basemaps from the USGS National Map.
%   attribution = "Credit: U.S. Geological Survey";
%   basemaps = ["USGSImageryOnly"; "USGSImageryTopo"; ...
%      "USGSTopo"; "USGSHydroCached"];
%   displayNames = ["USGS Imagery"; "USGS Topographic Imagery"; ...
%      "USGS Shaded Topographic Map"; "USGS Hydrography"];
%   maxZoomLevel = 16;
%   baseURL = "https://basemap.nationalmap.gov/ArcGIS/rest/services";
%   usgsURL = baseURL + "/BASEMAP/MapServer/tile/${z}/${y}/${x}";
%
%   for k =1:length(basemaps)
%      basemap = basemaps(k);
%      url = replace(usgsURL,"BASEMAP",basemap);
%      basemap = lower(basemap);
%      displayName = displayNames(k);
%      addCustomBasemap(basemap,url,"Attribution",attribution, ...
%        "DisplayName",displayName,"MaxZoomLevel",maxZoomLevel)
%   end
%
%   % Create a basemap picker to select a basemap from the USGS and
%   % display a route from Boston Logan International Airport
%   % to The MathWorks, Inc. in Natick, MA.
%   fig = uifigure;
%   gx = geoaxes(fig,"Basemap",basemaps(1));
%   hold(gx,"on")
%   tb = axtoolbar(gx,"default");
%   addToolbarMapButton(tb,"basemap","BasemapNames",lower(basemaps), ...
%      "DisplayNames",displayNames)
%   T = readgeotable("sample_route.gpx","Layer","routes");
%   geoplot(gx,T,"r","LineWidth",2)
%
%   Example 4
%   ---------
%   % Add basemap from MBTiles file containing USGS Imagery. 
%   % Display basemap over 2-D map and 3-D globe. MBTiles files 
%   % can be used in offline environments. 
%   % (Requires Mapping Toolbox(TM))
%   basemap = "usgsimagery";
%   mbtilesFilename = "usgsimagery.mbtiles";
%   addCustomBasemap(basemap,mbtilesFilename)
%
%   figure
%   geobasemap(basemap)
%
%   fig = uifigure;
%   gg = geoglobe(fig,"Basemap",basemap);
%   
%   See also addToolbarMapButton, GEOAXES, GEOBASEMAP, GEOBUBBLE, GEOGLOBE, GEOPLOT, removeCustomBasemap, WEBMAP

% Copyright 2018-2022 The MathWorks, Inc.

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

%#function map.internal.vectortiles.VectorTileSetReader
%#function map.internal.vectortiles.VectorTileSetFileReader
%#function map.internal.vectortiles.generateStyle
