Activity Workshop
 

GpsPrune how-tos

Note: This page is now also available auf deutsch, en français and en español! Thanks to all the translators!

The following sections attempt to explain the most common functions of GpsPrune, and how to use them. Some potential problems and their solutions are also given in the problem-solving page, and there are also a few demo videos available to show the basic functions. If you have any questions or feedback please use the email address at the bottom of the page.

User guide

Would you be interested in purchasing a detailed manual of how to use GpsPrune? The information here, plus lots of other step-by-step guides, detailed screenshots and practical examples, has been put together into a great-looking, full-colour and fully-searchable pdf guide which is now for sale. The current version is 162 pages long and completely revised and updated for GpsPrune version 18. For more information see the user guide page.

Note that, during this how-to, if a key combination such as Ctrl-O or Ctrl-right arrow is mentioned, this key combination is platform-specific. Linux and Windows use the Ctrl (or control) key for these keys, whereas Mac uses the ⌘ key (Command key or Clover key). For simplicity, Ctrl is used in these descriptions.

The first steps are to load some data, as without data Prune can't do much. There are three main ways of loading data - from a text file, from an xml file or directly from the GPS receiver. These will be described in turn:

Opening a text file

Prune can read any text file as long as each line of the file describes a point, with the fields separated by a known character. The order of the fields must be consistent throughout the file, although several files of different formats may be loaded separately. Prune can't understand binary formats.

Opening a file consists of three steps: firstly selecting the file, secondly selecting the delimiter, and thirdly specifying which fields are in which order.

To access the function, select the "File" menu and click on "Open". Or use Ctrl-O from the keyboard, or the corresponding button on the toolbar. A file dialog will appear, with which you can choose the file to open. The first of the two dialog panels will then appear showing the first few lines of the file and offering a choice of delimiter (see picture below).

Load part1

First load panel for selecting file delimiter

Load part2

Second load panel for selecting
field combination and altitude units

 

Prune will attempt to guess the delimiter, but if it's wrong you can select one of the others, or enter your own in the "Other" box. Given the delimiter, Prune can then split the lines into a table on the second panel (see picture) and offer choices of fields. The fields are listed in the lower grid, with some standard fields (like Latitude, Longitude, Altitude) and also the option to define your own custom fields. You can change the definition of each field using a dropdown within the grid (eg click on Altitude to change it). You can also change the order of fields by selecting one and using the "Move up" and "Move down" buttons. The description column is for the custom fields in case you want to give the field a more meaningful name.

Also on this second panel is a selection for altitude units, giving the choice of metres or feet. Finally by pressing the "Finish" button the data will be loaded and displayed. If you find you have made a mistake with the field definitions, you can use the "Undo" function to remove the loaded data and try again.

To combine several files, simply load each one in turn. When asked whether to append the data to that already loaded, select "Yes" to add the data together, or "No" to remove the data previously loaded and just load the new file instead.

Opening an XML file

Opening an XML file is easier, as long as the file is in GPX or KML format. The function is started in the same way as for a text file described above, but an XML file is chosen instead. In this case you just need to select the file and the file should then be loaded automatically.

You can also select a zipped XML file, either with extension KMZ (with a KML file inside), or a regular zip file (with either KML or GPX inside).

Opening multiple files

You can select multiple files in the "open file" dialog, using the ctrl key or shift key as normal. The files will be opened one by one, and the data appended together. If you select text files you will need to select the open options for each one as described above, but for GPX, KML, KMZ, ZIP and NMEA files, the files will be loaded without any questions.

You can also open files by dragging them into the GpsPrune window, either from the desktop or from your file manager.

Loading from GPS receiver

If you have gpsbabel installed (see dependencies), you can load the data directly from your GPS receiver. Select the "Load data from GPS" option from the File menu, and enter the device name and format in the dialog. You can also set these parameters in your settings so that you don't have to type them in every time you run Prune.

Using Openstreetmap maps

