MapsforgeSrv

This project was originally cloned from the MOBAC (Mobile Atlas Creator) project MapsforgeSrv.

The MapsforgeSrv is a local webserver providing rendered Mapsforge map tiles.
The tiles are always rendered on the fly when requested.

Source of this tile server is located at branch tasks of mapsforgesrv project.
The JAR file mapsforgesrv-fatjar.jar can be downloaded from assets of <release>_for_java11_tasks at releases.
The JAR file is developed and built with Java development kit (JDK) version 11 and needs Java runtime environment (JRE) version 11 or higher to run.
The JAR file contains everything needed to run.

Some graphical user interfaces to configure interactively and run MapsforgeSrv can be found at https://github.com/JFritzle.
In particular, there are convenient interfaces between MapsforgeSrv and the map applications QMapShack or MyTourbook.

Command line parameters:

-c   [config]		Configuration folder (default: none)
-h   [help]  		Print the help text and exit 

Run mapsforge tile server:

java -jar <Path>/mapsforgesrv-fatjar.jar -c <Configuration folder>

Configuration requirements:

• Configuration folder must contain a server configuration file server.properties and a subfolder tasks.
• Subfolder tasks can contain several task configuration files with file extension .properties.
• Each task configuration files configures a separate server task to be processed concurrently.
• Case-sensitive server task name = task file name with file extension cut off.

Each configuration file can contain

• Parameter assignment lines of type name=value
• Comment lines starting with character #
• Separator lines containing white spaces only

Server configuration file server.properties parameters:

Name	Description
host	IP address to listen on Default: unset = listen on all interfaces
port	TCP port to listen on Default: 8486
cache-control	Browser cache TTL Default: 0
terminate	Accept administrative terminate request to shutdown server gracefully Default: false
admin_anywhere	In addition to loopback addresses only, accept administrative requests terminate and updatemapstyle from any IP address Default: false
outofrange_tms	URL pattern of an external TMS server used to redirect for out-of-range tiles e.g. https://a.tile.openstreetmap.fr/osmfr/{z}/{x}/{y}.png Default: unset = no redirection Note 1: Server returns redirection URL and HTTP status code 302 to client. It is up to the client to handle redirection. Note 2: When built-in world map is appended to map files, redirection never occurs.
requestlog-format	Output format of logged server requests Default: From %{client}a Get %U%q Status %s Size %O bytes Time %{ms}T ms Empty value suppresses request logging! For description of format syntax see here.

Task configuration file parameters:

Name	Description
mapfiles	Comma-separated list of map file paths with file extension .map Default: unset = built-in world map automatically used
worldmap	Append built-in world map to list mapfiles of map files Default: false
language	Preferred language if supported by map file (ISO 639-1 or ISO 639-2 if an ISO 639-1 code doesn't exist) Default: unset = primary available map language used
themefile	File path with file extension .xml of external theme file or name of built-in Mapsforge theme to use for rendering. Currently known built-in Mapsforge themes: DEFAULT, OSMARENDER, BIKER, MOTORIDER, DARK or INDIGO Built-in themes may change depending on Mapsforge version. Default: built-in Mapsforge theme OSMARENDER
style	Theme's style used for rendering Default: unset = theme's built-in default style
overlays	Comma-separated list of style's overlays to be enabled for rendering Default: unset = style's overlays enabled in theme by default
demfolder	Folder path containing DEM (Digital Elevation Model) data files with file extension .hgt required by hillshading Alternatively, .hgt files can be embedded in .zip archives with same name, e.g. archive N49E008.zip containing one file N49E008.hgt Default: unset = no hillshading
hillshading-algorithm	One of hillshading algorithms used for hillshading simple(linearity,scale) diffuselight(angle) stdasy(asymmetryFactor,minSlope,maxSlope,readingThreadsCount,computingThreadsCount,preprocess) simplasy(asymmetryFactor,minSlope,maxSlope,readingThreadsCount,computingThreadsCount,preprocess) hiresasy(asymmetryFactor,minSlope,maxSlope,readingThreadsCount,computingThreadsCount,preprocess) adaptasy(asymmetryFactor,minSlope,maxSlope,readingThreadsCount,computingThreadsCount,preprocess) Hillshading algorithm name without parentheses and parameters is valid too! Default: unset = no hillshading Parameter defaults: linearity = 0.1, scale = 0.666, angle = 50., asymmetryFactor = 0.5, minSlope = 0, maxSlope = 80, readingThreadsCount = max(1,AVAILABLE_PROCESSORS/3), computingThreadsCount = AVAILABLE_PROCESSORS, preprocess = true Parameter ranges: 0. ≤ linearity ≤ 4., 0. ≤ scale, 0. ≤ angle ≤ 90., 0. ≤ asymmetryFactor ≤ 1., 0 ≤ minSlope < maxSlope ≤ 100, readingThreadsCount ≥ 0, computingThreadsCount ≥ 0, preprocess = {false|true}
hillshading-magnitude	Hillshading's gray value magnitude scaling, 0. ≤ value ≤ 4. Value < 1. = brighter gray, value > 1. = darker gray Default: 1. = unscaled gray values
hillshading-zoom-min	Hillshading's minimum zoom level, 0 ≤ value ≤ 20 Default: unset = theme's built-in value or default value used Note: The smaller the minimum zoom level, the longer the rendering may take
hillshading-zoom-max	Hillshading's maximum zoom level, 0 ≤ value ≤ 20 Default: unset = theme's built-in value or default value used
contrast-stretch	Contrast stretching of color value, 0 ≤ value ≤ 254 to increase contrast by raising black level from 0 towards white level 255 Default: 0 = no contrast stretching
gamma-correction	Gamma correction value > 0. for nonlinear luminance mapping Default: 1. = no gamma correction
text-scale	Text scale factor > 0. to scale size of labels on map Default: 1. = no text size scaling
symbol-scale	Symbol scale factor > 0. to scale size of symbols on map Default: 1. = no symbol size scaling
line-scale	Line scale factor > 0. to scale thickness of lines on map Default: 1. = no line thickness scaling
user-scale	Overall scale factor > 0. to scale all map elements Scales value of text-scale and symbol-scale and line-scale Default: 1. = no overall scaling
device-scale	Device scale factor > 0. Default: 1. = no device scaling

Hillshading requirements:

• Must be enabled in theme file
• Parameter demfolder must be set
• Parameter hillshading-algorithm must be set
• If parameter mapfiles is set, hillshading is applied to rendered map tiles.
  If parameter mapfiles is not set, alpha transparent overlay tiles are rendered

URLs to request tiles from tiles server:

scheme://address:port/zoom/x/y.format?task=name

URL item	Description
scheme	protocol either http or https
address	tile server's IP address
port	tile server's TCP port to request tiles
zoom	zoom level of requested tile
x	tile number in x direction (longitude)
y	tile number in y direction (latitude)
format	tile image format png, jpg, tif, bmp, ...
name	name of server task

URL example for requesting tiles from a task configured by the Map.properties task file:

http://127.0.0.1:60815/14/8584/5595.png?task=Map

Administrative server requests:

scheme://address:port/request

Request	Description
terminate	Gracefully shutdown server
updatemapstyle	Force server to reload theme files with file extension .xml from file system and update associated tasks (required if the file content has been changed)

By default, administrative requests are accepted from loopback addresses only. But this behavior can be overridden by the server property admin_anywhere to accept administrative requests from any IP address.

How it works:

After reading a task .properties file, server immediately initializes and starts each task's own task handler. As long as there are no incoming client requests for that task, the task handler does nothing but wait.

While server is running, task files and thus tasks can be added, modified or deleted on the fly.

Independently from other task handlers, each task handler renders tiles using the parameter set from it's own .properties file. Tiles are requested by task's unique request URL. Thus, different tasks do never conflict.

---

Build and distribution instructions

• can be found in the HOWTO

---

Contributors

• r_x created this tile server as part of mobac project https://sourceforge.net/projects/mobac/
• Thomas Th. @telemaxx: converted the mapserver server part in own git project with gradle nature.
• @pingurus (fixing stylesheets error)
• Bernd @bjmdev (multi map support)
• @JFritzle (selectable theme style, overlays, renderer, contrast-stretch, hillshading, gamma correction,
  some rendering scale factors, hillshading overlay with alpha transparency)
• @nono303 a lot of improvements/rework

Licenses

• MapsforgeSrv
  MapsforgeSrv is licensed under the GNU General Public License v3.0.
• Built-in Mapsforge world map
  All map data © OpenStreetMap contributors http://www.openstreetmap.org/copyright.
  OpenStreetMap is open data, licensed under the Open Data Commons Open Database License (ODbL).
• Included Marlin renderer engine
  Marlin is a fork from OpenJDK 8 and therefore licensed under the GNU General Public License, version 2, with the Classpath Exception.