Help

GPSFileViewer Help

Overview

Desktop application for browsing and visualizing GPS files on your hard drive or network.

• Browse GPS files (gpx, kml, csv) by directory using embedded file/track/metadata browser
• Show overview map of all tracks in directory. Tracks can be color coded based on metadata, e.g., distance, duration.
• Filter tracks in browser based on metadata, location, and path.
• Use Path Filters to find tracks that traverse a series of locations, for instance, to compare different routes.
• Simultaneously view tracks on map while graphing metadata (e.g., speed, elevation, hill gradient)
• Interactive display of distance and duration for selected portions of tracks

---

Table of Contents

• Installation
• Launching
  • Some Quick Notes
  • Track Overview
  • Moving Around in Map View
• Selecting Units (English/Metric)
• Filtering tracks
  • Geographic Filtering
• Color Coding Track Overviews
• Showing Individual Track Details
• Distances and Times within a Track
• Additional Features and Tips
  • Track Pre-Processing
  • Quick Subdirectory Switching
  • Path Filters
  • Managing Path Filters
  • Working with a selected filter
  • Exporting data
  • Track Display Color Coding
  • Graph-Map options in the UI
  • Secondary Graph Options
  • Time Zones
  • Overview Options
  • Showing Coordinates
• Acknowledgements
• Cutting room floor

---

(top) ↑

Installation

GPSFileViewer (GFV) is distributed as a zip file. Simply unzip the file to the directory of your choice.

Mac at this time requires running the python source files, which requires python 2.x (x >=7) and the following packages to be installed:

• wxPython, at least v3.0
• matplotlib, at least v1.3.1

(top) ↑

Launching

Windows: From the installation directory, run app/gpsfileviewer.exe.

Mac: From the installation directory, go to the script directory and click gpsfileviewer.command

Launching GFV brings up a set of sample gps files that comes with the application (located in the sample_gps subdirectory). The left side is a map that shows tracks and the right side is a track browser. Initially, you'll see only file-based metadata in the track browser.

note: GFV shows tracks by file directory. Selecting another directory shows any GPS files in that directory. csv, kml, and gpx formats are currently supported.

Click the "Load files" button at the top of the application window to read the files in and generate more detailed metadata. Loading files also shows a map overview of the tracks. Once loaded, you should see something like the image below.

note: The "Load Files" button caches the GPS data on your hard drive (the app/gps_cache subdirectory), so you only have to click it once for each directory.

(top) ↑

Some Quick Notes

• 24-hour time is used throughout GFV. AM/PM is not implemented in this version.
• For customizing GFV, there is a user-modifiable config file. See gpsfileviewer.cfg in gpsfileviewer's app directory. Additional documentation on config settings is provided within that file.

(top) ↑

Track Overview

After loading the files, you see GPS-specific metadata fields and an overview of all tracks on the map. The 'name' field is the either the track name or if there's none, the file name. For files that contain more than one track, the track number is appended to the file name.

The tracks are shown on the map as brown lines (config file: map.overview.solid_line_color). The tracks are semi-transparent so you can see when mulitple track overlap.

(top) ↑

Moving Around in Map View

Zoom and pan the map using any of the following:

• Drag with the mouse to pan
• The zoom tool at the bottom of the window:
• Shift click the "Auto" checkbox () to zoom the map to fit all tracks
• Keyboard shortcuts "+" and "-" to zoom in and out
• Double left-click within the map to zoom in, double right-click to zoom out
• Single-click on a track in the map and the browser and map will show only those tracks that go through that point.

(top) ↑

Selecting Units (English/Metric)

You can select between meters/kilometers and feet/miles by selecting from in the configuration row. Make sure the configuration row is vzvisible by clicking the button at the top of the window.

(top) ↑

Filtering tracks

There are several tools you can use to select which tracks are shown on the overview map and the track list. The filter row is on the right side of the window:

Click one or more of these toggle buttons to open up and use that type of filter. The following filters are available:

