https://sourceforge.net/p/gpsfv/wiki/Help/Recent changes to HelpenSat, 03 Sep 2016 17:53:37 -0000https://sourceforge.net/p/gpsfv/wiki/Help/<div class="markdown_content"><pre>--- v6 +++ v7 @@ -1,4 +1,6 @@ -# GPSFileViewer +# GPSFileViewer Help + +## Overview Desktop application for browsing and visualizing GPS files on your hard drive or network. </pre> </div>Rich KSat, 03 Sep 2016 17:53:37 -0000https://sourceforge.net91800bef11e5adf296b058de901708771134ab9dhttps://sourceforge.net/p/gpsfv/wiki/Help/<div class="markdown_content"><pre>--- v5 +++ v6 @@ -8,9 +8,8 @@ * 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 -<p> - ----- + +--------- ## Table of Contents * [Installation](#installation) @@ -38,6 +37,7 @@ * [Overview Options](#overview_options) * [Showing Coordinates](#showing_coordinates) * [Acknowledgements](#acknowledgements) + * [Cutting room floor](#cutting_room_floor) ----- <a name="installation"></a> @@ -80,7 +80,7 @@ <a href="#">(top) ↑</a> ### 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. @@ -93,8 +93,8 @@ 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 +* 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. @@ -104,7 +104,7 @@ <a href="#">(top) ↑</a> ## 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. +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. <a name="filtering_tracks"></a> <a href="#">(top) ↑</a> @@ -112,14 +112,14 @@ 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](#pfilter). -* __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  +* __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. @@ -136,17 +136,17 @@ * __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. +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. <a name="color_coding_track_overviews"></a> <a href="#">(top) ↑</a> ## 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. +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. <a name="showing_individual_track_details"></a> @@ -157,11 +157,11 @@ 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. + + +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](#graph_options)). @@ -173,11 +173,11 @@ 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. @@ -194,7 +194,7 @@ 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)<br/>`*` 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). +* 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 `&lt;no_time&gt;` <a name="pfilter"></a> @@ -203,19 +203,19 @@ <a href="#">(top) ↑</a> ### 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 `&lt;All&gt;` 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. +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 `&lt;All&gt;` 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. <a name="path_filters"></a> <a href="#">(top) ↑</a> ### 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: - - +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). @@ -227,10 +227,10 @@ <a href="#">(top) ↑</a> #### Managing Path Filters -* __Create a new path filter__ by clicking the new () button -* __ Copy an existing filter__ by clicking the copy () button. +* __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. +* __Delete the filter__ by clicking on the  on the right side. <a name="working_with_a_selected_filter"></a> <a href="#">(top) ↑</a> @@ -244,13 +244,13 @@ * __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. +* __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. <a name="exporting_data"></a> <a href="#">(top) ↑</a> ### 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. +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: @@ -267,7 +267,7 @@ 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: @@ -289,7 +289,7 @@ 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](#preprocessing) is not done. Click the toggle button again to turn off hires mode. <br/>_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 <span style="background: #ddd; padding: 2px; border: solid 1px;">(low) - (high)</span> in the textbox, with each being optional. For example, entering <span style="background: #ddd; padding: 2px; border: solid 1px;"> -10-30 </span> sets the lower limit to -10 and the upper limit to 30, while entering <span style="background: #ddd; padding: 2px; border: solid 1px;"> -30- </span> sets the lower limit to -30 and allows the upper limit to be set by the data. @@ -299,14 +299,14 @@ <a href="#">(top) ↑</a> ### Secondary Graph Options -Click the  button on the left of the graph-map config area to show secondary display 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](#time_zone) on local time calculation). * __Smooth Graph__ Values &gt; 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. +* __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. <a name="time_zones"></a> <a href="#">(top) ↑</a> @@ -322,7 +322,7 @@ 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](#geo_filter)) is also reset. @@ -333,9 +333,9 @@ <a href="#">(top) ↑</a> ### 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: - - +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. @@ -348,4 +348,3 @@ * [pyslip](https://github.com/rzzzwilson/pySlip) map display library * [gpxpy](https://github.com/tkrajina/gpxpy) gps analysis and manipulation library * [OpenStreetMap.org](https://www.openstreetmap.org) for granting permission for use of their osm tileserver - </p></pre> </div>Rich KSat, 03 Sep 2016 17:52:56 -0000https://sourceforge.nete083f36c916b7f1fd0e5bd14e7ee6d62323769e7https://sourceforge.net/p/gpsfv/wiki/Help/<div class="markdown_content"><pre>--- v4 +++ v5 @@ -63,7 +63,7 @@ *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. </pre> </div>Rich KSat, 03 Sep 2016 17:47:00 -0000https://sourceforge.nete087bd4ca17d7ee0c04f9f805c1a52d6a28fa469https://sourceforge.net/p/gpsfv/wiki/Help/<div class="markdown_content"><pre>--- v3 +++ v4 @@ -63,7 +63,7 @@ *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. </pre> </div>Rich KSat, 03 Sep 2016 17:42:30 -0000https://sourceforge.net0aefa4f92706cd89554edd00a3ec721c8401036bhttps://sourceforge.net/p/gpsfv/wiki/Help/<div class="markdown_content"><pre>--- v2 +++ v3 @@ -63,7 +63,7 @@ *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. </pre> </div>Rich KSat, 03 Sep 2016 17:41:10 -0000https://sourceforge.net943596e6e76fe3485761f959e98ed1c707854e36https://sourceforge.net/p/gpsfv/wiki/Help/<div class="markdown_content"><pre>--- v1 +++ v2 @@ -1,5 +1,3 @@ -&lt;style&gt;img {position:relative; top:3px}&lt;/style&gt; - # GPSFileViewer Desktop application for browsing and visualizing GPS files on your hard drive or network. @@ -40,7 +38,6 @@ * [Overview Options](#overview_options) * [Showing Coordinates](#showing_coordinates) * [Acknowledgements](#acknowledgements) - * [Cutting room floor](#cutting_room_floor) ----- <a name="installation"></a> @@ -66,7 +63,7 @@ *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. @@ -352,32 +349,3 @@ * [gpxpy](https://github.com/tkrajina/gpxpy) gps analysis and manipulation library * [OpenStreetMap.org](https://www.openstreetmap.org) for granting permission for use of their osm tileserver -<p> - ---------------- - - -<a name="cutting_room_floor"></a> -<a href="#">(top) ↑</a> -## Cutting room floor - -*note: While much of GFV can be configured from within the application, additional parameters can be changed by editing GFV's configuration file (see gpsfileviewer.cfg in the app directory). Most of the parameters are documented within comments in the file, and some of them are referenced in this help file.* - -*Note: In the current version of GFV, there is no undo apart from text fields.* - -* __Current Map View__ As mentioned above, panning and zooming the map filters out tracks not visible in the current view -* __Clicked Map Location__ As mentioned above, single-clicking near a track on the map filters to show only those tracks that pass near the clicked point. - -* Dragging mouse in graph shows distance and duration for portions of tracks - -As you pan and zoom the overview map, the track list (right side of application) shows only those tracks that are in the current map view. - -When one or more tracks are selected in the track list, moving the mouse in the graph area shows the corresponding location for that time or distance as a dot on the track(s). The time associated with that location and the graph Y value(s) are shown in the status bar. - -The following options are available: - * __ _lo#_-_hi#_ __ Sets both Y limits according to the value provided - * __ -_hi#_ __ Sets maximum Y to value provided; automatically sets minimum value - * __ _lo#_- __ Sets minimum Y to value provided; automatically sets maximum value - * __ _(blank)_ __ (default) Automatically sets both minimum and maximum Y values. - -Sync Map and Graph Bounds: When selected, the graph horizontal limits will show the same portion of the track that's visible in the map. </p></pre> </div>Rich KSat, 03 Sep 2016 17:39:56 -0000https://sourceforge.neta4a656f3f95ce41bc98323fccffa1f3954715510https://sourceforge.net/p/gpsfv/wiki/Help/<div class="markdown_content">&lt;style&gt;img {position:relative; top:3px}&lt;/style&gt; <h1 id="gpsfileviewer">GPSFileViewer</h1> <p>Desktop application for browsing and visualizing GPS files on your hard drive or network. </p> <ul> <li>Browse GPS files (gpx, kml, csv) by directory using embedded file/track/metadata browser</li> <li>Show overview map of all tracks in directory. Tracks can be color coded based on metadata, e.g., distance, duration.</li> <li>Filter tracks in browser based on metadata, location, and path.</li> <li>Use Path Filters to find tracks that traverse a series of locations, for instance, to compare different routes.</li> <li>Simultaneously view tracks on map while graphing metadata (e.g., speed, elevation, hill gradient)</li> <li>Interactive display of distance and duration for selected portions of tracks<br/> <p></p></li> </ul> <hr/> <h2 id="table-of-contents">Table of Contents</h2> <ul> <li><a class="" href="#installation">Installation</a></li> <li><a class="" href="#launching">Launching</a><ul> <li><a class="" href="#some_quick_notes">Some Quick Notes</a></li> <li><a class="" href="#track_overview">Track Overview</a></li> <li><a class="" href="#moving_around_in_map_view">Moving Around in Map View</a></li> </ul> </li> <li><a class="" href="#selecting_units_(english/metric)">Selecting Units (English/Metric)</a></li> <li><a class="" href="#filtering_tracks">Filtering tracks</a><ul> <li><a class="" href="#geographic_filtering">Geographic Filtering</a></li> </ul> </li> <li><a class="" href="#color_coding_track_overviews">Color Coding Track Overviews</a></li> <li><a class="" href="#showing_individual_track_details">Showing Individual Track Details</a></li> <li><a class="" href="#distances_and_times_within_a_track">Distances and Times within a Track</a></li> <li><a class="" href="#additional_features_and_tips">Additional Features and Tips</a><ul> <li><a class="" href="#track_pre-processing">Track Pre-Processing</a></li> <li><a class="" href="#quick_subdirectory_switching">Quick Subdirectory Switching</a></li> <li><a class="" href="#path_filters">Path Filters</a></li> <li><a class="" href="#managing_path_filters">Managing Path Filters</a></li> <li><a class="" href="#working_with_a_selected_filter">Working with a selected filter</a></li> <li><a class="" href="#exporting_data">Exporting data</a></li> <li><a class="" href="#track_display_color_coding">Track Display Color Coding</a></li> <li><a class="" href="#graph-map_options_in_the_ui">Graph-Map options in the UI</a></li> <li><a class="" href="#secondary_graph_options">Secondary Graph Options</a></li> <li><a class="" href="#time_zones">Time Zones</a></li> <li><a class="" href="#overview_options">Overview Options</a></li> <li><a class="" href="#showing_coordinates">Showing Coordinates</a></li> </ul> </li> <li><a class="" href="#acknowledgements">Acknowledgements</a></li> <li><a class="" href="#cutting_room_floor">Cutting room floor</a></li> </ul> <hr/> <p><a name="installation"></a><br/> <a href="#">(top) ↑</a></p> <h2 id="installation">Installation</h2> <p>GPSFileViewer (GFV) is distributed as a zip file. Simply unzip the file to the directory of your choice.</p> <p>Mac at this time requires running the python source files, which requires python 2.x (x &gt;=7) and the following packages to be installed:</p> <ul> <li><a class="" href="http://www.wxpython.org/" rel="nofollow">wxPython</a>, at least v3.0</li> <li><a class="" href="http://matplotlib.org/" rel="nofollow">matplotlib</a>, at least v1.3.1 </li> </ul> <p><a name="launching"></a><br/> <a href="#">(top) ↑</a></p> <h2 id="launching">Launching</h2> <p><strong>Windows:</strong> From the installation directory, run <code>app/gpsfileviewer.exe</code>.</p> <p><strong>Mac:</strong> From the installation directory, go to the script directory and click gpsfileviewer.command</p> <p>Launching GFV brings up a set of sample gps files that comes with the application (located in the <code>sample_gps</code> 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.</p> <p><em>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.</em></p> <p><img alt="On Launch" src="./img/10_GPSFV_startup.jpg"/></p> <p>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.</p> <p><em>note: The "Load Files" button caches the GPS data on your hard drive (the <code>app/gps_cache</code> subdirectory), so you only have to click it once for each directory.</em></p> <p><a name="some_quick_notes"></a><br/> <a href="#">(top) ↑</a></p> <h3 id="some-quick-notes">Some Quick Notes</h3> <ul> <li><em>24-hour time is used throughout GFV. AM/PM is not implemented in this version.</em></li> <li><em>For customizing GFV, there is a user-modifiable config file. See <code>gpsfileviewer.cfg</code> in gpsfileviewer's app directory. Additional documentation on config settings is provided within that file.</em></li> </ul> <p><a name="track_overview"></a><br/> <a href="#">(top) ↑</a></p> <h3 id="track-overview">Track Overview</h3> <p><img alt="Files Loaded" src="./img/20_files_loaded.jpg"/></p> <p>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. </p> <p>The tracks are shown on the map as brown lines (config file: <code>map.overview.solid_line_color</code>). The tracks are semi-transparent so you can see when mulitple track overlap.</p> <p><a name="moving_around_in_map_view"></a><br/> <a href="#">(top) ↑</a></p> <h3 id="moving-around-in-map-view">Moving Around in Map View</h3> <p>Zoom and pan the map using any of the following:</p> <ul> <li>Drag with the mouse to pan</li> <li>The zoom tool at the bottom of the window: <img alt="Map Zoom Detail" src="./img/map_zoom_detail.png"/></li> <li>Shift click the "Auto" checkbox (<img alt="Auto Zoom checkbox" src="./img/autozoom_checkbox.png"/>) to zoom the map to fit all tracks</li> <li>Keyboard shortcuts "+" and "-" to zoom in and out</li> <li>Double left-click within the map to zoom in, double right-click to zoom out</li> <li>Single-click on a track in the map and the browser and map will show only those tracks that go through that point.</li> </ul> <p><a name="selecting_units_(english/metric)"></a><br/> <a href="#">(top) ↑</a></p> <h2 id="selecting-units-englishmetric">Selecting Units (English/Metric)</h2> <p>You can select between meters/kilometers and feet/miles by selecting from <img alt="units selector" src="./img/option_units.png"/> in the configuration row. Make sure the configuration row is vzvisible by clicking the <img alt="gear icon" src="./img/gear.png"/> button at the top of the window.</p> <p><a name="filtering_tracks"></a><br/> <a href="#">(top) ↑</a></p> <h2 id="filtering-tracks">Filtering tracks</h2> <p>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:</p> <p><img alt="filter buttons" src="./img/filter_buttons.png"/></p> <p>Click one or more of these toggle buttons to open up and use that type of filter. The following filters are available:</p> <ul> <li><strong>Duration</strong>: Enter a minimum and/or maximum duration (minutes) for tracks</li> <li><strong>Distance</strong>: Enter a minimum and/or maximum distance (miles or km, depending the units selected) for tracks</li> <li><strong>Path</strong>: 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 <a class="" href="#pfilter">here</a>.</li> <li><strong>Start Hour</strong>: 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 <img alt="start hour window starting at 6, window length 2 hours" src="./img/filter_select_start_window.png"/></li> <li><strong>Filename</strong>: 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.</li> </ul> <p>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.<br/> </p> <p>The filters are modifiable and expandable. See config file: <code>filelist.filter_functions</code>.</p> <p><a name="geo_filter"></a><br/> <a name="geographic_filtering"></a><br/> <a href="#">(top) ↑</a></p> <h3 id="geographic-filtering">Geographic Filtering</h3> <p>In addition to the above buttons, you can filter tracks geographically using either of the following two approaches:</p> <ul> <li><strong>Clicked Map Location</strong>: Single-clicking near a track on the map and track browser shows only those tracks that pass near the clicked point.</li> <li><strong>Zoom via Box Select</strong> 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.</li> </ul> <p>To reset geographic filtering, click the overview reset button (<img alt="Reload button" src="../img/reload.png"/>) on the right side of the filter row. Toggling one of the other filter buttons also resets geographic filtering.</p> <p><a name="color_coding_track_overviews"></a><br/> <a href="#">(top) ↑</a></p> <h2 id="color-coding-track-overviews">Color Coding Track Overviews</h2> <p>The Pallete button (<img alt="Palette icon" src="./img/palette.gif"/>) 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.</p> <p>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.</p> <p><img alt="Overview with color coding" src="./img/30_overview_color_coding.jpg"/><br/> The above example shows tracks color coded by distance and sorted by distance in the track browser.</p> <p><a name="showing_individual_track_details"></a><br/> <a href="#">(top) ↑</a></p> <h2 id="showing-individual-track-details">Showing Individual Track Details</h2> <p>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.</p> <p>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: <code>map.multitrack_offset_pixels</code>)</p> <p><img alt="Track Display" src="./img/40_track_selected.jpg"/></p> <p>The graph and track above are color coded according to speed <img alt="color param" src="./img/plot_color_param.png"/> . The color style Grn-Ylw-Red <img alt="color code" src="./img/cmap_detail_sm.png"/> 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.</p> <p>Within the graph, zoom and pan using the tools at the bottom of the window: <img alt="graph zoom tools" src="./img/graph_zoom_tools.png"/>. Additional help is provided in tooltips.</p> <p>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 <a class="" href="#graph_options">below</a>).</p> <p><a name="distances_and_times_within_a_track"></a><br/> <a href="#">(top) ↑</a></p> <h2 id="distances-and-times-within-a-track">Distances and Times within a Track</h2> <p>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.<br/> </p> <p>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.</p> <p><img alt="track display secondary options" src="../img/options_track_2ary_display.png"/></p> <p>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.</p> <p><img alt="Timing portion of track" src="../img/50_timing_of_portion_of_track.jpg"/></p> <p>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. </p> <hr/> <p><a name="additional_features_and_tips"></a><br/> <a href="#">(top) ↑</a></p> <h2 id="additional-features-and-tips">Additional Features and Tips</h2> <p><a name="preprocessing"></a><br/> <a name="track_pre-processing"></a><br/> <a href="#">(top) ↑</a></p> <h3 id="track-pre-processing">Track Pre-Processing</h3> <p>GFV does the following things to the GPS files as it reads and caches them:</p> <ul> <li>Smartly<code>*</code> reduce the number of points for performance reasons (config file: <code>map.overview.simplify_dist</code> for the overview and <code>gps.max_simplify_distance_m</code>, <code>gps.smooth</code>, and <code>gps.reduce_points_distance_m</code> for individual track display)<br/><code>*</code> uses Ramer-Douglas-Peucker algorithm</li> <li>Automatically split tracks into segments when there's a rest at a location (default is 5 minutes; config file: <code>gps.min_gap_to_autosplit_tracks_sec</code>). To see individual segments in the track browser, select <img alt="Track-Segment selector" src="../img/option_track_segment_radiobox.png"/> in the config row (ensure config row is visible via the <img alt="gear icon" src="./img/gear.png"/> button at the top of the window).</li> <li>Removes tracks with 3 or fewer points (Config file: <code>gps.min_track_segment_points</code>).</li> <li>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 <code>&lt;no_time&gt;</code><br/> <a name="pfilter"></a></li> </ul> <p><a name="quick_subdirectory_switching"></a><br/> <a href="#">(top) ↑</a></p> <h3 id="quick-subdirectory-switching">Quick Subdirectory Switching</h3> <p>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 (<img alt="subfolder icon" src="../img/subfolder.png"/>) shows a dropdown list containing the folder's subdirectories. Change subdirectories by selecting one of them in the dropdown.</p> <p>A special directory called <code>&lt;All&gt;</code> 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 (<img alt="subfolder icon" src="../img/map_ovw.png"/>) button.</p> <p><a name="path_filters"></a><br/> <a href="#">(top) ↑</a></p> <h3 id="path-filters">Path Filters</h3> <p>The path filter is in the filter row (<img alt="filter icon" src="./img/filter.png"/>) 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.<br/> </p> <p>You can create and edit path filters by clicking on the edit button in the path filter selector row (<img alt="pencil icon" src="./img/edit.png"/>). When you do that, the path filter editor is shown:</p> <p><img alt="path editor" src="./img/path_editor.png"/></p> <p>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).<br/> </p> <p>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.</p> <p>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.</p> <p><a name="managing_path_filters"></a><br/> <a href="#">(top) ↑</a></p> <h4 id="managing-path-filters">Managing Path Filters</h4> <ul> <li><strong>Create a new path filter</strong> by clicking the new (<img alt="add button" src="./img/add.png"/>) button</li> <li><strong> Copy an existing filter</strong> by clicking the copy (<img alt="copy button" src="./img/copy.png"/>) button.</li> <li><strong>Rename</strong> a filter by editing the Name box on the left.</li> <li><strong>Delete the filter</strong> by clicking on the <img alt="red X delete button" src="./img/delete.png"/> on the right side. </li> </ul> <p><a name="working_with_a_selected_filter"></a><br/> <a href="#">(top) ↑</a></p> <h4 id="working-with-a-selected-filter">Working with a selected filter</h4> <ul> <li><strong>Changing a filter's type</strong> by selecting betwen values in the dropdown list on the right.<ul> <li><strong>Ordered</strong>: A track must traverse each point in order (1, then 2, then 3, etc.)</li> <li><strong>All</strong>: A track must traverse all points; order doesn't matter. </li> <li><strong>Any</strong>: A track can pass through any one or more points</li> </ul> </li> <li><strong>Add points</strong> to the filter by panning and zooming the map to where you want and control-clicking on the map.</li> <li><strong>Insert points</strong> 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.</li> <li><strong>Reposition filter points</strong> by dragging them in the map.</li> <li><strong>Remove a point</strong> 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.</li> <li><strong>Change a point's radius</strong> 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.</li> <li><strong>Temporaily disable filtering</strong> While editing a path filter, you can temporarily turn off filtering by clicking <img alt="Inhibit filter" src="./img/option_inhibit_filter_checkbox.png"/>. This shows overview of all tracks which may make it easier to see where to place path filter points.</li> </ul> <p><a name="exporting_data"></a><br/> <a href="#">(top) ↑</a></p> <h3 id="exporting-data">Exporting data</h3> <p>Export data to your system's clipboard by clicking on the <img alt="Export clipboard" src="./img/export_clipboard_blue2.png"/> icon at the top of the application window. You can then paste the data into your favorite application.</p> <p>You can export the following:</p> <ul> <li><strong>Map as image</strong> Copies current map view to clipboard as image</li> <li><strong>Track Data as Table</strong> Copy currently selected track(s) as a tab-separated list of lat, lon, elevation, and time for each track point.</li> <li><strong>Graph as Image</strong> Copy the graph of the currently selected track(s) as an image.</li> <li><strong>Graph Data as Table</strong> Copy x-y data in current graph as tab-separated list of x-y values.</li> <li><strong>Table Data</strong> Copy values from track browser table as tab-separated list</li> </ul> <p><a name="track_display_color_coding"></a><br/> <a href="#">(top) ↑</a></p> <h3 id="track-display-color-coding">Track Display Color Coding</h3> <p>You can color points within a track. The controls for doing this are between the graph and map areas.</p> <p><img alt="track color coding UI" src="../img/option_track_color_coding.png"/></p> <p>Select a parameter, e.g., distance, speed, elevation) and a color scheme. In addition to these basic parameters, the following parameters are available:</p> <ul> <li><strong>Gradient %</strong> Shows slope (ascending = positive, descending = negative)</li> <li><strong>Vertical Climb</strong> Shows accumulated positive elevation gain (feet or meters, depending on units system)</li> <li><strong>Elapsed10</strong> 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.</li> <li><strong>Elapsed60</strong> Same as Elapsed10, except graph wraps top-to-bottom after each hour.</li> </ul> <p>In addition to several gradient color schemes (such as Copper above), the following schemes may helpful in certain situations:</p> <ul> <li><strong>Three-Color Gradient</strong> 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. <br/>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.</li> <li><strong>Solid Scheme</strong> 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 <code>solid</code> entry within <code>cmap.custom_cmaps</code>.</li> <li><strong>Banded Schemes</strong> These schemes stack multiple gradients on top of each other. For instance, if you plot speed of a track, set the Y-limits to <code>0-30</code>, 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.</li> </ul> <p><a name="graph-map_options_in_the_ui"></a><br/> <a href="#">(top) ↑</a></p> <h3 id="graph-map-options-in-the-ui">Graph-Map options in the UI</h3> <p>In addition to the above color coding, the following options are available in the configuration area between the map and graph:</p> <p><img alt="track display options" src="../img/option_track_display.png"/></p> <ul> <li>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 <a class="" href="#preprocessing">described above for cached data</a> is not done. Click the toggle button again to turn off hires mode. <br/><em>Note: while hires is clicked, each file is read in anew each time it is plotted, so performance will be a little slower.</em></li> <li>You can enter specific numbers to fix the Y limits for the graph and for the color scheme. Enter <span style="background: #ddd; padding: 2px; border: solid 1px;">(low) - (high)</span> in the textbox, with each being optional. For example, entering <span style="background: #ddd; padding: 2px; border: solid 1px;"> -10-30 </span> sets the lower limit to -10 and the upper limit to 30, while entering <span style="background: #ddd; padding: 2px; border: solid 1px;"> -30- </span> sets the lower limit to -30 and allows the upper limit to be set by the data.</li> </ul> <p><a name="graph_options"></a><br/> <a name="secondary_graph_options"></a><br/> <a href="#">(top) ↑</a></p> <h3 id="secondary-graph-options">Secondary Graph Options</h3> <p>Click the <img alt="gear icon" src="./img/gear.png"/> button on the left of the graph-map config area to show secondary display options.</p> <p><img alt="track display secondary options" src="../img/option_track_2ary_display.png"/></p> <ul> <li><strong>Elapsed</strong> 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 <a class="" href="#time_zone">note</a> on local time calculation).</li> <li><strong>Smooth Graph</strong> Values &gt; 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)</li> <li><strong>Sync Map and Graph Bounds</strong> 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.</li> <li><strong>Reload</strong> Clicking the <img alt="Reload button" src="../img/reload.png"/> 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.</li> </ul> <p><a name="time_zones"></a><br/> <a href="#">(top) ↑</a></p> <h3 id="time-zones">Time Zones</h3> <p>GFV currently does a very simple (inaccurate near boundaries) timezone calculation for locations within the U.S., Western Europe, and Japan.<br/> </p> <p>If you find that GFV is not providing accurate timezones for your locale, you can easily customize the calculation (see config file: <code>tz_offsets</code>).</p> <p><a name="overview_options"></a><br/> <a href="#">(top) ↑</a></p> <h3 id="overview-options">Overview Options</h3> <p>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.</p> <p><img alt="Overview Controls" src="../img/controls_overview.png"/></p> <ul> <li>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.</li> <li>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 (<a class="" href="#geo_filter">see above</a>) is also reset.</li> <li>Subset: When using geographic filtering, you can fix the selected tracks, so that the reset button </li> </ul> <p><a name="showing_coordinates"></a><br/> <a href="#">(top) ↑</a></p> <h3 id="showing-coordinates">Showing Coordinates</h3> <p>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 (<img alt="Coords button" src="../img/coordinates.png"/>) at the top of the application window. When toggled on, it looks like this:</p> <p><img alt="coords display" src="../img/coordinates_display.png"/></p> <p>You can change the map location by typing or pasting a lat-lon pair (decimal only) into the Center: textbox.</p> <p><a name="acknowledgements"></a><br/> <a href="#">(top) ↑</a></p> <h2 id="acknowledgements">Acknowledgements</h2> <p>Thanks to the following for providing the libraries and other support:</p> <ul> <li><a class="" href="https://github.com/rzzzwilson/pySlip" rel="nofollow">pyslip</a> map display library</li> <li><a class="" href="https://github.com/tkrajina/gpxpy" rel="nofollow">gpxpy</a> gps analysis and manipulation library</li> <li><a class="" href="https://www.openstreetmap.org" rel="nofollow">OpenStreetMap.org</a> for granting permission for use of their osm tileserver</li> </ul> <p> --------------- <a name="cutting_room_floor"></a> <a href="#">(top) ↑</a> ## Cutting room floor *note: While much of GFV can be configured from within the application, additional parameters can be changed by editing GFV's configuration file (see gpsfileviewer.cfg in the app directory). Most of the parameters are documented within comments in the file, and some of them are referenced in this help file.* *Note: In the current version of GFV, there is no undo apart from text fields.* * __Current Map View__ As mentioned above, panning and zooming the map filters out tracks not visible in the current view * __Clicked Map Location__ As mentioned above, single-clicking near a track on the map filters to show only those tracks that pass near the clicked point. * Dragging mouse in graph shows distance and duration for portions of tracks As you pan and zoom the overview map, the track list (right side of application) shows only those tracks that are in the current map view. When one or more tracks are selected in the track list, moving the mouse in the graph area shows the corresponding location for that time or distance as a dot on the track(s). The time associated with that location and the graph Y value(s) are shown in the status bar. The following options are available: * __ _lo#_-_hi#_ __ Sets both Y limits according to the value provided * __ -_hi#_ __ Sets maximum Y to value provided; automatically sets minimum value * __ _lo#_- __ Sets minimum Y to value provided; automatically sets maximum value * __ _(blank)_ __ (default) Automatically sets both minimum and maximum Y values. Sync Map and Graph Bounds: When selected, the graph horizontal limits will show the same portion of the track that's visible in the map. </p></div>Rich KSat, 03 Sep 2016 17:37:11 -0000https://sourceforge.netc8a7c45915df31ae015aecf7243c78c48c62a48d