After loading from a file, the data will be shown on the top-down map view and also (if it contains altitude data) on the profile view below. Prune can also overlay your coordinate data on top of a map from openstreetmap.org, as shown in the screenshots page. By default these maps are switched off, but you can enable them by simply clicking the map control at the top of the map window: icon or click the checkbox View -> Show map. These controls toggle the maps on and off. There is also a slider control which controls the transparency of the maps, so you can have just very faint maps (and see your data more clearly), have very faint data (so you can see the map clearly) or show both at the full opacity.

You can also select a different map server, for example to choose opencyclemap images or openpistemap, or just to use an alternative OSM renderer like Osmarenderer. To configure this, go to the menu View -> Set map background or use the right click menu on the map. From here you can select one of the preset servers from the list, or select "Add new" and enter the details (in the form of one or two Openstreetmap-style URL(s) or a cloudmade style number). For GpsPrune to remember which custom servers you have entered, you must use the Settings->Save settings command to save the information to a file.

If you want to speed up the map access and make them available offline, GpsPrune can save the map tiles to disk as it displays them. By default this is switched off, but you can enable it with the menu item Settings->Save maps to disk. Then if you enter a directory in which to save the map tiles, map tiles will be preferentially loaded from disk if available. If the "offline" mode is enabled (by turning the checkbox Settings->Load maps from internet off), then only locally-saved maps will be used, and GpsPrune will not attempt to get any from the online sources.

Other map servers

As well as the well-known map sets like openstreetmap and opencyclemap, there are other useful tilesets which you can easily add to GpsPrune. You can easily use these by adding a custom source in Settings -> Set map background:

Selecting a point

Selection view

Screenshot showing selected point and range

You can select any point and view the details on the "Point details" panel on the right. There are several ways to select a point:

The red crosshairs show the currently selected point. After selecting a point, this point may be deleted from the "Point" menu under "Delete point", or using the keyboard "delete" key.

Selecting a range of points

To select a range of points, use any of the methods above to select the start point, and then click the "Set range start" toolbar button or the "Set range start" function in the "Range" menu. This will select a new range from the current point to the end of the track. Now select the end point, and select "Set range end" (either from the toolbar or the menu). The range is now selected and the range details (including distance, time, altitude range etc) are shown on the right of the window.

A simpler way to select a range is to select the first point as above, and then with the "Shift" button pressed, click on the end point of the range, either on the map or in the profile view.

To delete a range, make sure the range is selected and then use the "Delete range" function in the "Range" menu.

To select the whole track, or to clear all selections, use the "Range" menu entries "Select all" or "Select none".

Track compression

To delete all duplicate points in a track, or to delete closely-spaced points, use the "Compress track" command in the "Track" menu. This offers four compression techniques, as follows:

Note that all four of these algorithms only mark the points for compression, they don't delete them yet. In the map view the points will be marked in red to let you review them and check that they really should be deleted. If they look ok, use the menu command Track -> Delete marked points to delete them.

Other track editing functions

To add new points to interpolate between a pair of data points, select a range between the two points (so that only the two points are selected) and then use the "Interpolate" command in the "Range" menu. Finally, choose the number of points to insert (calculated in an even straight line of latitude, longitude and altitude).

To reverse a section of the track, select it as a range and choose "Reverse range" from the "Range" menu. This simply mirrors the order of the points so that the track goes in the opposite direction.

Other editing functions include adding a time offset to the current selection (to disguise when you were actually there), merging track segments (to make the current selection one single track segment), and creating a new point at the average coordinates of the current selection (useful for more accurately marking a waypoint).

To undo any change made to the data, choose "Undo" from the "Track" menu (or use the "Undo" toolbar button) and select the number of operations to undo.

Panning and zooming the map

The map view is zoomable to allow you to see the fine detail more clearly. The zoom and pan functions can be controlled either with the mouse or with the keyboard. To zoom in and out:

To pan the map up, down, left and right:

By default, the auto-pan function is switched on, so when you select a new point which is off-screen, the map will pan to bring it into view. To deactivate this feature, use the context menu on the map to deselect the checkbox for "Autopan".

Saving the track

