Document: AGIS Real Time GPS position display design.

Written: R.D.Pask robertpask@compuserve.com ( robertpask@csi.com) 25 August 2001 ,
                  Updated 6 October 2001.

Purpose: This text is written in response to question 65 posted on the yahoo groups site for AGIS.

AGIS Real Time Position Display Design Notes:

With the addition of a wrapper application to manage the GPS interface, AGIS definitely has the capability to display the current position from a GPS receiver in real time using AGIS's integrated messaging and script mechanisms.

Existing application using AGIS script and messaging functions - "Track Edit"

"Track Edit" is an experimental C++ application that has used AGIS's script and Windows messaging interface to generate maps automatically from a GPS track log. AGIS provides the capability to modify the look and feel of a map by the end user and also allows additional data to be displayed very easily. "Track Edit" adds aviation data including navigation aids and runways to the basic world data provided with AGIS. "Track Edit" presents the user with different views of the GPS data - raw data in a table, point data in a dialog, a speed plot and finally an AGIS generated bitmap. By using the mouse as a pointer the user can click on the speed plot, or the table of raw data and the selected point is displayed on the AGIS map as an aircraft symbol. The user can change the colour of the segments of the track and then zoom into to the specified segments using a single toolbar button. The map is created by AGIS running a script in background in minimised mode. "Track Edit" communicates with AGIS through an interface file, a data file, and the registered windows messages AGIS_OK and AGIS_CONTINUE. The interface file, created by "Track Edit" holds a command word, the centre and scale of the map to display. The data file stores the latitude, longitude and heading for a symbol to show the selected track point position.

Figure 1 - "Track Edit" Application displaying AGIS Map

Real Time GPS position system high level architecture

Based on the experience building "Track Edit" a potential high level architecture for displaying a real time GPS position is shown in Figure 2.

Figure 2 - Application basic architecture

AGIS GPS display application functions

At a high level an application to achieve a real time display of current position might include the following functions:

  1. Initialisation
    a) Start AGIS running script - See below
    b) Write Initial Data file to display point.
  2. A GPS message parser to extract Latitude and Longitude in real time from the GPS probably using NMEA protocol that is common to most GPS's.
  3. Calculate map scale and centre position based on current GPS position.
  4. Write the following data into an interface file, e.g. AGIS.aif (AGIS interface file)
    in AGIS directory:
    a) Command
    ii)Redraw (following data new data receipt)
    iii) Re-centre map and re-scale then redraw
    b) Symbol Type
    c) Symbol Latitude and Longitude (degrees)
    d) Map Centre Latitude and Longitude. (Degrees)
    e) Map Scale
  5. Send the registered AGIS_OK windows message.
  6. Return to 2.

AGIS Script

For the above application AGIS would run a script after being started either independently or from within
the application during initialisation.

Based on the Script that AGIS runs for the experimental application "Track Edit" the following script
operations would display a symbol on a map at the current GPS position saved in an interface file .

Script Function:

  1. Declares variables for interface file parameter storage
  2. Sends AGIS_OK to application (to inform that AGIS has started).
  3. Opens interface file and writes first values (0's)
  4. Load the AGIS map file.
  5. Waits for AGIS_CONTINUE signal
  6. Reads interface file using read line into variables.
  7. Closes Interface file
  8. Read command from interface file (Exit, Redraw map, Redraw and
    change map scale/ centre position)
  9. If exit - Exit
  10. If Redraw - re-draw map
  11. If re-draw and Centre/Scale - change Centre/Scale and redraw
  12. Changes Map co-ordinates if required.
  13. Go back to 5

The actual script file used in "Track Edit" application is trackedit18.acf

AGIS Map File

The Map that AGIS loads needs to include the data file written to by function 4 in the application.

AGIS Interface File

The interface file is a simple flat text file this read by the AGIS script operation readline. The "Track Edit" interface files "trackedit.aif" used by script "trackedit18.acf" contains the following data:

\Program Files\JTSystems\Agis\Maps\aDisplayMap

The parameters on separate lines are used for the following.:

Parameter Value

Interface Function

4 Command
\Program Files\JTSystems\Agis\Maps\aDisplayMap Map File
display Save Bit Map Name
1 Symbol
-74.2021891 Longitude
45.4061117 Latitude
4 Heading
-73.9941447 Centre Longitude
45.5826416 Centre latitude
454526 Map Scale

Table 2 - Interface File contents.

In the "Track Edit" application the interface file parameters update the displayed map in different ways depending on the command word. And not all parameters are used at this time.

SYMBOL Data File

The file "symbol.dat" holds the longitude, latitude, symbol type and heading for the displayed symbol.

This file is in AGIS "dat" format and for "Track Edit" this is a single line of plain text created by the AGIS script. This file is added to AGIS map data layers.

Example file "symbol.dat".

" -74.0848551 45.3448324 1 248"

NMEA Parse Routine

The "Track Edit" application does not have a NMEA parse routine because it is designed to download the stored tracklog from a Garmin 90 using the GARMIN/GARMIN protocol. This download function was written as a separate application that is invoked from "Track Edit" and was found to be quite a challenge in C++ because it uses two threads, one to service serial port interrupts and receive characters, the other to format the characters received from the GPS into a Garmin Track Log file. The code however could be adapted to filter NMEA messages for current latitude and longitude, heading and status.

Displaying a Track History

Displaying a track history is also possible by adding a function to add position updates to an AGIS "dat" file in a similar way to the AGIS animation application. The track history trail will appear as point symbols on the map defined by the user in AGIS's map data layer set-up.

Displaying a track history in real time with AGIS, as a continuous line,  will be a little tricky as the track log points that form a line can only be display as a map layer (mpb). This requires the file holding the track log to be in AGIS "mpb" format that is proprietary to AGIS. The only conversion utility I have currently had time to use ,or build, is the dos based "extract.exe" available from AGIS. Running "extract" from a Window's application is a little messy as it covers the application with a dos window while it executes. What is required is a Windows DLL or application that runs minimised to help the overall user interface look and feel. My experimental application writes the track log points to an AGIS "mpa" data file and then executes "extract.exe" to create the "mpb" file for display on the map file.


AGIS has the capability to display GPS position in real time. "Track Edit" is an application that uses AGIS's Windows messaging and script file capabilities to generate bitmap files displaying a symbol at a specific latitude and longitude and orientated along the track path. "Track Edit" has many of the building blocks required to build a background application for AGIS to display current GPS position. "Track Edit" is an experimental application but specific C++ code examples for algorithms, e.g. Centre Position and Scale calculations, spawning AGIS with script, etc. could be provided on request under a co-operative development agreement. The main effort in building the application will be to write the position data extraction code for GPS NMEA position and status strings.



Copyright 2001 - R.D.Pask 25 August 2001.