fpw / avitab

X-Plane plugin that displays a tablet to aid VR usage
GNU Affero General Public License v3.0
299 stars 58 forks source link

Configurable online slippy maps 2 #166

Closed cyberang3l closed 10 months ago

cyberang3l commented 10 months ago

Add support for user configurable online slippy maps

image

This commit adds support for user configurable online slippy maps. The user must provide the configuration via the config file located in X-Plane 12/Resources/plugins/AviTab/online-maps/mapconfig.json.

The configuration file must contain a list of json dictionaries (one dictionary per map definition) with the following required keys:

name: This name parameter contains the name of the map that will be listed in the list of maps when the user clicks the "Online" button that was introduced in a previous commit in the MapApp. Note that it is up to the user to ensure that they provide unique names and don't confuse themselves when they end up seeing multiple lines with the same map name in AviTab. In the code, each map is treated with an incremental unsigned integer, so it is technically possible to have two different maps with the same name. The alternative would be to use the name as the unique identifier for each map, and either throw and error when the user defines a duplicate map name, or implicitly only show the last map that was defined with a given name. I didn't opt for the latter as any implicit action is more confusing even if it's documented (users never read the docs anyway). For any user with common sense should be relatively straight forward to figure out that the configuration they edited a minute earlier needs fixing in the unlikely scenario that they used the same name twice and see a duplicate entry in AviTab. Note that when editing the mapconfig.json, the user doesn't need to restart AviTab - only exit the map selection and re-open it.

servers: The servers parameter contains a list of hostnames that will be used to download tiles from, as it is often common to have more than one servers serving tiles. At least one server must be provided.

copyright: The copyright parameters contains a simple copyright notice string and is a required parameter.

url: The url param contains the url that each tile can be downloaded from. The placeholders {x}, {y}, and {z} are replaced with the x/y location of each tile, and the zoom level as explained here: https://wiki.openstreetmap.org/wiki/Slippy_map_tilenames

Three addition optional parameters can be used:

min_zoom_level: The min_zoom_level parameter must be a positive number (>= 0) that defines that minimum allowed zoom level for the given map. If not provided, 0 is used as the default min_zoom_level value.

min_zoom_level: The max_zoom_level parameter must be a positive number (>= 0) that defines that maximum allowed zoom level for the given map. If not provided, 16 is used as the default max_zoom_level value.

enabled: The enabled parameter is a boolean (true/false) parameter that tells AviTab if the current map will be included in the list of maps to be shown to the user. If not provided, a true value is assumed by default. This can be useful when a user has a configuration file with a large collection of maps, but wants to disable some of them (to save themselves from etternal scrolling) without deleting them from the config.

A sample configuration file that defines the OpenStreetMap and OpenTopoMap sources is included in this commit:

[
    {
        "name": "OpenStreetMap",
        "servers": [
            ".tile.openstreetmap.org"
        ],
        "copyright": "Map tiles (c) OpenStreetMap (ODbL)",
        "url": "{z}/{x}/{y}.png",
        "min_zoom_level": 1,
        "max_zoom_level": 17
    },
    {
        "name": "OpenTopoMap",
        "servers": [
            ".tile.opentopomap.org"
        ],
        "copyright": "Map Data (c) OpenStreetMap, SRTM - Map Style (c)
OpenTopoMap (CC-BY-SA)",
        "url": "{z}/{x}/{y}.png",
        "enabled": false
    }
]

Current decisions and limitations that will be altered/fixed in an upcoming PR:

  1. Only one tile server is supported at the moment and must be of the form ".tile.server.com". That is due to the OpenTopoSource class assuming by default three servers (a, b and c), and explicitly prepends those to the server name. This will be fixed in the next commit to allow for arbitrary definition of servers; I didn't want to mess with the OpenTopoSource in this commit.
  2. The min/max zoom levels are also not used yet - need changes in the OpenTopoSource class.
  3. The url is not yet used. Similar requirements for changes in the OpenTopoSource class.
  4. In the provided sample config, the OpenTopoMap map is disabled by default, as it is already a dedicated button in the MapApp. In an upcoming PR we can move the OpenTopoMap in the list of online maps and remove the dedicated button
cyberang3l commented 10 months ago

Addressed all the comments.