THIS FILE IS A WORK IN PROGRESS! The Xastir wiki at xastir.org is currently down and this file is being written from scratch.

It is also unfortunately a bit rambling and needs a great deal of editing to flow better. Sorry. Help if you like.

The Xastir map window

APRS is a full-featured packet communication system, but a large fraction of the information shared in APRS systems is location information. Xastir displays this information in its primary application window on a map.

In this image, you can see the basic features of the Xastir application. The top bar contains the primary menus, the largest frame displays the currently selected maps, overlaid on the map are APRS reports that have been received, and at the bottom is a status line showing a message box, the current cursor position and its relation to your station location, the current zoom level, a box that can contain various information about enabled logging, and a set of indicators representing all of the interfaces you have defined.

About the map in this image

The map shown here is using only the Online/OSM_tiled_mapnik.geo map. More will be said about choosing maps later in this document.

As noted in Keyboard-And-Mouse-operations there are various keyboard and mouse operations that are active in this window.

These other operations will be documented in future revisions of the Github wiki. For now, as it is displayed here, the main one we'd use is the ability to zoom in on an area by holding the left mouse button and dragging to define an area to display.

Default maps

When you start up Xastir for the very first time, the program will display a world map with very little detail. Which map it displays depends on how your Xastir installation was compiled.

If your Xastir was compiled with no optional libraries

The absolute bare-bones build of Xastir is very limited in what map types it can display. If you fire up Xastir for the first time with such a build, it will select the only map it has that can be displayed: worldhi.map, a low-resolution line map of the world that contains country boundaries and some rivers. It was created for WinAPRS by Keith Sproul in the early days of APRS, and even when it was new it had outdated country boundaries. But it's a map and it displays in versions of Xastir that are built without any extra map support libraries. It is used in Xastir with the gracious permission of its creator.

If your Xastir build has shapelib support built in

An Xastir built to include shapefile support will, when run for the very first time, select a set of maps taken from the Natural Earth collection of public domain shapefiles. This will provide you with country boundaries, rivers, lakes, and coastlines. It is still a fairly low-resolution representation of the world, but it is modern.

Choosing non-default maps

The basic map you get on first running Xastir is probably not the one you'll be using day-to-day. You can select which map you want to use through the Map Chooser, found under the Map menu:

The map chooser lists all the maps it has found in the directory that Xastir searches for them.

Choosing multiple maps

Xastir allows you to select as many maps as you like in the map chooser. These are all drawn into the map window one after the other. Unless you tell Xastir otherwise, the maps are drawn into the window in the order they appear in the Map Chooser (which is to say, alphabetically by file name including their path under the maps directory).

For maps that are just line maps (such as shapefiles), this is usually fine, as the points, lines, or polygons are just drawn right onto the screen.

For raster maps (those made from pre-rendered images), selecting more than one usually means that only the last one drawn is visible. These maps are best used as "base layers," that is, maps that are drawn first and over which line maps are drawn. Selection of "layers" is done in the Map Properties dialog.

Adding your own maps

You may add maps of any format that Xastir is configured to support by placing them in the directory where Xastir searches for maps. Xastir will scan this directory each time it starts up and index any new maps it finds there. You can also select the Map->Configure->Add New Maps menu to instruct Xastir to read new maps at any time.

Map->Configure->Reindex ALL Maps will cause Xastir to reread all the maps it finds in the maps directory, not just the new ones.

The maps directory may be organized in any way you choose. Grouping related files in subdirectories is a very good idea.

Supported map types:

Built in map types

The maps Xastir can read without having any additional libraries linked in are:

• USGS "GNIS" point data
• USGS "Populated Place" point data (using pre-2009 format GNIS files)
• APRSDOS and WinAPRS ".map" format

Unfortunately, most of these built-in maps make use of files in formats that are rarely available anymore, so the minimal build of Xastir is rather limited.

Optional add-on map formats

You will want to build Xastir with additional map support. This requires that you have additional external libraries installed on your system. All of these libraries are present in all package management systems on operating systems that support Xastir, so are easy to obtain.

Please see the install document for documentation of how to add additional map format support to Xastir.

When all optional libraries are configured, Xastir supports many map formats.

File format	Description	required libraries and features
image files	Any form of image file supported by GraphicsMagick	GraphicsMagick and a .geo file to provide georeferencing
GeoTIFF files	TIFF files with extra georeferencing information tags	libgeotiff
ESRI Shapefile	Point, line, and polygon GIS data	shapelib, pcre2, and a dbfawk file to direct how Xastir should draw them
Online WMS servers	Access to standard Web Map Service servers	curl, GraphicsMagick, optionally Berkeley DB for caching of files
Online OpenStreetMap servers	Open source maps in tiled images	curl, GraphicsMagick
APRSDos/WinAPRS maps	Vintage maps from the early days of APRS	built in
GNIS data	USGS Geographic Names Information System files	Built in

But that's not all

