  User's Guide for avdbtools
  John C. Peterson, <jaypee@netcom.com>
  v0.1, 1 May 1998

  The avdbtools package (short for aviation database tools) is a collec-
  tion of software designed to assist in creating and maintaining
  databases for aviation applications. As of this release, avdbtools
  consists of a single application that reads the databases distributed
  by the (United States) National Flight Data Center, and converts them
  into formats usable by other aviation related applications, as well as
  a small collection of Bourne Shell scripts.

  11..  IInnttrroodduuccttiioonn

  11..11..  AAbboouutt aavvddbbttoooollss

  This software was inspired by the discovery that the National Flight
  Data Center is now on the World Wide Web, they can be found at
   <http://www.tgf.tc.faa.gov/nfdc/index.html>. The web site now
  distributes the database files that were once available only on
  magnetic media.

  I've been a long time user of Steve Tynor's flight planning software
  called fplan which was posted to the comp.sources.misc USENET
  newsgroup.  The database files that were available for fplan were
  aging rapidly, and the need for new database files was clear. The
  avdbtools package also provides limited support for generating world
  files for ICAO Map.

  11..22..  CCooppyyrriigghhtt

  The avdbtools software package is Copyright (C) 1998 John C. Peterson,
  <jaypee@netcom.com>

  This software package is free software; you can redistribute it and/or
  modify it under the terms of the GNU General Public License, version
  2. A copy is included in this distribution in the file named
  "LICENSE".

  This software package is distributed in the hope that it will be
  useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  General Public License, version 2, for more details.

  11..33..  CChhaannggeess

  Release 0.1 is the first public release of avdbtools, so there are no
  changes to report. The code should be considered reasonably stable, I
  have done a fair amount of testing myself. (This should not be
  confused with the claim that there are no bugs!) The low version
  number is mostly indicative of the absence of desired features. The
  support for fplan databases is relatively complete, while support for
  ICAO Map still needs more work before it is complete.

  22..  IInnssttaallllaattiioonn

  22..11..  OObbttaaiinniinngg tthhee DDiissttrriibbuuttiioonn

  I don't have enough disk space at my current ISP to host the
  distribution myself, so I am using some of the popular archive sites
  for Linux software. I will be distributing avdbtools in compressed tar
  format as well as Red Hat Package Manager (RPM) format. You should be
  able to get the distribution by anonymous ftp from the sites listed
  below. If the files are not there, check the respective Incoming
  directories.

  +o  Compressed Tar:  <ftp://sunsite.unc.edu/pub/Linux/apps/aviation/>

  +o  Red Hat Package Manager (RPM):

  +o  Source:  <ftp://ftp.redhat.com/pub/contrib/SRPMS>

  +o  Binary:  <ftp://ftp.redhat.com/pub/contrib/i386>

  22..22..  RReeqquuiirreemmeennttss

  This software was developed and tested under Red Hat Linux, release
  4.2.  The requirements are relatively modest, you should be able to
  build and use this software under most any UNIX like environment with
  an Ansi C compiler (such as the Free Software Foundation's gcc
  compiler), a make utility, and the Bourne shell.

  22..33..  CCoonnffiigguurraattiioonn aanndd CCoommppiillaattiioonn

  To build faaconv, follow these easy steps;

  1. Edit the Makefile and change the macros that are related to
     specification of the environment, assigning values appropriate to
     your situation.  The only macros you should need to edit are; CC to
     specify your C compiler, and BINDIR, DOCDIR, LIBDIR, MANDIR to
     specify the directories where the executable, documentation, model
     coefficients, and man page, respectively, are to be installed.

  2. Run "make" to build the executable.

  3. Run "make install" to install the executable in BINDIR, and the
     model coefficients in LIBDIR.

  4. Run "make install-man" to install the man page in MANDIR and the
     user's guide in DOCDIR.

  This user's guide and the man page can be found in the doc
  subdirectory of the source distribution tree. Both are written in SGML
  (Standard Generalized Markup Language) format. The SGML format
  documents are translatable into other useful and popular formats such
  as LaTeX (and dvi, postscript from there), as well as standard HTML.
  The converted formats are up to date with respect to the SGML versions
  when distributed. If you make changes to the master SGML format
  documents, you will need the Linuxdoc-SGML formatting system to update
  the other formats. It is available from
   <ftp://ftp.cc.gatech.edu/pub/people/gregh/linuxdoc-sgml/>

  33..  TThhee ffaaaaccoonnvv AApppplliiccaattiioonn

  33..11..  AAbboouutt ffaaaaccoonnvv

  The faaconv application reads the databases distributed by the
  National Flight Data Center and converts them into formats usable by
  various other aviation related applications. It currently produces
  output in a format compatible with the fplan and ICAO Map applications
  as well as a generic format vaguely similar to the format used in the
  Airport/Facility Directory published by NFDC.
  33..22..  OObbttaaiinniinngg tthhee NNFFDDCC DDaattaabbaasseess

  As of this writing, the National Flight Data Center makes 5 different
  database files available over the Internet. They contain information
  on airports, navigation fixes, instrument landing system facilities,
  navigation aids, and runways. These files can be retrieved by
  anonymous ftp from the following location

  +o   <ftp://ftp.tc.faa.gov/nfdc/apt.tar.gz>

  +o   <ftp://ftp.tc.faa.gov/nfdc/fix.tar.gz>

  +o   <ftp://ftp.tc.faa.gov/nfdc/ils.tar.gz>

  +o   <ftp://ftp.tc.faa.gov/nfdc/nav.tar.gz>

  +o   <ftp://ftp.tc.faa.gov/nfdc/rwy.tar.gz>

     Although it's not absolutely necessary, I recommend that you fetch
     the files using client software that preserves the remote file time
     stamps. It's best if we know (as best as we can) the correct age of
     the information in the database, regardless of when the files were
     transferred. (Examples of such clients include ncftp, available
     from  <ftp://ftp.ncftp.com/ncftp/>, or wget with appropriate
     command line flags, available from
      <ftp://prep.ai.mit.edu/pub/gnu/>). I may be missing something, but
     of the many browsers I've used to transfer files by ftp, all
     cheerfully use the current date for the file time stamp.

  Please note that the home page of the National Flight Data Center web
  site clearly states that the data files are _n_o_t _t_o _b_e _u_s_e_d _f_o_r
  _n_a_v_i_g_a_t_i_o_n_a_l _p_u_r_p_o_s_e_s. Given this clear warning, it's quite possible
  you could get into deep dung if you crashed and used this information
  without doing some additional homework. You've been warned.

  A fundamental limitation of this data that you should be aware of;
  there is _n_o mention of what datum the latitude and longitude are
  referenced to (GPS uses the World Geodetic System 84 datum by
  default). I'm only guessing, but it's possible that no uniform datum
  was used. Be aware that two points with identical latitude and
  longitude, but referenced to different datums, can be as far apart as
  several hundred meters! Given this, don't even _t_h_i_n_k about using this
  data for a precision approach.

  33..33..  RRuunnnniinngg ffaaaaccoonnvv

  In this section, we provide a brief overview of running faaconv, a
  complete reference on command line syntax can be found in the provided
  man page. There are two options with important ramifications that we
  discuss below. What's right for you depends on your specific
  situation.

     --kk This option provides a mechanism for differentiating between an
        airport and navigational aid with the same identifier. (There
        are many examples of this in the airport database).  This option
        implements a convention currently used by many GPS
        manufacturers.  Any airport identifier that is all alphabetic,
        and is exactly three characters long, is prepended by the
        character "K". This applies to _a_l_l such airports, regardless of
        the existence of a navigational aid with the same identifier. So
        for example, HMT becomes KHMT, while identifiers like L78 and
        CL35 are not translated.
     --mm ((ddbb||ffmm))
        This option controls the convention used for determining the
        magnetic variation entries in the output databases. For some
        entries, such as fixes and navigational aids, the NFDC database
        does not provide a value for the magnetic variation, so a value
        _m_u_s_t _b_e _e_s_t_i_m_a_t_e_d using a model (see the following section). For
        other entries, the NFDC database provides a magnetic variation
        value. To use the database value, when it's available, use db as
        the argument to this option. To always use the value computed by
        the model, use fm. The later is the default and recommended
        value (the values in the NFDC database appear to be somewhat out
        of date).

  33..44..  TThhee GGeeoommaaggnneettiicc FFiieelldd MMoodduullee

  While examining the format of the new comma delimited data files from
  NFDC, to my surprise I discovered that the navaid files no longer had
  any entry for magnetic variation! (This isn't something you can ignore
  considering the fact that a VOR radial corresponds to a magnetic, not
  true bearing). At any rate, this presented an unexpected complication
  that had to be dealt with. I needed a model to calculate the magnetic
  variation, given an arbitrary latitude and longitude referenced to
  some datum.

  33..44..11..  TThhee PPhhyyssiiccaall MMooddeell

  After some research, I concluded that the best solution was to use one
  of the geomagnetic field models in common use by the Geophysics
  community. The two most commonly encountered models are the
  International Geomagnetic Reference Field, 1995 Revision (IGRF-95),
  and the United States Department of Defense World Magnetic Model, 1995
  Revision (WMM-95). In these models, the geomagnetic field potential is
  represented by a summation of spherical harmonics (using associated
  Legendre functions). The coefficients are found by fitting the model
  to precise measurements of the earth's geomagnetic field. A secular
  change model is used to account for the slow drifting of the earth's
  magnetic field over time. The models are updated once every five
  years, with the next model due to come out in the year 2000. The model
  coefficients and a collection of support software are distributed in
  the United States by the National Geophysical Data Center (NGDC)
  located in Boulder, CO. They can be reached on the Internet at
   <http://www.ngdc.noaa.gov/seg/potfld/geomag.html>

  33..44..22..  LLiimmiittaattiioonnss ooff tthhee PPhhyyssiiccaall MMooddeellss

  These physical models have limitations that you should be aware of.
  The low order polynomials used in these models capture only the
  contribution to the earth's geomagnetic field from the earth's fluid
  outer core. The models do _n_o_t have enough fidelity to capture the
  contributions to the total field from the earth's crust. These
  contributions, or other anomalies, are not uncommon, and in some cases
  can be quite significant (the iron ore deposits of the Mesabi Range in
  Northern Minnesota are a prime example). Anomalies can also be caused
  by magnetic storms in the ionosphere, man made sources such as high
  voltage electric power transmission lines, etc.

  On the other hand, these models are reasonably well suited to the
  intended application. In fact, if you own a GPS receiver, it's quite
  possible you are already using one of these models. I saw a USENET
  posting that referenced an unofficial communication with at least one
  GPS manufacturer, indicating that they use the IGRF model in their
  navigation code to convert a true heading into a magnetic one. The
  literature suggests that these models are good to about 30 minutes of
  arc for the angles, and to within about 25 nanoTesla for the total
  intensity.

  33..44..33..  SSooffttwwaarree IImmpplleemmeennttaattiioonn

  I initially considered using some of the software distributed by NGDC.
  I really wanted a C language solution and most of the NGDC software
  was written in Fortran 77 (which I have nothing against in general). I
  decided to start from scratch using only a theoretical description of
  the model. The results of that effort can be found in the file
  field_model.c. It was designed to use either of the IGRF or WMM model
  coefficient data files _e_x_a_c_t_l_y as distributed by NGDC (to make future
  updates of the model coefficients as easy as possible). The two files
  from NGDC that I used are

  +o   <ftp://ftp.ngdc.noaa.gov/Solid_Earth/Mainfld_Mag/Models/igrf95>

  +o   <ftp://ftp.ngdc.noaa.gov/Solid_Earth/Mainfld_Mag/Models/wmm95>

     The only change I made was to remove the trailing 95 from the file
     names, the contents were not changed in any way. I did this to; 1)
     eliminate the need to change source code when the time comes to
     update to new coefficients, and 2) to avoid the involuntarily
     episodes of nausea I sometimes experience when I see the number 95.
     If you try using coefficient files from _s_o_u_r_c_e_s _o_t_h_e_r _t_h_a_n _N_G_D_C,
     exercise appropriate caution. Some distributions of these models
     (WMM in particular) use different normalization factors for the
     associated Legendre functions, and would produce incorrect results
     when used with this software! Be warned, be careful.

  33..44..44..  SSooffttwwaarree PPrrooggrraammmmiinngg IInntteerrffaaccee

  Since the field model seemed liked it might be useful for other
  projects, I tried to make the implementation as self contained as
  possible. The field_model.c module contains three functions;

     eexxtteerrnn iinntt iinniitt__ffiieelldd__mmooddeell((cchhaarr **ffiilleennaammee));;
        This function is called to initialize the model coefficients,
        which are read from the specified file. If you want to switch
        back and forth between different models, just call the function
        again with the appropriate model coefficient file. It returns
        TRUE if the initialization succeeded, and FALSE if not.

     eexxtteerrnn iinntt ffiieelldd__mmooddeell((ffiieelldd__mmooddeell__tt **vvaalluuee));;
        This function is used to compute the geomagnetic field at a
        specified point. The input position and computed field values
        are exchanged through a single structure of type field_model_t
        which is described in the module header file field_model.h. The
        specified position is assumed to be described by geodetic
        latitude, longitude and altitude (or height for you ground
        pounders), referenced to the WGS-84 datum.  (The choice of the
        WGS-84 datum seemed best since that is the default for GPS which
        is become increasingly important in practical navigation).  The
        computed declination (what we pilots call variation) and
        inclination (or dip) angles are returned in units of decimal
        degrees. The computed total field strength is in units of
        nanoTesla. The sign convention for the angles is; positive
        declination corresponds to east, and positive inclination is
        down. It returns TRUE if the computation succeeded, and FALSE if
        not.

     eexxtteerrnn cchhaarr **ssttrreerrrroorr__ffiieelldd__mmooddeell((vvooiidd));;
        This function returns a pointer to a character string that
        contains an explanation of the last error that occurred. This
        allows the calling function to decide how to handle error
        recovery.

  33..44..55..  AAccccuurraaccyy ooff SSooffttwwaarree IImmpplleemmeennttaattiioonn

  I tested my implementation against some of the software distributed by
  the NGDC by anonymous ftp. It was a little disappointing to find that
  the various implementations available from them did not always agree
  with one another all that well (at least relative to my expectations).
  It was reassuring to find that my implementation agreed quite well
  with the software developed by the Defense Mapping Agency, the Fortran
  77 subroutine named GEOMAG.FOR, which can be obtained from the
  directory
  <ftp://ftp.ngdc.noaa.gov/Solid_Earth/Mainfld_Mag/DoD_Model/Fortran_Software/>.
  The table below shows the statistics for the comparison of 5 million
  random evaluations. All inputs were allowed to vary uniformly over the
  entire valid range, except for latitude which was distributed
  uniformly over the interval from 80S to 80N degrees. (I haven't
  finished implementing the limiting case of the geographic poles, so
  I've limited the inputs to this range for now. Sorry, you guys
  planning flights to Northern Greenland or Amundsen-Scott Station in
  Antartica will have to wait awhile).

         +-----------------------+------------------+------------------+
         |       Computed        | sqrt of the mean | maximum absolute |
         |       Quantity        |  error  squared  |      error       |
         +-----------------------+------------------+------------------+
         | declination (degrees) |   2.57954e-05    |    -0.0226572    |
         +-----------------------+------------------+------------------+
         | inclination (degrees) |   1.04046e-05    |  -7.28456e-05    |
         +-----------------------+------------------+------------------+
         |  total intensity (nT) |      0.010123    |      -0.06995    |
         +-----------------------+------------------+------------------+

  The average agreement is acceptable when measured by the square root
  of the mean of the squared error (quite good considering that the DMA
  software is only single precision). There are a few regions where the
  disagreement in declination is higher. In my tests it was always a
  point relatively close to one of the magnetic poles, near 78N 103W, or
  65S 139W. This is not unreasonable since the horizontal component of
  the magnetic field vanishes (by definition), and the declination
  ceases to be well defined as one approaches the magnetic poles.

  33..55..  CCrreeaattiinngg OOuuttppuutt ffoorr ffppllaann

  The fplan software expects two database files; airports.nav and
  vors.nav. The first file contains entries for airports, (gliderports,
  heliports, and ballonports too), and is generated by running faaconv
  with comma.apt as input. The second file contains entries for
  navigational aids and is generated from the combined outputs from
  faaconv with comma.fix, comma.nav as inputs.

  Unfortunately, the comma.ils file is useless. Although the identifier
  of the airport associated with each ILS facility is provided, the ILS
  identifiers themselves are not. The trouble is that they are not
  always related to the associated airport identifier (for example, LAX
  has multiple ILS systems, each with a unique identifier).  The
  comma.rwy file is not used either, it simply doesn't contain any
  information that fplan reads or uses.

  The generated files must then be sorted by identifier, and padded to
  fixed length records using the paddb utility supplied with fplan. (The
  fplan application uses a fast binary search that relies on fixed
  length records). A simple bourne shell script is provided to automate
  this conversion. Simply change to the directory where the NFDC files
  are located and run the script mknavdb.

  33..66..  CCrreeaattiinngg OOuuttppuutt ffoorr IICCAAOO MMaapp

  The ICAO Map software reads a single world database file that contains
  all airport and navigational aid information. You can simply merge the
  output from faaconv with comma.apt, comma.fix, comma.ils, comma.nav as
  inputs. To reduce the memory requirements of ICAO Map, you might
  consider creating seperate world files for your state or region.  The
  parser in release 1.0 of ICAO Map is not compatible with some of the
  characters output by faaconv. The file icao-1.0.patch contains a patch
  for the parser.

  44..  AAddddiittiioonnaall IInnffoorrmmaattiioonn

  44..11..  OOtthheerr SSooffttwwaarree

  44..11..11..  ffppllaann

  The fplan flight planning software package was written by Steve Tynor.
  It was designed for constructing VFR cross country flight plans.  The
  last public release by Steve was version 1.3 and was posted to volume
  30 of the comp.sources.misc USENET newsgroup. As a product of my
  efforts with avdbtools I made some improvements and fixes to fplan.
  When I approached Steve with the changes, he indicated he was too busy
  with other projects and offered me the option of taking over as
  maintainer, which I accepted.

  The next release of fplan should be available soon. It will include
  support for the graphics previewer option that is based on the XView
  Toolkit for X11 (release 1.3 required Suntools, making that option Sun
  specific). The XView Toolkit, developed by Sun Microsystems, is
  available in source code form, and has been ported to a wide variety
  of UNIX/X11 platforms including HP-UX, Linux, SVR4, and Solaris of
  course. When everything is ready, I plan to distribute fplan from the
  directory
   <ftp://sunsite.unc.edu/pub/Linux/apps/aviation/>.

  44..11..22..  IICCAAOO MMaapp

  ICAO Map is a program for generating and displaying maps for aviation
  purposes. It was written by Martin Pauly, and runs under UNIX systems
  with X11/Motif. It's input is a so called "world file", that contains
  descriptions of objects such as airports, navigational aids, roads,
  towns, etc. It can use either Lambert or Mercator projection to
  generate a map from this world file, either on your screen or as
  Postscript output.  It also includes interactive features, such as
  scrolling, rubber band lines to measure distances and tracks, etc.
  Additional features are available for both motorized and soaring
  (glider) flights. For more information, visit the ICAO Map home page
  on the World Wide Web at
   <http://www.oih.rwth-aachen.de/~pauly/icao.html>.

  44..22..  FFuuttuurree PPllaannss

  My immediate goal is to complete the support for ICAO Map, as well as
  for the generic format output. Once this is complete, I have some
  ideas for new features. A simple GUI interface to the Geomagnetic
  Field Model, perhaps based on the Tk, Xforms or similar widget sets
  might be useful. Another idea would be to generate database files for
  updating GPS receivers. I find it quite annoying to be shelling out
  lots of hard earned cash for something we basically paid for already
  in the form of taxes. This isn't a trivial project however, since all
  of the manufacturers zealously guard much of the necessary information
  (correct me if I'm wrong). Another idea would be to create an
  interface to a high quality database engine such as PostgreSQL. This
  idea is less interesting in view of the fact that this sort of thing
  is already available over the net, see  <http://www.airnav.com/>.

  44..33..  CCoonnttaaccttiinngg tthhee AAuutthhoorr

  If you find a bug in this software (especially if you also have a
  patch for it) you can contact me by electronic mail at
  <jaypee@netcom.com>.  Questions, comments, or suggestions are welcome.
  Please note that I sometimes go through periods of time when I can't
  check my mail regularly, so don't be alarmed if you don't get an
  immediate reply.

