Skip to content

.mapurl parameters

Jump to bottom Edit New page
Mark Johnson edited this page Jun 3, 2014 · 41 revisions

A (hopefully complete) .mapurl parameter list

*View [[.mapurl questions|.mapurl--questions]] a list of .mapurl questions *

*View [[.mapurl samples|.mapurl-sample_01]] a sample how to download a specific area *

*View [[.mapurl Convert Tile-Set to a .mbtiles file|.mapurl-Converting-Tile-Set-to-.mbtiles]] using .mapurl parameters *

Note: for .mapurl extension:

  • these files are simple text files that tell geopaparazzi how to communicate with a
    • tile-server (local or remote)
      • remote: url=http://tile.openstreetmap.org/ZZZ/XXX/YYY.png
      • local: url=tiles/1943.Brandenburg/ZZZ/XXX/YYY.jpg
        • do not add: /sdcard/maps/ to this entry
    • wms-server
      • url=http://fbinter.stadt-berlin.de/fb/wms/senstadt/plz?LAYERS=0,1&FORMAT=image/png&SERVICE=WMS&VERSION=1.1.1 &REQUEST=GetMap&STYLES=visual&SRS=EPSG:4326&BBOX=XXX,YYY,XXX,YYY&WIDTH=256&HEIGHT=256
  • each file can support only 1 server
  • the format used for the parser is:
    • parm=value
    • # : can be used as comment for that line and must be the first character
  • possible parameters are:

    • url=http://fbinter.stadt-berlin.de/fb/wms/senstadt/plz?LAYERS=0,1&FORMAT=image/png&SERVICE=WMS&VERSION=1.1.1 &REQUEST=GetMap&STYLES=visual&SRS=EPSG:4326&BBOX=XXX,YYY,XXX,YYY&WIDTH=256&HEIGHT=256

      • mandatory parameter
      • all external/remote servers MUST start with http://
        • [otherwise a directory in the /sdcard/maps is assumed]
          • do not add: /sdcard/maps/ to this entry
      • placeholders:
        • XXX : x tile for tile-servers or x-min/max position for wms servern
        • YYY : y tile for tile-servers or y-min/max position for wms servern
        • ZZZ : zoom-level for tile servers (not used by wms-servern)
        • SSS : 2 servers are supported for this paramater
          • http://mtSSS.google.com/vt/lyrs=s,h&z=ZZZ&x=XXX&y=YYY
            • whereby SSS would be a 'revolving' server ['1' or '2']
        • the order of the ZZZ,XXX,YYY is no longer important as it was in former versions

    • type=wms

      • mandatory parameter
      • possible values:
        • wms
          • &VERSION=1.1.1
            • [x_min,y_min,x_max,y_max] = &BBOX=XXX,YYY,XXX,YYY
            • &SRS=EPSG:????
          • &VERSION=1.3.0 and &CRS=CRS:????
            • [x_min,y_min,x_max,y_max] = &BBOX=XXX,YYY,XXX,YYY
          • &VERSION=1.3.0 and &CRS=EPSG:????
            • [y_min,x_min,y_max,x_max] = &BBOX=YYY,XXX,YYY,XXX
        • tms [y-position starts in the South and ends in the North]
        • google [y-position starts in the North and ends in the South]
          • known as 'Slippy Map' notation used in OpenStreetMap

    • minzoom=10

      • optional parameter [but should be set, based on what the server supports]

    • maxzoom=17

      • optional parameter [but should be set, based on what the server supports]

    • bounds=13.0512 52.3246 13.7785 52.6935

      • optional parameter [but should be set, otherwise 180.0 -85.05113 180.0 85.05113 will be assumed]
      • geopaparazzi will now move to centre of this area if the map, when loading, is outside of these bounds
        • if the present zoom-level is outside the min/max zoom - the nearest zoom (min or max) will be used

    • center=13.37771496361961 52.51628011262304

    • # Brandenburger Tor, Berlin

      • optional parameter [but should be set, otherwise centre of bounds will be assumed]
        • this must not be the centre of the map, but can be a chosen point [the point above is the Brandenburg Gate in Berlin]
      • geopaparazzi will now move to this point, when loading the map and the Map is outside of these bounds
        • if the present zoom-level is outside the min/max zoom - the nearest zoom (min or max) will be used

