patrick-lindemann / warzone-osm-mapmaker Goto Github PK

This tool is part of the Bachelor's Thesis OSM Risk Maps which was conducted at the Institute For Formal Methods of Informatics at the University of Stuttgart. For more information about the thesis or this project, feel free to contact an author.

• Map Creation
  • Downloading OSM Data
  • Preparing The Extract (Optional)
  • Inspecting The Extract
  • Creating The Map
  • Tips for Map Creators
• Map Upload
  • Setup
  • Uploading the Map
  • Uploading the Metadata
• Building the Project (Ubuntu)
  • Pre-Requisites
  • Installation
• Built With
• Authors

If you are not familiar with the OpenStreetMap project or Warzone, we recommend that you find out more about them in the OpenStreetMap Wiki or Warzone Wiki, repsectively.

This tool depends on real OpenStreetMap data in order to generate the playable maps. In detail, administrative boundary areas with specified admin_levels are extracted from an input file and put together into a Warzone Map. The meaning of administrative levels differs between countries, a mapping can be found in this table. You can visualize the administrative borders of various countries with tools such as OSM-Boundaries.

You can control which boundaries are extracted as territories and bonuses (and super-bonuses) with the two parameters

• --territory-level <level>
• --bonus-levels <level> ... <level>

For example, if you want to create a warzone map of Germany, using --territory-level 4 would yield a map with its federal state borders (Bundesländer), --territory-level 6 would use the county borders (Landkreise). By combining the levels with --territory-level 6 --bonus-levels 4, you would create a map with county borders as territories and federal state borders as bonuses.

You can find and download an extract of your choice from Geofabrik, a server that provides regularily updated OSM data files for the whole planet. Please note that such files can reach sizes up to 58.5GB (planet.osm.pbf), depending on the scale of your extract, which is why we recommend that you download the extracts compressed with the Protocol Buffer Format (.pbf).

If you just want to test the tool, you can use the mapmaker with the included data/isle-of-man.osm.pbf extract.

We are only interested in the administrative boundaries of OpenStreetMap to create our maps. Yet, map extracts contain lots of other information such as roads, buildings, points of interest, etc. This data is automatically skipped by the mapmaker, but larger files take longer to read, which can be tedious if you adjust the parameters for your map multiple times.

If you work with larger map extracts (> 10MB in compressed size), we strongly recommend to prepare the data by pre-filtering the boundaries of your downloaded map extract. This greatly reduces the file size of your data; for example, applying the pre-filter to a (compressed) map extract of Germany with a file size of 3.56GB reduces its file size to only 33MB.

To prepare your map extract, use the following command:

./warzone-osm-mapmaker prepare <path/to/file.osm.pbf> [parameters]

This will create a pre-filtered file with the naming schema <input-file>-prepared.osm.pbf. Afterwards, you can use this file for the next map creation steps.

The prepare command accepts the following parameters:

After you have downloaded (and pre-filtered) the map extract, you should inspect it by entering

./warzone-osm-mapmaker checkout <path/to/file.osm.pbf>

This will display a table of useful information as well as level level distribution for the map extract. You can use this table to decide which levels should be used as territory and bonus levels.

In this step, we can finally create our map by entering

./warzone-osm-mapmaker create <path/to/file.osm.pbf> [parameters]

The mapmaker creates two outputs: A svg file that contains the geometry of the territories and bonuses, and a .json file with the metadata, which consists of

• The name, center point and neighbors for each territory and
• The name, color, army count and subareas for each bonus.

In order to play your map in Warzone, you will need to upload the map, which will be covered in the next section.

Usually, you want to customize your generated map. For this, we offer a list of additional parameters that you can specify to alter the results:

• The width and height of your map should not exceed 2500x2500 pixels, as Warzone does not accept larger map sizes.
• Your generated map .svg should not exceed 2.5MB, as Warzone does not accept larger file sizes. You can reduce the map size by applying a greater compression tolerance.
• Currently, creating super bonuses is not possible through the Warzone API. If you add more than one bonus level, you need to add the super bonus metadata manually through the Warzone Mapmaker.

In order to upload maps to the Warzone Community Map Explorer, you will first need to create a Warzone Account. Afterwards, you can continue with the Setup.

To add the metadata that is generated with your map, we use the Warzone Set Map Details API. Before you can use the upload function, you first need to create a configuration file (named config.json), which you can do with the following command:

./warzone-osm-mapmaker setup [parameters]

During the setup, you will be asked to enter your Warzone user e-Mail and your personal API access token, which is needed to authenticate you in the upload process. You can retrieve your personal token via the Get Token API, which can be accessed directly with this link after you've logged in. The response will look like this:

{
  "APIToken" : "QPxpV5bRa$bBCYVOs3PF#MKgApbWISKW#kR0p8qY",
  "information" : "[...]"
}

Now, you can copy the value of the APIToken field (without the quotation marks) and pass it to the application when asked. After you finish the setup, your config.json should look like this:

{
   "email": "[email protected]",
   "api-token": "QPxpV5bRa$bBCYVOs3PF#MKgApbWISKW#kR0p8qY"
}

Important: Your personal API token is used along with your e-mail address to authenticate your user with Warzone and act on your behalf. You should never reveal this token to other players - treat it as you would treat your password. If you ever suspect that someone knows your API token, you should immediately change your Warzone account password, which will cause your token to re-randomize and stop the old one from working.

The setup command accepts the following parameters:

As of November 2021, Warzone offers no API endpoint to upload a generated map. Therefore, you need to upload your map manually by using the Warzone interface:

1. Open your browser and go to Warzone's home page https://www.warzone.com.
2. On the navigation bar on the top right, extend the item Multi-Player and select Design Maps.
3. Click on the button Add New Map.
4. In the appearing file explorer, find your generated .svg map file and upload it.
5. Next, a window will appear where you can enter a title and description for your map. After you filled out both fields, click on the Submit button.
6. If everything worked correctly, a new card with the name of your map will appear. If not, an error message will be shown.

Now, you can inspect your map in the Warzone Map Designer by opening and editing it. You will see that the borders of the territories and their center points are displayed in the editor, yet no names or connections are available. We will upload this metadata in the next step.

After you uploaded the map, you can upload the metadata of the generated .json with the mapmaker. Before you can proceed, you first need to retrieve the id of your uploaded map:

1. Open your map in the Warzone Map Designer.
2. Under Map Versions, click on Edit on your preferred map version (if you just uploaded the map, it will be 1.0).
3. In the left sidebar, click the button Link for Sharing.
4. A window with a public and private link will appear. You only need the public link, which has the pattern https://www.warzone.com/SinglePlayer?PreviewMap=12345. Copy the trailing number (here: 12345), which is your map id.

Now, you can upload the generated metadata with the upload command:

./warzone-osm-mapmaker upload <path/to/file.json> <map-id> [parameters]

At last, the result of the upload request will apper on the screen. If it was sucessful, the message will look like this:

{
  "termsOfUse" : "[...]",
  "Success" : ""
}

If an error occured during the upload, the message will contain an error:

{
  "termsOfUse" : "[...]",
  "Error" : " [...]"
}

You can use the error message to identify and fix the error.

The upload command accepts the following parameters:

This section provides an installation guide for Linux Ubuntu systems.

The project depends on multiple third-party libraries which have to be installed prior to the project setup. Before you start installing packages, be sure to update your current packages by entering

sudo apt update

You will need to install the build essentials that allow you to build this C++ project. You can install them at once with this command:

sudo apt-get install -y -V \
  git \
  g++ \
  make \
  cmake \
  doxygen \
  graphviz \
  autoconf \
  libboost-dev \
  libboost-filesystem-dev \
  libboost-program-options-dev

All other dependencies will be installed automatically by the super build during the installation. However, you can also install them optionally by yourself:

sudo apt-get install -y -V \
  libbz2-dev \
  liblz4-dev \
  libexpat1-dev \
  libosmium2-dev \
  libproj-dev \
  libsparsehash-dev \
  libutfcpp-dev \
  zlib1g-dev

1. Clone this repository via

git clone https://github.com/PatrickLindemann/warzone-osm-mapmaker.git

2. Build the project

mkdir build
cd build
cmake ..
make

3. Test the program by entering

./warzone-osm-mapmaker -h

If the installation was sucessful, a help message with the available commands will appear.

TODO: This section will provide an installation guide for 64-Bit Windows systems.

• Boost - Free peer-reviewed portable C++ source libraries - Github
• Libosmium - A fast and flexible C++ library for working with OpenStreetMap data - Github
• nlohmann/json - A modern JSON library for C++ - Github

• Patrick Lindemann - Initial work - Github