Using map images with a ".geo" file

You're helping provide comms support at a public event such as a race. The race has a small paper map indicating the race course, and you can get this image into a file by scanning it, or maybe they even have it online. You want to use this image on your APRS display.

Doing this requires that you know how pixels in the image relate to latitude/longitude coordinates in the real world. This is done by crafting a ".geo" file that contains the necessary georeferencing information and the name of the image file to display.

Requirements for using image files as maps with .geo

Processing of image files in Xastir is done through the GraphicsMagick package, which must be installed at the time Xastir is built for this to work. GraphicsMagick is present in the package management systems of most operating systems, and will pull in many other packages as dependencies. See Installing Xastir.

Format of a .geo file

A .geo file contains four important pieces of information:

the name of the image file it relates to
two "tie points" in the image and the latitude and longitude they correspond to. These two points should be close to the upper left and bottom right corners of the image for best results, but can be anywhere internal to the image if necessary.
the size of the image in pixels

The best way to find the tie points is to identify two spots in the image that correspond to locations whose latitude and longitude are easily found (say, on Google Maps, in Xastir with a good online map loaded, or other means). The upper left corner of the map is at pixel coordinates (0,0) and the bottom right will be at (width,height).

Finding the pixel coordinates in the image requires some sort of image editor. GIMP is one such editor that is commonly available on linux systems. KM5VY uses a very old, simple image viewer called xv that is still under development and often available on Linux package management systems. There are probably many others that can do the job.

The format of the .geo file needed for this use is:

FILENAME yourmap.png
TIEPOINT x0 y0 lon0 lat0
TIEPOINT x1 y1 lon1 lat1
IMAGESIZE width height

where (x0,y0) and (x1,y1) are in pixel coordinates and (lon0,lat0) and (lon1,lat1) are in decimal degrees. Width and height are in pixels.

Additional .geo file lines

While the four lines above are absolutely necessary to register a map image to Xastir's screen, you can add a few other optional lines.

REFRESH: The number following the REFRESH on this line is how often Xastir should reaccess the file for display, in seconds. Useful if the image is dynamic and needs to be reread.
TRANSPARENT: A 24-bit hexidecimal number following this keyword is used to tell Xastir to skip any pixel whose color matches, making the map transparent in its place. Multiple lines can be given to tell Xastir to ignore more than one color. 0xFFFFFF is a pure white that is often a good color to have here.
CROP: followed by four integers, tells Xastir to crop the image to the box whose upper left corner's coordinates are the first two integers and whose lower right corner is the second pair.
GAMMA, CONTRAST, NEGATE, EQUALIZE, NORMALIZE, LEVEL, MODULATE: These options are used to pass GraphicsMagick manipulations down to the library.

Example

An example of a user-created map

Here's an example image file and the ".geo" file needed to register it on Xastir's map screen. This is a real-world example, created for a ham that was supporting a race event. The .geo file defines "Tie points" for the latitude and longitude for points in the image file near the top left and bottom right, and the size of the image in pixels.

The geo file contains:

FILENAME D109A.bmp
TIEPOINT 71 67 -98.159555 34.506983
TIEPOINT 384 577 -98.051836 34.362287
IMAGESIZE 900 1070

In this geo file, the pixel (71,67) (close to the top left) is at 98.159555°W 34.506983°N. The pixel (384,577) (somewhere close to the middle of the image) is at 98.051836°W 34.362287°N. These locations were chosen because the map image has clearly identifiable street intersections at those pixels, and those streets could be found easily in Xastir with the OSM_tiled_mapnik online map, and those coordinates could be picked off of Xastir's map display. The coordinates of the pixels in the image corresponding to those street intersections were found using a graphics program that allowed display of that information.

Here's a screenshot of Xastir displaying the scanned map image described above on top of the "OSM_tiled_mapnik.geo" base layer, showing how multiple maps can be mixed together on the display, and showing how the image file has been correctly placed in the world so that roads of the OSM base layer properly connect to the same roads in the image file that's been plopped on top of it.

This method is only suitable for maps of small areas, and can be grossly inaccurate for larger maps

The .geo method of using images as maps is very primitive. Two tie points establish the locations of pixels near or at the corners of the image, and these establish a location on the map and a scale factor.

But this method ignores a very important property of flat maps: that they are always just "projections" of the surface of the earth onto a flat surface, and are always distorted in some way. Different types of projections distort the map in different ways, and over large areas this distortion is very important.

For maps of small areas it is possible to ignore this important aspect of mapping and the map will still be usable. For larger areas, however, the distortion of the map due to projection will become obvious. Features in the interior of the map will not be correctly placed even if the corners are.

Use of the .geo method is therefore most effective for things like maps of neighborhoods. It is extremely effective for getting maps of the kinds of events hams often support.

It is sometimes the only way to get a map of an area into Xastir, and sometimes the distortion of the map is obvious but acceptable. This fits with the early vision of APRS as frequently articulated by Bob Bruninga: APRS is not meant to be a mapping application, but an information sharing system. But it is not how most users of APRS see it today.

When accurate mapping is required, the .geo method is inferior to doing more careful georeferencing of the image. That can be done using gdal tools and other real GIS products, but is an advanced map topic.

Other uses of .geo files

The use of .geo files described so far is the original method of using them, to define a crude georeferencing method for static image files.

.geo are also used for Web Map Service and OpenStreetMap online mapping, but the format of the geo file is very different. Use of the .geo file for those purposes is described on the own pages for those map types.