TheKarte

TheKarte is an interactive map application to visualize and to create geographical data. It was designed with two design criteria in mind:

1. It works as a stand-alone application (i.e., keeping data private).
2. Everything can be done with a keyboard, is done with the keyboard.

TheKarte uses a VI-inspired menu for interacting with the map. Therefore, the application does not contain any buttons or other UI components beside the map. Moreover, TheKarte is implemented as single page application.

Functionality

Functionality for data handling:

• draw features (e.g., circles, points and polygons) and delete features,
• add and delete layers, and
• select features using other features (e.g., a subset of points within a polygon).

Loading and exporting data:

• load features from files (via drag and drop),
• exporting data via local download.

Functionality for styling:

• (default) every layer is assigned a distinctive color,
• use image (one per layer) to represent points (via drag and drop), and
• clip lower layers (hide background map).

Functionality to change the view:

• change the background tile,
• zoom to the extend of the current layer, and
• change rendering method if performance is not sufficient.

Privacy: Please note that all geographical data only resides in your web browser (while TheKarte is executed) and nothing is send to any servers. For background maps, see below.

Getting started

TheKarte presents a UI consisting of a map, which is presented in full screen. As expected, a user can interact with the map using his mouse or touchscreen for panning and zooming.

Demos

• Demonstration of the basic features: demo/TheKarte-basic.mp4
• Demonstration on how to create images: demo/TheKarte-image.mp4

Keyboard-based menu

To access more advanced functionality the keyboard-based menu needs to be used. By default, the menu is configured for use with the left hand with the fingers resting on ASDF. The menu is navigated by pressing the adequate key to navigate lower into sub-folders or execute desired actions (e.g., leafs).

Special keys are:

• 'h': (top of the menu only) show the menu structure in an extra window as well as on the browser's developer console.
• 'g': (for actions that require a parameter) enter the parameter first and then execute the action. For example, switch to a different layer.
• 'v': navigate the menu upwards (incl. exiting currently executed interaction).

On example on how to use TheKarte (in brackets are the keys to pressed for the keyboard-based menu):

1. Draw points:
2. Press 'a' and then 's' to execute MenuActionFeatureAdd(Point).
3. Click on desired locations to draw points.
4. When you are done: press 'v' to stop drawing while remaining in 'a' sub-menu.
5. Add a new layer: press 'a' to execute MenuActionLayerAdd. This action is immediately executed and thus 'v' is not necessary.
6. Draw circles:
7. Press 'f' to execute MenuActionFeatureAdd(Circle).
8. Click on desired locations to draw new circles.
9. When you are done: press 'v' (twice) to stop drawing and navigating to the main menu.
10. Export created data as KML: press 'w', 'a' and then 'd'.

The keyboard-based menu is defined in TheKarte.html. Please adjust to your personal needs (for example, remove unnecessary functionality).

Hint: The browser's developer console shows useful information about the usage of TheKarte.

Loading and exporting data

TheKarte loads geographical data via drag and drop: just drag files from your local computer onto TheKarte.

The following file formats are accepted:

• Keyhole markup language (KML): file suffix '.kml',
• GPS exchange format (GPX): file suffix '.gpx',
• GeoJSON: file suffix '.json' or '.geojson'.
• Well-known text (WKT): file suffix '.wkt' WKT can also be loaded by (a) dragging it as text and (b) pasting it onto TheKarte.

Moreover, two tools are included for data conversion:

• TheKarte-2kml.html: convert CSV-files and JSON-files to KML as well as KML to CSV.
• TheKarte-TheKarte-geocoder-OSM-nominatim.html: geocodes addresses via OpenStreetMap's Nominatim.

Background maps

By default, some background map services (i.e., Web Map Service (WMS)) are included in TheKarte.

PRIVACY ISSUE: Please be aware that by using such services you (a) download data from them and therefore (b) these can derive, which parts of the world you are looking at (incl. zoom level). If this is an issue, please use your own WMS (e.g., export of OpenStreetMap).

Screenshots

TheKarte enables to export the map as PNG image. See action MenuActionExportPNG. An exported image has the exact resolution of the map, which is by default identical to the map shown on the screen. Hint: The resolution can be increased by zooming out using the brower's zoom feature and respositing the map.

Configuration

TheKarte can be easily configured. This mainly considers modifying the settings to your needs or adjusting the keyboard-based menu. All relevant code for this resides in TheKarte.html. To create a new configuration, just copy TheKarte.html, modify this copy, and open in your web browser.

Autopilot

TheKarte features has an autopilot feature (i.e., allowing to load data and interact with it automatically). This scripting feature enables to pre-setup TheKarte if desired.

To use the autopilot, a URL containing the commands must be provided as location.search. Commands are separated by the variable separator & and are executed in order from left to right.

Supported commands:

• all configured keyboard-based menu commands (spelling must be identical to configuration)
• geoText(dataType, TEXT)
• geoURL(dataType, URL)
• styleImageURL(URL)
• screenshot(filename)

ATTENTION: Please note that the parameters usually need (depending on your browser) to be URI-encoded (e.g. encodeURI() for JavaScript). For example, white spaces need to be encoded as %20 in a URL. This is relevant especially while using [WKT(https://en.wikipedia.org/wiki/Well-known_text) (e.g., POINT(1 1) becomes POINT(1%201)).

Some autopilot demos:

• Draw a point for Berlin (Germany) on the first layer, add a second layer and Paris (France). Berlin is shown in blue and Paris in green as they reside on different layers.
  URL: TheKarte.html?geoText(wkt,POINT(13.03367%2052.41362))&a&a&geoText(wkt,POINT(2.3522219%2048.856614))
• Loading a KML file (contain points) and render these using the OpenLayers logo.
  URL: TheKarte.html?geoURL(kml,https://openlayers.org/en/latest/examples/data/kml/2012_Earthquakes_Mag5.kml)&styleImageURL(https://openlayers.org/en/latest/examples/resources/logo-70x70.png)
• Creates a screenshot and exports it as TheKarte-screenshot.png to the local device (usually the download-folder).
  URL: TheKarte.html?screenshot(TheKarte-screenshot.png)
• Load a local KML file (here: Berlin.kml).
  URL: file:///home/user/TheKarte/TheKarte?geoURL(kml, file:///home/user/TheKarte/data/Berlin.kml) ATTENTION: Access to local files and folders (i.e., file:///) is usually not permitted from a HTML-page, as this is considered a security risk.
  • Firefox: If the HTML-page was loaded from file:///, then files below this path can accessed. The path needs to be absolute.
  • Chrome/Chromium: Needs to be started with a command line parameter. Due to security implications this option is omitted here.

Technical details

TheKarte is implemented using OpenLayers and pure (aka vanilla) JavaScript. All map-related and geographical data-related features are provided by OpenLayers.