GPX Tools: gpxrewrite
Search:

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]]

Example:
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.

Settings File

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.

KeyDescription
Benchmark_Prefix
CITO_Event_Prefix
Earthcache_Prefix
Event_Prefix
Letterbox_Hybrid_Prefix
Locationless_Prefix
Mega_Prefix
Multi_Prefix
Project_APE_Prefix
Traditional_Prefix
Unknown_Prefix
Virtual_Prefix
Webcam_Prefix
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.
Waypoint_Format
Desc_Format
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 described below.
Waypoint_Max_Length
Desc_Max_Length
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.
Waypoint_Allowed_Chars
Desc_Allowed_Chars
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.
Active_No
Active_Yes
Bug_No
Bug_Yes
Found_No
Found_Yes
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.
Found
Not_Found

TYPE_Found
TYPE_Not_Found

TYPE_SIZE_Found
TYPE_SIZE_Not_Found
TypesSizes
Benchmark
CITO_Event
Earthcache
Event
Letterbox
Locationless
Mega
Multi
Project_APE
Traditional
Unknown
Virtual
Webcam
Large
Micro
Other
Regular
Small
Unknown
Virtual
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.

Format Codes

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.

CodeExampleDescription
%a Y This is replaced with the Active_Yes or Active_No settings if specified, or Y/N otherwise.
%b Y This is replaced with the Bug_Yes or Bug_No settings if specified, or Y/N otherwise.
%C T The prefix for the cache, as determined by the *_Prefix settings. T is the default for a traditional cache.
%D 2.5 The difficulty of the cache.
%d 4 The difficulty of the cache as a single number from 1 to 9, from the formula (difficulty * 2) - 1.
%f N This is replaced by the Found_Yes or Found_No settings if specified, or Y/N otherwise.
%H
%h
Under the log by the stream. The hint from the geocache. Both the uppercase H and the lowercase h will work.
%I 1234 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.
%i 1234 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.
%L FFDFW 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."
%N 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.
%O King Boreas The owner of the cache.
%P KB & Crew Who placed the cache.
%p GC 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.
%S Small The size of the container.
%s S The first letter of the size of the container.
%T 3 The terrain rating of the geocache.
%t 5 The terrain rating of the cache as a single number from 1 to 9, based on the formula (terrain * 2) - 1.
%Y Traditional Cache The cache type, spelled out.
%y T 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.
%0
through
%9
0
through
9
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.

Format Examples

For the following examples, we will assume we are dealing with the following configuration settings and geocache.

SettingsGeocache
# Mostly we will use the defaults
Waypoint_Max_Length=10

# A-Z, a-z, 0-9, period and space are 
# allowed automatically if
# we specify this value
Waypoint_Allowed_Chars=!@#$%^&*()

Bug_Yes=B
Bug_No=_
Name: GCTEST
Desc: It's An Example - Test
Difficulty: 1.5
Terrain: 2
Logs: FFDFW
Type: Multi-cache
Size: Large
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.

FormatResultNotes
  GCTEST
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.
%I %b
%N
TEST _
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.
%N
%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.
garbage in
%G%A%R%B%A%G%E out
garbage i
%G%A%R%B%A%G%E out
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.
Benchmark_Prefix=X
CITO_Event_Prefix=C
Earthcache_Prefix=G
Event_Prefix=E
Letterbox_Hybrid_Prefix=B
Locationless_Prefix=L
Mega_Prefix=E
Multi_Prefix=M
Project_APE_Prefix=A
Traditional_Prefix=T
Unknown_Prefix=U
Virtual_Prefix=V
Webcam_Prefix=W

# 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.
Waypoint_Format=%I %s%d%t
Waypoint_Max_Length=14
Waypoint_Allowed_Chars=+-

Desc_Format=%C%b%L
Desc_Max_Length=30
Desc_Allowed_Chars=+-

# I want to see a B or a - in my description instead of Y/N like Active and
# Found
Bug_Yes=B
Bug_No=-

# The defaults for Active and Found are fine
Active_Yes=Y
Active_No=N
Found_Yes=Y
Found_No=N

# Default symbols
Found=Geocache Found
Not_Found=Geocache_Found

Courage is not simply one of the virtues, but the form of every virtue at the testing point. Tyler Akins! <>
Contact Me - Legal Info