Using OpenStreetMap online servers

Requirements for using OpenStreetMap servers

You must have curl and GraphicsMagick installed for this process to work. The former is used to handle to the web interaction, the latter to display the images that are returned. These packages are in the package management systems of most operating systems. See Installing Xastir.

Ready to use OpenStreetMap servers

Xastir comes with three files that allow immediate access to online OpenStreetMap ("OSM") and compatible tile servers. These are:

Online/OSM_tiled_mapnik.geo: A general-purpose world-wide street level map that provides maps in small, reusable tiles.
Online/OSM_tiled_fosm.geo: A free map server that provides street-level map tiles in OpenStreetMap format. It is a fork of the OpenStreetMap project.
Online/OSM_tiled_cycle.geo: A map that should provide a bicycle-related OpenStreetMap view, but is currently displaying with a big "API Key Required" watermark.

These are usable with no modification as installed by Xastir.

Using other OpenStreetMap servers

If you want to use a different OpenStreetMap source, you can create a ".geo" file to allow Xastir to use other servers that conform to the OpenStreetMap API.

Format of the .geo file for OSM maps

The minimum .geo file required to use an OSM server has just two lines, one to specify the type of server and the rendering style, and one to specify the URL for the map API.

# Uncomment one of these depending on whether the server returns a
# single large image or smaller tiles, replacing "STYLE" with any style string
# that should be passed to the server
# Example: the "mapnik" style is used in OSM_tiled_mapnik.geo, so that line
# would be "OSM_TILED_MAP-mapnik"
# OSMSTATICMAP-STYLE
# OSM_TILED_MAP-STYLE

# Uncomment and set the URL to the correct base URL of the server
# Example: URL https://tile.openstreetmap.org/ for a tiled map server
#URL tileURL

Place your new .geo file into the maps directory and index new maps, and Xastir should allow you to select your new map in the Map Chooser.

Additional options

In addition to those two required lines, you can control the use of the map by adding additional lines to the .geo file

TILE_EXT allows you to change the format of image file Xastir should expect from this server. Only needed if the format is not "png"
ZOOM_LEVEL_MIN and ZOOM_LEVEL_MAX control the zoom levels at which this map should be skipped. The zoom level is NOT in the same units that Xastir considers as zoom levels, it's the level that OpenStreetMap considers. These are numbers from 0 to 18. The formula we use to transform from one to another is not simple, so you may have to experiment a little with this parameter to get it the way you want it. The default values of these parameters will display the map at all Xastir zoom levels.
TILE_DIR: Defaults to "OSMtiles". Xastir will cache OpenStreetMap tiles in this directory under the ".xastir" directory in your home directory so that they can be reused when needed without having to download them all the time.
OSM_OPTIMIZE_KEY: takes an X KeySym value for a key that can be pressed to change Xastir's zoom level to correspond exactly to an OpenStreetMap zoom level. If Xastir's zoom level is between two OpenStreetMap zoom levels, the tiles are stretched to fit. Pressing this key after adjusting Xastir's center or zoom level will make sure that the tiles are used without stretching. For reference, the "F4" key is X KeySym value 65473, and this value is used in all of our provided OSM .geo files.

There is a template for an OSM geo file in the Xastir source directory

The file OSM_template in the Xastir source tree is used by our build process to construct the three .geo files we provide; this file is modified by filling in the map type, style, and URL. You may use the same template to build your own.