Release 0.7b  Copyright ã1993, 1994 by Stefan Leuker, Oliver Meyer and Martin Pauly.  All Rights Reserved.
April 1994

ICAO Map 0.7b

¬

Introduction

What is ICAO?
(This one relates to the also available X11/Motif release of ICAO. What you are holding now is the brand new NEXTSTEP release! And always remember: This manual as well as most parts of the software is no more than a fast hack... Now, let's go to the real stuff:)

ICAO is the abbreviation of the"International Civil Aviation Organization". If you are a pilot, that won't be new to you. And the ICAO hasn't got too much to do with this program. So why is it called ICAO?

Well, work on this application started in December 1992. I got interested in the mathematics involved with map projections. A few books from our library provided me with the knowledge to draw a part of the earth onto the flat screen of a computer, using the conical Lambert projection with two standard parallels. It was interesting, nice to watch and useless.

It was about the same time that I got Linux, which I liked better the longer I used it. Not only could I work under the same environment I used at the university; it also seemed to me much more stable and a lot faster than most other operating systems for IBM clones. Then I turned to X11 programming. Equipped with some literature about X, I began rewriting the map projection program, probably just because I couldn't think of anything more intelligent.

As an empty map is rather boring, the next step was to draw some objects on it. The only map handy at that time was - guess what - the "Aeronautical Chart ICAO 1:500000", simply referred to in Germany as "ICAO Karte". The first executable that could draw an airfield symbol was named "icao". That's what it is still called today, and I guess unless a superb other name comes to my mind that won't change.

Naturally, Linux had become the development platform for ICAO. To verify portability, I compiled it on a HP Apollo Series 700 workstation from time to time, which worked fine.

Hardcoding the objects to be displayed into the program was OK for two airports, but impossible for the 600-odd objects that were in the world file in January 1993. That forced me to have a closer look at YACC and LEX (or rather BISON and FLEX, the GNU equivalents of the well-known UNIX tools), which I used to create the scanner and the parser that read the world file.

Most data currently contained in the world file comes from the official ICAO map and from the German AIP (Aeronautical Information Publication). The coordinates of civil airports and radio navigation facilities should be precise. Most other coordinates where read from the map with a digitizer, so that points of rivers, CTRs and towns are not always quite as precise.

At first, the program didn't have many functions: it could display the map, you could select new origins of the map to be displayed, zoom in and out as well as hide and show certain types of objects. You could also measure distances and true tracks from one point to another, and you could display info boxes for most objects. Many more things were planned for both soaring and motorized flying, but that would have to wait a bit - I was still looking for the Release-5-edition of the O'Reilly X Toolkit Intrinsics Programming Manual, which would (according to a local book shop) be available in April 1993. Till then, I improved the map display and added some more objects to the world file.

Well, the O'Reilly book finally arrived, and at about the same time Metrolink announced Motif for Linux. Not having seen much of Motif at that time, I just guessed that it could be useful for ICAO, so I ordered it. The result is what you are currently looking at.

If you have any suggestions about useful functions for the program, feel free to tell me. If anybody would like to contribute data to the world file - even better, I really can't manage it all by myself. If someone is willing to port ICAO to other (non-UNIX) platforms - great, contact me! Though I like UNIX, I'm aware of how few pilots have access to a UNIX machine.

About the Author
Martin Pauly was born in 1971 in Mðnchengladbach, Germany. He is currently a student of computer science in Aachen. He used to live in Krefeld for a couple of years, next to two airline captains who would get him more than just interested in planes. At the age of 14, he started soaring in a club at the airfield in Grefrath (EDLF). If you ever see an ASW-15B with the registration number D-2310, chances are good that he might be sitting inside it.

As far as computers are concerned, Martin started hacking on a Commodore VIC-20 in the early 80s. An ATARI ST followed later, finally an IBM clone. Fascinated by Linux and the large amount of other public domain software available for UNIX systems, he'd like to offer ICAO to anyone who might find it useful.

You can contact Martin by E-mail as well as snailmail:
Martin Pauly, Rötscherstr. 175/910, 52072 Aachen, Federal Republic of Germany
Internet: pauly@pool.informatik.rwth-aachen.de

Implementation notes

History

December 1992:
Work on ICAO begins. The roots come from an MS-DOS program that displays part of the globe.

January 1993:
Version 0.10 of ICAO is running under X11/Linux. Most object types have been implemented.

February 1993:
Version 0.20 of ICAO includes PostScript output. The master world file contains nearly 700 objects by now.

March 1993:
Version 0.50 is a first attempt to use the X-Toolkit for ICAO. Without any real programming manuals, writing a map widget was a bit difficult so that version did not contain any map display. For the first time, the number of objects contained in the world file exceeded 1000.

Summer 1993:
Like most glider pilots, Martin preferred spending his spare time at the airfield, not in front of his computer. No work on ICAO is done.

October 1993:
In version 0.60a, a Motif interface serves as a front-end for the features that version 0.50 already had, combined with the map display of the older versions. Oliver Meyer and Stefan Leuker start working on a NEXTSTEP port.

November 1993:
Almost one year after work on ICAO began, the UNIX/X11 version is uploaded to a number of FTP servers. Current version number is 0.60b.

January 1994:
The NEXTSTEP release of ICAO reaches the '0.60b' state, and is ready to ship.

March 1994:
Martin Pauly starts to write a new and highly improved Icao kernel.

April 1994:
The NEXTSTEP release of ICAO reaches the '0.7b' state, and is released.

Running ICAO.app

To run ICAO, you need an executable for your kind of computer (either i486 and/or m68k). You should have at least one of four possible Packages. Install the package and you may have:

the executable for your kind of computer.
 Just double-click the icon of ICAO.app.
 
the executable for both (i486 and m68k).
 Just double-click the icon of ICAO.app.
 
the source code of ICAO.
	You need GNU flex to compile ICAO.
	If you don't have it nor want to build it, get an executable of ICAO. 
	If flex is proper installed, simply double-click PB.project and select install in the launched Project Builder. You may need to select your kind of hardware in the Options... dialog box. Click Build (there shouldn't be any warnings except for yaccpar and scanner.l ) and you should find an executable in your Apps directory or wherever you told the Project Builder  to put the executable. Double-click that executable.

After ICAO has launched you will find Aachen to be the only place on the map. If you want to load a worldpart file on startup, you need to select Startup in the Preferences and set the 'Default Worldpart' to e.g. Deutschland.worldpart (see the Preferences section in this manual for further details).

You can close this window and open another worldpart (if you wrote your own :-) with the Open... command from the Worldpart menu.

The Map Window
After starting ICAO you should see a window similar to the following:
¬

Within the map view, mouse buttons perform the following functions:
Be sure to enable the Menu Button in the Mouse Preferences in NeXTs Preferences.app to make use of the right mouse button.

left:
The left mouse button is used to measure distances and true tracks. Go near the starting point of your line, press the left mouse button and hold it. Then move to wherever you want to go. Instead of your current position the two top fields will display the exact distance and track. Releasing the mouse button will quit this mode.  Please note that the "rubber band" you are moving snaps to objects when you get close enough. Feel free to press the shift-key anytime to prevent the line from snapping.

left (with shift):
Like the left mouse button without shift this measures distances and true tracks, but with shift the "rubber band" won't snap to objects near it. Feel free to release the shift key to make the moving end of the line snap.

left (double click):
Makes the current cursor location the new origin of the map. The map origin is the point in the middle of the map. This 'click and scroll' feature is taken from the Motif release and is definitely subject to change in later versions of the NEXTSTEP release!

right:
Displays additional information (if available) for an object close to the cursor. If no object is close enough, ICAO will tell you what airspace you are in.

The respective information is displayed in a small panel that automatically disappears when you release the mouse button.

right (with CONTROL):
Holding the CONTROL key while right-clicking into the map view makes the information panel stay permanent on-screen. (Though, you can close it like other panels, of cause.)

¬

¬
(Examples for permanent info panels.)

The Object Browser
The object browser contains the names of all objects that you could fly to (not necessarily land at). That includes airports, waypoints, towns and lakes, but not rivers and roads. The latter objects are to long to have something that can be called a center or a reference point.

When it comes to waypoints, the type of the object is sometimes part of the name. You might have the "Kraftwerk Weisweiler" in your world file. When you look for it in the object browser, you might also try to find the name "Weisweiler Kraftwerk". Both names are listed in the browser to make finding objects easier.

Scrolling through the list is simple. When you double click on a list item, that item will be brought into the center of the map. It may be nice for some people to scroll through the browser and guess where in the world certain objects are - the answer is only a mouse click away.

The Quick-Search Field
If you know the name of an object, you can quickly select it in the browser by typing its name (usually, the first couple of letters will be sufficient) into the quick search field that is located at the bottom left corner of ICAO's main window. Typing in letters will make the first object name selected that matches the letters you have typed so far.

The Route Display
You can select a route by specifying a take-off location, a destination and up to three points to pass during your flight. The names of the respective waypoints are displayed in the top left corner of the ICAO main window. Please note that the way the route panel is used will be changed as soon as Drag and Drop will be implemented.

Anyway, at the time being you choose a waypoint by typing its name in the respective Textfield. As with the Quick-Search Field the browser will select the corresponding object. 

When you leave a field of the current route (e.g. by pressing TAB) whatever you typed will be replaced by the selection in the browser.

Alternatively, you can select the complete text within a routefield (e.g. by doing a triple-click) and select an object in the browser.

The select switch current route checks wether a route should be visible in the Map Window or not. The Route will be drawn as a thick red line. 

Visible Objects...
For different purposes, the user may want different type of objects to be visible on the screen. The IFR pilot won't be too interested in highways and small VFR-only airfields, whereas a glider pilot will probably not take much advantage of radio navigation facilities. Apart from that, the smaller your scale is, the more objects have to be drawn on the map - it's a matter of course that your screen will be crowded, and the time it takes to redraw the map increases dramatically.

¬

Fortunately, you can choose what object types you would like to see on the map. A Visible Objects panel is used for that purpose. The result is not only visible on the screen, it also selects object for printing.

After changing the set of visible objects you must cause the map to reflect your changes. Use the Display button for that purpose.

Select the map projection
Without going into detail at this point: ICAO supports two different algorithms to project the three dimensional surface of the earth onto a two dimensional map. Depending on what characteristics you require, different projection algorithms can be more or less useful. In aviation, the conical Lambert projection and cylindrical Mercator projection serve most needs quite well as long as you do not approach the poles (which you should not try using ICAO - hey, it's damn cold there anyway).
You select one of the projection algorithms from the Mercator/Lambert popup button on the left below the map view.

Print...
When you choose Print.. from ICAOs Main Menu the normal Print Dialog appears extended by the following PopUp Button. 
¬
If you choose Keep Scale and Center the printed map will have the same scale and center as the map in the Map View. This is the default if there is no route ICAO knows about or if the current route isn't displayed in the Map View.
If you choose Adjust printed Map to Route, which is only selectable if ICAO knows about any Route, you'll get a printout of the complete route, covering the take-off location and destination as well as all the waypoints in between.  For that purpose ICAO selects a scale that makes your route fit on a single sheet of paper. It also determines wether landscape or portrait orientation is preferable. 
The printed Map will show only those objects that are currently marked in the Visible Objects dialog.

Autorouter
Provided that you have selected a take-off location and a destination (and optionally via waypoints), the autorouter can find a short route using radio navigation facilities. It respects the different ranges of the different VORs and NDBs. It also knows that you can fly to and from radials of VORs, but only towards NDB stations.

The autorouter divides your flight into sections that usually go from one radio beacon to another one. It then shows a window listing all these sections with their respective distances and tracks. Finally, it compares the total length of the suggested route with the length of the direct connection between start and destination. If your trip is not very short, ICAO usually finds a route that has only a rather small detour. (This window isn't what we call nice. It was taken more or less directly from the Motif Version, which already was something of a fast hack.)

While the Autorouter window is open the Map window will show the route found by the Autorouter. To make your selection visible as a route again, just close the Autorouter window.

The autorouter will fail to work if the distance between beacons is too large. It does not always find the shortest possible route.

Suggest Triangle
This function should only be interesting for glider pilots. When you do a cross country flight, usually triangles that respect the FAI rules result in the best score/distance ratio. The Suggest Triangle function was created to help you finding possible triangles that have a certain length and match the FAI requirements: the shortest side of the triangle must be at least 28% of the total distance (or 25% if the total distance is more than 500km), whereas the longest side may not exceed 45%.

To use this feature, select a take-off location in the route panel and call the Suggest Triangle menu item. A panel will appear, allowing you to enter the desired total length in km. Click on the Suggest button when you have entered a range. The browser will list all the routes that have been found.

¬

Clicking on the suggested triangles will select the current waypoints in ICAO's route panel and draw the route on the map.

A double-click on a triangle will not only select that route, but also change the scale an origin of the map display to display the complete route as described under Adjust printed Map to Route in the print... section of this manual. As mentioned under Autorouter the map will always show the found autoroute if an autoroute panel is visible. Thus if you double-click on a triangle while the autoroute panel is open the map display will be adjusted to the autoroute. We're not sure wether this is a bug or a feature.

Setting Preferences

The Preferences command in the Info menu displays the Preferences panel, shown below.  The Preferences panel lets you set default values for various ICAO options.  For example, you can choose a default worldpart for loading at startup. 

¬

Most settings are selfexplanatory. If you have questions about any of the settings, please ask!

¬
Click here if you auto-launch ICAO and want it to be hidden initially.  This button has no effect if you don't auto-launch ICAO.

¬
Select the projection type here that you want ICAO to choose when a new map window opens.

¬
When ICAO starts up you can have it do nothing (that is, open no worldparts or maps), or open the default worldpart.  If you select ªLoad the Default Worldpartº you need to make sure a default worldpart is specified in the Default Worldpart portion of the panel, described below.

¬
Although you can have any number of worldparts in your ~/Library/Worldparts directory, you can specify only one as the default worldpart.  To specify a particular worldpart as the default worldpart, click Set to open an Open panel in which to select the pathname.

¬
<< add information about optimize for mono here >>

The Worldpart File

All the information that is used to display the map comes from an ASCII file called the worldpart file (in earlier Versions of ICAO it was called the world file or icaomap file). It contains object definitions of most common aviation-related objects such as airports and radio navigation facilities, but also of other ground objects that will usually be found on a pilot's map. An worldpart file is read each time you start the program.

Being an ASCII file, the worldpart file can easily be extended by anyone who'd like to contribute data to the system.  You are strongly encouraged to provide information about areas that you know - the world is by far too big to be digitized by a single person!

This chapter tries to explain what the worldpart file looks like. It uses a meta language called Backus-Naur-Form.
Very simply, it is this:

<nonterminal symbol> ::= A | B | C
Assignment: the nonterminal symbol (i.e. an identifier) is either A, B or C.

[symbol]
Refers to either what symbol is or to nothing, i.e. you may either specify symbol or not.

{symbol}
In this case, symbol may be used any number of times in a row, including zero times.

Parentheses can be used to specify precedences.

Tokens and Types
A scanner usually has a list of tokens and data types that can be recognized. They are the terminal symbols of the worldpart file language:

intlairport	airport	airport_civ_mil
airport_mil	airfield	special_airfield
heliport	heliport_amb	glider_site
hang_glider_site	parachute_jumping_site	free_balloon_site
vor	vor_dme	vortac
tacan	ndb	marker_beacon
basic_radio_facility	obstruction	group_obstruction
fired_obstruction	fired_group_obstruction	waypoint
isogone	river	lake
highway	road	village
town	ctr	cvfr
reporting_point	at	@
elev	range	frequency
alias	runway	gras
asphalt	asph	concrete
conc	out	scale (this is gracefully ignored by ICAO for NeXT)
origin	parallels	show_map
digitize	calibrate	zeromeridian

The following data types can be processed:

<float> ::= {<digit>} [.] {<digit>}
<string> ::= <alpha> {<alpha>|<digit>|.|_|-}
<latitude> ::= <digit><digit>.<digit><digit>'<digit><digit>"(N|S)
<longitude> ::= <digit><digit>[<digit>].<digit><digit>'<digit><digit>"(E|W)

Two nonterminal symbols still need to be defined:

 <alpha> ::= a | b | ... | z | A | B | ... | Z
 <digit> ::= 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9

Comments can be put anywhere in the world-file using the C-style:
/* this is a comment */

A comment can be several lines long. Comments can not, however, be nested; therefore, the following construct would cause an error:
/* anything /*comment*/ more of anything */

Whitespace characters, i.e. spaces, tabs and newlines are ignored by the scanner as long as they don't occur inside a token. The scanner is not case-sensitive, meaning that it doesn't matter whether you write airport, Airport or AIRPORT.
The only exception are strings, for they are usually used for names and IDs.

Parsing the worldpart File
With these tokens and types in mind, we can look at what the parser does when it reads through the world file:

<world-file> ::= {<line>} 

<line> ::= [<loc> [<elev>]] [<object> {<quality>}] 
	| <command>

<elev> ::= elev <float>

<loc> ::= at <location>
	| @ <location>

<location> ::= <latitude> <longitude>

<quality> ::= frequency <float>
	| runway <float> <float> <runwaytype>
	| alias <string>
	| range <float>

<runwaytype> ::= asphalt | asph
	| concrete | conc
	| gras

<object> ::= intlairport <string> {<location>}
	| airport <string> {<location>}
	| airport_mil <string>
	| airport_civ_mil <string>
	| airfield <string>
	| special_airfield <string>
	| heliport <string>
	| heliport_amb <string>
	| glider_site <string>
	| parachute_jumping_site <string>
	| free_balloon_site <string>
	| vor <string>
	| vor_dme <string>
	| vortac <string>
	| tacan <string>
	| ndb <string>
	| marker_beacon <string>
	| basic_radio_facility <string>
	| obstruction <string>
	| group_obstruction <string>
	| fired_obstruction <string>
	| fired_group_obstruction <string>
	| reporting_point <string>
	| river [<string>] {<location>}
	| lake [<string>] {<location>}
	| highway [<string>] {<location>}
	| road {<location>}
	| town [<string>] {<location>}
	| isogone <float> {<location>}
	| village <string>
	| waypoint <string>
	| ctr <string> {<location>}
	| cvfr <string> {<location>}

<command> ::= out <string>
	| scale 1:<float>
	| origin <location>
	| parallels <latitude> <latitude>
	| show_map
	| digitizer
	| calibrate <location> <location>
	| zeromeridian <longitude>

Parse Errors
If the parser thinks that something is wrong in the worldpart file it will output a parse error message and the line number that was processed. It will not tell you what precisely is wrong, but usually an error will be easy to find. Typical mistakes are prohibited characters within a string (like blanks - use underscores (_) instead), mismatched quote marks in locations etc. Look at similar object definitions in the original worldpart file and compare it with the line that's causing trouble.

License Information
ICAO is not Public Domain or Shareware. It is copyrighted software that is simply free of charge, whether it is used for private use or for business purposes.

You are encouraged to use it, distribute it and even change the source code if you think you can make better use of it that way. Distributors may ask for a fee, but it must be obvious that this fee is for the media, shipping and handling only. 

The worldpart file contains nothing but names and coordinates. Typing it all in was a lot of work, but locations of objects can hardly be something that's worth a copyright. Therefore, the worldpart file is not copyrighted but public domain.

Martin Pauly welcomes new regions added to the worldpart file. Ports to other operating systems are also appreciated, except for any Microsoft operating system or user interface other than MS-DOS 1.0, i.e. porting ICAO to the latter platforms is prohibited.

ICAO is distributed without any warranty, without even the implied warranty of merchantability or fitness for a particular purpose. The only thing Martin Pauly guarantees is that the program will occupy disk space.

The use of general descriptive names, trade names, etc., in this document, even if the former are not especially identified, is not  to be taken as a sign that such names, as understood by the Trade Marks and Merchandise Act, may accordingly be used freely by anyone.

Unless especially mentioned, ICAO in this document refers to Martin Pauly's program and has nothing to do with the International Civil Aviation Organization.

The Future

New features are planned for future versions of ICAO. Things that will definitely be included in the next NEXTSTEP releases of ICAO include:

·	an index function for the suggest triangle function that depends on the detour a pilot will have to make to avoid restricted airspace
·	evaluation of cross country flights according to DMST rules, including flights that were not completed
·	wind influence
·	enhanced route printing, including text to help pilots with their flight preparation
·	deviation support for magnetic North reference
·	more precise distance and track measuring using an elliptical model of the earth rather than a spherical one.
·	a more NeXTish environment (Drag & Drop, multiple worldpart management, etc.)
·	a kernel that is rewritten from scratch which makes use of C++ classes

Any other suggestions from your side? Then don't hesitate to tell me about it! If I like your ideas, I'll see what I can do...

Apart from program extensions, the worldpart file will be extended by me. I plan to have all airports, airfields and glider sites in Germany in it, and more detailed information from the ICAO maps 1:500,000 "Duesseldorf" and "Frankfurt". Buying all the maps for Germany every year would be a bit expensive, but if anyone likes to contribute a map, I'll try to add it to the worldpart file.

You might have the impression now that the worldpart file should only include objects from Germany. This is not the case. However, as creating a detailed worldpart file really takes a lot of time, I will not do anything but Germany myself. A future version of ICAO will include a more complex worldpart file management, but no details have been fixed yet. If you want to create worldpart files for other countries and you need help, just contact me and I'll try to help you.

Known Bugs

There are some odd things about ICAO that we did not fix before releasing this version. Most of them aren't worked on, because the ICAO kernel is being rewritten. When the new kernel is finished a lot in the internal concepts will change.

- ICAO will crash if working with mutiple maps and Suggest triangle or Autoroute panels. 
- It's not possible to print the Autoroute data from Icao, at least you can copy it to some other Application, e.g. Edit.
- The Route isn't updated if you delete an entry with backspace.

If you find more things that need to be corrected, please tell us what it is.

EMail bug reports to:

	leuker@POOL.informatik.rwth-aachen.de
or
	oliver@POOL.informatik.rwth-aachen.de
	
Nextmail is okay, but slow.