Skip to main content

GM_LoadOnlineLayer

Updated

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 NULL, 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 GM_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 NULL 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 GM_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.

Syntax

C++
Copy 
GM_Error_t32 __stdcall GM_LoadOnlineLayer
(
const char*             aSourceName,        // in: source to load or NULL to ask user
const GM_Rectangle_t*   aLatLonRect,        // in: lat/lon rect to import (NULL to ask user)
GM_LayerHandle_t32*     aLayer,             // out: handle to loaded layer
const char*             aExtraLoadOptions   // in: string of extra load options
)

Related articles