HowTo:MAPS

About this page

This page is a subset of the information contained in the file README.MAPS of the Xastir distribution. It is not kept rigidly in sync with that file, nor does it contain all of the information in that file.

To find the real README.MAPS, please look in the source directory for Xastir, or in the installation directory ${prefix}/share/doc/xastir where "${prefix}" is usually /usr/local, but could also be /usr if you installed xastir from a binary package.

Maps for the impatient

If you compiled with ImageMagick and have wget or libcurl installed, you can use the online OpenStreetMap/Terraserver maps exclusively. However, having maps on your computer is often faster than transferring images over the Internet, and is not subject to network failures. See the section below on map caching for an exciting feature that works with most online maps to really speed things up!

What do you need?

Xastir isn't of much use unless you can display data in relation to geodetic information of the Earth. The developers have gone out of their way to provide the ability to use many map formats, as well as ways to make your own maps for use within Xastir. Fortunately, Xastir comes out of the box with the ability to display many map formats. Below is a list of the many types of map formats and the associated library packages needed to view them.

  Map Type:           Libraries Required/Notes:
  ---------------     -------------------------
  DosAPRS             Built-in.
  WinAPRS             Built-in.
  X-APRS              Built-in.
  MacAPRS             Built-in.
  PocketAPRS          Built-in.
  USGS GNIS           Built-in.  Can split into county-sized chunks using xastir/scripts/split_gnis.pl to speed things up.
  Address Lookup      Built-in.
  Weather Alerts      Shapelib
  pre-2003 Tigermaps  Shapelib
  post-2003 Tigermaps Shapelib, pcre
  ESRI Shapefiles     Shapelib
  Image Maps          ImageMagick.  Often need lcms library and others as well (whatever it takes to make ImageMagick
                      happy).  Can also use the XPM library for some image types without installing ImageMagick.
  Internet Maps       ImageMagick plus wget or libcurl.  Often need lcms library and others as well (whatever it
                      takes to make ImageMagick happy).
  UI-View Maps        Convert from .INF to .GEO format using xastir/scripts/inf2geo.pl
  OziExplorer Maps    Convert some maps to .GEO format using xastir/scripts/ozi2geo.pl
  USGS DRG Topo       libtiff, libtiff-devel, libproj, libgeotiff

The recommended configuration of Xastir allows to use of many of these map formats.

U.S. Users

  Minimum:  Shapelib, pcre
  
     Allows use of all built-in map types plus 2003 (and later) Tigermap data, shapefile weather alerts, and local ESRI Shapefile format
     maps, including U.S. satellite/image/topo maps via Internet.

  Medium:  Shapelib, pcre, lcms, ImageMagick, libcurl/wget,
  
     Allows use of all the above plus Internet maps and local image maps.

  Maximum:  Shapelib, pcre, lcms, ImageMagick, libcurl/wget, libtif, libproj, libgeotiff
     
     Allows use of all the above plus USGS topo maps.

Rest of World

  Minimum:  lcms, ImageMagick, libcurl/wget
  
     Allows use of all built-in map types plus local and Internet image maps, including Canadian topo maps via Internet.

  Medium:  lcms, ImageMagick, libcurl/wget, Shapelib, pcre
  
     Allows use of all the above plus ESRI Shapefile maps.

  Maximum:  libproj, libtiff, libgeotiff
  
     Adds more map types.  Some of these may not be useful in your part of the world.

The documentation

Map directory hierarchy

