|
3D Route Builder User Guide - For Version 0.2.2.1
Installation - Windows XP / Vista / 2000
Download version 0.2.2 from the download page. Once the download is complete, double click the installer to begin installation. If the default settings were used then to start 3D Route Builder, go to the Start menu, then Hybrid GeoTools, then to the 3D Route Builder folder.
IMPORTANT: If you are running a pre-Vista Windows operating system then the Microsoft .NET 2.0 Framework must be installed before running the application. If it is not installed then you will see an error message on starting 3D Route Builder. .NET is a Microsoft component and is a free download.
Note that Microsoft do not guarantee compatibility of .NET 2.0 with Windows XP SP1.
Overview
All items in the main Route menu can also be accessed by right clicking on the grid.
Getting Started - Importing Data
There are a number methods of getting data into 3D Route Builder.
1. Opening an existing KML or KMZ file containing one or more paths (KMZ is simply a zipped KML)
Click File : Open Route... and select a KML or KMZ file that you know contains one or more paths (LineStrings with a coordinates node). These LineStrings comprise one or more coordinates in the format longitude,latitude,altitude[SPACE]longitude,latitude,altitude ...For example:
<coordinates>8.3257,46.596,1622.1 8.324,46.596,1634.3</coordinates>
This method will clear any existing data. To add or insert data from file use Route : Import : Insert... or Route : Import : Add... Add always puts the new points at the end of the current route, while Insert puts the data before the first currently selected point (the row in the grid with the arrow at the left).
For information on creating KML files from routes in Google Earth see here.
2. Opening an existing GPS Exchange format file (GPX) containing one or more paths
Click File : Open Route... and select a GPX file containing either a route <rte> or a track <trk>.
The grid will fill with the available points. As with opening a KML file it is also possible to insert or add to a current route by using of Route : Import : Insert... or Route : Import : Add...
If present, time-stamp information will also be imported and automatically matched to any existing time-stamps on the route.
Note that other than the path the original GPX or KML file
3. Add or Insert Point from Geo Tool
To add the current location in Google Earth to the grid click Route : Insert Point from Geo Tool (Shift-Ins) or Route : Add Point from Geo Tool (Ins)
Activating Google Earth from 3D Route Builder
Any operation in 3D Route Builder that explicitly requires the use of Google Earth will automatically start it if it is not already started. Starting Google Earth can take some time therefore it is possible to modify the time-out settings in the options. Once started, logging in takes place. If you have a Plus or higher account then watch out for a log-in screen that may be hidden by 3D Route Builder. If Google Earth cannot log in then 3D Route Builder can continue for some functionality such as driving in off-line mode. Updating altitudes and editing routes is not possible off-line.
3D Route Builder will create three features in the Temporary Places folder of Google Earth:
- Route Builder Crosshair : a crosshair in the middle of the Google Earth view
- Route Builder Driver : a network link that will control a car icon that will move when driving a route
- Route Builder Path Viewer : a network link that will show the current route
If for any reason these items are not appearing in Google Earth places panel then go to Tools : Options, then the Google Earth tab and click Force Google Earth Feature Refresh. Next time you perform anything that requires Google Earth the features will reappear.
On closing 3D Route Builder these items will be removed.
It can happen that Google Earth occasionally does not refresh the Route Builder Driver and Route Builder Path Viewer network links. The car no longer moves when driving and the route is no longer updates when changes have been made. The normally green circle on the network links in Google Earth becomes orange and moves. To reestablish a network link right click on it in the Google Earth Place panel and click Refresh.
Viewing and Moving
To see the route and all selected points in Google Earth, click Route : Refresh Route in Geo Tool (Ctrl+R). To move to a specific point either double click at the left of the row, or hit F8 or click Route : Points : Fly to Point in Geo Tool.
To find the point in the 3D Route Builder grid that is closest to the current location in Google Earth, hit F6 or click Route : Points : Highlight Closest Point to Current Geo Tool Location. It is also possible to highlight a point via the Profile. Right click near the desired point and select Highlight Closest Point.
Moving through Google Earth is done as normal, though you may find for editing many points and accurate work that the use of a 3DConnexion SpaceNavigator simplifies life dramatically. Using this in your left hand and then using the keyboard shortcuts for editing with your right becomes natural.
Driving
Google Earth features a built-in pseudo driving mode for paths. 3D Route Builder takes it a step further by handling tunnels and aircraft and improving tracking and allowing real-time (scalable) driving based either on GPS time-stamps, manually entered time-stamps (do not need to be complete) or a default speed. The target is updated via a NetworkLink in Google Earth with a refresh rate of once per second. The car is followed by a “helicopter” from which the view is seen. It is possible to set a minimum and maximum range and tilt for the helicopter (the distance and angle between the helicopter and the target). If the imagery is good and the terrain not too mountainous then set these values lower, else it is generally best to set them higher.
.
Driving begins at the currently selected point in the grid. The main user interface will disappear to be replaced by a small progress dialog. Available info includes:
- Time (and scale factor if not set to 1)
- Distance Traveled (represented also by progress bar)
- Speed
- Altitude
- Section Grade
Stopping driving will return you to the main interface and select the point closest to where driving was stopped.
Set the range, tilt, scale, default speed and whether to use absolute or clamped to ground driving in options.
Updating Altitudes / Elevations
Altitudes can be fixed by checking the Fix Alt check box for a particular point. Fixing a point prevents the altitude from being accidentally updated and also forms the basis of altitude smoothing (i.e. you fix the points you are confident about).
Updating from Google Earth
Paths in KML files saved from Google Earth and many downloaded from popular trail / path sharing website do not contain altitudes. Loading a KML file saved from Google Earth or one of these other files into 3D Route Builder will show all altitudes to be zero (0). To update these, select one or more points in the grid (use Ctrl-A to select all) and then click Route : Altitude : Update from Geo Tool (or hit F12).
Updating based on Interpolation
Selecting one point in the grid then clicking Route : Altitude : Update based on Interpolation will calculate the altitude based on the point before and after the selected point. It is not possible to select the first or last point of a route. Selecting more than one point will interpolate between the first and last selected point.
Nudging Points Up and Down
It is possible to enter a new altitude directly into the grid. It is also possible to select multiple points and “nudge” the altitude up and down using Route : Altitude : Increase (F10) and Route : Altitude : Decrease (F9). By altering the tilt of Google Earth you immediately see the effect. In the options it is possible to alter the interval of altitude change. IMPORTANT: Unless the Clamped to ground option is unchecked you will not see any changes to the altitude. For clarity it is also best to have the Extend to ground option checked to give a curtain effect below the route. Also be aware that if the Clamped to ground option is unchecked that the altitudes are absolute and if the absolute altitude is underground then the route and any highlighted points will not be visible.
Smoothing
Smoothing altitudes removes irregular spikes and glitches from an altitude profile. Select multiple points and then click Route : Altitude : Smooth... The Altitude Smoothing tool will appear.
Smoothing can be done by Point Averaging or Interpolation. Interpolation basically will produce a straight line between fixed points. If no fixed points have been specified (see here for info on fixing points). The first and last selected point are always regarded as fixed. Point Averaging also works around fixed points but produces more natural results. Some options are available when using Point Averaging:
- Interval - the gap in metres between points used in averaging
- Distance - the distance before and after the point with which to base the averaging
To preview the results click Preview. The original and new profile will be displayed. It is possible to zoom into the graph by either drawing a box around the desired region or using the scroll wheel. Holding the Ctrl key while moving the mouse enables panning. The right mouse button brings up a menu with a variety of options including displaying point information and printing.
Profile
By checking View : Profile the altitude profile appears on the main form. Right click to bring up a pop-up menu with various options. It is not possible to edit the profile or perform vertical zooming on this profile.
Editing Points
Distances are in meters and the distance between points is measured using the small angle formula (i.e. it does not take altitude differences into account, so sections that are of steep gradient (> 20%) will have increasingly unrealistic distances).
Deleting Points
Points can be deleted by selecting the relevant rows and then pressing Del key or clicking Route : Delete Point(s)... or Route : Points : Delete All Points...
Adding and Inserting Points from Geo Tool
To add the current location in Google Earth to the grid click Route : Insert Point from Geo Tool (or press Shift-Ins) or Route : Add Point from Geo Tool (or press Ins). Add always puts the new points at the end of the current route, while Insert puts the data before the first currently selected point (the row in the grid with the arrow at the left). An alternative to the first is Route : Insert Interpolated Altitude Point from Geo Tool which does exactly the same in terms of location but instead of using the altitude from Google Earth, it interpolates the altitude between the previous and next points. This is very useful when working on routes with tunnels and bridges or flight paths.
Replacing (Moving) a Point
Select a single point in the grid to replace with the current location in Google Earth. Click Route : Replace Point from Geo Tool (or press F7)
Nudging Points Forward, Backward, Left and Right
If selected in the options you can move a point by a user definable distance to the left, right, backward or forward. If Google Earth is started then this direction is relative to the current view (azimuth) else it corresponds to west, east, south and north.
Reversing a Route
A complete route can be reversed by clicking Route : Points : Reverse Complete Route
Redundant Points
A redundant point is defined as a point that is within a user defined distance of the previous point. This distance is termed the threshold. The threshold can be altered in the options. All redundant points can be deleted with Route : Points : Delete All Redundant Points and it is possible to step through redundant points with Route : Points : Find Next Redundant Point (or hit Shift-F3)
Time
Time-stamps can either be imported from GPX files or added and edited manually. This powerful feature means that it is easy to add time information to routes either created manually (e.g. KML or directly from Route Builder) or to GPX files that do not have them. Perhaps you wish to sync to a helmet cam video you made? It is not necessary to enter all the time-stamps. At a minimum only one time-stamp is required (so long as it is not at the first point). All other time-stamps are calculated from this.
Time-stamps can be entered and edited directly in the Time column. Route : Time : Update based on Interpolation will fill in time-stamps based on available time-stamps. Time-stamps can be cleared with Route : Time : Clear... (or press Shift-Del).
One or more points can be shifted by use of Route : Time : Nudge.... This permits the selected (continuous) points to be moved within their current time window frame.
Two or more points can be scaled by use of Route : Time : Scale.... This permits the time frame or span (the time between the first and last selected points) of the selected (continuous) points to be increased or decreased by specifying either a new time span or a percentage of the original.
The start date can be seen and edited in the Route Properties. All times are relative to this date.
Route Properties
Basic properties of a route can be accessed by Route : Properties...
The name, description and start time can be edited.
Exporting a Route
3D Route Builder can export routes in a number of different formats. Click File : Export as... and select the required format.
KML and KMZ are generally used with Google Earth; KMZ being simply a compressed KML file. Note that if you began by loading a KML file into 3D Route Builder that all information in this file other than the paths (LineStrings) will be lost when saving. 3D Route Builder creates a new KML / KMZ file with a single path representing the route. Any selected points in the grid will be saved as individual placemarks. If these selected points do not contain descriptions then a description will be automatically generated of format:
D: 91.45m A: 1634.39m G: -3.44%
where D = Distance to next point, A = altitude, and G = gradient to next point
GPX is GPS Exchange format and is compatible with the majority of GPS devices. As per KML files, if you imported or started with a GPS file then all information will be lost and 3D Route Builder will generate a new GPS file based on the route. When exporting as GPX, the data is stored as route points (rtept). If one (not first point) or more time-stamps are present then time-stamps will be created for all points.
CRS is a Garmin GPS device course such as from the Forerunner and Edge 305 models. An exported CRS can be uploaded to these devices or viewed in Garmin Training Center software.
CSV (Comma Separated Values) saves each point as a line with the values of the currently visible columns separated by commas. This data can be imported into software such as Microsoft Excel. Columns can be hidden via the options. Only visible columns will be saved.
XML: Pro Cycling Manager format. A simple XML file that can be used as a basis for building routes in the popular computer game Pro Cycling Manager.
SAL is the file format used by the Salitaker tool for producing mountain pass profiles found on many cycling websites. Points at user specific intervals are saved, therefore it is not possible to recreate the full data from such a file and short climbs are not well represented. The interval can be specified in the options.
The table below summarizes the formats:
|
Feature
|
KML
|
KMZ
|
GPX
|
CRS
|
CSV
|
SAL
|
XML (Pro-Cycle)
|
|
Route Name
|
X
|
X
|
X
|
X
|
|
Filename
|
|
|
Route Description
|
X
|
X
|
X
|
|
|
|
|
|
Route Total Distance (Explicit)
|
|
|
|
X
|
|
X
|
|
|
Point Names
|
|
|
X
|
|
X
|
|
|
|
Point Locations (Longitude / Latitude)*
|
X
|
X
|
X
|
X
|
X
|
|
|
|
Point Description
|
|
|
X
|
|
X
|
X
|
|
|
Point Distance
|
|
|
|
X
|
X
|
X
|
|
|
Point Distance To
|
|
|
|
|
X
|
|
X
|
|
Point Altitude
|
X
|
X
|
X
|
X
|
X
|
X
|
X
|
|
Point Gradient To
|
|
|
|
|
X
|
|
X
|
|
Point Bearing To
|
|
|
|
|
X
|
|
|
|
Point Time
|
|
|
X
|
|
X
|
|
|
|
Compressed
|
|
X
|
|
|
|
|
|
|
* Distances, bearings and gradients are recalculated upon reloading the GPX, KML or KMZ file into 3D Route Builder.
Saving a Route
3D Route Builder can save routes in GPX format. Click File : Save as.... In almost all respects the behavior is as per the equivalent Export function. However if time-stamps are present then when saving only the points that actually have time-stamps will be saved with time-stamps. It therefore
Note: If a route is edited or built based on an non-3D Route Builder GPX file then the format and possibly extra information of the original file will be lost.
Options
Via the Tools menu are the Options.... The options are split into three tabs.
Editor Tab
By checking and unchecking the columns it is possible to control which columns in the main grid are visible. Checking Keep this program on top will keep 3D Route Builder above all other applications - convenient when working with Google Earth as is adjusting the Opacity.
Google Earth Tab
The Google Earth related options are split into five sections:
General:
3D Route Builder will start Google Earth when necessary. First time around this takes time. How long to wait can be controlled by setting the Initialize delay and Log-on delay in seconds. 3D Route Builder also creates three Features in Google Earth: Crosshair, Car icon and Route path. If these for any reason do not appear or have disappeared then click Force Google Earth Feature Refresh. Next time a Google Earth related function is used the features will reappear.
Point Updating:
When updating point altitudes 3D Route Builder will fly between locations in Google Earth. There is a potential delay in this dependent on machine speed, internet connection and responsiveness of the Google Earth server. To ensure that accurate data is obtained it is possible to set a Timeout for streaming (milliseconds) for Google Earth to reach a certain percentage of streaming (Wait for streaming % to reach). Timeout fo fly to (milliseconds) sets the maximum time Google Earth is allowed to take between points. NOTE: When updating altitudes, the Google Earth flying speed is set to “Teleport” (speed = 5.0). Max. Distance (metres) governs how close Google Earth must get to the point being updated before performing the update.
Flying:
This corresponds to the Google Earth flying speed settings and governs the time taken to fly from one point to the next when double clicking a point in the grid (or clicking Route : Fly to Point in GeoTool). If set to 1.0 then it will take approximately one second to get to the desired point, no matter how far away it is. If set to 0.1 it will take 10 seconds (1 / 0.1). If set to 5.0, the mode is said to be “Teleport” and travel time is almost instant.
Driving:
You can set the driving Default Speed in kilometers per hour - this will be used when no time-stamps are available. A Speed Scaling Factor can be applied that will increase or decrease the playback speed. Selecting Force Default Speed will override any time-stamps and use the Default Speed. The target follows the route and is seen from a helicopter viewpoint.
The minimum and maximum distance (more than 1 metre) and tilt (0 - 90 degrees) with which the helicopter tracks the target can be set with Tracking Range and Tracking Tilt. 0 degrees tilt is looking down vertically, 90 would be horizontal. Depending on the terrain quality and shape it is worth experimenting with these settings. The helicopter tries to fly as low as possible but will rise when the target passes through bends. The sharper the bend the steeper the angle above the target. This is to avoid collisions with landscape and avoid delays while swinging around.
Disable Helicopter Tracking allows you to manually follow the car.
Absolute Altitude Tracking means that the helicopter tracks the target’s altitude instead of the Google Earth surface. Select this option if your route has tunnels, bridges or flight paths and you wish to follow these.
Path:
The route being worked on can be shown live in Google Earth. The Width of the path can be set in pixels. Extend to ground draws a curtain effect beneath a path that is at an absolute altitude higher than the Google Earth terrain under it. In order for this to have effect absolute altitudes must be used. To do this uncheck Clamped to ground. Refresh on Point Select controls whether the selected points in the grid are automatically shown in Google Earth. If Show Point Names is unchecked then the point number is sown alongside selected points instead of the point name.
Geo Tools - General:
Altitude Options include Skip Fixed Points in Update: this means that any selected points in a mass altitude update that are set to Fixed Altitude will be missed out of the update. If unchecked an error would be given before the update began warning that fixed points have been included. The Adjust Interval is the distance in meters the altitude is altered each time by Increase and Decrease nudging.
Location Options: Redundant Point Threshold is the distance threshold in meters at which a point could be considered redundant if it is less than. Default Range is the maximum distance in meters between the camera and the focus point that the updating and fly to will use. If the current range is less than the default range then the current range will remain unchanged. Adjust Interval is the distance in meters the location nudge will move a point when the arrow keys are enabled. Enable the arrow keys by checking Enable Arrow Keys for Adjust.
When exporting data in Salitaker format it is possible to select the interval between spot heights. For longer climbs, 500 metres is standard but this can be varied.
Keyboard Shortcuts
|
Command
|
Keystroke(s)
|
Action
|
|
File Menu
|
Alt + F
|
Opens the File menu.
|
|
View Menu
|
Alt + V
|
Opens the View menu.
|
|
Route Menu
|
Alt + R
|
Opens the Route menu.
|
|
Tools Menu
|
Alt + T
|
Opens the Tools menu.
|
|
Help Menu
|
Alt + H
|
Opens the Help menu.
|
|
Open File
|
Ctrl + O
|
Opens the file open dialog box, allowing you to open all supported 3D Route Builder file types.
|
|
Insert Point from Geo Tool
|
Shift + Ins
|
Inserts a point into the route from Google Earth.
|
|
Insert Interpolated Altitude Point from Geo Tool
|
Ctrl + Ins
|
Inserts a point into the route from Google Earth with altitude interpolated between previous and next point.
|
|
Add Point from Geo Tool
|
Ins
|
Adds a point at the end of the route from Google Earth.
|
|
Delete Point(s)
|
Del
|
Deletes all selected points after asking for confirmation.
|
|
Refresh Route in Geo Tool
|
Ctrl + R
|
Shows the route in Google Earth. (Can be performed automatically if selected in options)
|
|
Drive Route in Geo Tool
|
Shift + F5
|
Drives the route in real-time in Google Earth beginning at the first selected point.
|
|
Update Altitude from Geo Tool
|
F12
|
Updates the altitude of the selected points from Google Earth.
|
|
Increase Altitude
|
F10
|
Increases the altitude of the selected point(s) by an amount defined in the options.
|
|
Decrease Altitude
|
F9
|
Decreases the altitude of the selected point(s) by an amount defined in the options.
|
|
Nudge Point Location
|
Arrow Keys
|
Moves the location of the selected point(s) by an amount defined in the options. (NOTE: The arrow keys must also be enabled in options)
|
|
Highlight Closest Point to Current Geo Tool Location
|
F6
|
Highlights the point in the grid view that is closest to the location pointed to by Google Earth.
|
|
Replace Point from Geo Tool
|
F7
|
Moves the currently selected point to the location pointed to by Google Earth.
|
|
Fly to Point
|
F8
|
Flies to the location pointed to by Google Earth at the default flying speed as set in the options.
|
|
Find Next Redundant Point
|
F3
|
Finds the next point that has is under the redundant point threshold.
|
|
Clear Times
|
Shift + Del
|
Clears the time from the selected points after asking for confirmation.
|
|
How to make KML files using Google Earth
Instead of starting a route from scratch it is often easier to use Google Earth itself to produce the first version of a route. Simply right click on any existing location or on a placemark you dropped on or near a road. Then select either Directions from here or Directions to here. The route details will be shown in the Search panel. Open the tree if necessary and scroll down to the Route. Right click and select Save as... Choose KML as the file type. This file can then be loaded into 3D Route Builder.
Click here to go to the Google Earth documentation on this subject.
Known Issues
GPX/KML format errors with ASCII files: Some files available from the various download websites contain invalid formats. Version 0.2.1 does not handle this gracefully. Basically these files do not explicitly say that the format is ASCII while the software regards it as UTF-8. Then characters such as umlauts and accents found in French and German that have an ASCII value greater than 127 cause an issue. To workaround this issue until before the next release, open the GPX or KML file in a text editor and add encoding="ASCII" to the first line. Therefore <?xml version="1.0"?> becomes <?xml version="1.0" encoding="ASCII"?>
Network links lost on certain machines: When many points are selected and also shown in Google Earth the network link has been observed as being unstable on one dual core machine.
Crossing the Prime Meridian: If your route goes over the prime meridian (i.e. longitude zero) then you may well experience a bumpy ride for a short time. Google Earth does not enjoy this but does recover after a few moments. It’s been reported and hopefully Google will fix this.
Salitaker Export makes unusable files with some operating systems versions: If you use an operating system in a language that uses commas for the decimal separator then the output for Salitaker is invalid. Until the fix is made it is possible to do a search and replace i the sal file using a text editor.
Incorrect start time set: Loading a GPX file without timestamps results in an invalid start time being set in the route. It is then impossible to export the file with timestamps added (GPX or CRS). Workaround is to go to Route Properties and enter a valid start time manually.
Error on saving Garmin CRS file with a name less than 15 characters: If the name of the route (see Route Properties) is less than 15 characters then you will get an error. Workaround this by padding the name with additional characters (not blank spaces).
Please report your findings here!
|
