Skip to content

Latest commit

 

History

History
34 lines (24 loc) · 15.1 KB

tiles.md

File metadata and controls

34 lines (24 loc) · 15.1 KB
Raw

<URLTile /> and <WMSTile />Component API

Props

Prop Type Default Note
urlTemplate String The url template of the map tileserver.

(URLTile) The patterns {x} {y} {z} will be replaced at runtime. For example, http://c.tile.openstreetmap.org/{z}/{x}/{y}.png. It is also possible to refer to tiles in local filesystem with file:///top-level-directory/sub-directory/{z}/{x}/{y}.png URL-format.

(WMSTile) The patterns {minX} {maxX} {minY} {maxY} {width} {height} will be replaced at runtime according to EPSG:900913 specification bounding box. For example, https://demo.geo-solutions.it/geoserver/tiger/wms?service=WMS&version=1.1.0&request=GetMap&layers=tiger:poi&styles=&bbox={minX},{minY},{maxX},{maxY}&width={width}&height={height}&srs=EPSG:900913&format=image/png&transparent=true&format_options=dpi:213.
minimumZ Number The minimum zoom level for this tile overlay.
maximumZ Number The maximum zoom level for this tile overlay.
maximumNativeZ Number (Optional) The maximum native zoom level for this tile overlay i.e. the highest zoom level that the tile server provides. Tiles are auto-scaled for higher zoom levels.
zIndex Number -1 (Optional) The order in which this tile overlay is drawn with respect to other overlays. An overlay with a larger z-index is drawn over overlays with smaller z-indices. The order of overlays with the same z-index is arbitrary.
tileSize Number 256 (Optional) Tile size, default size is 256 (for tiles of 256 _ 256 pixels). High-res (aka 'retina') tiles are 512 (tiles of 512 _ 512 pixels).
doubleTileSize Boolean false (Optional) Doubles tile size from 256 to 512 utilising higher zoom levels i.e loading 4 higher zoom level tiles and combining them for one high-resolution tile. iOS does this automatically, even if it is not desirable always. NB! using this makes text labels smaller than in the original map style.
flipY Boolean false (Optional)Allow tiles using the TMS coordinate system (origin bottom left) to be used, and displayed at their correct coordinates.
tileCachePath String (Optional) Enable caching of tiles in the specified directory. Directory can be specified either as a normal path or in URL format (file://). Tiles are stored in tileCachePath directory as /{z}/{x}/{y} i.e. in sub-directories 2-levels deep, filename is tile y-coordinate without any filetype-extension.

NB! All cache management needs to be implemented by client e.g. deleting tiles to manage use of storage space etc.
tileCacheMaxAge Number (Optional) Defines maximum age in seconds for a cached tile before it's refreshed. NB! Refresh logic is "serve-stale-while-refresh" i.e. to ensure map availability a stale (over max age) tile is served while a tile refresh process is started in the background.
offlineMode Boolean false (Optional) Sets offline-mode. In offline-mode tiles are not fetched from the tile servers, rather only tiles stored in the cache directory are used. Furthermore automated tile scaling is activated: if tile at a desired zoom level is not found from the cache directory, then lower zoom level tile is used (up to 4 levels lower) and scaled.
opacity Number (Optional) Map layer opacity. Value between 0 - 1, with 0 meaning fully transparent.

Using tile components

Both URLTile and WMSTile components require access to a tileserver. Please note that due to overuse OpenStreetMap free tileservers do not work on Android with URLTile and are not recommended to be used for iOS either for other than small scale test use.

URLTile and WMSTile components both implement caching and non-caching usage modes. Non-caching is the default and uses Android and iOS default implementations for tile overlays. Non-caching means that there is no caching of map tiles in React Native Maps implementation, however both iOS and Android do some limited caching with their default implementation. Non-caching mode works well when network connectivity is good and is simple to use.

Caching mode is activated when tileCachePath property is defined as a valid directory where React Native app has read & write access. In caching mode any new tile fetched from the tileserver is also cached in the directory defined by tileCachePath property and cached version is used for any future access to the tile, which means tiles can be used also when there is no or limited network connectivity. Caching also allows pre-loading of tiles to the cache directory, enabling offline map loading functionality which is typical feature in many map applications.

NB! There is no cache size management in React Native Maps, rather developer needs to implement in JS side code some mechanism to watch the size of tile cache directory and either automatically remove old tiles or allow user to delete the tiles.

tileCacheMaxAge property enables automatic renewal of cached tiles. Refresh logic is "serve-stale-while-refresh" meaning that when expired (i.e. older than defined tileCacheMaxAge) tile is requested the old cached ("stale") tile is served while a background process is started to refresh ("update") the expired tile. Refresh logic is optimised for poor network connectivity situation / app offline-mode use: if tile is cached, user is always served a tile even if it is stale, before a tile refresh is attempted and a failure in tile refresh is not a problem as stale tile remains available. Refresh logic is "lazy" i.e. tile refresh check is only done when tile is accessed. Any other refresh logic needs to be implemented in JS side code e.g. at set time intervals checking through tiles in cache and refreshing tiles as needed.

offlineMode property enables mode in which only cached tiles are used, tile fetch from tileserver is not even attempted. This is useful for situations when network connectivity is poor and repeated & possibly failed attempts to fetch tiles (even with caching enabled) from tileserver would increase device power consumption. Another benefit of offline-mode is that if a requested tile is missing from the cache then lower zoom level tiles are used if available and served (after scaling). This is especially useful when user has pre-loaded an area of map for certain zoom levels, allowing user to zoom in the map to higher zoom levels than which were pre-loaded.

maximumNativeZ property works both in caching and non-caching mode, however it is very much recommended to be used in caching mode: it sets the highest zoom level for tiles to be fetched from the tileserver. Any higher zoom levels that maximumNativeZ will be created by scaling a lower zoom level tile. This will help to manage the cache size, since an increase in zoom level means 4 times as many tiles are needed as in a previous level. Depending on type of map tiles and their quality a maximumNativeZ set at 15 - 17 and maximumZ set at 18 - 20 will often give good results, allowing user to zoom in deep into the map with good enough map visual quality.