• Duration: Enter a minimum and/or maximum duration (minutes) for tracks
• Distance: Enter a minimum and/or maximum distance (miles or km, depending the units selected) for tracks
• Path: Select path filters and use them to filter tracks that traverse through a specific set of points. Help for creating and editing path filters is here.
• Start Hour: Select tracks that begin over a range of hours during the day. Select an hour where the window starts and the duration of the window. For instance to show only tracks starting in the early morning (e.g., between 6 am and 8 am), choose
• Filename: You can filter based on filename. Filter terms are not case sensitive and partial words are matched. You can filter filenames using Python-style regular expressions by prefixing your search with a forward slash.

A filter is only active when its toggle button is clicked and its data entry row is shown. You can apply multiple filters at the same time by opening them up.

The filters are modifiable and expandable. See config file: filelist.filter_functions.

(top) ↑

Geographic Filtering

In addition to the above buttons, you can filter tracks geographically using either of the following two approaches:

• Clicked Map Location: Single-clicking near a track on the map and track browser shows only those tracks that pass near the clicked point.
• Zoom via Box Select If you shift-drag on the map (creating a box on the map), the map and track browser show only those tracks that pass within the box and the map zooms to show only those tracks.

To reset geographic filtering, click the overview reset button () on the right side of the filter row. Toggling one of the other filter buttons also resets geographic filtering.

(top) ↑

Color Coding Track Overviews

The Pallete button () allows you to color code tracks based on summary metadata. Colors are applied to both the track list row backgrounds and track color on the map. The palette button is to the right of the row of filter buttons.

You can select metadata (distance, duration, day of week, etc.) and what color scheme is used to color the tracks. The legend (to the right of the parameter/color selectors) shows the resulting color coding.

The above example shows tracks color coded by distance and sorted by distance in the track browser.

(top) ↑

Showing Individual Track Details

Show an individual track by clicking on a row in the track list. The selected track is shown via a color-coded track on the map and a graph of the attribute selected in the 'Param:' dropdown directly beneath the map.

Select multiple rows in the track list, either by shift- or control-selecting with your mouse. Alternatively, you can select additional tracks via keyboard using shift- or control- with the up or down arrow. Additional tracks are shown, shifted in the map from the first track (to minimize overlaps). The amount of shift can be changed (config file: map.multitrack_offset_pixels)

The graph and track above are color coded according to speed . The color style Grn-Ylw-Red shows the slowest speeds as red, speeds near the midrange in yellow, and highest speeds in green. Other 3-color styles (e.g., Blue-White-Red) behave similarly.

Within the graph, zoom and pan using the tools at the bottom of the window: . Additional help is provided in tooltips.

As you pan and zoom in the map, the graph horizontal limits automatically adjust to show the part of the track visible in the map. You can disable this by deselcting the Sync Map and Graph Bounds option (see below).

(top) ↑

Distances and Times within a Track

Get the time and distance of a map point by moving the mouse within the graph area. The point on the map is shown as a dot and the time associated with that location and the graphed value(s) are shown in the status bar.

The time shown in the status bar will be elapsed time (from track start) if the "elapsed" checkbox is checked; otherwise it will show the local time.

To show distance and time for a portion of the selected track, click the mouse within the graph and drag left or right. Doing this highlights that segment on the track and shows its duration and distance in the status bar.

For the example above, click a track in the track list, then move the mouse in the graph area to where you want to start measuring (a dot will appear on the track corresponding to the time on the graph). As you drag the mouse, the dot turns into a line and summary time/distance of the segment is shown in the status bar.

---

(top) ↑

Additional Features and Tips

(top) ↑

Track Pre-Processing

GFV does the following things to the GPS files as it reads and caches them:

• Smartly* reduce the number of points for performance reasons (config file: map.overview.simplify_dist for the overview and gps.max_simplify_distance_m, gps.smooth, and gps.reduce_points_distance_m for individual track display)
  * uses Ramer-Douglas-Peucker algorithm
