Downloads and displays data from online TMS tile services, like OpenStreetMap.
More...
|
bool | AutodetectProxy () |
| Retrieves and applies proxy server settings (address and port) from IE settings More...
|
|
bool | CheckConnection (string url) |
| Sends HTTP request to the specified address and reports back whether there is a response. More...
|
|
void | ClearCache (tkCacheType cacheType) |
| Clears cache of the specified type. More...
|
|
void | ClearCache2 (tkCacheType cacheType, int providerId, int fromScale=0, int toScale=100) |
| Clears cache of the specified to type for a given provider ID and scales. More...
|
|
void | ClearCache2 (tkCacheType cacheType, tkTileProvider provider, int fromScale=0, int toScale=100) |
| Clears cache of the specified to type for a given provider and scales. More...
|
|
void | ClearPrefetchErrors () |
| Clears information about prefetching errors. More...
|
|
void | ClearProxyAuthorization () |
| Clears user name and password set by Tiles.SetProxyAuthentication method. More...
|
|
void | Deserialize (string newVal) |
| Restores the state of Tiles class from string. More...
|
|
double | get_CacheSize (tkCacheType cacheType) |
| Gets the current size of cache. More...
|
|
double | get_CacheSize2 (tkCacheType cacheType, int providerId=-1, int scale=-1) |
| Gets the current size of cache used for specific provider and zoom level. More...
|
|
double | get_CacheSize2 (tkCacheType cacheType, tkTileProvider provider=tkTileProvider.ProviderNone, int scale=-1) |
| Gets the current size of cache used for specific provider and zoom level. More...
|
|
int | get_DiskCacheCount (int providerId, int zoom, int xMin, int xMax, int yMin, int yMax) |
| Gets number of tiles stored in disk cache for a given provider, zoom and region. More...
|
|
bool | get_DoCaching (tkCacheType cacheType) |
| Gets the value indicating whether tiles requested from server will be automatically cached. More...
|
|
string | get_ErrorMsg (int errorCode) |
| Gets the description of the specific error code. More...
|
|
double | get_MaxCacheSize (tkCacheType cacheType) |
| Gets the maximum allowable size of cache. More...
|
|
bool | get_UseCache (tkCacheType cacheType) |
| Gets a value indicating whether specific type of cache should be used to display tiles. More...
|
|
MapWinGIS.Extents | GetTileBounds (int providerId, int zoom, int tileX, int tileY) |
| Gets the bounds of specific tile in decimal degrees (for inner use/debug purposes). More...
|
|
Extents | GetTilesIndices (Extents boundsDegrees, int zoom, int providerId) |
| Gets indices of tiles within specified bounds in coordinates of the given zoom level. More...
|
|
int | Prefetch (double minLat, double maxLat, double minLng, double maxLng, int zoom, int providerId, IStopExecution stop) |
| Caches tiles of the specified provider within specified geographic bounds to SQLite database for further offline use. More...
|
|
int | Prefetch2 (int minX, int maxX, int minY, int maxY, int zoom, int providerId, IStopExecution stop) |
| Caches tiles of the specified provider to SQLite database for further offline use. More...
|
|
int | PrefetchToFolder (Extents ext, int zoom, int providerId, string savePath, string fileExt, IStopExecution stop) |
| Caches tiles to the specified file system folder for further offline use. More...
|
|
string | Serialize () |
| Serializes the state of the Tiles class to be restored later with Tiles.Deserialize method. More...
|
|
void | set_DoCaching (tkCacheType cacheType, bool pVal) |
| Sets the value indicating whether tiles requested from server will be automatically cached. More...
|
|
void | set_MaxCacheSize (tkCacheType cacheType, double pVal) |
| Sets the maximum allowable size of cache. More...
|
|
void | set_UseCache (tkCacheType cacheType, bool pVal) |
| Sets a value indicating whether specific type of cache should be used to display tiles. More...
|
|
bool | SetProxy (string address, int port) |
| Set proxy server for tiles class. More...
|
|
bool | SetProxyAuthentication (string username, string password, string domain) |
| Sets credentials for proxy authorization. More...
|
|
|
int | CurrentZoom [get] |
| Gets zoom (scale) of tiles currently displayed on the map. More...
|
|
int | DelayRequestTimeout [get, set] |
| Gets or sets the delay request timeout. More...
|
|
string | DiskCacheFilename [get, set] |
| Gets or sets the filename of SQLite database to cache tiles into. More...
|
|
ICallback | GlobalCallback [get, set] |
| Gets or sets a Callback object which handles progress and error messages. More...
|
|
bool | GridLinesVisible [get, set] |
| Gets or sets a value indicating whether a grid should be drawn to displayes borders of tiles (for debug purposes). More...
|
|
string | Key [get, set] |
| A text string associated with object. Any value can be stored by developer in this property. More...
|
|
int | LastErrorCode [get] |
| Gets the code of last error which took place inside this object. More...
|
|
bool | LogErrorsOnly [get, set] |
| Gets or sets a value indicating whether log will include all HTTP requests or only unsuccessful ones. More...
|
|
string | LogFilename [get] |
| Gets filename to write log into. More...
|
|
bool | LogIsOpened [get] |
| Gets a value indicating whether logging of HTTP requests will be performed. More...
|
|
int | MaxScaleToCache [get, set] |
| Gets or sets the maximum zoom (scale) to be cached if the automatic caching is chosen. More...
|
|
int | MaxZoom [get] |
| Gets maximum available zoom level for the current provider. More...
|
|
int | MinScaleToCache [get, set] |
| Gets or sets the minimum zoom (scale) to be cached if the automatic caching is chosen. More...
|
|
int | MinZoom [get] |
| Gets minimum available zoom level for the current provider. More...
|
|
int | PrefetchErrorCount [get] |
| Gets the number of unsuccessful HTTP requests during prefetching operation (Tiles.Prefetch and overloads). More...
|
|
int | PrefetchTotalCount [get] |
| Gets the total number of requests carried out during prefetching operation. More...
|
|
bool | ProjectionIsSphericalMercator [get] |
| Gets a value indicating whether [projection is spherical mercator]. More...
|
|
tkTilesProjectionStatus | ProjectionStatus [get] |
| Get information about whether map projection and tile projection match. More...
|
|
tkTileProvider | Provider [get, set] |
| Gets or sets active provider to serve the tiles. More...
|
|
int | ProviderId [get, set] |
| Gets or sets active provider to server the tiles. Ids of both default and custom providers can be specified. More...
|
|
string | ProviderName [get] |
| Gets the name of the active provider. More...
|
|
TileProviders | Providers [get] |
| Gets list of the available default and custom tile providers. More...
|
|
string | Proxy [get] |
| Gets proxy server settings for tiles class including IP and port, e.g. 192.168.0.1:80. More...
|
|
tkProxyAuthentication | ProxyAuthenticationScheme [get, set] |
| Gets or sets the proxy authentication scheme. More...
|
|
GeoProjection | ServerProjection [get] |
| Gets projection used by specific tile service. More...
|
|
int | SleepBeforeRequestTimeout [get, set] |
| Gets or sets the amount of time in milliseconds a worker thread will sleep before the next HTTP request. More...
|
|
bool | UseServer [get, set] |
| Gets or sets a value indicating whether server requests will be made to get the tiles. More...
|
|
bool | Visible [get, set] |
| Gets or sets a value indicating whether the tiles will be displayed on the map. More...
|
|
Downloads and displays data from online TMS tile services, like OpenStreetMap.
- Attention
- MapWinGIS doesn't grant you any legal rights to use data from particular online services. Please look for license information on acceptable usages of the data on official sites of these services.
Online tile services provide 2D maps of Earth surface, which are split into small parts (usually 256 by 256 pixels) called tiles. Tiles are provided at a number of zoom levels with greater detail on each subsequent level. Typically there are about 15-20 zoom levels with just 4 tiles for the whole Earth surface on the first one, and 4^zoom on subsequent levels. Depending on service the maps can be:
- synthetic: features of Earth surface are displayed with some arbitrary set of symbols (OpenStreetMap, GoogleMaps);
- satellite: satellite imagery (Bing satellite, Google satellite);
- hybrid: labels and objects displayed on top of satellite map.
To get more information on tiles services see specification: here.
A. Coordinate system and projection.
In order to display tiles from online datasource the coordinate system & projection of server must match or at least be compatible with those settings for the map control. Three scenarios are possible:
1) Projections match: tiles will be displayed in their native projection without distortions.
2) Projections don't match but transformation from server projection to map projection is possible: tiles will be displayed with distortions, which may be acceptable in some cases (spherical Mercator server projection, WGS84 map coordinate system) or hardly usable in others (spherical Mercator server projection, UTM projection of WGS84 as map projection).
3) No projections for map is set or map/server projections doesn't match and there is no transformation between them: tiles can't be displayed.
Here are screenshots which illustrate types of distortions introduced by projection mismatch (server projection is Spherical Mercator).
|
|
Spherical Mercator -> WGS84 | Spherical Mercator -> WGS84 UTM16 |
To check whether map projection match the server one use Tiles.ProjectionStatus property.
Most tile servers like OpenStreetMap, GoogleMaps, etc. are using spherical Mercator projection (aka Google Mercator; EPSG 3857). Therefore in most cases it may be set without additional checks:
tkMapProjection
Commonly used map projections to be set in Form Designer (see AxMap.Projection property).
Definition: Enumerations.cs:1741
B. Providers.
MapWinGIS supports built-in default providers and custom providers.
MapWinGIS has a number of built-in providers defined in tkTileProvider enumeration. To activate one of those use:
tkTileProvider
Tile providers enumeration
Definition: Enumerations.cs:2837
The default provider is OpenStreetMap.
To display list of available providers and their settings:
for (
int i = 0; i < providers.
Count; i++)
{
Debug.WriteLine(
"Provider name: " + providers.
get_Name(i));
Debug.WriteLine(
"Provider type: " + (providers.
get_IsCustom(i) ?
"custom" :
"default"));
Debug.WriteLine(
"Min zoom: " + providers.
get_MinZoom(i));
Debug.WriteLine(
"Min zoom: " + providers.
get_MinZoom(i));
Debug.WriteLine("-----------------------------------");
}
Holds the list of tile providers associated with Tiles class.
Definition: TileProviders.cs:21
bool get_IsCustom(int Index)
Gets a value indicating whether given provider is a custom one.
Definition: TileProviders.cs:107
string get_Name(int Index)
Gets name of the specific provider.
Definition: TileProviders.cs:117
int get_MinZoom(int Index)
Gets minimum zoom level provided by tile server.
Definition: TileProviders.cs:182
int Count
Gets the number of providers in the list.
Definition: TileProviders.cs:54
To add a custom provider to the list (in this example OpenStreetMap is configured as custom provider):
providers.
Add(providerId,
"Custom TMS provider",
"https://{switch:a,b,c}.tile.openstreetmap.org/{zoom}/{x}/{y}.png",
tkTileProjection
Possible tile server projection.
Definition: Enumerations.cs:1665
bool Add(int Id, string Name, string urlPattern, tkTileProjection Projection, int minZoom=0, int maxZoom=17)
Adds a custom tile provider.
Definition: TileProviders.cs:36
The following placeholders can be used:
- "{zoom}", "{x}", "{y}" will be substituted with value for particular tiles to form HTTP request;
- "{switch:a,b,c}" will randomly choose one of the comma separated values, thus switching between URLs of servers.
To set this provider as an active one:
axMap1.Tiles.ProviderId = providerId;
To retrieve custom provider already added to the list:
int providerId = 1025;
Debug.WriteLine(
"The recently added custom provider is: " + providers.
get_Name(index));
int get_IndexByProviderId(int ProviderId)
Gets the index of provider in the list by its ID.
Definition: TileProviders.cs:97
It's necessary to distinguish unique providerId passed to TileProviders.Add method and used by caching mechanism, and index of provider in TileProviders collection which may differ across application runs. To get index in collection by providerId use TileProviders.get_IndexByProviderId.
C. Zoom levels.
Originally MapWinGIS doesn't support concept of discrete zoom levels and can display any arbitrary zoom level between those defined by tile service. This will lead to scaling of tiles, i.e. separate images will be drawn using size other than their original (256 by 256 pixels), which may decrease their readability. To force MapWinGIS to display tiles without scaling set:
axMap1.ZoomBehavior = zmUseTileLevels;
Map can also be zoomed to particular tile level:
axMap1.ZoomToTileLevel(10);
axMap1.CurrentZoom = 10;
Zoom levels supported by active provider can be accessed via Tiles.MinZoom, Tiles.MaxZoom properties:
Debug.WriteLine(string.Format("Provider {0} supports zoom levels from {1} to {2}", axMap1.Tiles.Provider.ToString(),
axMap1.Tiles.MinZoom, axMap1.Tiles.MaxZoom));
Available zoom levels for other providers can be retrieved via: TileProviders.get_MaxZoom, TileProviders.get_MinZoom. Visibility of data layers displayed on the map can set for specific zoom levels only with: AxMap.set_LayerMaxVisibleZoom, AxMap.set_LayerMaxVisibleZoom.
D. Caching.
To speed up the display and reduce network traffic it's common to use caching for tiles, i.e. save them locally for further reuse. MapWinGIS supports 2 types of tile cache:
- RAM cache: tiles are stored in memory (is on by default);
- disk cache: tiles are stored in SQLite database (by default existing database is used but no new tiles are written to it).
To enable cache usage:
axMap1.Tiles.set_UseCache(tkCacheType.Disk, true);
axMap1.Tiles.set_UseCache(tkCacheType.RAM, true);
To make MapWinGIS add newly downloaded tiles to cache:
axMap1.Tiles.set_DoCaching(tkCacheType.RAM, true);
axMap1.Tiles.set_DoCaching(tkCacheType.Disk, true);
At this point new SQLite database will created to store tiles if it wasn't created so far. Default filename is mwtiles.db3. Location - the folder with application executable. To change location of disk cache use Tiles.DiskCacheFilename property.
axMap1.Tiles.DiskCacheFilename = "D:\tiles_cache.db3";
If no file with such name exists it will be created automatically. Only one database can be used at a time.
For both types of cache there is built-in mechanism to limit its size, under exceeding of which the oldest tiles will be removed to give space for the more recent ones:
axMap1.Tiles.set_MaxCacheSize(tkCacheType.RAM, 200.0);
axMap1.Tiles.set_MaxCacheSize(tkCacheType.Disk, 500.0);
To get information about the size and content of cache use: Tiles.get_CacheSize, Tiles.get_DiskCacheCount. To clear all the cache or only data for particular zoom levels and providers use: Tiles.ClearCache, Tiles.ClearCache2.
E. Functioning.
If map projection is compatible with server tiles are loaded automatically when map extents change and Tiles.Visible property is set to true. AxMap.TilesLoaded event is fired when all tiles for particular extents are loaded. In case all tiles were found in cache the event will fire immediately, otherwise - after execution of HTTP requests. If new extents were set for map before all HTTP request for previous set of tiles were completed, AxMap.TilesLoaded event won't fire, tiles already requested will be added to the cache, but other pending requests will be discarded. Internally to queue HTTP requests 2 thread pools are used. To identify potential problems HTTP requests can logged into file with Tiles.StartLogRequests method.
The behaviour of tile services depend upon how server and map projection are related. Several cases are possible:
- Server and map projections are the same.
- tiles are displayed without scaling using original size (256 by 256 pixels);
- snapping to discrete zoom levels works on any change of extents (if AxMap.ZoomBehavior = zbTileLevels);
- examples: OpenStreetMap tiles and Google Mercator projection of the map.
- Special case of: server projection is GMercator, map projection - WGS84.
- width of tiles will match the original, height will be equal (on equator) or smaller than original;
- snapping to discrete zoom levels works on any change of extents (if AxMap.ZoomBehavior = zbTileLevels);
- no gaps between tiles.
- Server projection is local one (like Amersfoort/RD New), server projection is different:
- size of tiles will be adjusted to be as close to original as possible, but will vary for individual tiles;
- gaps between tiles, which gradually become smaller at close zoom levels;
- no automatic snapping to discrete zoom levels on changing extents.
- Server projection is GMercator, map projection is some sort of local projection (like WGS84 UTM zones):