Map Source Definition

<MapSources>

This is the top-level element, which must always be present in a valid Map Source XML file.

Parent: None

Attributes: None

<MapSource>

Represents a single map source definition within the file.

Parent: <MapSources>

Attributes:

• guid - defines a unique value (Global Unique Identifier) for identifying the map source. GUIDs are hexadecimal and of the form 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'. All official and community map sources in the ActiMap online library are assigned unique identifiers which allows them to be automatically updated should details of their map services change. It is not necessary to specify a value for a user-defined map source - one will be allocated automatically when it is imported.

• minzoom - specifies the minimum zoom level of the map (how far out the user can zoom). For a Web Mercator projection, the minimum allowable zoom level is '1' which represents a single view of the entire World. For a custom projection, the minimum allowable zoom level will be the zero-based index into the list of custom resolutions or scales provided, and will typically be '0'.

• maxzoom - specifies the maximum zoom level of the map (how far in the user can zoom). For a Web Mercator projection, there is no technical maximum, but map services will typically support maximum zoom levels in the range of 15 - 18, which roughly correspond to equatorial ground scales of 1:18,000 - 1:2,200. For a custom projection, the maximum alowable zoom level will be one less than the number of provided custom scales or resolutions.

• defaultzoom - specifies the default zoom level at which the map is displayed when first shown. If no value is specified, then a default somewhere between the maximum and minimum is chosen.

• maxfreezoom - specifies the maximum zoom level permitted for the free edition of ActiMap (ActiMap Free). This will not typically be specified for any user-defined map sources. Note: For all official map sources, any value specified in the XML may be overridden and a hard-coded value based on any obtained license used.

• maxdownloadtype - specifies the most severe or aggressive type of download supported by the map service according to the provider's licensing and terms of use. Most have no limitation, while some have restrictions on size or caching duration. When creating a user-defined map source it is strongly suggested that the licensing terms of the map provider are checked and adhered to, although of course this cannot be enforced, and for solely 'personal use' is unlikely to be of concern. If no value is specified, the the default of 'bulk' is assumed. Note: For all official map sources, any value specified in the XML may be overridden and a hard-coded value based on any obtained license used. Supported values are:

  • 'bulk' - full bulk download is supported up to the maximum size permitted by the running edition of ActiMap.

  • 'ondemand' - map tiles and data are downloaded and stored as they are first accessed. (*)

  • 'intellicache' - similar to 'ondemand', but downloaded tiles can age and require online refreshing - a process which happens automatically. (*)

  • 'none' - no offline access is permitted.

• region - specifies the geographic region of coverage of the map. This will be either a 2-character ISO-3166 country code or one of the special values: '00' (World) or '01' (Europe). If no value is specified, then a default of '00' is assumed.

• projection - specifies the projection of the map in EPSG notation, e.g. EPSG:3857, EPSG:27700, etc. If no value is specified, then the default of EPSG:3857 (Web Mercator) is assumed. If a different (custom) projection is specified, then this must be supplemented by defining an origin and a set of scales or resolutions for the map source.

• type - specifies the type of map service. If no value is specified, then the default of 'XYZ' is assumed. Supported values are:

  • 'ImageWMS' - a map service which adheres to the OpenGIS® Web Map Service (WMS) specification. The map is not provided as a set of tiles; instead, when viewing a map, a single web request is made which returns a single map image filling the ActiMap full-screen map display. When downloading from a web service of this type, it is treated as if it were 'TileWMS' service. WMS version 1.3.0 is assumed, but may be overridden with the <WmsService> element.

  • 'TileWMS' - a map service which also adheres to the OpenGIS® Web Map Service (WMS) specification, but where web requests are made to retrieve individual 256x256 images corresponding to standard web tiles. Note that depending on the map images being rendered, there may be artifacts or misalignments at the borders of each virtual 256x256 tile. WMS version 1.3.0 is assumed, but may be overridden with the <WmsService> element.

  • 'XYZ' - a standard XYZ tile map service.

• ignorecertificaterrors - indicates if any SSL certificate errors are to be ignored. If no value is specified, then the default of 'False' is assumed. When you access secure websites (https:) the site must provide a valid security certificate; if it does not, then there is a security risk and your browser will typically display a security warning. The same is true of map services, most of which now require a secure connection (https). However some OpenSource map services let the certificates lapse or do not provide true public-facing certificates. To access such a map source, certificate errors should be ignored by specifying 'True'.

