Rewrite a GPX file so that you change the name, description, and symbol
tags for the caches. This can provide more information at your fingertips
by giving geocaches custom symbols for different sizes and add extra
information to the name and description of your geocaches.
Command Line Syntax
|gpxrewrite settings_file [gpx_in.gpx [gpx_out.gpx]]|
gpxrewrite settings.ini my_query.gpx reformatted.gpx
settings_file: This is where all of the formats, symbols, and
other settings are kept. It is the only parameter that must be specified on
the command line.
gpx_in.gpx: The source of the data, which must be in the GPX
format that is returned from a Geocaching Pocket Query. Unknown things can
happen if you try to reformat a standard GPX file that is lacking the extra
groundspeak attributes. Unknown things are bad. If you do not specify a
file, you can instead pass one in with stdin. (If you're not sure what that
means, just specify the file on the command line.)
gpx_out.gpx: The rewritten GPX file will be either written out
to the file name that you specify or to screen. If you do specify a
filename, it will write without prompting. It will not even ask if you want
to overwrite an existing file, so be careful. If you do not specify a
filename, you can redirect output as you so see fit.
gpxrewrite requires a settings file, which I have called settings.ini,
but you are free to name it whatever you like. Settings are specified in a
key=value pair, one per line. Keys are case insensitive, and the last one
specified in the file is the one that is used.
These codes specify what will replace %C format codes. If you do not
change them, a default one-leter code is assigned for each prefix. See the
sample settings file below.
This determines the format used to rewrite the name and description tags
in the GPX file. If one is not specified, no change will be made for that
one tag. The name of the waypoint when you load it on your GPS is the
"name" tag, and that is changed with Waypoint_Format. Likewise, the
Desc_Format changes the "desc" tag, and that is used for the waypoint
description in your GPS. The format layout supports the format codes as
If specified, the waypoint name and description will be truncated/autofit
to be at most this many characters long. If not specified the name or the
description will not be truncated.
Filter the waypoint name and description to only contain some characters.
If you do not include this line in your config file, no characters will be
stripped. You do not need to specify letters (a-z and A-Z), numbers (0-9),
and some symbols (space and period). Every character counts, including
spaces, so "ab cd" is 5 characters: a, b, space, c, d.
Specifies the strings used when you use the %a, %b, and %f format codes,
depending on whether or not the specific cache is active, if it has at least
one travel bug, or if you have found the cache already.
Specifies the default symbols for geocaches that are found and ones that
are not found. Rules are checked from most specific to least specific, so
if you have a traditional micro cache that was not yet found, it will check
for "Traditional_Micro_Not_Found", then "Traditional_Not_Found" and finally
"Not_Found". If none of those settings are in the settings file, the
symbol will not change.
Formats for waypoint names and descriptions can use the following special
codes. When you use a % symbol as specified below, you will get it swapped
out with a different value. You can also specify a maximum width or that
this field should be automatically resized to fit into the name or
description field. See the Format Examples for an explanation.
||This is replaced with the Active_Yes or Active_No settings if specified, or Y/N otherwise.|
||This is replaced with the Bug_Yes or Bug_No settings if specified, or Y/N otherwise.|
||The prefix for the cache, as determined by the *_Prefix settings. T is the default for a traditional cache.|
||The difficulty of the cache.|
||The difficulty of the cache as a single number from 1 to 9, from the formula (difficulty * 2) - 1.|
||This is replaced by the Found_Yes or Found_No settings if specified, or Y/N otherwise.|
|Under the log by the stream.
||The hint from the geocache. Both the uppercase H and the lowercase h will work.|
||The code after the "GC" in the waypoint ID. If the waypoint doesn't start with GC, the entire code remains. This is an example for a waypoint GC1234.|
||The code after the first two characters in the waypoint ID. This is nearly identical to %I except that this always removes the first two characters. This is an example for a waypoint TB1234.|
||The first letters of the log types. The example is for a cache where the last five logs were "Found it," "Found it," "Didn't find it,", "Found it", "Write note."|
||Some Fake Cache
||The name of the geocache. This may change in the future to be "smart truncated" if anyone wants to get the name automatically shortened.|
||The owner of the cache.|
||KB & Crew
||Who placed the cache.|
||The first two characters of the waypoint code. With a combination of %p and %i you have more control over splitting up the waypoint code if you want. This is an example for the waypoint GC1234.|
||The size of the container.|
||The first letter of the size of the container.|
||The terrain rating of the geocache.|
||The terrain rating of the cache as a single number from 1 to 9, based on the formula (terrain * 2) - 1.|
||The cache type, spelled out.|
||The prefix for the cache as determined by the *_Prefix settings. T is the default for a traditional cache.|
||Adds a literal %. Implemented in case you want to really use % somewhere.|
|Adds a literal number. These are available if you wanted to add a number after a format code when you do not want to specify a length to the format code.|
For the following examples, we will assume we are dealing with the
following configuration settings and geocache.
# Mostly we will use the defaults
# A-Z, a-z, 0-9, period and space are
# allowed automatically if
# we specify this value
Desc: It's An Example - Test
Travel Bugs: None
Below are a few examples so you can understand how things are working
with the format layouts. For the format and result, the top line is the
waypoint name and the bottom is the description.
It's An Example - Test
|If you do not specify a Waypoint_Format or Desc_Format, they will not be changed. Also, since there is no format, the illegal characters will not be removed.|
It's An Example - Test
|The name has had the "GC" from the waypoint ID removed, and then the "_" was added since there were no bugs in the cache. The description is not changed because no Desc_Allowed_Chars was specified.|
%a%C %d=%D %t=%T
|Its An Exa
YT 2=1.5 3=2
|The apostrophe from the name is removed from the waypoint name because Waypoint_Allowed_Chars is set and does not contain the apostrophe as an allowed character. It is also truncated to Waypoint_Max_Length characters (10).|
|%I %Y0 %s
%L3 - %%L3 - %L%3
|TEST Tra S
FFD - %%L3 - FFDFW3
|The waypoint name has %Y0, which means we should try to fit as much of the cache type into the allowed space, and will always display at least 1 character. In this example, "TEST " takes 5 characters and " S" uses up 2. The maximum length is 10, which leaves at most 3 letters for the cache type. The description shows three similar formats with three very different results. %L3 means to show at most 3 letters from the cache logs. The double %% means to show a literal %. The last example shows how to put a literal number after another format code.|
|The name is truncated to 10 letters, and invalid codes are copied verbatim to the output.|
Sample Settings File
# This is a sample settings file that shows the default settings
# for all of the options.
# This is the default code that is used when you use the %C format code.
# My own personal waypoint name and description formats, lengths,
# and allowed characters. This is tweaked for my own personal preferences
# and what is allowed by my Garmin GPSMAP 60CSx. Change for your GPS and
# alter to what you like to see.
# I want to see a B or a - in my description instead of Y/N like Active and
# The defaults for Active and Found are fine
# Default symbols