You can have any number of maps in the /usr/local/share/xastir/maps directory. You can organize the maps however you like. You can also use symbolic links to link to files/directories on other disks. Map files are loaded in the order that they appear in the chooser unless you adjust the layering priorities in the "Properties" dialog (it's recommended that you use these now instead of a directory hierarchy to choose the layering).

There are many methods for organizing many maps. Create a map hierarchy using something that makes sense to you. The old method of creating transparent/filled or raster/vector directories has been superseded by the new map layering features in the Map Chooser->Properties dialog. It's now suggested that the map layering be done there, and the directory layout designed to make it easiest for the user to select maps. Perhaps a good start would be:

    World/
    Canada/
    Canada/Province/
    USA/
    USA/State/WA/
    USA/State/WA/County/
    ...
    GNIS/
    Overlay/

Please note that the map directories are entirely up to the user now. Use the map layering facilities (Map Chooser->Properties) to determine the order in which they will be drawn, and to determine which will draw filled areas. Note that raster maps will always draw filled, it doesn't matter what the setting suggests. For vector maps, you have a choice of:

   Fill = No       Polygons will never be filled
   Fill = Yes      Polygons will always be filled
   Fill = Auto     Polygon fill is determined by map (or if it's a Shapefile, by any associated dbfawk file).

Map types by file extension

Vector Format:

   .shp/.shx/.dbf  Shapefile vector map (need all three files)
   .map            APRSdos/WinAPRS/MacAPRS vector map
   .gnis           GNIS labels file (actually points instead of vectors)
   .geo            Vector map or Internet vector map.  Note that for http/ftp-based maps Xastir requires an IMAGESIZE line.

Raster Format:

   .tif/.fgd       geoTIFF raster image map
   .geo            Raster image map or Internet raster image map.  Note that for http/ftp-based maps Xastir requires an IMAGESIZE line.

Note: ".geo" is listed twice because it can fit in both categories, depending on the base format of the map file that the .geo file points to. .geo files are handled by the XPM library or by ImageMagick, so most anything that can be handled by those installed libraries can by handled by Xastir.

Online maps

Online maps are downloaded on-demand, based on the current map view and zoom level. They require an Internet connection, however map tiles are cached so once loaded, they will be available from local disk.

OpenStreetMap

Online map functionality includes support for OpenStreetMaps (streets and trails). Just open the map chooser and look for the "Online" directory, then select the desired maps.

Online Tiger Maps

Please note THE ONLINE TIGERMAPS NO LONGER WORK. They are permanently gone (the service has been discontinued at tiger.census.gov), however OpenStreetMaps have replaced them. You will need to acquire and compile the latest Git version for full OSM support. Tiger/Line shapefiles are still available and supported, see below for instructions on downloading them.

WMS Map Servers

Xastir has support for WMS map servers built-in. To use this you'll need to create a *.geo file in your map directory (usually "/usr/local/share/xastir/maps/Online/", "/usr/share/xastir/maps/Online/" or any directory below those) for each LAYER you wish to use, perform a re-index of your maps, then select them in the Map Chooser.

Procedure: Hunt down a WMS map server that you wish to use, then find its "GetCapabilities" link. Here's an example:

 http://geogratis.gc.ca/maps/CBMT?service=wms&version=1.1.1&request=GetCapabilities

Look at it directly in your browser or use Xastir's "wms.pl" script to see the structure and keywords of the XML. Note that if using "wms.pl" you must add backslashes prior to each '&' character in the URL.

 wms.pl "http://geogratis.gc.ca/maps/CBMT?service=wms\&version=1.1.1\&request=GetCapabilities"

"wms.pl" will show the format of the XML file plus a section at the end which looks like:

POSSIBLE .GEO FILE CONTENTS:

WMSSERVER
URL http://geogratis.gc.ca/maps/CBMT?service=wms&version=1.1.1&request=GetMap&SRS=EPSG:4326&FORMAT=image/png&BGCOLOR=0xFFFFFF&TRANSPARENT=FALSE&STYLES=&LAYERS=National

WMSSERVER
URL http://geogratis.gc.ca/maps/CBMT?service=wms&version=1.1.1&request=GetMap&SRS=EPSG:4326&FORMAT=image/png&BGCOLOR=0xFFFFFF&TRANSPARENT=FALSE&STYLES=&LAYERS=Sub_national

WMSSERVER
URL http://geogratis.gc.ca/maps/CBMT?service=wms&version=1.1.1&request=GetMap&SRS=EPSG:4326&FORMAT=image/png&BGCOLOR=0xFFFFFF&TRANSPARENT=FALSE&STYLES=&LAYERS=Regional

WMSSERVER
URL http://geogratis.gc.ca/maps/CBMT?service=wms&version=1.1.1&request=GetMap&SRS=EPSG:4326&FORMAT=image/png&BGCOLOR=0xFFFFFF&TRANSPARENT=FALSE&STYLES=&LAYERS=Sub_regional

This means there are four different map layers you can get from that WMS server. To see/use each one you'll need to create four different .geo files for Xastir. The format of a WMS Server .geo file is exactly two lines. Try using each of the two-line outputs from wms.pl as a start towards creating your own .geo files.

Where to find offline maps

Offline maps are stored locally on your computer, so no Internet connection is required for normal use.

See also: Major_Features

Lots of links to downloadable maps: Xastir Maps

Dos/Win/MacAPRS style vector/fill maps:

• http://www.cnunix.com/ftp/hamradio/rutgers.mirror/maps/maps2/
• ftp://ftp.tapr.org/aprssig/maps/

WORLDHI.MAP is suggested as a basic view of the world map.

You can use any of the other maps available from this site. Many of these were created from Tiger/Line maps, but they are several years out of date. It is suggested that you don't use these as your primary street-level maps; the newer shapefile-based maps are usually preferable. In cases where you cannot compile shapefile support, these maps suffice.

PocketAPRS vector maps

The WinAPRS 2.51 distribution included the full collection of PocketAPRS vector maps for the USA. The download is about 60MB, from the TAPR ftp site.

ftp://ftp.tapr.org/aprssig/winstuff/WinAPRS/waprs251.zip

Raster Maps

For Canada theres a country wide set of topographic map images available from the "Department of Natural Resources Geomatics Canada". Running /scripts/toporama250k.pl will pull down 430mb of 1:250k map images from that departments site. If thats not enough data, running /scripts/toporama50k.pl will pull down around 10gigs.

• • • • Note that recent changes at the "Department of Natural Resources Geomatics Canada" have made these scripts fail. Changes to the scripts are being coded and tested. Git will be updated once the scripts are proven to work again. ****

For Ireland, EI8IC (http://www.mapability.com) has produced a set of overlay maps that show the County Borders, Main Towns and Roads. John, EI7IG, has created a set of ".geo" files to go with them and they are all available in one tarball from ireland.aprs2.net They are free for non-commercial use.

Also available are a map of the country, with an associated geo file, the South East, its associated geo and a Weather Radar .geo file.

Shapefile format maps (Requires shapefile support)

Shapefile format maps are slowly becoming the standard vector format of maps used with Xastir. Xastir 1.3.2 and above by default enable dbfawk support for parsing shapefile metadata, see below.

Shapefile extracts from the OpenStreetMap project are great to use if you can find recent extracts and they have the layers you need. I sometimes combine these with county shapefiles from NWS if the land shapes aren't extracted from OSM.

A nice world map is available at http://aprsworld.net/gisdata/world/ thanks to James Jefferson, TerraSpace, Russia, and the Digital Chart of the World (for Antarctica). Note that this file is currently available only in uncompressed or in tar/bzip2 format. To decompress the latter file, you'd type "bunzip2 filename" and then "tar xvf filename" (or tar xvfj <filename>).

USA Maps

If you also use GeoTIFF images, get the handy usgs_24kgrid.zip file from http://data.geocomm.com/quadindex/. This file provides a grid of all of the 7.5' maps and their names for the U.S. A nice world map is available at http://aprsworld.net/gisdata/world/ thanks to James Jefferson, TerraSpace, Russia, and the Digital Chart of the World (for Antarctica). Note that this file is currently available only in uncompressed or in tar/bzip2 format. To decompress the latter file, you'd type "bunzip2 filename" and then "tar xvf filename".

http://www.bts.gov has the "National Transportation Atlas" that you can download pieces of (at least for the larger layers) or ask for (free) CD-ROM's to be mailed to you.

Some other shapefile format maps are available at: http://www.nws.noaa.gov/geodata/

Still other shapefiles are available from esri.com, geographynetwork.com and gisdatadepot.com (from their "free data" link). Lots of useful stuff at these sites, just look around. You can also check with your County GIS office for shapefiles of your county. You can convert them from State Plane to Lat/Long projection using instructions later in this document.

Canada street maps

Canadian street maps in Shapefile format are available at http://www.geobase.ca

Australian Maps

Geoscience Australia supplies downloadable shapefiles from the 1:250K mapping series. They can be retrieved from Geoscience Topographic Mappingif you know the name of map required, or searched for at Geoscience Map Search if you do not know the name required. Choose ArcView Shape file at the download screen.

This will download a zip file with 80 to 90 separate map layers. dbfawk files have been prepared for some of these layers. If you haven't got a recent build of Xastir the dbfawk files can be found at Xastir feature requests.

Copy the dbfawk files to your ../xastir/config/ directory. From the unzipped shape files, find the required files (four for each layer) and copy to your ../xastir/maps/ directory.

For example, for roads to show on your xastir map, copy from GEODATA_TOPO250K_TILE_DATA/D5415/Shapefiles/Transport the files d5415_roads.dbf d5415_roads.prj d5415_roads.shp d5415_roads.shx. Copy AU_roads.dbfawk into your config directory.

To see the road names you may need to set Xastir to show names. Map>Enable Map Labels

Coastline A Coastline shape file can be downloaded from Geoscience Australia. Copy the cstauscd_l files to your map directory and AU_coastline.dbfawk to your config directory.

USA Tiger/Line ESRI shapefiles

Recent versions of Xastir have the ability to display Tiger/Line 2008 and 2009 ESRI format maps. The latest Git should provide all of the files needed except for the maps themselves. You will need dbfawk support compiled in.

The most recent release of the data is Tiger/Line 2009. Here are instructions for obtaining a single county's worth of files, extracting the maps, and configuring them for use in Xastir. Instructions for HowTo:MAPS:OldTigerLine are also available.

Download the Tiger 2009 files

Go to ftp://ftp2.census.gov/geo/tiger/TIGER2009 with a browser. Use this to find the name of the directory for the state and counties you are interested in. Most of the files are not practical for use with Xastir, so we'll only get a subset.

Create a directory for your state, then store your desired state and county names in a pair of variables (change the parts in italics as desired):

    mkdir -p ~/tiger2009/MN
    cd ~/tiger2009/MN
    
    STATE="27_MINNESOTA"
    COUNTIES="27003_Anoka_County 27123_Ramsey_County 27053_Hennepin_County"

Once that's done, the "for" loop can be cut and pasted into your shell to get the files we want from each county and unzip them:

    for county in $COUNTIES; do
    mkdir -p $county
    cd $county
    for file in edges areawater pointlm arealm; do
    wget "ftp://ftp2.census.gov/geo/tiger/TIGER2009/$STATE/$county/*$file*"
    unzip *$file*.zip
    rm *$file*.zip
    done
    cd ..
    done

You should now have a set of directories for each county, each containing edges, water features and points/areas of interest.

As an alternative, you may download an entire state with the following commands (replace STATE below with the desired NN_state directory name seen on the FTP site):

    GET='*_[0-9][0-9]_county.zip,*_[0-9][0-9][0-9][0-9][0-9]_cousub.zip,*lm.zip,*water.zip,*edges.zip'
    wget -nH --cut-dirs 2 -r -c ftp://ftp2.census.gov/geo/tiger/TIGER2009/STATE/ -A "$GET"

Move the extracted files to your maps directory

Move the directory hierarchy and ensure everyone can read the files:

    cd ~
    sudo mv tiger2009 /usr/local/share/xastir/maps/
    sudo chmod a+rX /usr/local/share/xastir/maps/tiger2009

You may want to adjust the directory hierarchy depending on your personal preferences.

Obtain dbfawk files

Depending on how recent your Git installation of Xastir is, you may need to obtain the dbfawk files for the Tiger/Line 2009 shapefiles.

    mkdir ~/xtmp     (or the temporary directory of your choice)
    cd ~/xtmp
    wget ftp://luno.org/xastir/config/tl_2009*.dbfawk
    chmod a+r *dbfawk
    sudo mv *.dbfawk /usr/local/share/xastir/config

Start Xastir, open the map chooser and you should see a Tiger2009 folder. Select the map(s) you want to view. Enjoy!

A word of caution

You probably want to select just a county (or maybe a few) at a time. Selecting an entire state in the map chooser is likely to make loading maps really really slow, even on a fast machine.

Map Caching

Map caching works in conjunction with the map download routines, which fetch maps from http or ftp addresses. The map caching features use functions found in Berkeley DB 4.0 library, AKA libdb (version 4.0 or better), to create and manage a cache directory and a persistent database of information about the files in the cache directory. This directory defaults to ~/.xastir/map_cache. The files under this directory can be cleaned up or removed by hand at any time - the caching routines will simply download the maps and put new entries into the .db file.

Map files are saved with filenames that include the number of seconds since the Unix epoch. This allows the caching routines to easily determine the age of maps so that older cached maps can be deleted. This is currently (Dec 2004) controlled with a compile time maximum age setting. See map_cache.h for specifics and for brief documentation about all of the map_cache functions.

Drawing your own maps using Xastir

The final result here will be ESRI Shapefile vector maps that you can then use within Xastir. You'll need Shapelib compiled into Xastir to make use of this feature.

• Turn off Object Transmit first (Interface menu).
• Place an object or item at the start location of your route.
• Click on the "Move" button to active move mode, then move that object around the map. Once you're done you'll have a bunch of straight lines that depict the course.
• Now bring up Station Info on that object and click on the Store Track button. If you've got Shapelib compiled in, you'll get a shapefile created with the track you just drew.
• After you're done you can delete the object and then turn on the Object Transmit toggle again. You'll end up transmitting the deleted final position of the object for a few hours unless you kill/restart Xastir, but that's ok. Nobody will see it on their maps 'cuz it's a deleted object.
• Look in ~/.xastir/tracklogs/ for the Shapefile. Copy it to your maps directory, changing the name on the three files as you like, then create a dbfawk file for it if you want to change how it is drawn in Xastir.

Another way would be to drive the course with a GPS and then download the track via Xastir/GPSman to create a Shapefile map.

Yet another way would be to drive it with an APRS rig and then Store Track as described above. You could also drive with GPS/Xastir (without APRS) to get a very detailed track and then save your own track.

Drawing SAR search segments in Xastir

• Turn on "Draw" mode (togglebutton at the top of the main window). The cursor should change to the Measure/Draw symbol.

• Using the middle mouse button, click on each vertex until you are almost done describing a polygon (don't close it yet). If you don't have a middle mouse button, clicking on BOTH mouse buttons at once will do it if you have "emulate third mouse button" enabled in your X11 configuration.

• Go to Map->Draw CAD Objects->Close Polygon. The polygon will get completed, the area enclosed will be computed, and a dialog will pop up asking you for more information. You do not have to enter any information in this dialog, but a name of some type is helpful in order to be able to identify each segment when modifying/deleting/viewing these segments.

• Note that these CAD Objects get saved in a file and reloaded each time you start Xastir, but they cannot currently be written out as a map file and used as a general map.

• Also note that these CAD Objects don't get transmitted. They are currently for local display only.

• The display of various kinds of data related to these segments can be modified in the Map->Draw CAD Objects menu. Modifying parameters for any segment is done in the Map->Draw CAD Objects->CAD Polygons dialog.

• Click on the dashed line in the menus in order to separate that menu from the rest and allow you to keep the menu on the screen. This is very useful when drawing CAD Objects or changing display/filtering options.

• Turn off "Draw" mode when you're done. The cursor should return to normal.

Summary of distance/area/angle calculations

Distance

• Haversine formula (2-parameter atan version) for computing distance between two points, for our general distance routines:

  calc_distance()
  calc_distance_course()
  distance_from_my_station()

• Haversine formula (2-parameter atan version) in "Measure" for both the X/Y offsets and the total distance.

Haversine formula is more accurate for shorter distances than spherical trigonometry calculations. Both methods are equivalent for longer distances. Both are Great-Circle calculations (as opposed to Rhumb-line or planar geometry). See the GIS FAQ for info on these methods. Dr. Math website mentions both of these and refers people to the same GIS FAQ.

Also note that the Haversine formula is ill-conditioned if the two points are antipodal (on opposite sides of the Earth). From the GIS FAQ: "but the error, perhaps as large as 2km (1 mi), is in the context of a distance near 20,000km (12,000 mi)." For our purposes that's just fine.

Area

• Area of a spherical rectangle from Dr. Math's website for the "Measure" function. There are errors in their last two derived formulas. They have been notified of it. Our implemented code is correct.

• The area calculation for CAD Object Polygons is probably not spherical, but closer to planar. It might take some doing to calculate the area of irregular polygons on a spherical surface. We use Greene's Theorem to compute the area based on the vectors. The lengths of each vector are computed via the Haversine formula, so it's not strictly a planar area calculation either. Somewhere in-between planar and spherical? This should be plenty good enough for areas that are less than 12 miles on a side (that's about where planar geometry starts to diverge from spherical trigonometry), perhaps also for somewhat larger areas than this due to the advantage of computing the vector lengths with the Haversine formula.

Angle

• Great Circle departure angle for the "Measure" function.
• Great Circle departure angle for the calc_distance_course() function.
• Dead-reckoning angle is essentially a Rhumb-line calculation (constant heading), with a few caveats:

We compute the next point along a constant angle based on the last position transmitted, the time elapsed, and the course desired. This then gets corrupted a bit either by the standard APRS grid that it has to snap to (and the position snapped to for the previous position) and/or by the relatively course angle available for Base-91 compressed positions.

Standard APRS positions give 1-degree angular resolution but 60-foot or so grid points. Base-91 Compressed positions give something like 1 to 3-foot grid points but less angular resolution (+/- 2 degrees. We can't win!

The end result is that we start off like a drunk sailer due to our short transmit times and the above limitations, then the angle smooths out as the time increases between the transmits. You can see this easily at zoom level 1 when you place an object, when you make a change to an object, or move an object (transmit rate goes up for any of these conditions).

Dead-reckoning effectively does a Rhumb-Line calculation as it is trying to do a constant heading. That means it is not the shortest distance between the points. I'm still trying to get my head around that last concept as it is counter-intuitive to someone versed in compass/maps on land and with shorter distances.

A Great-Circle route is the shortest distance between two points on a sphere, whereas a Rhumb-line is what you get if you move along a constant compass heading and is a bit longer.

We probably do not need to go to ellipsoid calculations for Xastir. Spherical calculations should be accurate enough for what we do.