geoqo (1) - Linux Manuals
geoqo: Geocaching DataBase
NAME
geoqo - Geocaching DataBase
ABOUT GeoQO
The geoqo program is designed to be:
- usable with a graphical user interface
- usable on the command line
- fast (uses a database (mysql, postgresql, sqlite2 or sqlite supported)
- highly extensible. It's easy to:
- add new search types
- add new import routines
- add new export routines
- add new display routines
- add new modification plugins
- ...
- A very extensive scripting ability that can automatically create
GUI screens from script definitions.
- In summary, you should be able to control your data.
DOCUMENT CONVENTIONS
The documentation uses the following structures for examples:
> geoqo -argument value
output line 1
output line 2
In the above example, ``>'' is the command prompt. ``geoqo -argument value'' is an example command, and ``output line 1'' (and 2) would be the example output it might give.
Tutorials and Other Documentation
Make sure you check out the wiki pages as well, which provide tutorials, tips and tricks, FAQs, and other documentation:
http://www.geoqo.org/wiki/
This document discusses how to use geoqo using the command line syntax. For instructions on using the GUI, please see the tutorial on the wiki web page above which contains screen-shot walk throughs.
QUICK OVERVIEW
Import a file:
geoqo -i filetoimport.gpx
Search for and list all caches owned by Yamar
geoqo -s cache:owner_name=Yamar -d list
Display result number 3 from the last search:
geoqo -s 3 -d show
Export your search to a new file (in this case, the last search [Yamar's caches] since a new -s flag wasn't specified)
geoqo -e filetoexport.gpx
List geocache data sets (includes imports, searches, etc)
geoqo -d sets
Show stats about your data:
geoqo -d stats
THE LONG, LONG MANUAL
GeoQO is very powerful. Thus, you'll find that this manual is long. It's divided up into sections based on the types of things geoqo can do: setup, import, search, display, modify, and export.Make sure you check out the wiki pages as well, which provide tips and tricks, FAQs, and other documentation:
http://www.geoqo.org/wiki/
Have I mentioned the wiki yet?
Help Is Nearby
The -d switch (you'll learn about this later) displays things. One of the things it can display is ``help''. To get help at any time, run:
> geoqo -d help
To get started with the help system. To get help about a particular topic, include the major type and a slash (/) and the subtype. For example, Get get information about importing gpx files:
> geoqo -d help:topic=import/gpx
To get a list of the particular subtypes for a given section, look up the major section:
> geoqo -d help:topic=import
And it will list all of the subtyes (in the example above, it would display a list of all the import types).
DATABASE SETUP
Database setup is automatic for the default database. You can, however, create as many databases using other file names as you want (but why?).
> geoqo --db-name otherdb --setup-database
IMPORTING DATA
To import an existing pocket query or other gpx file, simply use the -i switch:
> geoqo -i somefile.gpx
You can import multiple files:
> geoqo -i somefile.gpx,someotherfile.zip
Note that most importing plugins do store things in ``sets''. See sections further below for more details on what a ``set'' is and how useful they can be.
File import types currently available:
Import Gpx:
> geoqo -i myfile.gpx > geoqo -i gpx:setname=myname:myfile.gpx
The gpx importer imports gpx files taken from the geocaching.com site (and probably many other sites too, but only geocaching.com GPX files have been tested so for) and imports the data into your geoqo database.
- setname:
- Uses setname as the name of geoqo SET to create based on the data. Normally this is extracted from the name field within the gpx file itself and prepended with ``import:''. IE, if you had a pocket query named ``my search'' then, when you imported the gpx file into geoqo, you'd get a new set named ``import:my search''.
Import Zip:
> geoqo -i myfile.zip
The zip importer allows you to simply specify a zip file for importing instead of having to unzip it yourself. It expects the contents of the zip file to be named similar to the zip file itself, just like groundspeak sends them out for geocaching.com pocket queries. IE, if you import ``111111.zip'' it'll try to unzip it and then import the contained 111111.gpx file. It'll also try to import the 1111111-wpts.gpx file, if one existed as well.
Note: using this importer requires you to have unzip installed on your system.
- setname:
- Uses setname as the name of geoqo SET to create based on the data. Normally this is extracted from the name field within the gpx file itself and prepended with ``import:''. IE, if you had a pocket query named ``my search'' then, when you imported the gpx file into geoqo, you'd get a new set named ``import:my search''.
- tmpdir:
-
The zip importer works by copying the zip file to a tmpdir and then unzipping it there. This is normally set to $HOME/.geoqo/tmpdir. This option lets you override that default.
default: /home/hardaker/.geoqo/temp
Import Dir:
> geoqo -i /path/to/directory/
The dir importer allows you to simply specify a directory (``folder'') to attempt to read every file from. It will skip any file types it does not understand.
- setname:
- Uses setname as the name of geoqo SET to create based on the data. Normally this is extracted from the name field within the gpx file itself and prepended with ``import:''. IE, if you had a pocket query named ``my search'' then, when you imported the gpx file into geoqo, you'd get a new set named ``import:my search''.
- tmpdir:
-
The zip importer works by copying the zip file to a tmpdir and then unzipping it there. This is normally set to $HOME/.geoqo/tmpdir. This option lets you override that default.
default: /home/hardaker/.geoqo/temp
Import Loc:
> geoqo -i myfile.loc > geoqo -i loc:setname=myname:myfile.loc
The loc importer imports loc files taken from the geocaching.com and waymarking.com site (and probably many other sites too, but only geocaching.com and waymarking.com LOC files have been tested so for) and imports the data into your geoqo database.
- setname:
- Uses setname as the name of geoqo SET to create based on the data. Normally this is extracted from the name field within the gpx file itself and prepended with ``import:''. IE, if you had a pocket query named ``my search'' then, when you imported the gpx file into geoqo, you'd get a new set named ``import:my search''.
Import Base64:
> cat message | geoqo -i base64:-
The base64 importer allows you to send mail messages with encoded pocket queries directly to geoqo for decoding, unzipping, extracting and importing.
Note: using this importer requires you to have MIME::Base64 installed on your system. Most modern perl packages contain this out of the box.
- setname:
- Uses setname as the name of geoqo SET to create based on the data. Normally this is extracted from the name field within the gpx file itself and prepended with ``import:''. IE, if you had a pocket query named ``my search'' then, when you imported the gpx file into geoqo, you'd get a new set named ``import:my search''.
- tmpdir:
-
The zip importer works by copying the zip file to a tmpdir and then unzipping it there. This is normally set to $HOME/.geoqo/tmpdir. This option lets you override that default.
default: /home/hardaker/.geoqo/temp
Import Wigle:
> geoqo -i myfile.wigle > geoqo -i wigle:setname=myname:mywiglefile
The wigle importer imports wigle files taken from the geocaching.com and waymarking.com site (and probably many other sites too, but only geocaching.com and waymarking.com WIGLE files have been tested so for) and imports the data into your geoqo database.
Import System:
> geoqo -i "system:gpsbabel -i garmin -f /dev/ttyS0 -o gpx -F %{file:gpx}"
The system importer allows you to simply specify a command to run which generates a file of a type that geoqo can actually import. For example, the above command runs gpsbabel to import all the waypoints stored in a GPS on a unix system (/dev/ttyS0 is the name of a serial device on a linux machine).
- cmd:
- It must contain a %{file:TYPE} string that indicates where the output file will be stored, but the path and the name of that file will be created by geoqo. Example gpsbable arguments would be -o gpx -F %{file:gpx}
- setname:
- Uses setname as the name of geoqo SET to create based on the data. Normally this is extracted from the name field within the gpx file itself and prepended with ``import:''. IE, if you had a pocket query named ``my search'' then, when you imported the gpx file into geoqo, you'd get a new set named ``import:my search''. However if your system command doesn't properly name the resulting file, this can be used to override it.
- tmpdir:
-
The temporary directory to use
default: /home/hardaker/.geoqo/temp
Import Create:
> geoqo -i create:ident=home,lat=N38
The create import plugin lets you create new waypoints and inserts them into the database. The list of options is quite long as each type supported by a given supported waypoint system (geocaching, geodining, ...) requires an appropriate set of fields. Running geoqo simply as:
> geoqo -i create
should bring up a GUI form which will prompt you for the needed information. Leave anything out that isn't appropriate for the waypoint type you're creating.
- type:
- default: Waypoint
- ident:
- setname:
- default: created
- desc:
- lat:
- lon:
- sym:
- time:
- subtype:
- url:
- urlname:
- cmt:
Import Average:
> geoqo -i average:ident=newwaypoint,from1=oldwaypoint1,from2=oldwaypoint2
The average import plugin lets you create a new waypoint by averaging the latitude and longitude of a number of other waypoints. Useful to find the center of a number of waypoints, which is required for a number of geocaching puzzle caches.
Import Project:
XXXXX DO NOT USE THIS PLUGIN; IT IS NOT FINISHED XXXXX
> geoqo -i project:ident=newwaypoint,from=oldwaypoint,distance=528,direction=45
The project import plugin lets you project a new waypoint which is a distance from an older one.
SEARCHING THE DATABASE
The search system in geoqo is highly flexible and extensible. It supports multiple types of searching, which are documented below. The ``-s'' or ``--search''. The format of the search field is as follows:
type:terms
Type is the type of search you want to do. This can be any of the types shown further below, or any types provided by a plugin. For those that want to write search plugins, please run ``perldoc GeoDB::Search'' to learn how to write search plugins.
Note: searching does nothing if you're not going to act on the results. Thus, you should at least provide a -l, -S or -e flag to list, show, or export the results. All the examples below are using the -l flag.
Search Cache:
> geoqo -s cache:name=unusual -d count Search/Set Count: 6
Searchs the database for only waypoints that are of type 'Geocache' and conform to the terms given. See the documentation on the waypoint: search type for further details on how to use it because everything else is the same.
Possible search columns for geocaches include the following, beyond those listed in the waypoint section:
available
archived
groundspeak_name
groundspeak_placed_by
groundspeak_owner_id
groundspeak_owner_name
groundspeak_type
groundspeak_container
groundspeak_difficulty
groundspeak_terrain
groundspeak_country
groundspeak_state
groundspeak_short_description_html
groundspeak_short_description
groundspeak_long_description_html
groundspeak_long_description
groundspeak_encoded_hints
Search Waymark:
> geoqo -s waymark:name=unusual -d count Search/Set Count: 6
Searches the database for only waypoints that are of type 'Waymark' and conform to the terms given. See the documentation on the waypoint: search type for further details on how to use it, because everything else is the same.
Possible search columns for waymarks include the following beyond those listed in the waypoint section:
waymark_owner_name
When waymarking.com starts releasing more data in .gpx files, this will get significantly longer, of course.
Search Geodining:
> geoqo -s geodining:resturant_name=Cafe -d count Search/Set Count: 6
Searches the database for only waypoints that are of type 'Geodining' and conform to the terms given. See the documentation on the waypoint: search type for further details on how to use it, because everything else is the same.
Possible search columns for geodining waypoints include the following beyond those listed in the waypoint section:
geodining_restaurant_name
geodining_submitted_by
geodining_price
geodining_service
geodining_continent
geodining_country
geodining_state
geodining_city
geodining_zip
geodining_address
geodining_description
geodining_details
Search Wigle:
> geoqo -s wigle:name=unusual -d count Search/Set Count: 6
Searches the database for only waypoints that are of type 'Wigle' and conform to the terms given. See the documentation on the waypoint: search type for further details on how to use it, because everything else is the same.
Possible search columns for wigles include the following beyond those listed in the waypoint section:
wigle_ssid
wigle_netid
wigle_discover
wigle_channel
wigle_type
wigle_freenet
wigle_firsttime
wigle_sep
wigle_comment
wigle_qos
wigle_lastupdt
wigle_paynet
wigle_userfound
Search Waypoint:
> geoqo -s waypoint:name=unusual -d count Search/Set Count: 6
The waypoint search type is for searching for primary fields in a waypoint record. Possible search terms include anything in the type-specific searches (since waypoint: searches include everything) and the following fields which apply to all waypoints regardless of specific type:
desc
lat
lon
sym
time
type
subtype
url
urlname
cmt
The following are some examples of how to use the waypoint: search type. Note that cache: and waymark: searches work the exact same way and also do everything below, but limit your search to just waypoints of those types.
The format for using the waypoint (or similarily for cache: or waymark:) search terms is:
geqo -s waypoint:I<TERMS>
where TERMS are a comma separated list of search terms. Normally these would be specified like:
waypoint:FIELDNAME=VALUE
The FIELDNAME indicates the field name you want to search (see below), and the VALUE is the value you want to search for. The value field is actually surrounded by wildcards, and thus searching for ``me'' will match any value with ``me'' somewhere in it including ``He and I went to the store'' and ``sometimes''. Using two equals signs turns off the automatic wildcard support (ie, name==me means search for a name that is just ``me'').
An example: find all waypoints with a urlname field containing ``unusual'':
> geoqo -s waypoint:urlname=tubular -d list
num GCID Name
1 GCDFE0 Hidden Headstones
2 GCE29A Celebrated Cemetery
3 GCHW9M The eyes have it (Yamar's unusual #1)
4 GCJ491 O where art thou (Yamar's unusual #2)
5 GCJ5DV Inverted Cache (Yamar's unusual #3)
6 GCJ66H Gone Fishin' (Yamar's unusual #4)
7 GCQEBQ Yamar's Unusual #6: The ORB
8 GCB284 Don't Be A Drip!
An example: find all geocaches owned by 'Spelunk':
> geoqo -s cache:owner_name=spelunk -d list
num GCID Name
1 GCJVTR Here's to Your Health Cache
2 GCJY4V Sumac Grove Cache
3 GCJZ2N Wildlife View Cache
4 GCKNZB Misplaced Seed Cache
5 GCKQBN Out-N-About Cache
6 GCKVFW We Give-A-Hoot Cache
7 GCNWM9 BUG JAR
8 GCP5YP Greenbelt Hideaway
9 GCPZK3 Davis Shopping Spree
10 GCQ6Q8 BUG JAR II
11 GCQ6TV Great Experience Cache
12 GCQ87Z Here's to the Greenbelts
13 GCQFYJ Toby & Willie's Friends
14 GCQH1M Connect the Dots Cache
15 GCTCC5 Canal Cache
16 GCTFJH The Micro Equalizer Cache
17 GCVVWY Spelunk's 'Fishy' Doings
18 GCW26F Mountain or Desert? Cache
Note that terms will match anything beyond the underscore (``_''). IE, if you do a search for:
waypoint:short=some text
It will search the short description for ``some text'' even though the actual field name it'll search is ``groundspeak_short_description''. Using an exact fully spelled out field name is the most precise, but you can truncate names for convience.
Finally, you can use '*'s to indicate wildcard spots (u*sal would match ``unusual'' and ``unit of sale''). By default geoqo already adds a * to both the front and the back of your search time (ie, name=unusual is actually interpreted as name=*unusual*).
You can also use the folling ARGUMENT types when searching for field values in a waypoint:
field ARGUMENT value
- field=value
-
Fuzzy match on value. The value will be surrounding by wildcards, as
previously discussed so searching for ``desc=blowfish'' will actually
search the desc field for ``*blowfish*''.
waypoint:desc=blowfish
- field==value
-
Also as mentioned above, if you don't want to use the automatic wild
card searching discussed above, you can use 2 equal signs to indicate
this. Thus if you search for ``desc=blowfish'' it will search the desc
fields for an exact match on the word ``blowfish'' (IE, must not contain
any other words).
You should use == searches for numeric values too, or else something like ``difficult=3'' will also match difficult numbers like 3.5.
waypoint:desc==blowfish
- field<value and field>value
-
Allows you to search on less than or greater than numeric values. IE:
waypoint:lon<42.123
or
waypoint:terrain>2
- <>
-
If you use both, it becomes ``not equal to''. IE:
waypoint:type<>unusual
Will list all waypoints without the word unusual in their desc field. This is also doing the same automatic wildcard matching like the = sign does, and thus the above search is actually searching for ``*unusual*''.p
- <=>
-
This is also ``not equal to'', but is an exact match and thus:
waypoint:desc<=>blowfish
will match any type of cache that doesn't have a desc field of ``blowfish''. It will include, in the search, caches with a desc field of ``blowfish dinner'' however because it's not an exact match.
Search Ident:
> geoqo -s ident:gcabcd,gcefgh,gcijkl -d count Search/Set Count: 3 > geoqo -s ident:abcd,efgh,ijkl -d count Search/Set Count: 3
The ident plugin merely lets you quickly list a bunch of waypoint identifiers you want to select with geodb.
The identifiers do have a wild card inserted before them so you can leave off a common prefix, as shown in the second example above, and still match the list (saves typing).
Really, the ident: search type is just a faster way to type:
> geoqo -s waypoint:ident=abcd||waypoint:ident=efgh||...
Search Log:
The log: search type lets you search waypoint log entries for waypoints matching a criteria. As an example, you can search for all waypoints in you database found by Yamar (me):
> geoqo -s 'log:finder=Yamar' -d list
num GCID Name
1 GCJVTR Here's to Your Health Cache
...
Log tokens to search by:
id ident date type logger_id logger text_encoded text
Special tokens to search by (makes sure a log was made by someone of a particular type):
finder noter dnfer
WARNING: this may be amazingly slow on a mysql server. I think. Postgresql or sqlite2 (the defualt) database backends are just zippy, however.
Search Attribute:
Attribute searches groundspeak (geocaching.com) attributes that were loaded into the database when doing an import from a groundspeak .gpx file.
> geoqo -s attribute:Dogs -d count Search Result Count: 32
NOTE: this does NOT search the user-defined attributes and only searches (geocaching.com) attributes. For searching user attributes you should use the attr: search plugin intstead.
Search Attr:
Attr searches attributes that you yourself have placed on a cache using the modify setattr module.
> geoqo -s ident:gcabcd -m setattr:found=1 --save > geoqo -s attr:found=1 -d count Search Result Count: 1
NOTE: this does NOT search groundpseak (geocaching.com) attributes. For this you should use the attribute: search plugin intstead.
Search Rating:
The rating plugin lets you search ratings that may have been placed on a cache using the modify rate module.
> geoqo -s ident:gcabcd -m rate:fun=8 > geoqo -s "rating:fun>5" -d count Search Result Count: 1
If you have downloaded average ratings from the ratings server, you can search by those as well by prefixing the name with ``others:'' to search by the average rating given to the cache by others:
> geoqo -s "rating:others:fun>5"
If you want to search for all caches that you have not rated for a particular category, use:
> geoqo -s "rating:fun=-"
Search Tag:
Tag searches tags that you yourself or others have placed on a cache.You can place them using the Tag Modify plugin:
> geoqo -s ident:gcabcd -m tag:cool/awesome > geoqo -s tag:cool -d count: Search Result Count: 1
Prefix the tag names with ``mine:'' if you want to search just you tags, or ``others:'' if you want to search other people's tags.
> geoqo -s tag:mine:cool -d count: Search Result Count: 1 > geoqo -s tag:others:cool -d count: Search Result Count: 2
Search Set:
Sets, which are described further below, are a bunch of waypoints all with an identically named ``tag''. As an example, if your geocaching.com pocket query was named ``my query'' and you import it into geoqo using the -i switch the waypoints contained in that gpx file will be assigned to the ``import:my query'' set. You can use the set:setname search type to load these waypoints.
> geoqo -s "set:import:my query" -d count Search Result Count: 500
This command would count everything in the database that was in the ``import:my query'' set name (that was likely imported from a pocket query). See the Advanced Searching section in the geoqo documentation for other examples of combining set: searches and waypoint: (or other) searches so you can search for ``all waypoints matching a criteia within a set'' for example.
If you prefix the name with a minus sign (-) then it will include all caches NOT in that set. For example to find all caches that are in seta but not in setb then the following expression would accomplish that:
> geoqo -s 'set:seta&&set:-setb'
Search File:
> geoqo -s file:foo.gpx -d count Search/Set Count: 3 > geoqo -s file:foo.loc -d count Search/Set Count: 3
The file plugin loads a file into memory and then searches the normal geoqo database for all the waypoints that match those found in the file.
Search Track:
> geoqo -s track:mytrackfile.gpx -d count: Search/Set Count: 3
The track plugin loads track data from a GPX track file (which you can retrieve from you gps using gpsbabel) and then compares the list of caches in you database to this data. It then matches all caches where your speed dropped below a configurable speed (3MPH is the default) and where the distance from the track is less than a configurable amount (defaults to near 500 feet).
This is even more useful when combined with the Track modify plugin, which can order caches based on the track and report the times you found them as well.
If you know all the caches are in a given set, however, you should probably limit the data it has to search through to a subset of you total database if it runs slowly.
To get track data from the gps, use gpsbabel:
gpsbabel -t -i garmin -f usb: -o gpx -F track.gpx
See the Modify/Track plugin for a detailed example
- trackfile:
- A GPX trackfile to load and search by
- speed:
-
Only look for caches where your speed dropped below this
default: 3
- delta:
-
lat/lon delta to use looking for caches near a stopping point
default: 0.002
- laterthan:
- Only use track points which are beyond a specifed time.
Search File:
> geoqo -s file:foo.gpx -d count Search/Set Count: 3 > geoqo -s file:foo.loc -d count Search/Set Count: 3
The file plugin loads a file into memory and then searches the normal geoqo database for all the waypoints that match those found in the file.
Search Returnhome:
> geoqo -s gps -d count Search/Set Count: 3
This plugin combines the functionality of a number of other ones rolled into one. In particular, it:
1. pulls the existing waypoints from the GPS
2. pulls the existing track from the GPS
3. searches for the waypoints in the geoqo database that match the
ones in the GPS using the GeoDB::Search::File plugin
4. seaches the results of those for ones that the track came close
using the GeoDB::Search::Track plugin.
Search Gps:
> geoqo -s gps -d count Search/Set Count: 3
The gps plugin talks to a gps and finds all the waypoints in the geoqo database that are also in the GPS. This is done by pulling out all the waypoints from the GPS and then using the list to search the database.
Search Any:
The any: search type simply uses all the waypoints in the entire database. It (hopefully) obviously doesn't make sense to use this combined with other types of searches.ADVANCED SEARCHING
There are advanced things you can do while searching. This section documents those:Accessing a single result from the last search
Sumarize just the 12th waypoint from the last search results:
> geoqo -s 12 -d list
12 GCNK57 James Bond 047
Export caches 5-10 from the last search results:
> geoqo -s 5-10 -e out.gpx
Logical Searches
You can use && (AND) and || (OR) pairs to add powerful searching combinations to your results. In fact, this is actually useful and can increase the speed of your queries if used properly (if you know you only want to search the data from a particular import, use a set: search && with a waypoint: search and the result will likely be returned faster).This example searches for all waypoints owned by ``spelunk'' that I have found (ie, it exists in the ``import:My Finds Pocket Query'' imported gpx file).
> geoqo -s 'waypoint:owner_name=spelunk&&set:import:My Finds Pocket Query' -d list
num GCID Name
1 GCJVTR Here's to Your Health Cache
2 GCJY4V Sumac Grove Cache
3 GCJZ2N Wildlife View Cache
4 GCKNZB Misplaced Seed Cache
5 GCKQBN Out-N-About Cache
6 GCKVFW We Give-A-Hoot Cache
7 GCNWM9 BUG JAR
8 GCP5YP Greenbelt Hideaway
9 GCPZK3 Davis Shopping Spree
10 GCQ6Q8 BUG JAR II
11 GCQ6TV Great Experience Cache
12 GCQ87Z Here's to the Greenbelts
13 GCQFYJ Toby & Willie's Friends
14 GCQH1M Connect the Dots Cache
15 GCTCC5 Canal Cache
16 GCTFJH The Micro Equalizer Cache
17 GCVVWY Spelunk's 'Fishy' Doings
18 GCW26F Mountain or Desert? Cache
That is likely faster than doing the next search, but the following is another way to do something similar. In this case, I'm searching for all waypoints owned by spelunk that there is a log entry by me for (note: finder is a mis-nomer as a finder may have logged it as a ``did not find''; search on the log ``type'' as well to limit it to just finds):
> geoqo -s 'waypoint:owner_name=spelunk&&log:finder=Yamar' -d list
num GCID Name
1 GCJVTR Here's to Your Health Cache
... [same result] ...
grouping search terms
The () arguments can be used to group search terms together as well when you need to mix operations. In the following case we're looking for all waypoints ``owned by scoobert AND have the word Ditch in them'', and add to that all waypoints logged by me and all waypoints with 'ninja' in the title. Silly example, I know.
> perl -I. geoqo -s '(waypoint:groundspeak:name=Ditch&&waypoint:owner_name=scoobert)||waypoint:groundspeak:name=ninja||log:finder=Yamar' -d list
1 GCYBDY Whodunit?
2 GCP8MT All Day
3 GCQJY0 Kate's Watching
[...]
SETS: Searches, imports, and just about everything are saved in sets
Actually, just about everything is stored in a set. They're a powerful way to ``tag'' a group of waypoints. The -N flag (or --set-name) flag specifies which name you want to store your current search results into (it's currently required and will always store the results somewhere).Sets can be created from a search
> geoqo -N search:47dad47 -s waypoint:owner_name=47dad47 -d list
num GCID Name
1 GCH5EF Sacramento's Second Webcam Cache
[...]
14 GCR86K .
> geoqo -N search:gary -s waypoint:owner_name=gary -d list
num GCID Name
1 GCRWXC Fishing in Cache Creek
Sets can be listed:
> geoqo -d saved
Set Name Cache Count
-------------------- -----------
file:somefile 200
search:geoqo 13 <i>(default search name)</i>
search:47dad47 14
search:gary 1
And they can be combined:
> geoqo -s set:search:gary,search:47dad47 -d list
num GCID Name
1 GCRWXC Fishing in Cache Creek
2 GCH5EF Sacramento's Second Webcam Cache
[...]
15 GCR86K .
DISPLAYING SEARCH RESULTS
You've already seen the effects of the -d list switch, which lists all the waypoints in the resulting set/search. But there are a number of display types to pick from, and 'list' is only one such search output style:Display Help:
The help module displays help on a given topic. You can specify help on a given topic.
Example 1: geoqo -d help Example 2: geoqo -d help:topicname
The help routine displays help for the various geoqo plugins.
Display Count:
Example: geoqo -s 'set:import:my pocket query' -d count Search/Set Count: 500
The Count display simply counts the results in a set. This is very useful for counting the results before you do something with them (like dumping 500 caches to your screen when you were looking for just a few).
Display List:
Example 1:
geoqo -d list
num GCID Name
1 GCMR3M The Mystery of Livinrgttoo
2 GCPWBT Hidden Cactus Garden
Example 2:
geoqo -d 'list:format=%{3:count} %{6:ident} terr=%{3:groundspeak_terrain} diff=%{groundspeak_difficulty}'
1 GCMR3M terr=1.5 diff=1.5
2 GCPWBT terr=2 diff=1.5
The List display shows the contents of the search Set one line at a time. By default, the format is (may vary depending on type though):
%{3:count} %{8:ident} %{66:urlname}
The number prefix is the number of spaces to print it in and it will pad with extra spaces if it doesn't fill that space. If left out, it'll print it straight out in any length it may be. Adding a decimal point will limit it to a maximum of that length. IE:
%{20.20:urlname}
Will print only the first 20 characetrs of the urlname.
Display Show:
Example 1:
geoqo -s 1 -d show
Show (-d show) the waypoint details for #3 from the last search (which is
really #3 from the default set or the set specified via the -N
switch):
> geoqo -s 3 -d show
GCHW9M Multi-cache Location: 38.542933, -121.6998
Name: The eyes have it (Yamar's unusual #1)
Owner: Yamar (#183928) Created: 2004-03-08
Placed By: yamar
Rating: 3/1.5
URL: http://www.geocaching.com/seek/cache_details.aspx?guid=5f9bd8d4-193a-4e0c-92c4-f107ae6d878b
Short Description:
A 3 part waypoint: a virtual, an unusual and a regular
Long Description:
Yamar to Spelunk on 2004-04-06:
"If this cache is under that lamp post [again], I'm going to scream."
[...]
Show the waypoint details and also the logs (-L, but this may change in the future):
> geoqo -s 3 -d show -L
GCHW9M Multi-cache Location: 38.542933, -121.6998
Name: The eyes have it (Yamar's unusual #1)
[...]
Log #13914681 by Mango101: (Found it)
This cache took us way too many tries! Finally we found it! TNLN.
Log #14812407 by Mister Grim & Pooka: (Found it)
The hint threw us for a loop but we figured it out
eventually. Thanks for another great cache!
[...]
Display Map:
Example 1: geoqo -s 'set:import:My Pocket Query' -d map
The Map display plugin displays a map of a set of waypoints with little red dots for each waypoint.
This plugin requires internet access since the map tiles are pulled from the http://www.openstreetmap.org/ project (which I highly recommend you contribute to; it's easy and fun to edit/fix the maps!).
(Eventually it should be possible to display with symbols, colors, etc as well as display the density overlays like the KML export plugin does)
- style:
- default: icons
- icondir:
- default: dist/tomtom-icons/
- iconscale:
-
Size to scale icon sizes in the map. ``auto'' scales based on the number of waypoints to be shown.
default: auto
- maptiles:
- default: 2
- notext:
- dodensity:
Display Top10:
The top10 dispaly plugin counts the values in a particular field and shows you the top10 results of the counts in that field.Example (defaults to counting the top 10 waypoint owners):
> geoqo -s any: -d top10 Top 10 'groundspeak_owner_name's Num % Value ---------------------------------------------------------------------- 22 4 BootyBuddies 20 4 sailorscodgers 17 3 retiredprof 16 3 two bison 14 2 Sac D 14 2 Oldhippy & Granny 13 2 TRAKD 12 2 rivercity 11 2 2Dee2Dee 10 2 jimlips 10 2 Pirate Princesses
Example: counting container types
> geoqo -s any: -d top10:groundspeak_container
Top 10 'groundspeak_container's
Num % Value
----------------------------------------------------------------------
234 50 Micro
103 22 Regular
92 19 Small
13 2 Not chosen
12 2 Other
10 2 Virtual
4 0 Large
Setting the ``doaverage'' parameter will also display the average value associated with a numeric field:
> geoqo -s 'cache:owner_name=Yamar' -d top10:groundspeak_difficulty,doaverage=1
Top 10 'groundspeak_difficulty's
Num % Value
----------------------------------------------------------------------
14 38 2
9 25 1.5
6 16 1
3 8 2.5
2 5 3
1 2 4
1 2 3.5
Average: 1.90278
- field:
- default: groundspeak_owner_name
- show:
- default: 10
- doaverage:
- averagetext:
- default: Average:
- script:
- noblank:
- default: 1
Display Sets:
Example: geoqo -d sets Count Set Name ----- ---------------------------------------- 450 import:Bethel Island 500 import:Concord 500 import:Copy of SanFrancisco [...]
Shows the list of existing sets remembered by the geoqo system, and the number of caches in each one. See the geoqo documentation on ``sets'' for further details.
- match:
- Only lists set names containing this value
- orderby:
-
Can be set to order by ``modified'' (default) or ``setname'' or ``count''
default: modified
Display Attributes:
Example:
geoqo -d attributes
Id Attribute Name
------ ----------------------------------------
1 Dogs
3 Climbing gear
4 Boat
5 Scuba gear
[...]
Shows the list of known groundspeak/geocaching attributes. This is useful for knowing which attributes you can search with using the 'attribute' search plugin.
- match:
- Only lists attributes names containing this value
- orderby:
-
Can be set to order by ``attributename'' (default) or ``attributeid''
default: attributename
Display Stats:
Example:
> geoqo -d stats Waypoints: 8754 Geocaches: 8751 Waymarks: 0 Logs: 56659 Sets: 33
The stats display plugin shows statistics about what is contained in your database.
Display Gui/list:
Example: geoqo -s cache:urlname=funny -d gui/list
The gui/list module displays a GUI in a graphical window that lets you examine the caches within a cache set.
This is only very preliminary work and is subject to greater expansion in the future.
Display Gui/show:
Example: geoqo -s cache:urlname=funny -d gui/show
The gui/show module displays a GUI in a graphical window that lets you examine the caches within a cache set.
This is only very preliminary work and is subject to greater expansion in the future.
Display Bounds:
Example 1: geoqo -s set:import:minneapolis -d bounds min lat: 44.888483 max lat: 45.061767 min lon: -93.391317 max lon: -93.146517 center lat: 44.975125 center lon: -93.268917
The Bounds display shows the maximum and minimum latitude and longitude found in the set. It also outputs the center of the bounds as well.
Display Graph/find:
Example: geoqo -s log:finder=Yamar -d graph/find:finder=Yamar
This shows a graph of finds over time by a given person. Generally, you'll want to run this after you've incorporated a pocket query of all of your finds. You can run it against other user names too, but it's unlikely you have every log record for them unless you've imported their find pocket query too.
- finder:
- Sets the NAME of the finder you're looking for to a particular geocaching name (ie, the name of the user that is logging the finds). 99/100 egoists recommend using your own geocaching name here.
- logtype:
-
Defines the log type to graph.
default: Found it
Display Graph/placed:
Example: geoqo -s any: -d graph/placed:type=month
Shows a graph displaying which during months, weeks, etc the caches were placed. Really this just gives an indication of which months are the most popular months for placing a cache (probably due to weather).
- type:
-
Examines creation date based on this frequency (X-axis column). PERIOD may be either month, day, year, weekday or yearday. The default is month (ie, the graph will be from 1-12 showing the number of caches placed during each month in your loaded search set).
default: month
Display Dump:
Example 1: geoqo -d dump Example 2: geoqo -d dump:short=1 Example 3: geoqo -d dump:format=perl
The Dump display type dumps the contents of a set of waypoints. This is primarily a debugging mechanism.
Options:
- short=1
- Makes everything fit on one 80column line per item. This will truncate field values to something short enough to do this.
- format=perl
- Uses Data::Dumper to show the output in perl structure form. For the expert.
- short:
- If specified, limits output to 1 line per field
- includeall:
-
If set then all waypoint items will be included, even if the field itself is blank
default: 0
- format:
- If set to ``perl'' will use perl's Data::Dumper to dump the perl object
MODIFYING RESULTS
There are a number of modification plugins that modify data after it's been extracted from the database and before it gets either displayed (-d) or exported (-e). These are most useful for changing data before it's exported.Modify Solved:
Example of solving a puzzle and saving it:
> geoqo -s ident:GCABCD -m 'setattr:puzn=N38 42.444,puzw=W121 42.444' --save
Example of exporting it with the replaced coordinates:
> geoqo -s ident:GCABCD -e 'solved:+loc:out.loc'
This plugin replaces the latitude and longitude coordinates of a waypoint with those in the puzn and puzw attributes. Use the above examples as a guide for solving a puzzle and then using the solved: plugin when exporting your database ready for uploading into a GPS.
- nattr:
-
The name of the attribute storing the new north coordinate
default: puzn
- wattr:
-
The name of the attribute storing the new west coordinate
default: puzw
- dropunparsed:
-
Drops caches that do not have puzzle answers but are not parseable
default: 1
Modify Gctodiff:
The ``gctodiff'' plugin (short for ``GC to difficulty'') replaces the first two letters in the 6-digit cache identifier with a single digit representation of both the difficulty and terrain ratings.IE, if you had this cache:
> geoqo -l
num GCID Name
1 GCQEBQ Yamar's Unusual #6: The ORB
It's rated a 1.5 in difficulty and a 2 in terrain. If you ran the gctodiff modify plugin on this data, it would replace the 'GC' with a 2 and 3:
> geoqo -m gctodiff: -d 'list:format=%{newident} %{desc}'
23QEBQ Yamar's Unusual #6: The ORB
It actually stores the data in the 'newident' field so the old one is still available. The export modules, however, use the newident field when writing out the cache identifiers so this is what your GPS, or what-have-you, will see when you load it into that.
I (Yamar) do this specifically so when I'm looking at my garmin, for example, I get an immediate feel for how hard a particular cache is going to be without having to pull up data about it. (I also use the symbol plugin to change the symbol so I can see the type of cache it is too). My goal here is to maximize the amount of data I seen on the screen!
The map from groundspeak/geocaching.com ratings is as follows:
1 => 1 1.5 => 2 2 => 3 2.5 => 4 3 => 5 3.5 => 6 4 => 7 4.5 => 8 5 => 9
Modify Rewrite:
The rewrite modify plugin lets you rewrite fields based on other fields. For example, I (Yamar) use the following rewrite when putting stuff to a gpx file I'm going to load into my TomTom so I get as much information as possible when clicking on the icon in the tomtom map display:
rewrite:groundspeak_name=%{ident}/%{4:subtype}: %{groundspeak_name}
That way the groundspeak_name which might have been ``some cache'' becomes ``GCABCD/Trad: some cache'' to give me more information about it. (actually, I use the gctodiff plugin too and use the newident field instead; see the gctodiff plugin for details).
Modify Setattr:
The ``Setattr'' plugin (short for 'Set Attributes') allows you to add your own ``attributes'' to waypoint(s). You must specify the command line option ``--save'' to get them to be saved permenently to the database though. You can pick any attribute name you want, although some other modify plugins (like the ``solved'' plugin) may expect particular attribute names.Atttributes can be used for just about anything. For example, you can use them to store notes, remember hints from other people, collect data for a complex puzzle cache, etc.
Example of storing a note:
> geoqo -s ident:GCABCD -m 'setattr:notes=I hate this puzzle' --save
Example of something silly:
> geoqo -s ident:GCABCD -m 'setattr:foo=bar' --save
Then you can search for all caches with that name and value later:
> geoqo -s attr:foo=bar -l
Example of solving a puzzle and saving it:
> geoqo -s ident:GCABCD -m 'setattr:puzn=N38 42.444,puzw=W121 42.444' --save
Example of exporting it with the replaced coordinates:
> geoqo -s ident:GCABCD -e 'solved:+loc:out.loc'
The setattr plugin lets you store your own information about a cache into the database. Some of the other plugins use attributes to manipulate things (see the solved plugin for an example). Sometimes you may want your own ``notes''. As an example, I modify Unknown puzzles that you solve in the field (instead of ``in advance'' puzzles like cross puzzles) with ``setattr:infield=1''. (then I can use that attribute with the modifier: plugin to drop all unknowns that don't have that attribute set or don't have a 'puzn' coordinate assigned showing I've solved it.
IMPORTANTNOTE: You must specify --save to the command line to have geoqo save your attribute changes back to the database. Otherwise you're only setting attributes temporarily during the one-time call of geoqo.
Math and Substitution
Math and Substition can be done by prefixing the values with ``math:'' and ``substitute:'' where the contents will be searched for names with other attribute names in ()s and replaced with the attribute values. And if the math: was used, it will then be evaluated. Multiple depth replacements/math will work.Here's a more complex than needed example (the puzw attribute needs to be set as well for this to work):
> geoqo -s ident:GCABCD -m 'setattr:puzn=substitute:N38 42.(A)(B)(C)' --save > geoqo -s ident:GCABCD -m 'setattr:A=4' --save > geoqo -s ident:GCABCD -m 'setattr:B=math:(A)*2' --save > geoqo -s ident:GCABCD -m 'setattr:C=math:(B)-(A)' --save > geoqo -s ident:GCABCD -m solved: -e out.gpx
Note that the actual equation will still be stored as the attribute; The calculation is done when the attribute is later read (for example, by the ``solved'' modify plugin).
Modify Tag:
The ``Tag'' plugin allows you to add ``tag''s to your caches.Example:
geoqo -s cache:owner_name==Yamar -m 'tag:tags=awesome/cool'
Another to remove tags:
geoqo -s cache:owner_name==Yamar -m 'tag:tags=lame,deletetags=1'
Your tags may be published to a geoqo tag server, and you may pull information about how other people have tagged waypoints from the tag server. To do this you must first create an account on the tag server:
http://tagserver.geoqo.org/
Then put your created username and password into your $HOME/.geoqo/config file like:
geoqouser YOURUSERNAME geoqopass YOURPASSWORD
Then you can publish your tags for a given set using:
geoqo -s SEARCHTERMS -m tag:publish=1
Additionally you can fetch data about other people's tags using:
geoqo -s SEARCHTERMS -m tag:fetch=1
When you use the -S option to show a the data for a waypoint you will see a list of all your tags as well as a list of other peoples tags that you have fetched.
- tags:
- deletetags:
- publish:
- publishtags:
- ignoretags:
- default: lamppost/found
- fetch:
- geoqouser:
- geoqopass:
Modify Rate:
The ``Rate'' plugin allows you to add ``ratings''s to your caches.Example:
geoqo -s cache:owner_name==Yamar -m 'rate:overall=4'
(at the moment ``overall'' is the only rating you can provide; more coming)
Your ratings may be published to a geoqo rating server, and you may pull information about how other people have rated waypoints from the rating server. To do this you must first create an account on the rating server:
http://ratingserver.geoqo.org/
Then put your created username and password into your $HOME/.geoqo/config file like:
geoqouser YOURUSERNAME geoqopass YOURPASSWORD
Then you can publish your ratings for a given set using:
geoqo -s SEARCHTERMS -m rate:publish=1
Additionally you can fetch data about other people's ratings using:
geoqo -s SEARCHTERMS -m rate:fetch=1
When you use the -S option to show a the data for a waypoint you will see a list of all your ratings as well as a list of other peoples ratings that you have fetched.
Modify Makepuzzle:
This plugin extracts puzzle coordinates and equations from a cache description and sets up some attributes for doing the puzzle solving. If a cache description has text in it like ``N38 AB.CDE'' then this plugin will create 5 attributes A-E and a ``puzn'' attribute with the text ``replace:N38 (A)(B).(C)(D)(E)'' so that merely by filling in the A-E attributes will complete the puzzle.- nattr:
-
The name of the attribute storing the new north coordinate
default: puzn
- wattr:
-
The name of the attribute storing the new west coordinate
default: puzw
- reextract:
-
Force rextraction of the equation wiping out the existing data
default: 0
Modify Delete:
This command removes the waypoints from the database. Obviously, this should be used with caution because it can not be undone.For those that really and truly hate puzzles:
> geoqo -s 'cache:subtype=Unknown' -m delete
This can be useful for temporarily importing a bunch of items you don't want to keep around in the long run.
Modify Classify:
Options:- inputprefix:
- default:
- outputprefix:
- default: predicted:
- categories:
- default: kids,coolcontainer,goodlocation,fun
- LearningType:
- default: DecisionTree
- stopwordsfile:
- default: /usr/share/geoqo/classify-ignore-words
- Debugging:
Modify Symbol:
This plugin replaces symbol identifier (normally ``Geocache'' for geocaches) with a new symbol based on your set criteria.As an example, I (Yamar) use the following mem: file definition to remap all my symbols into things that look (on my garmin) kind like the cache container:
symbol: subtype=Multi-cache=Fitness Center, subtype=Unknown Cache=Information, subtype=Webcam Cache=Shower, groundspeak_container=Micro=Cemetery, groundspeak_container=Small=Tunnel, groundspeak_container=Large=Geocache Found, subtype=Virtual Cache=Ultralight Area
Then I can run geoqo to remap stuff before exporting it to a .gpx file:
> geoqo -s some_search_criteria -e 'mem:FILENAME+out.gpx'
That way all multi-caches get remapped to a 'Fitness Center' because the 'Fitness Center' icon on my garmin looks like a little guy lifting weights, and thus I know it's going to be a harder cache (or one I'll likely have to walk more). I like multi's a lot, but I do like to know when I'm hitting them. Similarily, a Cemetery icon on my etrex is a small dot, a Tunnel is a bit larger, and a Geocache found icon is very large so I use them to represent sizes.
If you want to use the symbol plugin, you should pick your own symbols that seem right on your gps or other software system. Each GPS's symbols tend to be quite different (and the name chosen should be a symbol your GPS or software actually matches).
The format of the plugin is as follows:
symbol:CACHEDATA=CACHEVALUE=SYMBOLNAME,CACHEDATA2=CACHEVALUE2=SYMBOLNAME2,
They are exact matches only. So the CACHEVALUE must exactly equal the value found in the CACHEDATA field or it won't be replaced. The symbol plugin will stop after the first match so the first symbol in the list that gets matched always wins.
Modify Translate:
By far, this is one of the most powerful modification plugins. It uses online services (like Google) to translate cache fields from one language to another. As an example, here are some of my caches:
> geoqo -s cache:owner_name==Yamar&&waypoint:ident=GCJ -l num GCID Name 1 GCJYPW Hoppin' mad about Davis 2 GCJGRQ Beneficial cache 3 GCJKMD Historical water tower 4 GCJ7KT Got Coffee? 5 GCJ66H Gone Fishin' (Yamar's unusual #4) 6 GCJ491 O where art thou (Yamar's unusual #2) 7 GCJ5DV Inverted Cache (Yamar's unusual #3)
And here is what they look like when translated from English to Spanish:
> geoqo -s cache:owner_name==Yamar&&waypoint:ident=GCJ -l -m translate:source=English,destination=Spanish num GCID Name 1 GCJYPW Hoppin' enojado sobre Davis 2 GCJGRQ Escondrijo beneficioso 3 GCJKMD Torre historica del agua 4 GCJ7KT Cafe Conseguido? 5 GCJ66H Fishin ido ' (4) inusual de Yamar # 6 GCJ491 O donde mil del arte (2) inusual de Yamar # 7 GCJ5DV Escondrijo invertido (3) inusual de Yamar #
Valid languages to pick from:
English Spanish French German Italian Korean Japanese Portuguese
1) you must be connected to the net
2) you must have the WWW::Babelfish perl module installed.
- source:
-
The source language to translate from.
default: Spanish
- destination:
-
The destination language to translate to.
default: English
- fields:
-
A / separated list of fields to translate.
default: urlname
- service:
-
The name of the translation service to use.
default: Babelfish
Modify Distance:
The distance modify plugin puts distance information from a given lat, lon coordinate and inserts the data into the ``distance'' field of the waypoint. You can then use it in other ways like in rewrite modification engines or in list formatting, etc.
> geoqo -s ident:GCABCD -d 'list:format=%{ident} %{distance}
You can calculate distance from coordinates:
> geoqo -s ident:GCABCD -m 'distance:n=n38 12.123,w=w42 22.333'
or from another waypoint already in the DB:
You can calculate distance from coordinates:
> geoqo -s ident:GCABCD -m 'distance:from=GCABCD'
- from:
- The waypoint name distances should be calculated from
- n:
- The North coordiante to calculate distance from
- w:
- The West coordiante to calculate distance from
Modify Sortby:
The sort by function sorts data in a set by a particular field.
> geoqo -s SOMETHING -m sortby:groundspeak_terrain -l
Modify Track:
The track plugin lets you compare a list of waypoints found in a search against the data in a gpx track file. Specifically, it:
- adds the following attribute fields to the waypoint's attribuets (not permenantly; use --save to save them): trkptdate - The date of the track point nearest the cache trkpttime - The time of the track point nearest the cache trkptnum - The number of the track point nearest the cache trkptname - The name of the track the point is in trkptdist - Distance in feet from the cache to the nearest track point trkptnum - The Nth track point counter into the track point data trkptepoch - Seconds since 1970 of the trackpoint closest to the cache trkptstart - Start time of the search (got closer than config distance) rtkptend - End time of the search rtkptnearby - Amount of time spent searching (= end - start) - optionally sorts the resulting waypoints by time visited if the sort option is set.
Using this and the track search plugin you can take a track GPX file downloaded from a GPS and list all the caches you came near in the order you went to them along with the time stamp when you visited it. As an example, this is the results of a trip I took one day:
> geoqo -s 'track:track.gpx' -m 'track:track.gpx' -d list:'%{7.7:ident} %{attr:trkpttime} %{urlname}'
GC10J27 10:55:22 This one is Golden
GCPC2R 11:16:53 "THE ISLAND"
GCYCGE 13:02:07 Legacy Trail #1 - River BBQ
GCD8A1 13:10:55 Under Lock & Key
GC5CBC 13:52:32 Let the Games Begin
GCPR6E 14:11:27 YFcache10
GCWR36 14:31:10 Granite Rock
GCK8YR 14:54:07 The Cache in The Middle of The Freeway
GCYYXV 16:02:05 Cisco Grove TB Stop
GC10Q0Q 16:02:41 Hard Rock Exchange #2
GCW1C3 16:27:08 Crack with a View
GCG38E 16:45:33 The Solar System - Pluto
To get track data from the gps, use gpsbabel:
gpsbabel -t -i garmin -f usb: -o gpx -F track.gpx
- trackfile:
- Track data to sort by
- sort:
-
field to sort resulting set by (if set)
default: trkptepoch
- distance:
-
Distance away in feet to use for determining how long you were in the area
default: 528
- hroffset:
- Offset in hours to use from the datestamp found in the track; useful if the timezone in the GPS/track does not match the track was laid
Modify Diff:
Options:Modify Limit:
This module limits the number of waypoints in a set to a certain number (starting at an optional certain point in the list of waypoints).IE, it starts at the offsetth waypoint in the set being modified, and limits the total number to number, stripping off all of the waypoints before the offset first and then everything from offset+number next.
If just number is specified (the common case) the firest number waypoints are kept.
If there are 250 caches in the set:
- number = 100, offset = 0
- Will get the first 100 caches
- number = 100, offset = 100
- Will get the next 100.
- number = 100, offset = 200
- Will get the last 50.
This module is very useful when combined with the distance and sortby modify pluigns to get the top 10 caches (for example) near something:
geoqo -s 'set:import:mypocketquery' -m distance:from=GCABCD+sortby:+limit:10
Modify Only:
This is most useful when doing really complex exporting. See Yamar's usage description on the web page for why this is helpful sometimes. It's mostly useful when you want to only include certain waypoints in a given export file, and you want to create lots of export files (TomTom's require one file per POI you wish to create, and I (Yamar) create different POIs for each cache type, size, etc.)The argument formatting is:
only:field=value
where field is the field (or attribute prefixed with 'attr:') name, and value is the exact value. The valid match types are:
- only:field=value
- Includes the waypoint only if the value is exactly the same as the waypoint's field value.
- only:field<>value
- Matches if the field is not that value
- only:field=-
- Matchs if the field doesn't exist.
- only:field=+
- Same as =- but only includes the waypoint if it does exist.
Modify Drop:
This is most useful when doing really complex exporting. See Yamar's usage description on the web page for why this is helpful sometimes.The Drop modifier is a compliment to the only modifier. Generally the ``only'' modifier will be easier for most people to think about, but technically you only need one as they can both accomplish the same tasks with inverse logic.
The argument formatting is:
drop:field=value
where field is the field (or attribute prefixed with 'attr:') name, and value is the exact value. The valid match types are:
- drop:field=value
- Matches only if exactly the same.
- drop:field<>value
- Matches if the field is not that value
- drop:field=-
-
Matchs if the field doesn't exist. I use this like follows:
# # unknown caches with solved puzzle coords # drop:subtype<>Unknown Cache +drop:attr:puzn=- +solved: +gpx:nologs=1:palm-solved.gpx
To drop any unknown cache that a 'puzn' attribute hasn't been added to it (see the Solved modify plugin for details).
- drop:field=+
- Same as =- but only drops it if it does exist.
Modify Dropexisting:
This modify function is really only useful during an import before a data save.The plugin simply removes all data from the current set that already exists in the database. This can be used to import data where only the new data is desired.
Example:
> geoqo -i 'myfile.gpx+dropexisting'
Modify Load:
This is only useful when you're going to be doing complex exporting where you need the caches data loaded early before exporting to multiple files. Otherwise geoqo may load all the data once per file.
> geoqo -s something -m load -e 'gctodiff+file1.gpx;file2.gpx
See the export documentation for details on why file1.gpx and file2.gpx may contain separate data.
Basically, since this is a confusing one, is if you're doing complex exporting (multiple files at once) put this on the -m switch to speed things up.
EXPORTING RESULTS
None of this is useful if you can't export your results of course. There are a number of export plugins you can pass to the -e switch to export the results of your search to a file.QUICK EXPORT EXAMPLES
Some quick examples:Exporting all waypoints from two sets:
> geodb -s 'set:search:gary&&set:search:47dad47' -e garyand47.gpx --debug 1
1: writing file: garyand47.gpx
Exporting all waypoints in a set that are of type ``Unknown'' to a .loc file:
> geodb -s 'set:import:somefile&&waypoint:type=Unknown' -e partfilebackout.loc
EXPORTING AND MODIFYING
You can also combine modifications and exports in one pass. First list the modifications specs you want to do (see the documentation on the modification plugins for details) separated by + signs. Everything before the last + will call a modification plugin, and after the last + will be an export plugin.An example:
> geodb -s 'cache:type=Unknown' -e gctodiff+partfilebackout.loc
OUTPUTING TO MULTIPLE FILES
You can also specify multiple output files separated by ';'s. Modification attributes will only apply to the next file. If you want every file to contain a modification plugin result, use the -m flag instead.
> geodb -s 'cache:type=Unknown' -e 'gctodiff+partfilebackout.loc;partfilebackout2.gpx
The above applies the gctodiff plugin to only the .loc file; the gpx file is written out using raw data.
EXPORT PLUGIN TYPES
Export Gpx:
> geoqo -s 'cache:name=cool cache' -e myfile.gpx
The gpx exporter writes out a gpx file containing all the caches in the search set.
Options are applied between the colon delimiter type specifier (first part) and the file name (th e last part) like so:
> geoqo -s 'cache:name=cool cache' -e gpx:nologs=1,setname=boo:myfile.gpx
- setname:
-
Makes the name field in the gpx file set to this value.
default: geoqo-export
- nologs:
- If set the resulting gpx file does not contain the wayoint logs.
- nogcattributes:
- If set the resulting gpx file does not contain the groundspeak attributes.
Export Loc:
> geoqo -s 'cache:name=cool cache' -e myfile.loc
The loc exporter writes out a loc file containing all the caches in the search set.
Export Map:
Example: geoqo -s set:import:myPQ -e map:output.png
The map will show red dots whereever there is a cache (Yes virginia, there will eventually be symbols and names). The output (currently) must be a PNG file.
- style:
- default: icons
- icondir:
- default: dist/tomtom-icons/
- iconscale:
-
Size to scale icon sizes in the map. ``auto'' scales based on the number of waypoints to be shown.
default: auto
- maptiles:
- default: 2
- notext:
- dodensity:
Export Html:
> geoqo -s 'cache:name=cool cache' -e myfile.html Prints a set of caches to a series of web pages. Each cache will get it's own file and a top level index file will be created that links to each cache page. Very useful for outputting geocaches to plucker.
- subdir:
-
Puts created HTML files in this sub directory name.
default: caches
- title:
-
The title to put at the top of the page
default: GeoDB HTML Export
Export Kml:
> geoqo -s 'set:import:near me' -e fortheearth.kml
The software will also produce a density plot as well, which shows the density of caches in particular areas color-coded by relief colors (rainbow; red = very few, purple = many). Examples of this can be seen on Yamar's cache homepage page http://geocaching.sharedlists.com/.
Options:
- size=NUM
-
> geoqo -s 'set:import:near me' -e kml:size=100:fortheearth.kml
Changes the number of squares in the density plot to NUM by NUM. Defaults to 50.
- width=NUM
- height=NUM
- Changes just the width and height of the squares. The size parameter can change both at once.
(there are a bunch of options for the density plot, which are currently undocumented).
- bogus:
- dataname:
- default: Export from GeoQO
- dowaypoints:
- default: 1
- dodensity:
- default: 1
- dojail:
- default: 0
- bogus:
- waypointstyle:
- default: geoqo
- waypointheight:
- default: 150
- waypointmode:
- default: relativeToGround
- waypointextrude:
- default: 1
- includedescriptions:
- default: 1
- bogus:
- squareratio:
- default: 1
- size:
-
Creates a plot where there are SIZE by SIZE squares of colored rectangles
default: 200
- width:
- Normally equal to the size value but can be set independently. It specifies the width (in squares) of the density plot.
- height:
- Normally equal to the size value but can be set independently. It specifies the height (in squares) of the density plot.
- spread:
-
Sets the spread that determines the number of neighboring squares that a given cache will effect. EG, a spread of 5 will affect a circle of density squares in a radius of 5. This generally should be a low value of probably not more than 5 or so.
default: 5
- doempty:
-
If set to 1, even empty squares will be colored (red). Otherwise the empty squares are removed from the plot leaving the plane ground underneath.
default: 0
- bogus:
- altitude:
-
The altitude to set the density plot squares at.
default: 1000
- densitymode:
- default: relativeToGround
- extrude:
-
Whether or not to extrude the density plot squares down to the ground.
default: 0
- opaque:
-
The opacity of the density squares. Must be between 0 and 100, with 0 being completely see-through (and thus completely useless).
default: 20
- linewidth:
-
The width of the border lines to draw (0-4). 0 means don't draw borders on the squares.
default: 0
- bagus:
- jailaltitude:
- default: 100
- jailmode:
- default: relativeToGround
- bogus:
- limitdata:
- default: 1
- nmax:
- The maximum north coordinate value to created the grid over. Normally this is automatically set by the maximum value found in the data, but can be overridden
- nmin:
- The minimum north coordinate value to created the grid over. Normally this is automatically set by the minimum value found in the data, but can be overridden
- wmax:
- The maximum west coordinate value to created the grid over. Normally this is automatically set by the maximum value found in the data, but can be overridden
- wmin:
- The minimum west coordinate value to created the grid over. Normally this is automatically set by the minimum value found in the data, but can be overridden
Export System:
There are two ways to use the system export mechanism:- Run a system command for cache:
-
> geoqo -s 'cache:name=cool cache' -e 'system:cmd=echo %{ident} %{desc}'That command runs echo for each cache in the set, replacing %{ident} and %{desc} with the fields from those caches.
Useful things to do for this would be to open firefox (a web browser) on each cache page:
> geoqo -s 'cache:name=cool cache' -e 'system:cmd=firefox %{url}' - Run a system command
-
You can also run a command on a file generated by an export module.
As an example, the following command will call gpsbabel to convert a
gpx file to a tomtom compatible file:
> geoqo -s 'cache:name=cool cache' -e 'system:cmd=gpsbabel -i gpx -f %{file:gpx} -o tomtom -F mycaches.ov2'
- cmd:
- COMMAND is what gets run. If it contains a %{file:TYPE} string in it, that will be replaced with a file name of that type and it'll get run just once. If it doesn't, it'll get run once per cache in the set being processed and each %{token} specifier will get replaced by that item from the cache.
- sleep:
- Between each command executed in the per-cache mode, geoqo will sleep for NUM seconds before running the next. It defaults to 1, and can be set to 0 to just fire them off as fast as possible.
- dontdelete:
- if set to 1, don't delete the temporary files
- tmpdir:
-
The temporary directory to use
default: /home/hardaker/.geoqo/temp
PLUGINS TO USE EVERYWHERE
Here are some useful plugins that can be used in many command line definitions.Everywhere mem:
It hard to repeatedly type complex queries, tasks, or what have you so to facilitate this you can use the Mem plugin for remembering complex strings (or even simple onse, if you choose).To do this, take a complex search (or export, or modify) string and save it in a file in the directory ``$HOME/.geoqo/mem/TYPE/FILENAME''. Where TYPE is one of ``search'', ``export'', or ``modify'' and FILENAME is a file name of your choosing. You can also store file entries directly in $HOME/.geoqo/mem/FILENAME (note the missing ``TYPE'' part), which then makes the definition usable for all types. It is not likely you'll need to use a definition for both searching and exporting (as an example), however, so I suggest you store them in a type-based subdirectory instead. Only because it's cleaner. You want to be neat and tidy right?
All lines read in these file will be merged together and leading and trailing white-space characters are stripped as well comment lines (which should start with a #). For example if you had a file like so:
> cat $HOME/.geoqo/mem/search/memtest
# Searches a particular imported set named "near me"
set:import:near me
# but only for items I haven't logged as found
&&cache:finder<>Yamar
# and aren't unknown caches.
&&cache:subtype<>Unknown
You can then run geoqo like so:
> geoqo -s mem:memtest -d count Search Result Count: 480
Which is really a replacement for:
> geoqo -s set:import:near me&&cache:finder<>Yamar&&cache:subtype<>Unknown -d count
Since you may want to frequently replace parts of your super-long and complicated definition strings you've built up, you can do this as well by putting %[NAME,DEFAULT] strings inside your definitions. IE, doing this:
> cat $HOME/.geoqo/mem/memtest
set:import:%[setname,near me]
&&cache:finder<>Yamar
&&cache:subtype<>Unknown
Makes the import: set default to ``near me'' so the above example command will work just like it would before, but if I specify a setname option on the command line I can override it. Here's the original command example:
> geoqo -s mem:memtest -d count Search Result Count: 480
And here's using the same search criteria, but using ``fairfield'' as the import set name instead of the default ``near me'':
> geoqo -s mem:memtest,setname=fairfield -d count Search Result Count: 182
Final note: you can have mem: definitions that call other mem: definitions. The only caveat there is that parameters aren't passed down automatically, so if your second mem: definition being called has a %[something,xxx] definition then you should call it within the higher definition as mem:subdef,something=%[something,xxx] as well.
SCRIPTING ABILITY
GeoQO can also perform a bunch of tasks at once in a scripted fashion. IE, if you find yourself repeatedly doing a standard search followed by an export, you can script things together in a single file and call geoqo -x FILE.The script file format contains lines that start with a '%MODE' followed by text for that MODE. MODE should be one of: search, export, import, modify, display or print. You can break long lines into pieces just like the mem: plugin discusses above.
Thus the following script (saved in, for example, ``myscript.txt'') will display unsolved puzzles in your database ordered by distance:
# searches for all 'Unknown' caches %search subtype=Unknown &&attr:puzn=- # displays them in list format %display list
Then running the script will display the list:
> geoqo -x myscript.txt ... [list displayed here] ...
Scripts can be stored in $HOME/.geoqo/scripts and if a script is run and the file doesn't exist in the current working directory, then the $HOME/.geoqo/scripts directory will be checked to see if it contains the file.
Scripts can contain %[name,default value] sections just like Everywhere Mem: definitions can and are acted upon the same way. Thus a script of:
%search waypoint:type==%[type,Waymark] %display count
Will default to counting all the Waymarks in the database. But if run as:
> geoqo -x myscript.txt:type=Geocache
It'll count all the geocaches instead.
Special Script Formatting
White Space WrappingNormally script lines are merged together, stripping leading and trailing white space off of a line. EG, Scripts that look like:
%search
waypoint:type=
=
Geo
cache
will actually be translated to a search using just:
wayoint:type==Geocache
If you need to force whitespace into a script line at the begining or end you can use a triple " in order to forec it. EG:
%search cache:owner_name=Super """ Sleuth"
Will keep the space between the """ and the word Sleuth:
cache:owner_name=Super Sleuth
Trailing """s work similarily.
Special Script Keywords
All script pieces begin with a % sign on a new line. The line format looks like:
%keyword someoption=1 otheroption=yes
These special options may include these global options as well as any keyword-specific options discussed below:
- allowgui=1
- This lets the GUI screens be shown for the sub-scripts. Normally they're hidden as the top script is always expected to pass needed parameters down.
The special script keywords that mayb be used are:
-
Prints everything from that section to the screen.
Example:
%print hello world
- %script
-
Runs a subscript based on the text following the %script line. (may include
the script name and potentially arguments following a ':').
Example:
%script scriptname:arg1=value1
- %include [ARGUMENTS] SCRIPT_FILE_NAME
- Include another script as part of this script. Unlike the
%script command, the %include command operates on the same search set, becomes part of the same auto-gui screen, etc.You can also pass a type=hooks argument to include a bunch of files. EG:
%include type=hooks specialhooks/*.inc
Will include every file that matches that pattern in each of the script search paths. The order in which they are included is determined by alphabetical ordering of the last filename component (ie, not directory path component).
Finally, you can auto-wrap includes in if statements and use the resulting titles from the included files in menu to select which file gets executed. This is primarily intended for building dynamic menus from found plugins. This is best seen by an example:
In a file called ``testincludetop.txt'', we put the menu definition:
%ignore %[mymenu,0 ,labels=(%{VALUELABELS}) ,type=menu,text=top menu: ,refresh_on_change=1 ]In two files called testinclude-1.txt and testinclude-2.txt we put:
#scriptname: item number 1 %print some thing or other to handle choice #1
(And something similar for number 2)
Then finally, in the real top level script you call the whole shabang with:
%include type=hooks autoif=mymenu hookheader=testincludetop.txt testinclude*.txt
In the end, the whole result gets built as follows:
%ignore %[mymenu,0 ,labels=(0,item number 1,2,item number 2) ,type=menu,text=top menu: ,refresh_on_change=1 ] %if "%[mymenu]" eq "0" %title item number 1 %print some thing or other to handle choice #1 %endif %if "%[mymenu]" eq "1" %title item number 2 %print some thing or other to handle choice #2 %endif
If you could follow that, I'll be impressed. But it's really powerful! See the included ``searchbase'' script for a much larger example.
- %save
- Calls 'save' on the current set saving all the data to the db (needed if modified in anyway that should result in a save, such as when the setattr: modify plugin was called).
- %saveset name=MYNAME
- Remembers the current set as MYNAME.
- %webfile
-
Pulls a file from a URL and saves it to a file. The format is the
file name to save it to, a comma and then the URL. Example:
%webfile waymarks-train.gif,http://www.waymarking.com/images/cat_icons/train.gif
You can then refer to these files using webfile:waymarks-train.gif in %copy or %system commands.
- %copy
-
Copy's a file from one place to another. Example format:
%copy file1.loc,file2.loc
Or refering to a webfile previously pulled from a %webfile directive:
%copy webfile:waymarks-train.gif,/some/path/to/waymarks-train.gif
- %system
- Run's a system command. webfile: prefixes within the command string will be replaced by paths to a stored %webfile.
- %if CLAUSE
- %else
- %endif
-
These sections allow for variablity of what is done based on user
input. CLAUSE is evaluated as perl code (returning a perl true or
false response (eg, 1 or 0)) to determine what to do next. CLAUSE
will be evaluated first in terms of parameteritized input. Thus:
%print %if %[desire,1,type=checkbox] hello %else world %endif
Will print ``hello'' if the user clicks the check box (defaults to on) or ``world'' if the user does not. (They may also hand-specify the 'Desire' parameter as scriptname:desire=1 or equievelent).
Nesting is properly handled.
- %foreach VAR value1 value2 ...
- %endforeach
-
Allows repeated script sections with %{VAR} being replaced with a
different value for each section.
%foreach it 1 2 3 a b word %print This is it: %{it} %endforeachWill output:
This is it: 1 This is it: 2 This is it: 3 This is it: a This is it: b This is it: word
- %perl
-
Embeds perl into the script. $self is a reference to the master GeoDB
object. Use this functionality only if you're an expert (and in
desperate need).
%perl leavewhitespace=1
- %title
-
Names the script with a title.
%title My super title
- %introduction
-
Includes a paragraph in the top of the GUI screen when the script is run.
%introduction This is how you use this screen
COMMAND LINE OPTIONS
- -i STRING
- --import-file=STRING
- Import a file. File should be specified as type:file
- -n STRING
- --name=STRING
- Comma separated names to assign to the objects in the file
- -m STRING
- --modify=STRING
- Modify the search set before displaying or exporting
- -e STRING
- --export-file=STRING
- Export a file. File should be specified as type:file
- --execute-script=FILENAME
- -x FILENAME
- Run a script stored in FILENAME
Search Options:
- -s STRING
- --search=STRING
- Search terms for geocaches
- --limit=INTEGER
- Maximum number of records to return for searches
- -N STRING
- --set-name=STRING
- Set/Search Storage Name ('search:geoqo')
Display Options:
- -l
- --list-caches
- List geocaches found in search
- -S
- --show-caches
- Show details of geocaches found
- -L
- --show-logs
- Show log messages in details output
- -d STRING
- --display=STRING
- Display output thingies
- --save
- --save-changes
- Save changes to the set to the DB
Database Options:
- -t STRING
- --db-type=STRING
- Database Type (sqlite2, sqlite, mysql, postgres)
- -H STRING
- --db-host=STRING
- Database Host (localhost)
- -u STRING
- --db-user=STRING
- Database User (geoqo)
- -p STRING
- --db-password=STRING
- Database Password
- --db-name=STRING
- Database Name (geoqo)
- --db-flush
- Delete the existing DB first
- --db-port=INTEGER
- Port number for the database
- --setup-database
- Initialize the database table structure
Configuration Options:
- -c STRING
- --config-file=STRING
- Configuration File to read
- -C
- --no-config
- Do not read any configuration file
- --debug=INTEGER
- Turn on debugging output
- --test
- Prints a bunch of test output that Yamar (or someone else) may ask you for if you have problems.
Help Options
- -h
- Display a help summary (short flags preferred)
- --help
- Display a help summary (long flags preferred)
- --help-full
- Display all help options (both short and long)
- --version
- Display the script version number.
CONFIGURING
GeoQO supports a configuration file where multiple types of things can be specified.Command Line Options and Default
You can also store ``always use this'' options in a configuration file named ~/.geoqo/config. This file should be the option name on the left (single letter option if available, not longer ones) followed by the value you want after a space. EG to always use debugging and postgresql and the 'geo' database user:
t postgresql u geo debug 5
Any option may be added to this file. Options on the command line will override options in this file (as you'd expect).
GUI Defaults
When using the auto-gui created screens, you can specify your own defaults for widgets created by geoqo modules or scripts using the ``default'' keyword. EG:
default searchby Power Search
Will set the default search mechanism to the ``Power Search'' option. Knowing what keyword to use and what value to use generaly requires understanding how geoqo works at this point though (or you can ask Yamar in the #geoqo IRC channel).
Per-Screen GUI Defaults
You can also set defaults or for particular script screens. To set the default search type in the devices/cachemate script GUI screen:
screen devices/cachemate searchby Power Search
Debugging
If you really want to see what geodb is doing internally, run with the --debug switch. In particuluar, ``--debug 5'' will print lots of interesting information. Too much. The higher the number the more you get.ACKNOWLEDGEMENTS
The following people (geocachers) helped in useful ways with this program:- BlueNinja
-
Self proclaimed ``test monkey''. He tested lots of early verions and
has caught various bugs as well and given me better usage ideas
through his ``why can't I do this'' set of questions.
He was also the first person to get it working on Windows and has contributed vastly to the windows documentation.
- ClayJar
-
Who won the renaming contest on IRC after SourceForge told me GeoDB
was an internal reserved name:
[03:38:13 pm] <ClayJar_SSH>Yamar: How about "Geoqo". You'll have sole Google of that one, I imagine. You can pronounce it "ge-OH-ko", and "QO" is DB after ROT13.
For those that don't know, ROT13 is the cheap encryption mechanism that geocaching.com (and other places) use to encrypt their logs.
(ROT13 is used in many, many other ways too, and the first most popular usage of it was to encrypt potentially offensive material (ie, jokes) when posting to USENET news groups)
- Planet
- Planet nicely volunteered to proof-read a copy of this manual and sent me many wonderful suggestions about improving it.
- jslagle
- The first person to send me a code patch (implementing a better zip file import handler)! Yay! He's now a co-developer.
- brdad
- The first person to wade through what it takes to get the GUI working under windows.
- lairsdragon
- Submitted patches for the build system to make it more PREFIX friendly.
- Zemmy
- An early Windows test case for the installer components.
AUTHOR
Wes Hardaker <hardaker ATAT users.sourceforge.net>AKA ``Yamar'' on Geocaching.com, IRC, and other places