To save the edited data, select "Save" from the "File" menu, or click the "Save" button on the toolbar. This brings up the first page of a 2-page save dialog, to allow you to select the options. The first page selects which fields to save and in what order, as well as the delimiter to use. The second, optional, page lets you specify any data format conversions to apply.

The field selection panel shows all the fields available, and whether they currently contain data or not. The third column of the grid lets you specify whether to save this field in the file or not. By selecting a row of the grid and using the "Move up" and "Move down" buttons, the order of the fields can be changed. The delimiter is selected in the same way as for opening a file, either using one of the listed ones or entering your own.

By clicking "Next", you can choose to select the format of the coordinates and altitudes to save in the file. By default just the values from the original file will be copied, but you may choose to convert to different units or formats.

The final step is to select the filename with which to save the data, which can be either a new file or can overwrite an old one.

Exporting to Xml formats

There are two Xml formats supported by GpsPrune: KML (used by applications like Google Earth) and GPX (used by many other programs). To export data in these formats, use the "Export KML" or "Export GPX" functions from the "File" menu. These Xml files don't support all the fields which a text file can contain, so make sure you save your data as a text file using the "Save" function if you wish to reload your data into GpsPrune. GpsPrune can read KML and GPX files but some fields may be lost in the translation.

Editing points

To edit a point, firstly select it as described above. Then bring up the point editing dialog using the menu item "Edit point" in the Point menu, or the "Edit point" toolbar button. In this dialog, each of the fields of the point (including any custom ones) are shown in a table. Select the field to change, click the Edit button, and enter the new value in the box. Repeat this for all the fields to change, and then click the "OK" button to confirm the changes.

If only the waypoint name needs to be changed, it's simpler to use the separate "Edit waypoint name" menu item instead - this is a simplified dialog with just the waypoint name editable. Functions for converting the name to upper case (eg "CHINZIG CHULM"), lower case ("chinzig chulm") or mixed case ("Chinzig Chulm") are also provided.

Viewing in 3d

With a loaded track, select the menu item "Show in Three-D" from the View menu. This will open a new window containing the 3d display. Note that Java3D must be installed in order to use this function. This is an extra library which can be downloaded separately from the main java runtime. You can spin the model by clicking and dragging the mouse in the main window. To make a higher-quality rendering of the model, use the "Export POV" button on this display window to go directly to the Povray export function (see below).

Exporting to Povray

Povray is an external program available for Windows, Mac and Linux, which can make very high-quality renderings of 3d models. GpsPrune can export your data into POV format, which can then be loaded into the Povray program. For more information about Povray and how to set the quality settings for good rendering, see the tutorials at povray.org.

To export in POV format, use the menu item "Export POV" from the File menu. This brings up a short dialog to set the font and the camera coordinates to use, and then allows selection of the output file. You can also bring up this dialog from the "Show in Three-D" function (see above).

Note that GpsPrune does not invoke Povray directly, it just exports the data in the correct format. See the Povray documentation for how to call Povray using your platform.

Correlating photos

To load photos, use the "Add photos" option on the File menu (also in the Photo menu), or use the "Add photos" button on the main toolbar. If the photos already have coordinate information in the exif tags, these will be read and new points created. If not, you can manually connect photos to points by selecting a photo (using the list box in the lower left), selecting a point (as described above) and then either using the "Connect to point" option from the Photo menu, or using the corresponding button on the toolbar.

If the track information has timestamps associated with the points (not all tracks have this information), then the automatic correlation function can be used to try to link the photos and points together. This works by matching the photo timestamps with the point timestamps. However, the camera's clock and the GPS receiver's clock are not perfectly synchronized, and in addition, the camera's clock is probably set to local time whereas the GPS receiver's clock is set using the satellites' signals in UTC time. So there is always a difference to add or subtract before matching the timestamps. The best way to figure out this difference is to manually connect at least one photo and then use that difference to correlate the others.

