SABX File Creation/Update Tutorial

v1.0.1, 2010-1-28

Jay Farrimond

Table of Contents


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.

Create An SABX File

The main thing you're going to want to do with SABX files is create them.

1 get a GPX or TCX file

I create these by downloading data from my GPS to the computer.

2 convert it into an SABX file

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

3 convert that into an HTML file

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

4 create a blank CSV file

sabx_csv does this with the "-b" option.


$ sabx_csv -b sample.csv

5 fill-in the ride description, parking, stops, pois, and roads in the 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.

6 use the HTML map to fill-in the starting and ending points for roads

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.

7 fill-in the parking, stop, and poi (lat,lon) with points or real (lat,lon) data

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.

8 merge the CSV file and the SABX file

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

9 add the USGS elevation data to the SABX file

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

10 remove any stray points from the SABX file

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.

11 renumber the updated SABX file

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

12 fill-in the rest of the data for the SABX file

Mostly this is just things like overall description, zip prefix, photos, and history. I use a text editor for this.

13 proof your work

Come on, you know you should!

Add A Ride To An SABX File

In addition to creating new SABX files, you're also going to want to add new rides to existing files.

1 create an SABX file containing the new ride

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.

2 re-number the new SABX file so it doesn't conflict with the old one

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

3 copy the parking, turns, segments, stops, and pois over to the old one

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.

4 re-point your duplicate segment stops and pois to ones already in 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.

5 copy the ride over

Copy the ride itself from the new file into the old one.

6 if using existing parking, point ride parking to existing one

If you're using an existing parking place in the new ride, change its reference in the ride.

7 if some new and old turns and/or segments are duplicates, point ride at originals

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.

8 get rid of any now-unused items

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

9 renumber the updated SABX file

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

10 add a change to the history reflecting new ride

Add a change to the history section of the SABX file with the current date and a description of what was added.

11 proof your work

Just go ahead and do it. You won't regret it.

Document History

v1.0.1 1/28/2010 Minor reformatting.
v1.0 12/23/2009 This is the initial release of the tutorial.