• Automatically split tracks into segments when there's a rest at a location (default is 5 minutes; config file: gps.min_gap_to_autosplit_tracks_sec). To see individual segments in the track browser, select in the config row (ensure config row is visible via the button at the top of the window).
• Removes tracks with 3 or fewer points (Config file: gps.min_track_segment_points).
• For tracks that do not include timestamps for each point, GFV adds dummy timestamps to allow the rest of the GFV functions to work. In the track display, this is denoted with a track name prefix of <no_time>
  

(top) ↑

Quick Subdirectory Switching

If you've organized your GPS files into related subdirectories (e.g., each year in its own subdirectory), GFV allows you to quickly switch between them. Clicking the subfolder button () shows a dropdown list containing the folder's subdirectories. Change subdirectories by selecting one of them in the dropdown.

A special directory called <All> is available in the subdirectory list. Choosing this causes all gps files in all subdirectories to be loaded into the track browser. Note: this may take additional time to load the files, and additional time to create the track overview. You can speed up the overview by disabling the map overview. Do this by toggling the overview () button.

(top) ↑

Path Filters

The path filter is in the filter row () on the right side of the window. Turn on path filtering by clicking the "Path" toggle button. Selecting a path filter causes only tracks that traverse the corresponding points to show in the track browser.

You can create and edit path filters by clicking on the edit button in the path filter selector row (). When you do that, the path filter editor is shown:

While a path filter is selected, the filter's numbered points are shown on the map. Each path filter point has as associated radius. This allows path testing to tolerate inexact matches, or allow considerations of areas (e.g. path passes near an intersection or around a city).

On the map, this radius is shown as a shaded red disc around the filter point. Depending on the radius, the ring and shaded area may be too small to see on a zoomed-out map. Zoom in to see it.

If you check "Trim to path limits", only the portion of a track between the path filter points is shown in the results. If unchecked, then entire track is shown.

(top) ↑

Managing Path Filters

• Create a new path filter by clicking the new () button
• Copy an existing filter by clicking the copy () button.
• Rename a filter by editing the Name box on the left.
• Delete the filter by clicking on the on the right side.

(top) ↑

Working with a selected filter

• Changing a filter's type by selecting betwen values in the dropdown list on the right.
  • Ordered: A track must traverse each point in order (1, then 2, then 3, etc.)
  • All: A track must traverse all points; order doesn't matter.
  • Any: A track can pass through any one or more points
• Add points to the filter by panning and zooming the map to where you want and control-clicking on the map.
• Insert points by clicking an existing filter point on the map or a row in the path filter point list (the numbered list in the center of the path filter edtor), then control-clicking on the map.
• Reposition filter points by dragging them in the map.
• Remove a point from the filter by clicking on a point on the map (or selecting a row in the point list above) and hitting the backspace or delete key.
• Change a point's radius Each path filter point has an associated circle-- if a track goes within the circle, it passes the filter. Change a point's radius by dragging the outer ring in or out.
• Temporaily disable filtering While editing a path filter, you can temporarily turn off filtering by clicking . This shows overview of all tracks which may make it easier to see where to place path filter points.

(top) ↑

Exporting data

Export data to your system's clipboard by clicking on the icon at the top of the application window. You can then paste the data into your favorite application.

You can export the following:

• Map as image Copies current map view to clipboard as image
• Track Data as Table Copy currently selected track(s) as a tab-separated list of lat, lon, elevation, and time for each track point.
• Graph as Image Copy the graph of the currently selected track(s) as an image.
• Graph Data as Table Copy x-y data in current graph as tab-separated list of x-y values.
• Table Data Copy values from track browser table as tab-separated list

(top) ↑

Track Display Color Coding

You can color points within a track. The controls for doing this are between the graph and map areas.

Select a parameter, e.g., distance, speed, elevation) and a color scheme. In addition to these basic parameters, the following parameters are available:

• Gradient % Shows slope (ascending = positive, descending = negative)
• Vertical Climb Shows accumulated positive elevation gain (feet or meters, depending on units system)
• Elapsed10 Shows distance covered (horizontal axis) for each 10 minutes of the track. Graph wraps top-to-bottom after each 10 minutes. Vertical gaps are pauses in time. Shallower slopes indicate higher speeds while steeper slopes indicate slower speeds.
• Elapsed60 Same as Elapsed10, except graph wraps top-to-bottom after each hour.

