Advanced Map Topics

There are a lot of detailed things you can do with external applications that are too detailed for other pages about mapping in Xastir --- the pages would be too cluttered with details of interest to a tiny fraction of users.

These advanced topics will instead be collected here.

Using GeoTIFF files that are not in UTM or EPSG:4326

If you have a GeoTIFF file that doesn't say it's in UTM or a "GCS: 4326" projection, using it in Xastir will either display incorrectly, have distortions internal to the map, or not display at all. Such a GeoTIFF has to be "warped" into a coordinate system Xastir can use. This will distort the map, but make it display properly in Xastir. You will require an external tool for this.

Find the "gdal" package in your system's package management system and install the library and any package of applications that go with it (on Ubuntu, for example, there's a libgdal package for the library and a gdal-bin for the applications that go with it).

The program "gdalwarp" is the one you need. It can take a georeferenced image file in one coordinate system and warp it into a different system and even a different file type. It is a complex application that can do a lot of different things, but for our purposes we just need it to do something simple, taking a GeoTIFF in a projection Xastir can't use and warping it into one that Xastir can use.

The generic command you need is:

gdalwarp -t_srs EPSG:4326 Input.tif Output.tif

This command will transform the "Input.tif" file that is in any coordinate system and create a new file "Output.tif" that is in the EPSG:4326 coordinate system that Xastir needs.

Example: Aviation Sectional Map

I have a GeoTIFF file that is an aviation sectional map. These maps are usually not in a coordinate system that Xastir can use.

