v1.0.1, 2010-1-28
Contact:
Jay Farrimond
jay@sabikerides.com
http://www.sabikerides.com/
This tutorial expects you to have a firm grasp of the layout of an SABX file and the intricacies of how its data elements interact. Please first read the SABX file format specification here if you don't already know this. Since there is quite a bit of hand-editing of SABX files necessary for these tutorials, understanding their layout is essential. You'll also need to have the sabx10 package installed so that the utilities mentioned in this tutorial will be available.
The main thing you're going to want to do with SABX files is create them.
I create these by downloading data from my GPS to the computer.
The utilities gpx2sabx and tcx2sabx are used for this.
For the example I'll assume we're starting with a GPX file named sample.gpx. I'll convert it into a file named sample_raw.sabx to denote that it's the raw, unprocessed SABX information.
$ gpx2sabx -i sample.gpx -o sample_raw.sabx
Use sabx2html for this. It creates an HTML file that contains a Google Map of the ride with the waypoints as pushpins for easy identification.
$ sabx2html -i sample_raw.sabx -o sample.html
sabx_csv does this with the "-b" option.
$ sabx_csv -b sample.csv
Open the blank CSV file and fill it in. I usually use the OpenOffice spreadsheet program for this. The help for sabx_csv explains what all the fields are and how to use them.
Look at the waypoints on the HTML map and decide which ones are the start and end points for each segment. Remember that adjoining segments will end on one point and then start on the next one (no overlap). This is because the SABX format assumes that the end point for a segment is really the starting point of the next segment and adjusts things accordingly.
Again, use the HTML map to choose points for parking, stops, and pois. If you have actual (lat,lon) values for any of those, use them instead. When merging with the SABX file, any (lat,lon) values for the stops and pois will be matched to the closest waypoints.
Use sabx_csv for this. It will merge the data from the two files together and form an SABX file from it all. Look over the new SABX file to make sure everything looks right.
Notice that we put the merged data into sample.sabx, preserving the sample_raw.sabx file. This way we can re-run the merge if we find any major problems when inspecting the new file.
$ sabx_csv -i sample_raw.sabx -o sample.sabx sample.csv
Use sabx_usgs for this.
Notice that I am specifying the same file name for both input and output files. This effectively updates sample.sabx by over-writing the original copy with the updated copy.
$ sabx_usgs -i sample.sabx -o sample.sabx
While mapping the ride, I sometimes will make stops, stray from the course, turn around to get people, etc... This can create extra waypoints in the ride that look funny and give bad distances when processed. Use the HTML map to identify any of these and remove them from the SABX file by hand using a text editor.
Renumber the updated SABX file so that its ids are consistent. You don't have to do this to make things function, but it's nice for anyone who has to later read the file.
$ sabx_number -i old.sabx -o old.sabx
Mostly this is just things like overall description, zip prefix, photos, and history. I use a text editor for this.
Come on, you know you should!
In addition to creating new SABX files, you're also going to want to add new rides to existing files.
Start off by following the instructions of section 2 to create a new SABX file with the new ride.
For this example, we'll call the new file new.sabx and the existing file old.sabx.
Next, renumber the new SABX file so that its ids don't clash with those of the SABX file you're adding to. Open the old file in a text editor and look through it to see what its highest id is. I usually then renumber the new file to a much higher starting value just to be sure nothing overlaps.
$ sabx_number -i new.sabx -o new.sabx -s 10000
Open the old and new SABX files in a text editor. Copy the parking, turns, segments, stops, and pois from the new file to the old file.
It's common for new rides to share stops and pois with the rides in the old SABX file. Change the references in the new segment waypoints to point to the old stops and pois that they share.
Copy the ride itself from the new file into the old one.
If you're using an existing parking place in the new ride, change its reference in the ride.
It's common for new rides to have some overlap with the rides in the old SABX file. Point the new ride to the old segments and turns so that new and old rides share them. Do this by changing the references in the new ride to have the ids from the old turns and/or segments.
Now that you have copied all the information for the new ride into the old file, and pointed the new ride to use existing parking, turns, segments, stops, and pois, there is probably some unused data items left over from the new file. Use the sabx_cleanup utility to remove these from the updated SABX file.
$ sabx_cleanup -i old.sabx -o old.sabx
Renumber the updated SABX file so that its ids are consistent. You don't have to do this to make things function, but it's nice for anyone who has to later read the file.
$ sabx_number -i old.sabx -o old.sabx
Add a change to the history section of the SABX file with the current date and a description of what was added.
Just go ahead and do it. You won't regret it.
| Version | Date | Description |
|---|---|---|
| v1.0.1 | 1/28/2010 | Minor reformatting. |
| v1.0 | 12/23/2009 | This is the initial release of the tutorial. |