1CMCONVERT(1) General Commands Manual CMCONVERT(1)
2
6 cmconvert - CacheMate waypoint file converter
7
9 cmconvert [-a] [-A] [-b] [-B] [-C] [-D] [-f] [-F] [-h] [-H] [-l] [-L]
10 [-N max_log_count] [-o output_file] [-O] [-q] [-s] [-S] [-t] [-T] [-v]
11 [--owner=owner_name] [--country=country] [--state=state] [--cont=con‐
12 tainer] [--sym=symbol] [--type=cache_type] [--excl=waypoint_list]
13 [--radius=distance,lat,lon] [--radius=distance,waypoint] [--filter=fil‐
14 ter_file] input_file1[,input_file2...] [waypoint ...]
15
17 cmconvert is a file converter, which takes one or more EasyGPS LOC or
18 GPX XML files as input and outputs a Palm database file that CacheMate
19 (a geocaching database for Palm OS) can import. GPX file extensions
20 specific to Geocaching.com, Geocaching.com.au and TerraCaching.com are
21 converted as well. These extensions are referred to as "site-specific"
22 features throughout this document.
23 Selection of waypoints to convert (and later import) is possible by
25 specifying the waypoint names on the command line after the input file.
26 Waypoints contained in the input file may also be listed along with
27 descriptive information. Selection by certain criteria is also possi‐
28 ble, using the filtering options documented below.
29
31 -B Includes travel bug names from Geocaching.com GPX files in the
32 description field.
33 -C Includes container type/size from site-specific GPX files in the
35 description field.
36 -D Includes date information from GPX files in the description
38 field, if available.
39 -h Generates an HTML file, name based on the output PDB file name,
41 which contains URLs for any links and images found in HTML
42 descriptions for records that are converted. The file will con‐
43 tain links to the cache page and any contained links for caches
44 that have them (plain text descriptions and HTML descriptions
45 that are just text are omitted).
46 -H Prevents the encoding of hint text from site-specific GPX files.
48 -l Lists waypoints names from input file, along with description,
50 terrain and difficulty information if available. If any filters
51 are in place or waypoint names are specified, only those that
52 are selected will be listed.
53 -L Includes cache location (state/province and/or country) from
55 site-specific GPX files in the description field.
56 -N max_log_count
58 If specified with a count of at least 1, cache logs from a site-
59 specific GPX file will be imported, until one of three per-cache
60 limits is reached: specified log count, number of logs in the
61 record, or 8k of log information. Each log entry is trimmed to
62 3k in size, if it is larger than that.
63 -o output_file
65 Specifies the file to which cmconvert writes the resulting Palm
66 database file. The default name is based on the first input
67 file name, with a .pdb extension.
68 -O Includes cache owner from site-specific GPX files in the
70 description field.
71 -q Suppresses all output except error messages.
73 -s Causes the parser to semi-intelligently strip quotes from cache
75 names.
76 -S Includes cache status (active/inactive) from site-specific GPX
78 files in description field.
79 -t Adds items taken/left template to log notes field for each con‐
81 verted record.
82 -T Force old (pre-1.8.3) method of dealing with duplicate records
84 (see below).
85 -v Displays version and copyright notice.
87
89 Versions of CMConvert older than 1.8.3 compared entire converted
90 records to determine whether or not records from different input files
91 were duplicates of each other. If there were differences in records
92 with identical waypoint names, both records would be included and would
93 then appear to be duplicates.
94 The current behavior is to use file timestamps and compare waypoint
96 names between old and new records. If a match is found, the old record
97 will be updated if the new record comes from a file with a later time‐
98 stamp. If an input file is in GPX format and contains a file-level
99 timestamp, that will be used. Otherwise, the last-modified time of the
100 file is used.
101
103 The following options may be used to select waypoints for conversion
104 based on certain critera. Most of the options only apply if supported
105 site-specific information is in the GPX file being converted, and may
106 otherwise result in no waypoints being converted.
107 Filters that use an argument, except for radius filters, do a case-
109 insensitive search of the corresponding field for a match, to make them
110 forgiving of incorrect case and allow for partial search strings. For
111 example, a cache type filter of "event" will match the text "Event
112 Cache" from the GPX file. Multiple search strings are also possible,
113 when separated by colons (:). Specifying one of these options more
114 than once will add strings to that filter, instead of replacing it.
115 All filtering options, including waypoints specified on the command
117 line, are additive in their effects. For example, a search combining
118 the "found" and "not found" filters on a Geocaching.com pocket query
119 will result in no records being converted.
120 -a Selects only caches that are active, according to site-specific
122 information in the GPX files. If this information is not
123 present in the input file (as with LOC files), the cache is
124 assumed to be active.
125 -A Selects only caches that are inactive, using the same criteria
127 as the -a filter option.
128 -b Selects only caches that have travel bugs.
130 -f Selects only caches that have been found (symbol name = "Geo‐
132 cache Found").
133 -F Selects only caches that have not been found (symbol name =
135 "Geocache").
136 --cont=container_type
138 Filters caches based on container type (regular, micro, etc.).
139 --country=country
141 Filters caches based on the country where they are located.
142 --state=state
144 Filters caches based on the state or province where they are
145 located.
146 --owner=owner_name
148 Filters caches based on the owner's name.
149 --type=type_name
151 Filters caches based on cache type (traditional, event, virtual,
152 etc.).
153 --sym=symbol_name
155 Filters waypoints based on symbol name.
156 --radius=distance,lat,lon
158 Filters waypoints based on distance from a certain set of coor‐
159 dinates. Distance is a number of kilometers (n.nnK, n.nnKM),
160 statute miles (n.nnMI) or nautical miles (n.nnM, n.nnNM). If no
161 unit is specified, nautical miles are assumed by default. The
162 latitude and longitude are expressed as decimal degrees.
163 --radius=distance,waypoint
165 Filters waypoints based on distance from a given waypoint. Dis‐
166 tance is expressed in the same way as the more explicit radius
167 filter.
168 --excl=waypoint_list
170 Allows an exclusion filter on waypoint names.
171 --filter=filter_file
173 Specifies a file from which to read name/value pairs, in the
174 format name=value, which correspond to any of the string/radius
175 filter types. The options in the filter file will be applied as
176 if they were expanded into command-line arguments where this
177 option is specified.
178
180 Most fields in GPX files from TerraCaching.com are mapped to their
181 equivalent CacheMate fields, which are based on those used by Geo‐
182 caching.com. Some that may not be so obvious are:
183 Mental challenge -> Difficulty
185 Physical challenge -> Terrain
186 The "camo challenge" rating is prepended to the description text, if
188 present.
189
191 The following are various examples of cmconvert with different filter‐
192 ing options.
193 To list all of the caches that you haven't found, that contain travel
195 bugs and are owned by bartacus or honeychile, you might do the follow‐
196 ing:
197 cmconvert -lFb --owner=honeychile:bartacus caches.gpx
199 To list all caches located within 5 miles of the coordinates N36/W80,
201 you would enter:
202 cmconvert -l --radius=5M,36,-80 caches.gpx
204 A simpler example, this command would list all of the micro caches in
206 the input file:
207 cmconvert -l --cont=micro caches.gpx
209 This command converts the caches listed above into a PDB file
211 (caches.pdb) to import into CacheMate:
212 cmconvert --cont=micro caches.gpx
214 The following commands merges two GPX files into a single import file
216 (caches.pdb):
217 cmconvert caches.gpx,benchmarks.gpx
219
221 cmconvert is free; anyone may redistribute copies of it to anyone under
222 the terms stated in the GNU General Public License, a copy of which
223 accompanies each copy of cmconvert.
224
226 Brian Smith <brian@smittyware.com>
227 12 May 2010 CMCONVERT(1)