• minversion - specifies the minimum version of ActiMap required to be able to access the map source. This will not typically be specified for any user-defined map sources. Note: As more complex map sources are added to the official map sources library, these will often require additional support in ActiMap itself, so many of these will have a value specified.

(*) 'ondemand' and 'intellicache' download types will be available in ActiMap Pro only, when released.

<Website>

Provides a link to the public-facing website containing a map viewer for the map source, or the most appropriate URL if there is none.

Parent: <MapSource>

Attributes: None

The URL is provided as the text content of the element, for example:

<Website>https://opentopomap.org//</Website>

<Description>

Provides a description of the map source, which is displayed when listed within ActiMap.

Parent: <MapSource>

Attributes: None

The description is provided as the text content of the element, for example:

<Description>World topographic map with hillshading, contours, and hiking &amp; biking layers from opentopomap.org</Description>

<Resolutions>

Defines the ground resolutions at each zoom level for a map source using a custom projection, i.e. other than Web Mercator. Ground resolutions in effect define how much each pixel represents in real-world distance. They are likely to be values specific to the map source provider and will be detailed in their API documentation.

Parent: <MapSource>

Attributes: None

Resolutions are provided as comma-separated text content of the element, with one value given for each supported zoom level, for example:

<Resolutions>896,448,224,112,56,28,14,7,3.5,1.75</Resolutions>

For a custom map projection, only one of <Resolutions> or <Scales> should be specified. if both sets of values are provided, then the defined scales take precedence.

<Scales>

Defines the scales at each zoom level for a map source using a custom projection, i.e. other than Web Mercator. Scales define the relationship between the size of something on the map and its size in the real world, and are values likely to be familiar to those who use paper maps - 1:25000, 1:50000, and so on. The actual values will to be specific to the map source provider and will be detailed in their API documentation.

Parent: <MapSource>

Attributes:

• • gisconversion - defines how scales are to be converted mathematically to and from resolutions. Different GIS software from different providers use slightly different mechanisms. The exact value chosen is unlikely to make any difference, but in some cases may cause problems when using pinch-to-zoom and zoom level boundaries are crossed. Sometimes some trial-and-error is required to determine the correct value! If no value is specified, the the default of 'ExactIpm' is assumed. Supported values are:

    • 'ExactIpm' - conversion is done using 0.0254 metres per inch

    • 'RoundedIpm' - conversion is done using 39.37 inches per metre.

Scales are provided as comma-separated text content of the element, with one value given for each supported zoom level, for example:

<Scales gisconversion="RoundedIpm">4000000,2500000,1250000,600000,400000,200000,100000,50000,25000,10000</Scales>

For a custom map projection, only one of <Resolutions> or <Scales> should be specified. if both sets of values are provided, then the defined scales take precedence.

<Origin>

Defines the location of the 'top left' corner of the map area covered by a map source using a custom projection. The actual coordinate values will to be specific to the map source provider and will be detailed in their API documentation.

Parent: <MapSource>

Attributes: None