In addition to several gradient color schemes (such as Copper above), the following schemes may helpful in certain situations:

• Three-Color Gradient Three color scheme (Blue-White-Red, Blue-Black-Red, Red-Ylw-Grn, etc.) shows low values in the first color, values near the midpoint in the second color, and high values in the third color. This makes it easy to see above- and below-average values in a track.
  For example, when the gradient parameter is plotted with this color scheme, the first color means downhill, second color means (approximately) level, and third color means uphill.
• Solid Scheme The Solid scheme simply shows each selected track in a different solid color. This allows you to distinguish tracks and graph lines when multiple tracks are selected. Colors can be changed in the config file: see the solid entry within cmap.custom_cmaps.
• Banded Schemes These schemes stack multiple gradients on top of each other. For instance, if you plot speed of a track, set the Y-limits to 0-30, and then select the "3 bands, RGB" scheme, Red denotes speeds of 0-10, Green 10-20, and Blue 20-30. Within each band, darker shades are slower, lighter shades are faster. You get similar results choosing the 4- or 5- band scheme with a Y range divisible by 4 or 5 respectively.

(top) ↑

Graph-Map options in the UI

In addition to the above color coding, the following options are available in the configuration area between the map and graph:

• Click the 'hires' toggle button to show tracks in full (original) resolution in both the map and graph. Hires data is not cached and the data reduction described above for cached data is not done. Click the toggle button again to turn off hires mode.
  Note: while hires is clicked, each file is read in anew each time it is plotted, so performance will be a little slower.
• You can enter specific numbers to fix the Y limits for the graph and for the color scheme. Enter (low) - (high) in the textbox, with each being optional. For example, entering -10-30 sets the lower limit to -10 and the upper limit to 30, while entering -30- sets the lower limit to -30 and allows the upper limit to be set by the data.

(top) ↑

Secondary Graph Options

Click the button on the left of the graph-map config area to show secondary display options.

• Elapsed When selected, the time axis of the graph shows time elapsed from the beginning of the track. If this option is unchecked, the local time at the GPS location is shown (see note on local time calculation).
• Smooth Graph Values > 1 cause graph values to be increasingly smoothed. A median smoothing algorithm is used. This can be useful for "noisy" parameters (e.g., elevation and gradient)
• Sync Map and Graph Bounds When selected, as you pan and zoom on the map, the graph limits adjust to show you only the portion of the track displayed in the map.
• Reload Clicking the button re-reads the file containing the currently graphed track from disk. This can be helpful if you are editing data points in a GPS file using a separate application or text editor.

(top) ↑

Time Zones

GFV currently does a very simple (inaccurate near boundaries) timezone calculation for locations within the U.S., Western Europe, and Japan.

If you find that GFV is not providing accurate timezones for your locale, you can easily customize the calculation (see config file: tz_offsets).

(top) ↑

Overview Options

On the right side of the filter row in the track browser are a series of track overview buttons. Each one is described below, left to right.

• Show Overview Map: This toggle button determines whether overview tracks are shown on the map. It is on by default. If you have many (hundreds) of tracks in the track list, filtering and updates will be quicker by turning this button off.
• Reset Overview: this button resets the overview map, zooming out to fit all tracks. Any filtering (via the filter row buttons) remains in effect. Geographic filtering (see above) is also reset.
• Subset: When using geographic filtering, you can fix the selected tracks, so that the reset button

(top) ↑

Showing Coordinates

To show the current lat-lon coordinates of the mouse while in the map as well as the coordinates of the center of the map, click the coordinates toggle button () at the top of the application window. When toggled on, it looks like this:

You can change the map location by typing or pasting a lat-lon pair (decimal only) into the Center: textbox.

(top) ↑

Acknowledgements

Thanks to the following for providing the libraries and other support:

• pyslip map display library
• gpxpy gps analysis and manipulation library
• OpenStreetMap.org for granting permission for use of their osm tileserver