In fact, most other types of map data can be converted into file types Xastir supports with the aid of external programs. The gdal package is an essential tool for map nerds who want to do that.

We should have documentation on how to use each of these types, and they should each be their own page, not more text right here.

Finding useful maps to use in Xastir

APRS is most useful when one is able to view APRS data on a map of sufficient details for your needs. Xastir has only a few basic supported map types built in, but can be compiled against additional libraries to provide support for additional map types. When you run Xastir from a terminal window, it will tell you which map types it was compiled to support.

We should have a separate page of recommended map sources. But that rapidly becomes dated because nothing lives forever on the web except bad links.

Online maps available upon installation

When Xastir is installed, it will provide you with several easy-to-access files that allow you to use online map sources. These maps we provide for you will be found in the "Online" subdirectory of the maps directory:

Map name	Description
Online/OSM_tiled_mapnik.geo	an excellent world-wide street-level map from OpenStreetMap
Online/OSM_tiled_fosm.geo	world wide map also from Open Streetmap data, provided at a different server
Online/OSM_tiled_cycle.geo	a map meant to provide information about bicycle trails. But it requires an API key for rendering without a watermark, and at the moment we don't have one.
Online/nationalmap.gov/WMS_USGS_*.geo	several useful maps from the US Geological Survey, worldwide coverage
Online/USTigermap.geo	A good street-level map from the US Census, but of course only helpful if you're in the US
Online/geogratis.gc.ca/	a directory of National, regional, sub-national, and sub-regional online maps of Canada
Online/NWS/	a directory of weather radar overlays (US-specific)

More on online maps

Online maps are downloaded using the "curl" library (libcurl) by posting an http request to some map server. The images themselves are processed using GraphicsMagick calls. Thus, use of online maps requires that you have both of these libraries linked into Xastir.

Online maps downloaded from Open Street Maps sources are downloaded in small tiles which are then cached locally. These cached map tiles will continue to be available to Xastir even if you go offline.

Online maps downloaded from other sources are also cached, but in a different way. This non-OSM map cache requires that Xastir be linked with a version of the Berkeley DB library. Without the Berkeley DB linked in, all non-OSM online map sources require Xastir to download the map image every time the map is updated. With the Berkeley DB linked in, Xastir will reuse map images it has already downloaded.

Using the NWS radar images

The National Weather Service radar image maps are best used by setting a high layer number so that they are plotted on top of any other maps you've got displayed. Configure that in the Map Properties dialog after selecting the map in the Map Chooser.

Accessing online map sources other than those we set you up for

It is possible to use Xastir to access any Web Map Service (WMS) server by constructing a ".geo" file that tells Xastir what URL to use. This requires that you understand details of the WMS API and how to tell the server what map layers you want. Xastir will take care of adding to that URL to specify which part of the world it should download for display. The ".geo" files we provide might help you figure out what to do.

Future documentation efforts on our part will help more, but it's not written yet.

Offline maps

Other than "worldhi.map" and the Natural Earth world map, Xastir comes with no maps suitable for offline use. However, you can add as many as you like.

You can place maps in any format that Xastir knows how to display in the maps directory it searches or any subdirectory of that maps directory. This feature allows you to build a library of useful maps specific to your needs.

We will have a page on each map type when this wiki is more developed, and will link to those pages here. If you see a link below, we've documented it, otherwise that documentation is on our TODO list.

• ESRI Shapefiles: One of the most commonly available file types for map features, and one well supported in external GIS programs and converters.
• Raster images in GeoTIFF format: TIFF format images with georeferencing tags.
• Image files with ".geo" file: Any scanned map image can be used as an offline map with appropriate georeferencing information provided in a separate file.
• GNIS: But older versions were useful point maps and support remains for those old files. This is mostly of historic interest.
• Vintage APRSDOS and WinAPRS maps: Stick-figure maps that were in a simple format that were commonly used in early APRS clients. Also mostly of historic interest.

Furthermore, converters from other formats to formats we support exist, and we document some of them on our Map Converters page.

Using random map images

Xastir can take any image you provide and use it as a map. This can be helpful for things like public event support where the event has provided a simple map of the activities.

You can often make use of them by constructing a .geo to go with the image to tell Xastir how to place it on the map window.

This feature requires that Xastir be built with GraphicsMagick support, and takes some careful preparation work.

Finding good offline maps

That's a challenge, iddnit? We should say something about it. For now, let's say that one can find useful shapefiles through local government agencies, university geography departments, and many other sources.

We will try to collect links to good map sources on our Mapping Links page.

Create your own maps

With the number of different map formats we support, it is relatively simple to create your own maps for special purposes.

Notes on how to expand this documentation:

We should not make this page so bogged down with detail that it becomes unreadable. Highly detailed topics (like, say, converting GeoPDF to GeoTIFF or reprojecting raster maps, or dealing with individual map sources) should be their own pages.

Ooops, this is not finished, really! Come back later.