The coordinates are provided as the text content of the element in the format 'X,Y' (in units according to the map source's projection), for example:

<Origin>-238375,1376256</Origin>

<WmsService>

Allows the default behaviour of a map source of type 'ImageWMS' or 'TileMWS' to be altered, optionally within a specific zoom range.

Parent: <MapSource>, <ZoomLevel>

Attributes:

• • version - specifies the version of WMS used by the web service. If the <WmsService> element is not used, or no attribute value is given, then version 1.3.0 is assumed.

  • crs - specifies the Coordinate Reference System or projection used by the web service, e.g. EPSG:3857, EPSG:27700, etc. If the <WmsService> element is not used, or no attribute value is given, then this will default to the projection of the map source, which itself defaults to 'EPSG:3857'. Occasionally a WMS service will required a CRS in a notation other than EPSG, or use an alternate EPSG value for the same projection, which is why this override is supported.

<UrlTemplate>

Defines the map service URL from which map tiles or images are requested by the map source, optionally within a specific zoom range.

Parent: <MapSource>, <ZoomRange>

Attributes: None

The URL is provided as the text content of the element, for example:

<UrlTemplate>https://{a-c}.tile.opentopomap.org/{z}/{x}/{y}.png</UrlTemplate>

The URL template can contain a number of different placeholder values:

• {a-j} - represents a range of sub-domains to which requests can be made. For reasons of performance, load sharing, and legacy browser support, some map services allow web requests to be made from one of a number of different URLs. Up to ten sub-domains are theoretically supported, although in practice the limit is usual four - i.e. a range of {a-d}. When map service requests are made, each consecutive request is made cyclically from a different sub-domain.

• {x} - represents the X (horizontal) index of required tile for an XYZ tile map service.

• {y} - represents the Y (vertical) index of the required tile for an XYZ tile map service.

• {z} - represents the zoom level of the required tile for an XYZ tile map service.

• {q} - represents a BingMaps QuadKey of the required tile for an XYZ tile map service which supports the QuadKey tile addressing system. A BingMaps QuadKey combines the X, Y, and Z components into a single key string. A tile URL template should contain either {q} or the {x}/{y}/{z} combination, but not both.

• {k} - represents the API key required to access the web service. Some providers require user registration in order to access them, at which point a unique API key for tracking and licensing purposes can provided. The {k} placeholder indicates where this will be included in the URL. When a {k} placeholder is used in a user-defined map source, the user will be required to enter a valid key in order to view the map in ActiMap. Note: For all official map sources requiring an API key, the hard-coded and embedded licensed key will be used.

<Headers>

Specifies any headers which are to be included in all web requests to the map service, optionally within a specific zoom range.

Parent: <MapSource>, <ZoomRange>

Attributes: None

Headers are not usually needed by a map service, but if required, one or more may be specified with child <Header> elements.

<Header>

Specifies an individual header which is to be included in all web requests to the map service.

Parent: <Headers>

Attributes:

• name - specifies the name of the header, typical values of which might be 'referer' or 'key'. The map source provider's API documentation should explain which headers are required and under which circumstances. Header names must be unique.

• value - provides the value of the header. This may include the {k} placeholder if the map source authenticates using a header value instead of the URL, which is more common. Details of the meaning of the {k} placeholder are given in the discussion of the <UrlTemplate> element.

<Start>

Defines the coordinates of the centre of the map display to use the first time the map is shown.

Parent: <MapSource>

Attributes: None

The coordinates are provided as the text content of the element in the format 'latitude, longitude' (in degrees), for example:

<Start>63.7,-102.6</Start>

If no starting coordinates are defined, then the map is initially centred based on the map's region as given with the MapSource region attribute.

<ZoomRanges>

Allows different map services to be used for different ranges of zoom levels between the map source's defined minzoom and maxzoom attribute values.

Parent: <MapSource>

Attributes: None

Zoom ranges are not usually needed to define a map source, but if desired, one or more may be specified with child <ZoomRange> elements. Where used, a zoom range will typically be specified to provide a better base map for lower zoom levels where often the main basemap becomes too small to read.

<ZoomRange>

Represents the details of a map service to use within a specific range of zoom levels lying between the map source's defined minzoom and maxzoom attribute values.

Parent: <ZoomLevel>

Attributes:

• minzoom - specifies the minimum zoom level at which the zoom range applies (how far out the user can zoom). If less than the map source's defined minzoom attribute value, then the greater value will be used. Further details on zoom levels in general are given in the discussion of the <MapSource> element.

• maxzoom - specifies the maximum zoom level at which the zoom  range applies. (how far in the user can zoom). If greater that the map source's defined maxzoom attribute value, then the lesser value will be used. Further details on zoom levels in general are given in the discussion of the <MapSource> element.

• type - corresponds exactly to the equivalent attribute at the map source level, but applied to this zoom range specifically. Full details are given in the discussion of the <MapSource> element.

• ignorecertificateerrors - corresponds exactly to the equivalent attribute at the map source level, but applied to this zoom range specifically. Full details are given in the discussion of the <MapSource> element.

Note: When making use of zoom ranges, all zoom levels between the map source's minimum and maximum supported levels should be covered, with no overlaps or gaps. Failure to do so may result in unexpected behaviour when viewing the map.