> listgeo Albuquerque_75_North.tif
...
Projection Method: CT_LambertConfConic_2SP
   ProjFalseOriginLatGeoKey: 34.000000 ( 34d 0' 0.00"N)
   ProjFalseOriginLongGeoKey: -105.500000 (105d30' 0.00"W)
   ProjStdParallel1GeoKey: 38.666670 ( 38d40' 0.01"N)
   ProjStdParallel2GeoKey: 33.333330 ( 33d19'59.99"N)
   ProjFalseEastingGeoKey: 0.000000 m
   ProjFalseNorthingGeoKey: 0.000000 m
GCS: 4269/NAD83
Datum: 6269/North American Datum 1983
Ellipsoid: 7019/GRS 1980 (6378137.00,6356752.31)
Prime Meridian: 8901/Greenwich (0.000000/  0d 0' 0.00"E)
Projection Linear Units: 9001/metre (1.000000m)

This map is Lambert Conformal Conic projection. It will not display correctly in Xastir. However, I can warp it into WGS84 Geographic Coordinate System with one gdalwarp command:

gdalwarp  -t_srs EPSG:4326 Albuquerque_75_North.tif Albuquerque_75_North_ll.tif

This will create the file Albuquerque_North_75_ll.tif in a form that Xastir can use. If I "listgeo" this file I'll get the output:

> listgeo Albuquerque_75_North_ll.tif
Geotiff_Information:
   Version: 1
   Key_Revision: 1.0
   Tagged_Information:
      ModelTiepointTag (2,3):
         0                 0                 0
         -110.216970855117 36.2799546362302  0
      ModelPixelScaleTag (1,3):
         0.000686415531838486 0.000686415531838486 0
      End_Of_Tags.
   Keyed_Information:
      GTModelTypeGeoKey (Short,1): ModelTypeGeographic
      GTRasterTypeGeoKey (Short,1): RasterPixelIsArea
      GeographicTypeGeoKey (Short,1): GCS_WGS_84
      GeogCitationGeoKey (Ascii,7): "WGS 84"
      GeogAngularUnitsGeoKey (Short,1): Angular_Degree
      End_Of_Keys.
   End_Of_Geotiff.

GCS: 4326/WGS 84
Datum: 6326/World Geodetic System 1984
Ellipsoid: 7030/WGS 84 (6378137.00,6356752.31)
Prime Meridian: 8901/Greenwich (0.000000/  0d 0' 0.00"E)
Projection Linear Units: User-Defined (1.000000m)

This will render in Xastir just fine. However, it will have neatlines that are curved and so it will be difficult to have several such maps displayed seamlessly.

Before this warping, the image looked like this:

After the warp, the image has been changed to this:

Note that the western edge of the map, which is a line of constant longitude, was at an angle in the original image and is now a vertical line in the warped image. The eastern edge, which was vertical and NOT a line of constant longitude in the original image, is now a diagonal line in the output image.

The northern and southern edges of the map, which were lines of constant Lambert Conformal Conic coordinates and NOT lines of constant latitude, are now curved. This is what makes them difficult to stitch together in Xastir --- Xastir can't deal with neatlines that aren't straight lines.

Generally speaking, maps that have been warped this way are not easy to make into seamlessly stitched mosaics in Xastir.

Using "gdal raster reproject" instead

More recent versions of gdal have a "gdal" top-level application with "raster" and "vector" options that can do the same thing that older, single-function gdal programs used to do (and still exist to do).

The equivalent of the gdalwarp program is gdal raster reproject. Its documentation can tell you how to use it.

Seamless stitching of warped maps

Maps with curved neatlines (i.e. those that have been warped from some other projection) must be "collar-stripped" with external programs. This is not easy, and I don't have time to document it yet. It will involve other GDAL tools. Google might be your friend here until I document this fiddly process.

Using Shapefiles that are not in latitude/longitude WGS84 coordinates

Some government agencies produce shapefiles in a coordinate system that is not latitude/longitude. Fortunately, most modern sources of such shapefiles provide a file alongside them with a ".prj" extension that contains the Well Known Text (WKT) representation of that coordinate system, and this file has enough information in it for some of the GDAL/OGR tools to transform them into something Xastir can use.

Install the gdal applications (as described above), which should give you an "ogr2ogr" program. This program can transform vector GIS data from any format it understands into any other format, and can change its coordinate system in doing so.

The basic command is:

  ogr2ogr -f "ESRI Shapefile" -t_srs EPSG:4326 OutputDirectory InputShapefile.shp

This will create a new shapefile in the OutputDirectory containing the same records with the same attributes as the input shapefile, but with the coordinates transformed into WGS84 latitude and longitude.

Using "gdal vector reproject" instead

The GDAL package has a newer interface for performing the same thing as the ogr2ogr command. It's gdal vector reproject. See its documentation for details.

That command only transforms the endpoints of line segments in the shapefile

The ogr2ogr command given previously simply transforms every coordinate pair in the input shapefile to lat/lon coordinates. This is usually a reasonably thing to do for shapes that are relatively detailed, as the line segments in the shapefile are short.

However, for shapefiles that represent large areas and have really long line segments, this simple transformation can produce a map that is something of a lie --- when a line in one projection is transformed to another, it is often no longer a line, but a curve. The command above will not have that effect.

ogr2ogr offers additional command line arguments that can break up line segments in the input shapefile and transform the smaller line segments to the new projection. Using that option would get you curves out of lines when you should see that. It is the "-segmentize" option. See the ogr2ogr documentation for details.

There is a more modern gdal tool to do this

ogr2ogr is sort of a Swiss army knife of vector translation operations and has been the go-to tool for many years. More recent releases of gdal have a new interface that can also be used through a top-level tool named "gdal" and a "vector" option. The segmentizing option described above can also be done with

gdal vector segmentize [options...]

See https://gdal.org/en/stable/programs/gdal_vector_segmentize.html#gdal-vector-segmentize for details.

But what if there's no .prj file?!?!?

Unfortunately, sometimes shapefiles are not provided with the appropriate .prj file needed to determine the coordinate system they're written in. This was often the case in the early 2000s, but is less of a problem today as more and more GIS departments understand how important it is to provide metadata with their products.

If you find yourself in this unfortunate predicament, you'll need to figure out what coordinate system they're in and tell ogr2ogr what that system is. You must figure out what the correct EPSG code is for that system. If you're lucky, the source of your shapefile on the web should tell you one or the other of these. If you're unlucky you might have to dig pretty deeply. Sites like spatialreference.org or epsg.io might help you figure out what EPSG code to use if all you know is the name of the system. Consulting with the source of the shapefiles is always wisdom.

For off-line use, a list of EPSG codes and the Well Known Text for the projections they define can be found at https://gdal.org/en/stable/proj_list/Wkt_adam.zip This is an extremely old file from 1999, but the data in it is still valid, and it can be useful.

Once you know the EPSG code for the coordinate system of your input shapefile, you just provide it to ogr2ogr along with the desired output file:

  ogr2ogr -f "ESRI Shapefile" -s_srs EPSG:<your number> -t_srs EPSG:4326 OutputDirectory InputShapefile.shp

The argument you give the -s_srs flag is the coordinate system of the source file, the one you give to -t_srs is the desired coordinate system of the output.

Georeferencing arbitrary map images

While Xastir has a simple way of sticking an arbitrary scanned map into its map using the .geo file method, that method is not really accurate and may not be suitable for maps of large areas or that are in arcane projections. Getting such maps into Xastir so that the internal features are in the correct location (as opposed to just getting two corners in the right place) requires correct georeferencing.

This is a complex topic and requires use of GIS tools. We should document it at a high level of detail, but for now, if you need to do this you should seek out external web sites that tell you how to do it.

A few suggested places to start

These sites document how to create a properly georeferenced file from an arbitrary scanned image of a map. Both of them use QGIS, an open-source GIS.

• The documentation for QGIS's georeferencing tool is a good place to start. It walks through the process of georeferencing a scanned image by finding tie points internal to the image and relating them to the same points in another, already georeferenced image.
• This site digs a little deeper and shows how to do the same thing with an old scanned map that has a latitude/longitude grid but that is in a much different projection, by creating a simple latitude/longitude grid and warping it into the desired projection, then equating the points where the grid lines meet to the same grid lines in the scanned image.

Once you've georeferenced the image in a GIS, you can have that GIS write it out into a GeoTIFF file for Xastir to import. Make sure that the GeoTIFF file you get in the end is either in UTM or EPSG:4326 (Geographic) projection. If not, you have another step to do --- warping it as described earlier on this page.

Some old GeoTIFF files are defective!

There was a time in the early 2000s where it was common for GeoTIFF files that had originally had good georeferencing information to be processed in a tool that stripped out all the coordinate system information. This was often done in the process of compressing or collar-stripping GeoTIFF files before posting them on a web site where space was at a premium. One particular GIS product was notorious for doing that.

In our old "README.MAPS" file we used to have the following text, which referred to the situation on the ground in the early 2000s. Fortunately, GIS standards are much better today and the situation described below is rarely encountered anymore unless you dig up old files that have been brutalized in this way.

Defective GeoTIFF files need more special processing

The section above about warping images assumes that the input GeoTIFF file has coordinate system metadata in it. If that is missing, it won't work.

It is unfortunately the case that the software in use by many GIS departments produces GeoTIFF files that have NO information about the coordinate system that applies to them --- they'll have just enough information to know what the numerical coordinates of each pixel are, but no information to tell you whether those coordinates are UTM, Lat/Lon, State Plane, or anything else. For such maps you will need to determine the coordinate system by finding external files called "metadata" that are associated with the images. US Federal datasources have a standardized file format (".fgd") that provides this information, but many state or university GIS departments just make some other format up for themselves. Most sources of map data should have such metadata available, but sometimes it is a bit of a chore to find it.

You can determine whether a .tif file has coordinate system information in it using the "gdalinfo" command from the GDAL suite or "listgeo" from the libgeotiff distribution. If gdalinfo shows something like this:

  Driver: GTiff/GeoTIFF
  Size is 5364, 7620
  Coordinate System is `'
  Origin = (588067.750000,5331248.500000)

you're the lucky owner of a file that has no coordinate system info (because the only thing after "Coordinate System is" is a pair of quotation marks). Another dead givaway would be:

Metadata:
     TIFFTAG_SOFTWARE=Arc/Info

which tells you that the image was processed with a piece of software that fails to put in all the right tags.

If you get maps whose metadata say are in UTM projection but for which gdal indicates missing geoTIFF tags like it does in the example above, xastir won't be able to display them unless you fix them up. Fortunately, the GDAL library tool "gdal_translate" can do the job. For example, if you have a source map with metadata that says it's in UTM Zone 10, NAD83 datum, to make it suitable for Xastir to read you can do something like this:

gdal_translate -a_srs EPSG:26910 original.tif georeferenced.tif

The inclusion of the -a_srs option to gdal_translate forces the new tiff file to have the correct geotiff tags to indicate that coordinate system.

The EPSG number to use for images in UTM projection with NAD83 datum is 26900 plus the UTM zone number. The EPSG number for UTM in NAD27 is 26700 plus the zone number. The above command will allow Xastir to read in the image and reference it properly.

If your maps are NOT in UTM, you must also gdalwarp, because xastir cannot properly display geotiffs that are in projections other than UTM or Geographic Coordinate System (EPSG:4326).

EPSG numbers for odd-ball coordinate systems can be found at https://gdal.org/en/stable/proj_list/Wkt_adam.zip (this is a very old file, but the numbers in it haven't changed). A useful EPSG lookup site is https://epsg.io

Maps that require gdalwarp include the FAA sectionals mentioned above, and some topo maps in obscure state plane coordinates from various state GIS departments.

Xastir can only use GeoTIFF files that are 8-bit-per-pixel with one band

Some geotiff files contain multiple bands or multiple bytes per pixel. Xastir currently uses only BYTE format, so you may need to convert the geotiff file with gdal_translate. The number of bands, bytes per pixel and other information about geotiff files can be obtained using gdalinfo. Obviously, you need GDAL for this.

One-band, 16- or 32-bit-per-pixel

The command

gdal_translate -ot BYTE original.tif new.tif

can convert 16 and 32 bit per pixel geotiffs to ones that can be used by xastir

Multiple band, 8-bit-per-pixel

The command

gdal_translate -ot BYTE -b 1 old.tif new.tif

can extract a single band as a grey scale layer from a multi-band geotiff file, but this is probably not what you really want.

The command

rgb2pct.py old.tif new.tif

can create a single band palette based geotiff from a three band rgb tif by dithering the colors down to a small palette. This last tool requires gdal built with Python support. See the gdal documentation for these tools for further information. Your system might include these python tools with other gdal tools, or might provide a separate package for the python interface.

Chopping up a big shapefile into smaller "tiles"

While Xastir does use a fairly efficient method of reading shapefiles so that it doesn't try to read parts of the file that are clearly outside the current map frame, a very large shapefile (say, covering the entire world) may render relatively slowly when one is zoomed in at, say, city level.

It might be desirable to chop that shapefile up into smaller files, each covering a smaller geographic area.

This is best done with GDAL tools, and the user is referred to the gdal vector clip documentation. This tool can split a shapefile up by geographic area, but it can also be used to split a shapefile up according to the attributes of records. It is very powerful.

Using a GIS to explore map data

We recommend QGIS as an open-source, fully featured GIS system.

Converting maps from unsupported formats into formats Xastir can read

See Map Converters.

For further reading about mapping

These links need expanding. At the moment, the one link that's here is the only one that still exists that was recommended by our old README.MAPS document.

• Geodesy for the Layman It's old, but it still exists.

Implementation details

This section is primarily of interest to those working on Xastir code or who want to see what approximations Xastir makes in angle, distance, and area computation.

Distance

There are three functions that compute distances in Xastir:

• calc_distance()
• calc_distance_course()
• distance_from_my_station()

These functions, as well as the "Measure" feature in the map window use the haversine formula to compute great-circle distances.

The 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).

Note that the Haversine formula is ill-conditioned if the two points are antipodal (on opposite sides of the Earth).

Area

Unfortunately, the README.MAPS file that used to contain this information merely made reference to a site called "Dr. Math" that no longer exists, even in web archives.

Xastir computes the area of a "rectangle" of particular extents of latitude and longitude. A web site that describes the formula that was current as of 17 Jan 2026 is John Cook's page on the problem.

From README.MAPS:

• 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.

Angles

From the old README.MAPS:

• 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 easily accurate enough for what we do.