Special commands for mbtiles support:

  • it is possible, while the application is running, to store the requested tiles to a mbtiles-database

    • once stored, that tile will be read from the mbtiles database and no longer requested from the tile-server

    • mbtiles=stadt-berlin.de/berlin_postleitzahlen.mbtiles

      • optional parameter
      • starting with version 3.7.0, a mbtiles file can be used to store the retrieved tiles
      • the given directory must be inside the /sdcard/maps/ directory
        • if the directory does not exist, it will be created
        • if the mbtiles file does not exist, it will be created
          • all the needed tables and views (also for, the not-used, grid-tables) will be created
          • the metadata-table default values will be set, many from those used in the .mapurl file
      • Note: when images are being retrieved by the application, it will first look in the given mbtiles file
        • if found: the image will be returned
        • if not found: the normal request to the wms or tile-server will be done
          • when the image has been retrieved, it will be stored into the mbtiles file

    • name=Berliner Postleitzahlen ; 1:5000 ;1:10000

      • optional parameter, mandatory for mbtiles metadata

    • description=Darstellung der Postleitzahlengebiete und deren Postleitzahlen.

      • optional parameter, mandatory for mbtiles metadata

    • defaultzoom=17

      • optional parameter
      • Note: together with the center= parameter, the mbtiles.metadata field will be created
        • center=13.37771496361961,52.51628011262304,17
        • this is a 'tillmill' specific parameter and NOT part of the mbtiles specification
          • useful when you have many files of the same area and want to use a common starting point

    • format=jpg

      • optional parameter
      • which image format should the tiles be stored in [jpg,png]
      • Note: jpg is the default.
        • in my experience mbtiles files with jpg are about 70% smaller that those with png.

Special commands for mbtiles background downloading from given areas and zoom-levels:

  • when the fill command is used a temporary table called request_url will be created inside the mbtiles file

    • for each tile that is to be downloaded there will be one record

  • once the tile has been stored, this request record will be deleted

  • should the application stop before all the requests have been retrieved:

    • the request_url will still have all of the open requests

  • when all of the requested tiles have been retrieved and the request_url is empty:

    • then the request_url table will be deleted

  • this will work all tile-servers supported by the .mapurl, including local tile diretories

  • request_type commands:

    • replace: fill request_url with the 'requests' of tiles of the given request_zoom_levels and request_bounds
      • replacing existing tiles
    • fill: fill request_url with the 'requests' of tiles of the given request_zoom_levels and request_bounds
      • ignoring existing tiles [it will retrieve only the missing tiles]
    • once the table has been filled, fill or replace can be removed
    • drop: drop the request_url table, created with fill or replace [no more requests will be made]
      • drop will be called automaticly when the request_url is empty
    • load: download tiles requested in request_url
      • this can be added to the fill or request
        • but can also run alone assuming the 'request_url' table has been filled
    • update_bounds: set the bounds min/max/default zoom-levels based on the tiles found in the database
      • load will call update_bounds when starting and at every new zoom-level
    • reset_metadata: will manually reset the mbtiles-metadata entries: [if you want to change the description]
      • 'name','description','bounds','center','minzoom','maxzoom' ; NOT: 'format','tile_row_type'
      • if used with load, reset_metadata will run after load has completed
# 'no `run` ***no fun*** - without 'run' or a 'runx': all request commands will be ignored
# use ',' with multiple commands - order is not important (drop will be done before fill; load as last)
# request_type=run,load
# request_type=run,update_bounds
# the following command would: fill the 'request_url' table, 
# download the files and 
# afterwords **replace** the calculated center with `center`and `defaultzoom` given above 
# - the order is **NOT** important
  • request_type=run,fill,load,reset_metadata
# the bounds to use when creating 'request_url'
# if 'request_bounds' is not set: 'bounds' value will be used [care should be taken with this]
  • request_bounds=13.2605 52.4634 13.4544 52.5519
# if 'request_zoom_levels' are not set: `minzoom`and `maxzoom` values  will be used
  • request_zoom_levels=10-12
# the zoom levels to use when creating 'request_url'

Tips: for .mapurl creation:

  • possible restrictions of tile / wms servers
    • the Application User should be aware that some tile / wms servers have restrictions of usage terms
      • some do not permit the local storage of their tiles
      • some only permit the usage for non-commercial purposes
        • please take this into consideration when using the mbtiles= parameter
      • some only permit the usage when they are named as the original source
        • please use the description= parameter for this
  • for wms servern retrieve the 'GetCapabilities' Information:
    • wget 'http://fbinter.stadt-berlin.de/fb/wms/senstadt/plz?&SERVICE=WMS&REQUEST=GetCapabilities' -O Berliner_Postleitzahlen.txt
      • search for : 'LatLonBoundingBox'
        • <LatLonBoundingBox minx="13.0512" miny="52.3246" maxx="13.7785" maxy="52.6935" />
          • use these values for the bounds: bounds=13.0512 52.3246 13.7785 52.6935
      • search for : '<SRS>EPSG:4326</SRS>'
        • geopaparazzi can only retrieve data from servers that support EPSG:4326 [Wsg84]

2014-06-03: Mark Johnson, Berlin Germany

Add a custom footer
Add a custom sidebar
Clone this wiki locally