% $Revision: 1.11 $
\documentclass[a4paper,10pt]{article}


% Title Page
\title{File format specification for KFLog and Cumulus Aeronautical data files}
\author{Andr\'e Somers}

\usepackage{rotating}

\begin{document}
\maketitle

\begin{abstract}
KFLog and Cumulus currently use a set of binairy data files for aeronautical data. Because the need to edit the data manualy has arrisen, a new text-based format needed to be defined, that allows users to manually edit the data files. This is the specification for that file format. Airspace definitions are not covered in this specification, but may be added in a future version.
\end{abstract}

\section{Considderations}
When defining the file format, the following condidderations were kept in mind:
\begin{itemize}
\item The full range of objects currently available in the binairy format should be supported.
\item The file format should allow for multiple runways and multiple points of contact for each entry.
\item The file should be easy to edit manually without the need for a specialized editor.
\item The file should be easy to parse and manipulate in scripting languages.
\end{itemize}
We studied the specifications for existing file formats (like SeeYou's CUP file format), but found them inadequate for our needs. Therefore, we decided on designing our own, open, format.\\

Text based formats have the disadvantage that they are relatively slow to parse. Currently, Cumulus allready has a method to store data in a projected manner. Upon first reading of the file, the data is stored in this compiled, binairy fileformat so it will be read faster the next time the data is read.

\section{Basic format}
The basic format of the file is a single entry per line with tab delimited fields. Every field can contain either a key or a value. Each key is followed by 0 or more values, depending on the key. Keys are case insensitive. Unrecognized keys and additional tabs are ignored\footnote{See also section \ref{sec:impl}: Implementation directions.}. A record may, depending on its type, have mandatory and/or optional keys. Additional spaces around the key or the value are ignored. Each line is referred to as a \emph{record} in the following text.

Each record is terminated with an CR and/or a LF character. Empty lines are allowed. Comments should start with a \verb|#| or \verb|//| as the first character(s) on the line.\\

In the following text, tab characters are displayed as \verb|<tab>| and end of line characters as \verb|<CR>| and \verb|<LF>|.\\

example:
\begin{verbatim}
//This is a comment<LF>
# This is also a comment<CR>
KEY1<tab>VALUE<tab>KEY2<tab>VALUE1<tab>VALUE2<CR><LF>
\end{verbatim}

\section{Preamble}
The document \emph{must} start (comments and empty lines before the preamble are allowed, but not recommended) with the preample. The preamble contains meta-data about the document. It consists of a single record in the general KEY / VALUE pair format. The preable \emph{must} start with a \verb|PREAMBLE| key, that takes no arguments. The preable also \emph{must} contain a \verb|DATE| key, a \verb|VERSION| key and a \verb|TYPE| key with their appropriate arguments.

The \verb|DATE| key takes a single argument, consisting of a date formatted as YYYY-MM-DD. This KEY / VALUE pair defines the date the last modification was made. It is used to determine if the data needs to be re-compiled.

The \verb|VERSION| key takes a single argument, consisting of an integer. Currently, the only allowed value is \verb|1|. This field is used to distinguish the file from future versions.

The \verb|TYPE| key takes a single argument, consisting of the text \verb|airfield|. This field is used to distinguish the file from other subtypes using the same basic file format.\\

Other KEY / VALUE pairs may be added, but they are ignored. Future revisions of this file format may define new values here. Use \verb|X-| as the name of your custom key to avoid problems with future versions. Additional preamble records in the file are ignored.\\

example:
\begin{verbatim}
PREAMBLE<tab>DATE<tab>2004-01-23<tab>VERSION<tab>1<tab>TYPE<tab>airfield<CR>
\end{verbatim}

\section{Units}
Values of keys may be entered in different units. For instance, altitudes may be given in meters, feet or flightlevels. All records following a unit-record are taken to use the units defined in this units record. A units record may appear on any line of the file, defining the units for the records to follow this record. Only units that are actually defined in a Units record are changed, so, if you only want to change the \verb|LENGHT| unit, you just enter a Units record with only the \verb|LENGTH| key defined.

A Units record starts with a single \verb|UNIT| key, followed by 0 or more pairs of quantity names and units. The following KEY / VALUE pairs are allowed:
%\begin{table}[h]
\begin{tabular}{rlp{7cm}}
\textbf{key} & \textbf{value} & \textbf{details}\\
\hline
\verb|ALTITUDE| &  & Defines the unit used for altitudes like \verb|ELEVATION|. \\
& \verb|m| & Use meters. This is the default value.\\
& \verb|ft| & Use feet.\\
& \verb|fl| & Use flightlevel. \\
\verb|LENGTH| &  & Defines the unit used for lengths like the length of a \verb|RUNWAY|. \\
& \verb|m| & Use meters. This is the default value.\\
& \verb|km| & Use kilometers.\\
& \verb|ft| & Use feet.\\
& \verb|nm| & Use nauticle miles.\\
& \verb|ml| & Use statude miles. \\
\verb|COORDINATE| & & Defines how coordinates are specified, as used for the \verb|COORD| key.\\
& \verb|dd:mm:ss| & Use the coordinate format with seconds. An additional \verb|N| or \verb|S| is used for latitudes, and an additional \verb|E| or \verb|W| is used for longitudes. This is the default value.\\
& \verb|dd:mm.mmm|  & Use decimal minutes, also followed by \verb|N|, \verb|S|, \verb|E| or \verb|W|.\\
& \verb|kflog| & Use the internal KFLog format. This format consists of a single signed integer, using this formula: $kflog = 600000 * degrees + 10000 * minutes + 167 * seconds$. Negative values are used for the southern and western hemipheres.\\
\hline
\end{tabular}
%\caption{\label{table:units}Overview of quantity-keys and their possible argument values.}
%\end{table}

example:
\begin{verbatim}
UNIT<tab>ALTITUDE<tab>m<tab>COORDINATE<tab>dd:mm:ss<CR><LF>
\end{verbatim}

\section{Aeronautical data}
The Aeronautical data is the data around which this whole file specification revolves. There are many types of objects that are significant for aeronautical use. These include different types of airfields and airports, obstacles, mountain tops and --passes and other points of interest. This file specification only deals with \emph{single point} type data, that is, data for which a single point can be used in its representation.

Every aeronautical record (`aero record' for short) starts with a single key \verb|TYPE|, which has a single parameter. This parameter defines the type of object that is being defined. See the table on page \pageref{table:aerotypes} for a list of acceptable values.\\
Following the \verb|TYPE| key/value pair, there are 0 or more key/value pairs defining the objects properties. Most of these properties may only appear once, but some may appear multiple times. The latter are explicitly marked as such.\\

The following table lists the properties available for aero records:\\
\begin{tabular}{rlp{8,5cm}}
\textbf{key} & \textbf{argument(s)} & \textbf{details}\\
\hline

\verb|COMMENT| & \emph{string} & Comments on the object. This is a free string of any length. Linebreaks are currently not supported, but in a future version may appear in an encoded form.\\

\verb|CONTACT| & & Represents a contact. Takes 3 parameters. This key may be used multiple times for an aero record.\\
& \emph{float} & The frequency in the $123.50$ format, in Mhz.\\
& \emph{string} & Callsign used to call the field on this frequency.\\
& \emph{string} & Comments. Additional comments on this contact, for instance when to use this contact in opposition to when to use another contact.\\

\verb|COORD| & & Shorthand for \verb|COORDINATE|. See \verb|COORDINATE| for description.\\
\verb|COORDINATE| & & Coordinates for the object. This property has two arguments.\\
& latitude & Latitude of the object, in the format defined by the previous Units record.\\
& longitude & Longitude of the object.\\

\verb|DESC| & & Shorthand version of \verb|DESCRIPTION|.\\
\verb|DESCRIPTION| & \emph{string} & Description for the object. This is used to store the complete name for the object, where the \verb|NAME| may be an abbreviated version of the name.\\

\verb|ELEV| & & Shorthand version for \verb|ELEVATION|.\\
\verb|ELEVATION| & altitude & Elevation of the object, in the format defined by the previous Units record.\\

\verb|ICAO| & \emph{string} & ICAO code of the airfield. 4 characters in length.\\

\verb|NAME| & \emph{string} & Short name for this object. 6 characters is the recommended limit.\\

\verb|RUNWAY| & & Represents a runway on an airfield or airport. Takes 6 parameters. This key may be used multiple times for an aero record.\\
& \emph{integer} & Direction of the runway. Integer in the range $0\cdots36$. 0 and left blank is interpretted as `unknown'. The second direction is not used when this value is unknown.\\
& \emph{integer} & Second direction of the runway. If ommitted, the diagonal of the first direction is used. If the same as the first direction, the runway may only be used in this direction.\\
& length & The length of the runway, in the units defined in the last Units record. If negative or left blank, the value is interpretted as `unknown'.\\
& \verb|u|, \verb|a|, \verb|c| or \verb|g| & Surface of the runway. \verb|u| for unknown, \verb|a| for asphalt, \verb|c| for concrete or \verb|g| for grass. If left blank, \verb|u| is assumed.\\
& \verb|y| or \verb|n| & Runway open? \verb|yes| may be used for \verb|y|, and \verb|no| for \verb|n|. If left blank, \verb|y| is assumed.\\
& \emph{string} & Comments. Additional comments on this runway.\\

\verb|WINCH| & -- & Indicates the availability of a winch for gliders on this airfield. There are no parameters for this key.\\

\hline
\end{tabular}

\subsection{Aeronautical object types}
Currently, there are 40 aeronautical object types defined. For each object type, you can use either the numerical ID or the associated name as the argument for aero records \verb|TYPE| key. That means that \verb|TYPE<tab>10| and \verb|TYPE<tab>GLIDERSITE| are equivalent.

Every aeronautical object type \emph{must} have the \verb|COORDINATE| and the \verb|ELEVATION| (or their shorthand equivalents) keys defined. For all objects, the \verb|COMMENT| key is optional. On top of that, there can be both mandatory and optional additional keys for each object type. The table below lists all the currently defined object types. Mandatory keys are marked with a \emph{M}, and optional keys are marked with an \emph{O}. Other keys have no meaning for that object type\footnote{See also section \ref{sec:impl}: Implementation directions.}.\\

\begin{tabular}{|r|l|c|c|c|c|c|c|}
\hline
\textbf{id} & \textbf{name} &%
 \begin{turn}{70}\verb|CONTACT|\end{turn} &%
 \begin{turn}{70}\verb|DESCRIPTION|\end{turn} &%
 \begin{turn}{70}\verb|ICAO|\end{turn} &%
 \begin{turn}{70}\verb|NAME|\end{turn} &%
 \begin{turn}{70}\verb|RUNWAY|\end{turn} &%
 \begin{turn}{70}\verb|WINCH|\end{turn}\\
\hline
 0 & UNKNOWN &&&&&& \\
 &&&&&&&\\
\hline
 1 & INT\_AIRPORT &O&O&O&M&O&O\\
 2 & AIRPORT &O&O&O&M&O&O\\
 3 & MIL\_AIRPORT &O&O&O&M&O&O\\
 4 & CIVMIL\_AIRPORT &O&O&O&M&O&O\\
 5 & AIRFIELD &O&O&O&M&O&O\\
\hline
 6 & CLOSED\_AIRFIELD &O&O&O&M&O&O\\
 7 & CIV\_HELIPORT &O&O&O&M&O&O\\
 8 & MIL\_HELIPORT &O&O&O&M&O&O\\
 9 & AMB\_HELIPORT &O&O&O&M&O&O\\
10 & GLIDERSITE &O&O&O&M&O&O\\
\hline
11 & ULTRALIGHT &O&O&O&M&O&O\\
12 & HANGGLIDER &O&O&O&M&O&O\\
13 & PARACHUTE &O&O&O&M&O&O\\
14 & BALLOON &O&O&O&M&O&O\\
15 & OUTLANDING &O&O&O&M&O&O\\
&&&&&&&\\
\hline
34 & OBSTACLE &&O&&O&&\\
35 & LIGHT\_OBSTACLE &&O&&O&&\\
36 & OBSTACLE\_GROUP &&O&&O&&\\
37 & LIGHT\_OBSTACLE\_GROUP &&O&&O&&\\
38 & SPOT &&O&&O&&\\
&&&&&&&\\
\hline
80 &DAM &&O&&O&&\\
81 & MINE &&O&&O&&\\
82 & INDUSTRY &&O&&O&&\\
83 & DEPOT &&O&&O&&\\
84 & TOWER &&O&&O&&\\
\hline
85 & SETTLEMENT &&O&&O&&\\
86 & CASTLE &&O&&O&&\\
87 & LIGHTHOUSE &&O&&O&&\\
88 & STATION &&O&&O&&\\
89 & BRIDGE &&O&&O&&\\
\hline
90 & FERRY &&O&&O&&\\
91 & MOUNTAINTOP &&O&&O&&\\
92 & MOUNTAINPASS &&O&&O&&\\
93 & ROAD\_INTERSECTION &&O&&O&&\\
94 & RAIL\_INTERSECTION &&O&&O&&\\
\hline
95 & ROAD\_RAIL\_INTERSECTION &&O&&O&&\\
96 & RAIL\_BRIDGE &&O&&O&&\\
97 & CHURCH &&O&&O&&\\
&&&&&&&\\
\hline
100 & TURNPOINT &&O&&O&&\\
\hline
\end{tabular}
\label{table:aerotypes}

\section{implementation directions}
\label{sec:impl}
This section gives some directions for the implementation of parsers for this fileformat. Implementors may deviate from these directions if they wish, but we feel it would good to keep the following guidelines:
\begin{description}
\item[Completeness]Different aeronautical record types require different key/value pairs to be present. We recomment to ignore incomplete records rather than using default values if these are not explictly defined in this specification, because default values may give the user of the software the feeling that the default represents `real' data, rather than a placeholder for it. This can lead to problems when for instance the elevation is set to 0, while that point has a real elevation of 350 meters. In that case, it may appear within reach for a pilot, while in fact it is not.
\item[Error reporting]Parsers should report errors found in the parsed files, complete with linenumber and if possible key name and value. A parse error on a specific record must not stop the parse process, but only ommit the record in which the error occurred. Errors may be send to a \verb|stdout| or \verb|stderr|.
\item[Additional data]Key/value pairs that are not recognized for a particular aeronautical record type, may be added to the comments field except if the name of the key starts with \verb|X-|, which is the default prefix for extended records. This gives the user the opportunity to keep additional data in a semi-structured way. Ignoring the additional data is acceptable though.
\item[Shorthands]Implementations may accept shorthand forms of both keys and values, as long as these remain unique. That means, that an implementation may choose to accept \verb|E| as key for \verb|ELEVATION| in aero records, as this is the only key starting with an `E'. However, \verb|C| can \textbf{not} be used, as there are three keys starting with a `C'. The minimum length to use here is \verb|COM|, \verb|CON| and \verb|COO|. Note that an implementation using this must take care to interpret the \verb|VERSION| key in the \verb|PREAMBLE| record! Keys added in later versions may conflict with abbreviated versions of keys defined in this version of the specification.
\end{description}

\section{Formal EBNF specification}

\section{Example file}

\end{document}