The correlation function is reached from the "Correlate all photos" item in the "Photo" menu. If at least one photo has already been correlated with a timed point, then a list is shown in order to select one. If not, the dialog jumps to the second step where the time difference can be entered manually. Limits can be set for the time between points or the distance between points to limit when photos will be correlated. Using the "preview" button, a table can be displayed showing which photos can be correlated using the selected time offset and limits. The checkboxes can be used to select or deselect photos, or the settings can be adjusted and another preview made. Finally the selected photos will be connected to the corresponding points (or new points will be created by interpolation).

After the photos have been correlated, the coordinates can be saved into the exif information of the jpg files (see below). Also, a KMZ including photo thumbnails can be created (see below), for example for showing in Google Earth.

Also note that audio files (such as your own dictated notes) can be correlated in the same way - see the Audio menu for how to load, play, link and correlate audio files with your coordinate data.

Exporting photos to Google Earth

Firstly, load and if necessary correlate photos as described above. Then select the "Export KML" function from the File menu. Make sure the "KMZ" option is checked, and the export image thumbnails option, and select the file to save. Then load this KMZ file into Google Earth to view. The thumbnails will appear in the description bubble for the points when clicked on. If you want to change the size of the thumbnail images, use the command "Set KMZ image size" in the "Settings" menu. Of course you can save your chosen settings with Settings -> Save settings.

The data can be further edited in Google Earth, for example by reordering waypoints, moving items into separate folders, associating "snapshots" with points, and editing the captions of the photos. The result can be saved again from Google Earth using the right-click menu.

Saving exif information

To save the coordinates into the jpeg files, Prune uses an additional program called exiftool. This is based on perl and available for Windows, Mac and Linux. For Linux and Mac, you just need to install the exiftool package, but for Windows you get a zip file containing an executable called exiftool(-k).exe - you'll need to rename this to "exiftool.exe" and put it somewhere in the path - or edit the path to include the directory where you put exiftool.exe. This will allow Prune to find it at runtime. The about screen (Help -> About) shows whether Prune can find exiftool on your system.

To save the coordinates, correlate the photos either manually or automatically as described above, then choose the "Save to Exif" menu item from the "Photo" menu. A list of correlated photos will be shown, simply select the photos to save using the checkboxes and press "Ok". If the "Overwrite files" checkbox is checked, the photo files will be overwritten, which may be dangerous and could corrupt the file (although this is very unlikely). If this checkbox is unchecked, the original file is renamed with the extension _original and a new copy is made.

Creating charts

To create charts of altitudes, distances, speeds and so on, use the menu command View -> Charts. This allows you to choose the X-axis (either distance or time) and between one and four y-axes for the charts. This function requires gnuplot to be installed and for Prune to know where to find gnuplot. The charts can be displayed directly on the screen, or can be saved to an svg file.

So what can you do with the charts after creation? If you display the chart to the screen, you can simply make a screengrab using your normal tools and manipulate the picture using your usual graphics editor. One free multiplatform alternative for this is Gimp. Make sure you reduce the colour depth and save it in a lossless format (eg png) for best results. Don't save it as a jpeg!

If you save the chart as an svg file, there are a variety of tools you can use to display and edit the file. The biggest advantage of this is that it's a vector format, so you can scale it to as big as you like without getting ragged pixels. The files are also usually much smaller than an equivalent png file. You should be able to view the svg file in browsers like Firefox or Opera, and also in normal graphics editors like Gimp. To manipulate the svg file you'll need an editor for vector graphics, like Inkscape, but in the current versions of Inkscape there are rendering bugs - you need to replace all the instances of "stroke:currentColor" with "stroke:black" for them to show up properly. You can do this with a text editor or with a simple sed command.

Finding out when the next version is released

There are a few ways to keep up-to-date. Obviously you can check activityworkshop.net regularly, and look at the news summary there. Or you can subscribe to the rss feed which will keep you informed about all new stuff here on the site via your rss reader (see the home page for the link to the rss feed). Thirdly you can keep an eye on the development page which has information about the latest progress on GpsPrune development. And fourthly you can use the "Check for new version" command in the "Help" menu in GpsPrune, which will show you whether you're running the latest version or not. Shortly before release of the new version, this dialog will give you an idea of when to expect the next release.