globalmapper.LoadOnlineLayer
============================

.. currentmodule:: globalmapper
.. py:function:: LoadOnlineLayer (str aSourceName, GM_Rectangle_t aLatLonRect, str aExtraLoadOptions) -> GM_Error_t32, GM_LayerHandle_t32

    Loads data from an online source, like WMS, OSM, TMS, or Google Maps tiles. This includes data sources providing
    terrain, imagery, and street maps for the entire world. If the *aSourceName* value is None, a dialog will be displayed
    asking the user which online data source and bounds to load. If the *aSourceName* is the full path and name of a local
    file that contains new source definitions, rather than loading a new layer those sources are added to the source
    list. You can then call back in to :doc:`LoadOnlineLayer<globalmapper.LoadOnlineLayer>` to load a layer from the new
    added sources.

    Valid theme names are any name that shows up in the dialog when calling this with a None theme name, such as the
    following examples (any match will do though):

    -   "OpenStreetMap.org Global Street Maps"
    -   "World Imagery"
    -   "United States Elevation Data (NED) (10m Resolution)"
    -   "ASTER GDEM v2 Worldwide Elevation Data"
    -   "SRTM Worldwide Elevation Data (3-arc-second Resolution) [Use http://srtm.csi.cgiar.org/ if fails]"
    -   "Landsat7 Global Imagery Mosaic (Natural Color, Pan-Sharpened)"
    -   "Landsat7 Global Imagery Mosaic (Psuedo-Color, Pan-Sharpened)"

    The layer handle returned in aLayer must be freed with a call to CloseLayer when the caller is done using it.

    The *aLatLonRect* can be used to provide the bounding box to load. If provided, the bounding box shall be lat/lon
    degree bounds using the datum of the current projection. If no current view/export projection is available WGS84
    will be the datum for the lat/lon values. If you would like to provide the bounds in some other projection, specify
    the projection using a BOUNDS_PROJ value in *aExtraLoadOptions* (see below).

    The *aExtraLoadOptions* string can contain additional options as a space-separated string. Currently the following
    are supported:

    -   **BOUNDS_PROJ** - Specifies the projection for the coordinates in the aLatLonBounds parameter. See Script
        Reference for a description of the allowed values. For example, you could specify the bounds are lat/lon WGS84
        using the EPSG code by passing "BOUNDS_PROJ=EPSG:4326" for aExtraLoadOptions.
    -   **CLAMP_TO_BOUNDS** - Specifies whether or not the layer bounds should be clamped to the specified bounding box
        or if panning over the entire data set should be allowed. The default is to clamp to the bounds. Use
        CLAMP_TO_BOUNDS=NO to disable the clamping behavior.
    -   **ZOOM_OFFSET** - Specifies an offset to apply to the calculated optimal zoom level to use for a particular draw
        or export. For example, adding ZOOM_OFFSET=-1 would cause every draw/export to use one lower zoom level (i.e.
        half resolution) than would otherwise by used for the resolution of the draw/export.
    -   **INC_LAYER** - specify name of layer/group to include. Can include wildcards. Multiple values allowed. If
        present only those layers that match an INC_LAYER value will be added. You can also include group names before
        the name, separated with ' \--> ' or '<sub>'. For example, to add only those sources in the \*** POPULAR SOURCES \***
        or TERRAIN DATA groups, use "\\"INC_LAYER=\*POPULAR SOURCES\*\-->\*\\" \\"INC_LAYER=TERRAIN DATA \--> \*\\"" (the escape
        sequences match what C/C++ code would use). To only add the NAIP imagery, use "\\"INC_LAYER=NAIP Color Imagery*\\"".
    -   **EXC_LAYER** - specify name of layer/group to exclude. See the INC_LAYER definition above for information about
        formatting. If present any layers that match an EXC_LAYER value will not be added.
    -   **FLUSH_CACHE[=source_type]** - specify that you want to flush the local cache of files rather than load a new
        source. If you provide a numeric source type (from the GM_OnlineSourceType_t enumeration) then only local files
        for that source type are flushed. For example, FLUSH_CACHE=0 flushes only files from GM_SourceType_WMS sources.
        If you also provide a recognized source name to the function then only the cached files for that source are flushed.

    :param str aSourceName: name of the online source to load or None to ask user
    :param GM_Rectangle_t aLatLonRect: lat/lon rect to import (None to ask user)
    :param str aExtraLoadOptions: string of extra load options
    :returns: Error Code
    :rtype: GM_Error_t32
    :return: Handle to loaded layer
    :rtype: GM_LayerHandle_t32