gpsLog.m version 01Jul23
(Analysis of GPS data)

File format

The first step in using gpsLog.m to analyze your GPS data is to convert your data into the format that gpsLog will accept which is known as universal csv (comma separated variables). This is a simple text-based format where the first line of text contains a list of the data fields and each of the remaining lines contains the data for a single location. Take a look at the gpsLog.csv file created by this application (in the plt\ini folder) to gain an understanding of the basic idea behind this format. (You don't need to understand the details of the universal csv file format to use this application since GPSBabel handles the details for you.)

If your GPS receiver creates a log file using this format, you are good to go, but more often you will need to convert your log file to the universal csv format. Fortunately, there is a free application called GPSBabel which can do this job for you (and runs on Windows, Mac, or Linux computers).

You can downloads this application from their website: gpsbabel.org. It converts data from about 60 different formats which covers most GPS receivers and applications.

In the example shown here, the data from the GPS receiver was in NMEA format, so that format was selected in the popup menu at the top. Be sure to check the "Tracks" checkbox and then select "Universal csv" for the output format and type in the file name and path where you want to save the result ... then click OK and GPSBabel will do the rest. If you are converting dozens of files, you may find the command line interface more convenient.
When you look at the csv output from GPSBabel you may see a dozen or so fields listed in the header, but gpsLog only uses these six fields:

latitude in degrees - for example 37.456182
longitude in degrees - for example -122.112418
time hh:mm:sec - for example 13:59:59 or 13:59:59.999 if milliseconds are included
elevation in meters (the heading 'altitude' is accepted as an alternative to 'elevation')
course in degrees (true)
speed in meters per second

Only the first three characters of the field name are used, so for example, the elevation field could be specified as 'ele' or 'alt'. These fields may appear in any order. gpsLog determines the order of the data in each line from the order the field names appear in the header line. Latitude and longitude are required fields and the remaining 4 fields are optional. If the time field is not included, gpsLog will assume the first data point is at 00:00:00, the second data point is at 00:00:01, and so on (i.e. a one-second data rate). If the elevation field is missing, an elevation of zero is assumed.

Calling sequence:   gpsLog filename Let's first assume we start the application by simply typing gpsLog (i.e. no arguments):

This figure (referred to as the speed & elevation chart) as well as the figure below (referred to as the position chart) is what you will see if you start the application with no arguments. (Assuming you have not modified the gpsLog.csv file).

The blue text on this plot, as well as the blue and orange text on the other plot contain some simple help messages to get a new user started, even if they haven't had the time to read this document. This help text only appears when you have loaded the default csv file (gpsLog.cvs). To avoid clutter, the help text disappears as soon as you click inside the plot area. Right clicking on the Help tag in the menu box toggles the help text on or off.

The first trace (TraceID = Alt) in green shows the altitude in meters. Here the cursor has been placed on the altitude trace near the 12-and-a-half minute mark of the log file. You can see in the X cursor edit box that the exact cursor location is 12.69692 minutes after the start of the log file (which was 19:50:30 Zulu time, as specified in the X axis label). You will often want to know the exact time associated with the cursored location. You could of course compute it by adding 12.69692 minutes to the log start time, but this has already been done for you, and you can see the result to the nearest millisecond (20:03:11.815 Z) on the text box below the plot in the other figure (the position plot shown below).

The next trace (purple) shows the speed in meters/sec and its TraceID is "sCalc" which reminds us that this speed has been calculated from the position and time information in the csv file. If successive points are close together, this speed calculation will be somewhat noisy, so before being plotted, it is passed thru a simple six-point moving average filter (by default). The length of the moving average filter is identified by the Avg edit box in the upper left corner of the figure. Click on the "6" slightly to the right of the number to increase this value, and click slightly to the left to decrease the number. If you decrease it to "0", then the raw data will be plotted (i.e. no filtering).

The next trace (red) also shows speed and its TraceID is "sFile" which reminds us that this speed value has been read from the CSV input file. You don't see the red trace in this example because the default gpsLog.csv file does not have a column for speed. Whether this column exists or not will depend on the GPS receiver you used and the application used to record the data. Sometimes speed is reported and sometimes not. (Note that the "sFile" TraceID is in italics. This indicates the trace has been turned off.) The GPS receiver computes speed in a somewhat similar way as we do for the sCalc trace however it has the potential to be more accurate. There are two reasons for that. The first is that a GPS receiver usually uses a Kalman filter which is more sophisticated than the moving average filter used here and that filter is likely tuned to be optimal for the application the receiver was designed for. The second reason is that in good signal conditions, the receiver can make use of doppler information derived from the GPS signal to improve the speed calculation.

The top plot (in cyan) shows the True Course. As with the sCalc trace, this is also calculated from successive position points and also filtered with the same moving average filter. As you change the length of the moving average filter, you can observe its effect on the true course plot. If a portion of the track has a heading that is close to zero or 360 degrees, the display may look noisy as the course bounces back and forth between a course of 1 degree and a course of 359 degrees (for example). Even though the trace may look noisy in that situation, it doesn't indicate that the data is poor in that region.

The two Yaxis edit boxes to the right of the "y" label show the Y cursor readout for the lower and upper plots. The right one (cyan) reads out the cursor value of the upper plot (true course). The left one (green) shows the altitude, but it will change show the speed (and change to purple) when you click on the purple speed trace. (This is the usual arrangement that plt uses for subplot cursors.) One drawback of this cursor style is that you can't see readouts for the altitude and speed at the same time. For that reason, the function of the lower plot Yaxis edit box is essentially duplicated by the green and purple text below the Xaxis label. They show the altitude and calculated speed for the cursored position respectively. Another use of these green and purple text items is that they allow you to change units by clicking on them. Clicking on the green text alternates between the five allowed altitude units (meters, kilometers, feet, thousands of feet, and miles). Clicking on the purple text alternates between the five allowed speed units (meters/sec, km/hour, knots, miles per hour, and feet/sec.) The left and right axis labels and limits will be adjusted to reflect your unit choices. Once you set your preferred units, those units will remain in effect as you move the cursor around.

The csv log file may also include a column for the course calculated by the GPS receiver. In that situation, the upper plot will include an additional trace (in red) to show that data, and an additional TraceID box will appear on the right side of the plot allowing to select which of the two traces you would like the cursor to follow. You don't see it here because the default csv file does not include course data. An example will be shown later so you can see what the additional traces for file data (speed & course) look like.



This is the second of the two figures (the position chart) that appears when you start the application. As mentioned above, the orange and blue help text on the plot disappears as soon as you click in the plot area and as before, right clicking on the Help tag in the menu box toggles the help text on or off.

The GPS track contained in the csv file fills the entire area of the position plot. This allows you to see the most detail but it doesn't show you the true shape of the plot because the aspect ratio is not 1. (i.e. a square course may look like a rectangle and a circular course may look like an ellipse. If you want to see the true shape, LEFT click on the "Aspect" button below the plot and the axis limits will be adjusted to produce an aspect ratio of 1 (i.e. a square or circular course will actually look like a square or a circle.) The axis limits can be restored to what they were before you clicked the Aspect button by RIGHT clicking on the same button. This is a multi-level undo, and if you RIGHT click one more time after all the LEFT clicks have been undone, the axis limits will be restored to the values they were when the application first started.

The latitude/longitude/time associated with the position marked by the large yellow cursor is shown in the box next to the Xaxis cursor edit box near the lower edge of the figure and we can also see that this is the 377th point recorded in the GPS file (near the Yaxis cursor edit box). And since the cursors between the two figures are always linked, we can see that the elevation, speed, and course associated with this point are 80.68 meters, 5.795 meters/sec, and 217.8 degrees. To move the cursor, we can simply click on the part of the plot we are interested in using either figure. Or sometimes it is more useful to move the cursor forward or backward one sample at a time. To do this left or right click on the X axis label. (This works in either figure). After the click, you can hold down the mouse button while you watch the cursor continue to move forward or backward in time.

If the position markers are far apart, it can be useful to see a solid line linking the markers. To do this, click on the "o" button in the lower-left corner of the figure. Click on it a second time to show the track as a solid line without the markers. (That's the most useful mode to see as much detail as possible when there are so many sample points in the file that the markers start to overlap.) Click on it a third time to return to the markers-only display.

If you zoom into a portion of the speed/elevation chart, then the position chart will no longer show the whole track. It will only show the portion of the track that is within the time limits shown on the x-axis of the speed/elevation chart. This is usually useful, but occasionally you may want to see the complete route even when the speed/elevation chart is showing just a portion of the data. To do this, simply check the "allPoints" checkbox.



Suppose we now click the "kmz" button in the speed/elevation chart (without changing any of the parameters in the kmz box). This will create a file with the same name and in the same folder as the .csv data file except that the .csv extension is changed to .kmz. The kmz button will flash off and on briefly to give you some visual feedback that the kmz file was written. kmz is the native format for Google Maps or Google Earth, so you can easily import this file into either of those applications. You won't be able to cursor the data points as precisely and as easily as with the position chart described above, however, the big advantage with Google Maps or Google Earth is that you can see the route in context (roads, terrain, etc.)

This screen capture of Google Maps shows a small portion of the route contained in the default gpsLog.csv file used above. The route is shown with a thin solid white line superimposed with yellow dashes. The yellow dashes help make the trace more visible and also allow you to see where the GPS data points are. (There are always GPS data points at both ends of each yellow dash.)

You can change the width of both the solid line and the dashes in the kmz box. The defaults are widths of 2 and 6 for the solid and dashed lines respectively. You can change these widths to any value between 1 and 9 to suit your taste. You can also change the colors used for the solid and dashed line which is especially useful when you are comparing two or more similar tracks recorded at different times, or recorded at the same time by two different GPS receivers. For example, to change the color of the yellow dashes, click on the yellow bar in the kmz box and you will see a new figure that you can use for making the new color selection. (If you are not clear on how to use this color selection box, see the ColorPick section of the help system.)

You may also disable either the solid line or the dashed line by assigning a width of zero to the respective track. If you prefer to have a compact kmz file, the kmz file size will be much smaller when you assign a width of zero to the dashed track.

If instead of left clicking on the kmz button, you right click on it instead, then a kml file will be created instead of a kmz file. A kml file is essentially the same as a kmz except that it is not compressed. Since the kml file is larger, you will rarely want to use that format, but kml is best if you later want to edit it with a text editor. (You can't open a kmz file with a text editor). Google Earth and Google Maps natively support both kmz and kml files. You can also convert between kmz and kml files using a zip compressor or extractor.

Instead of using the kmz button, you could create a kml file directly from your original GPS data file by converting it to kml format using GPSBabel. However, that approach has several disadvantages:
• You won't have the option of producing both the solid and dashed tracks of the type shown in this picture. (I've found that style to be generally the most useful.)
• Using the kmz button allows you to select the portion of the track that you want to be included in the kmz by zooming and panning the altitude/speed plot. GPSBabel always includes the entire data set.
• GPSBabel doesn't support .kmz directly (although you can manually zip the kml to create a kmz file).
• With GPSBabel you would have to enter the desired track color using 6 hex digits instead of selecting the color more naturally from a color palette.


Now let's load a more complicated .csv file to demonstrate some additional features of gpsLog.m. This data was collected during a 57-minute flight traveling 142 statue miles, taking off from Mariposa Yosemite airport in California and landing at Palo Alto airport. The data was saved in NMEA format which was the native format of the panel-mounted GPS receiver. GPSBabel was used to convert this data to the universal comma-separated variable format that can be read by gpsLog.m. This csv file contains the same columns as the previous file used above (gpsLog.csv) plus these three additional columns:
date: The date associated the first data point in the file is included in the figure name, following the csv file name.
speed: This column contains the ground speed computed by the GPS receiver (in meters/sec) and is plotted by the third trace in red (sFile) of the lower plot. The plots above did not include this third trace since no speed data was included in the data file. As before speed is still calculated from the lat/lon data and plotted by the 2nd trace in purple (sCalc). At this scale, the red and purple traces look pretty much the same, but zooming in will show that there are differences because of the different way that speed is calculated.
course:This column contains the true course computed by the GPS receiver and is plotted in red on the upper plot. As before, course is still calculated from the lat/lon data and plotted in cyan. In this case, the two course traces are so similar that one or the other of the traces is not visible, being covered up by the other. Still, if you zoom in far enough, differences will be noticeable.
Often there will be several additional columns (such as fix number, fix type, HDOP, and more), but those columns are ignored by gpsLog.m.

From the true course shown in the upper plot, we can observe that after the first 4 minutes the flight heads westbound (approximately 270°) and remains that way until the last eight minutes of the flight - that is except for the noticeable 6-minute deviation starting about 16 minutes into the flight. In that section, the true course curve shows a series of steps separated by about 90 degrees. This is a square course segment which will become more obvious when we look at the position chart below.

The cursored position is 10.583 minutes into the flight (from the Xaxis cursor edit box). The time at that point is 12:51:06 Z which we can read from the position plot. The Z is an abbreviation for "Zulu" time which is also known as GMT (Greenwich Mean Time) or UTC (Coordinated Universal Time). The altitude at this point is 7968.8 feet as indicated by the green text below the Xaxis label. (We clicked on this green text to select "feet" as our preferred altitude unit.) Below that we see that the speed calculated from the lat/lon/time data is 116.82 knots and the 117.99 value (in red and surrounded by parentheses) is the speed data included inside the csv file. (We clicked on this purple/red text to select knots as our preferred speed unit.)

The true course (calculated) at the cursored point is 273.53° (from the second Yaxis edit box). We know that this is a calculated value because both the cursor and the edit box are cyan which matches the color of the "Calc traceID shown in the traceID box to the right of the upper plot. Although it wouldn't make much difference in this case since the two traces are so similar, but if you wanted to readout the values of the course data from the file, simply click anywhere in the traceID box to the right of the upper plot. Then the next time you move the cursor, the cursor marker and the Yaxis edit box will turn red indicating that the edit box is now displaying the course data from the file.


The Aspect button has been pressed so that the track shows the true shape of the track. Then the axis was panned so the track was in the lower portion of the plot (just so I could make a smaller screen capture here). The cursor is always linked to the other figure, so we know the large yellow cursor is at the 10.583-minute mark. We can see that this is the 128th data point in the file and that the path length since the beginning of the flight is 18.134 miles. (We clicked on the path length string to select miles as the preferred unit for this readout.)

The markers have been removed from the track by clicking on the "o" button. This allows us to see more detail because the data points in this view are so close together that those markers would overlap, obscuring some of the detail.


Now let's expand the x-axis of the speed/altitude plot to focus on the square loop portion of the flight. Perhaps the easiest way to do that is by using the xView slider above the true course plot. The black bar spanning the plot width represents the entire x-axis range of the data and the size and position of the smaller gray bar represent the portion of this range that is currently displayed. If you grab this gray bar near the middle and slide it back and forth, the speed/altitude plot will continually update to show the selected region and the position plot will be continually updated to show only the data points it that range. More details on how to use the xView slider can be found near the end of the here in the Zooming and panning Section.

You might guess that the reason for flying this square path was for sightseeing, but actually the purpose was for making a precise estimate of airspeed. For this measurement, it's important to keep the altitude constant. By zooming into a small altitude range, we can see that I didn't quite manage this, losing about 40 feet during the circuit. However, that deviation is small enough that it wouldn't invalidate the measurement.

The xView slider in the plot above was adjusted until the position plot included only GPS samples acquired while flying the square path. Markers were enabled again from the "o" button since we are now only displaying a much smaller set of positions. Then I clicked on the "TAS" tag at the bottom of the menu box at the left edge of the figure. In response to that click, the true airspeed and the wind velocity is calculated from this portion of the GPS data with the results displayed next to the Xaxis edit box at the bottom of the figure. (This area is normally used to display the latitude/longitude/time associated with the cursor position.) Since the results of this calculation are used by the airspeed.m application, the calculation is described in more detail in the here in the airspeed.m help section.


If you want to see the climb profile for this flight, click on the "Climb" tag at the bottom of the menu box on the speed/elevation plot. This will create a new figure such as this one.

The cursor is on the point 37 minutes into the flight and is showing that at that point the descent rate was 236 ft/min and the descent angle was 0.926 degrees.

The same moving average filter (length 6 in this example) that was chosen for the speed and course calculations is also used to filter the climb rate and climb angle to make these plots less noisy.

Now let's create a kmz file so we can view the flight in Google Earth Pro. First, we click on the "2" (the default track width for the solid track) and select "2e" from the popup menu. The "2" still refers to the track width and the "e" stands for "extrude" which indicates we want to see lines added that project the 3D locations down to the surface. As we will see below, this will make it easier to visualize the flight path.

Here is an overview of the entire flight. This is a low-resolution thumbnail image. Click on the thumbnail to see the full-resolution image. (All the remaining images below are also clickable thumbnails.)

Here we have zoomed in to the takeoff and early climbout portion of the flight. Note how the extrusion lines make it easier to visualize the flight path. (If we zoom in even more, we can view the taxiing movement before takeoff.)

This image shows the landing phase of the flight. I haven't shown it here, but Google Earth also gives you the option to show the elevation profile below the flight track. And as with the gpsLog application, Google Earth links the cursors so when you point to a spot on the elevation profile, the corresponding track location is identified.

The default white/yellow colors for the solid/dashed track are great for Google Earth or other satellite views, but a darker scheme such as this one will be easier to see on Google Maps in its default mapping mode. The solid color is green at 50% intensity and the dashed color is blue at 100% intensity. Of course, the colors and intensities you prefer will depend on your taste, which is why these selections and the colorpick menu are provided.

Here is the overall flight path shown in Google Maps using the color scheme described above. Remember to click on these thumbnails to view the full-resolution images.

And again we zoom in on the beginning and end of the path to see the takeoff and landing phases in more detail.

I have demonstrated using this application with flight data, but you will find it just as useful to analyze your motion over the earth during your favorite activities, no matter the medium (sky, sea, dirt, ice, roads, mountains, etc.)


Copyright © 2023
Paul Mennen