There is some one-time setup. Since my macros assume certain file locations, you'll need to modify any
macros if you choose to store files in different subdirectories than what I use. The macros used by GSAK
are simple text files that can be created or modified using the NOTEPAD program that comes with all MS Windows computers.
Next, we need the graphics that we're going to use as pushpins. If you'd like to use the ones I'm using, then right-click the icon below and select "Save As." Then save the individual graphics (*.BMP files) in the icon directory (C:\GPS\Pushpins\icons\ in my scenario)
The icons included in the ZIP file above are shown below, and are for TerraCaching.com caches, Archived caches, Benchmarks, CITO events, DNF (did not find), Earth caches, Event caches, Found caches, Home base, Letterbox hybrid caches, Locationless, Micro caches, Offset or Multi-caches, Mystery and Unknown type caches, Traditional cache of type "other," Large traditional cache, Regular traditional cache, Small traditional cache, Virtual cache, and Web Cam caches.
The red circle with a cross is a generic pushpins that I use for "bases of operation" (work, parking lots, hotel during business travel, etc.) and the final icons are for
crumbtrail tracks and generic waypoints (e.g., like actual/corrected coordinates for multi/offset caches, trailheads, trail intersections, etc.).
Icons files used for MSST pushpins must be in the BMP file format. You can create them (or modify mine) using Microsoft Paint that is
included with Windows. They are 24-bit color depth and 16x16 pixels in size, which is the standard pushpin dimensions. The size is
important because PushPins expects 8 icons on each row in the icon selector dialog. But larger or smaller icons can be created if you do manual
icon selections. I find it easiest to work with these icons in MSPaint when zoomed to 800% (/View /Zoom /Custom /800%).
A neat trick that I stumbled upon accidentally is transparency. Normally, the BMP file type does not support transparency, but MSST will do the work for us. Whatever color pixel it finds in the upper left corner will be considered the transparency color. Normally that's white, but sometimes I want white to be part of my icon and not to turn transparent. So, I pick a wild color that's not part of the image and use it for background fill. Here's the icon for Micro Caches enlarged and showing how I used the bright cyan to indicate transparent areas since I wanted the cap to remain white.
04.11.2005 On the Microsoft MapPoint web site, one of the downloads is the "MapPoint PushPins" which also correspond to the MSST pushpin graphics.
This file has each of the delivered icons in individual BMP files. So you can copy/rename them or edit/tweak them and then use them as custom graphics
for caches. The link to the download is:
http://www.msdn.microsoft.com/mappoint/mappointintro/mappointdownloads/default.aspx
Next, we need to create filters for each type of cache that we want to have a distinct pushpin graphic. These filters will be named "Benchmark", "CITO", "Earth", "Event", "LetterBox", "Multi", "Mystery", "Other", "TraditionalSmall", "TraditionalRegular", "TraditionalLarge", "TraditionalOther", "Virtual", "WebCam", "Micros", "TerraCaches" (via User Data), "Found", "All DNF", and "Archived" I will show you how to create the "TraditionalLarge" filter and the rest should be easy to figure out. You can adjust the filtering to meet your preferences. The main point is that you need a filter for every pushpin type you want on your MSST map. That way you can call the named filter and export the pushpin data automatically.
To create a filter, press Ctrl-F or select /Search /Filter. When you change a default setting you'll see that your criteria are highlighted in yellow. Also, each tab in the dialog is red if there's a filter in effect on that tab. In this screen shot you can see that I'm on the "Other" tab which contains filtering controls for type and size. Only the "Traditional" cache type is selected, and for container size only "Large" is selected.
Next, I only want active caches to be included. So I uncheck the boxes for archived or temporarily unavailable so they will be filtered out. These caches will be in the "Archived" data set instead. Normally, you do not want data sets to overlap, but sometimes you do. For example, the "Found" and "DNF" data sets overlap the other datasets and that's the way I want it. After making all the changes I click the SAVE button and give the filter the name "TraditionalLarge" (the "Select a saved filter" at the top of the dialog shows that name). I can click the GO button to apply the filter and verify that I'm getting the results I want. I can always go back and change the filter and re-save it if needed.
Extract the files in this ZIP file to your C:\GPS\PushPins\ directory. It contains two batch files that will be called by the GSAK export macro (see below
for details of their contents). And it also contains the PUSHPINS.EXE file that performs the pushpins import, and PUSHPINS.INI which is a sample configuration
file that can control the behavior of the PUSHPINS program.
After the files are in place create a shortcut to the PUSHPIN.EXE program
For the adventerous, you can customize how PUSHPIN behaves. There are two
methods that can be used: command line parameters or via an INI file. You can actually
use both methods simultaneously. Command line parameters take precedence over values
from the INI file. PUSHPINS will prompt you for any missing items if they cannot be found
in the INI file or on the command line. Below is an example of the command line method
where several pieces are specified (you can specify as many or as few pieces as you want).
|
C:\GPS\PushPins\PushPins.exe LIST=C:\GPS\PushPins\PushPinList.txt ICONS=3
|
In this example, the PUSHPINS program will load the datafiles listed in the file
indicated by LIST= and the ICONS=3 setting tells PUSHPINS that there are already
three custom pushpin icons in the map that's being loaded.
If you use the command line method, be sure
that no spaces exist on either side of the equal signs. Also, if a file names contains
spaces, enclose the entire path in double quotes (e.g., LIST="C:\My Stuff\List of Pushpin Files.txt")
An INI file can be used to accomplish the same functions as the command line. An
example PUSHPIN.INI file is included and you can edit to match your needs.
If you use the INI file method, be sure that no spaces exist on either side of the equal signs. Also, if a file names contains
spaces, enclose the entire path in double quotes (e.g., LIST="C:\My Stuff\List of Pushpin Files.txt")
You'll notice that the entries have the same name and rules as the command line parameters.
Below is an abbreviated configuration file that performs the same import as the command line
example as above. See the sample INI file's comments for a list of all the customizeable
features of the PUSHPINS program.
[MAIN]
LIST=C:\GPS\PushPins\PushPinList.txt
ICONS=3
|
If you use the INI file method, the INI file must be named PUSHPINS.INI and it must
must be a plain text file (you can use NOTEPAD to create or edit it). Put the PUSHPINS.INI
file in the same directory as the PUSHPINS.EXE program or in your Windows directory.
Now we're ready to create a GSAK macro that will call our filters, and create the pushpin data files. You can use my GSAK macro if you'd like by right-clicking the icon below and selecting "Save As" To duplicate my environment you'd save this text file as C:\GPS\GSAKmacros\PushPins.txt but
it can really be anywhere. The GSAK help file states "It is recommended that you save all your macros in the 'Macro' folder of your install folder of GSAK.
Saving them here ensures they are backed up and restored when using the GSAK backup and restore features." (e.g., C:\Program Files\GSAK\macros\)
If you're mimicking my environment, you don't have to read the following paragraphs of this section! I'm going to give a little bit of the technical details in case you want to modify my macro or if you want to understand what it's doing.
GSAK macros are text files that can be edited using the Notepad program that is included with Windows. Below is an abridged version of the macro. It shows only one data set being exported (benchmarks) and I will walk you through an explanation of each command. The numbers on the left are NOT part of the macro, but allow me to reference each statement.
1.
2.
3.
4.
5.
6.
7.
8.
|
RUNPGM pgm="C:\GPS\PushPins\PushPinListReset.bat"
CANCELFILTER
FILTER name="Benchmark"
IF $_FILTERCOUNT > 0
EXPORT TYPE=SNT FILE=C:\GPS\PushPins\Benchmark.csv
RUNPGM pgm="C:\GPS\PushPins\PushPinListBuild.bat" parms=Benchmar,YYYNYYYY WAIT=YES
ENDIF
CANCELFILTER
|
Top of page
LINE 1: For the automated import of MSST pushpins, the import program requires a control file. This control file tells the import program what data files are to be imported, where the data files are located, and what graphic to use as the pushpin icon. This control file is C:\GPS\PushPins\PushPinList.txt and it is dynamically created by the GSAK export macro. Why is it dynamically created? Some filters may return zero records, and we don't want to import an empty pushpin data set. Therefore, we only put an entry into our control file if there were records that met the criteria of our filter. Below is an example control file. Any blank lines or lines beginning with a # will be ignored. Each line in the control file has two parts. First, there is the fully qualified (drive, path, and file name) data file that is to be imported. A semicolon is used to separate the first and second parts. The second part is the fully qualified graphic file that is to be used for the pushpin icon. You will notice in the example that none of the files contain an embedded space. Embedded spaces can confuse some programs, so it's best to avoid them. Spaces on either side of the semicolon will be ignored.
# My Push Pins
C:\GPS\PushPins\House.csv ; C:\GPS\PushPins\icons\House ;
C:\GPS\PushPins\Work.csv ; C:\GPS\PushPins\icons\Work ;
C:\GPS\PushPins\Benchmark.csv ; C:\GPS\PushPins\icons\Benchmark ; YYYNYYYY
C:\GPS\PushPins\CITO.csv ; C:\GPS\PushPins\icons\CITO ; YYYNYYYY
C:\GPS\PushPins\Earth.csv ; C:\GPS\PushPins\icons\Earth ; YYYNYYYY
C:\GPS\PushPins\Event.csv ; C:\GPS\PushPins\icons\Event ; YYYNYYYY
C:\GPS\PushPins\LetterBox.csv ; C:\GPS\PushPins\icons\LetterBox ; YYYNYYYY
C:\GPS\PushPins\Multi.csv ; C:\GPS\PushPins\icons\Multi ; YYYNYYYY
C:\GPS\PushPins\Mystery.csv ; C:\GPS\PushPins\icons\Mystery ; YYYNYYYY
C:\GPS\PushPins\TraditionalSmall.csv ; C:\GPS\PushPins\icons\TraditionalSmall ; YYYNYYYY
C:\GPS\PushPins\TraditionalRegular.csv ; C:\GPS\PushPins\icons\TraditionalRegular ; YYYNYYYY
C:\GPS\PushPins\TraditionalLarge.csv ; C:\GPS\PushPins\icons\TraditionalLarge ; YYYNYYYY
C:\GPS\PushPins\TraditionalOther.csv ; C:\GPS\PushPins\icons\TraditionalOther ; YYYNYYYY
C:\GPS\PushPins\Virtual.csv ; C:\GPS\PushPins\icons\Virtual ; YYYNYYYY
C:\GPS\PushPins\WebCam.csv ; C:\GPS\PushPins\icons\WebCam ; YYYNYYYY
C:\GPS\PushPins\Micros.csv ; C:\GPS\PushPins\icons\Micros ; YYYNYYYY
C:\GPS\PushPins\Found.csv ; C:\GPS\PushPins\icons\Found ; YYYNYYYY
C:\GPS\PushPins\DNF.csv ; C:\GPS\PushPins\icons\DNF ; YYYNYYYY
C:\GPS\PushPins\Archived.csv ; C:\GPS\PushPins\icons\Archived ; YYYNYYYY
|
Top of page
So, the GSAK macro begins by recreating the control file. It basically erases any old control file and starts a new one.
Since GSAK doesn't have the capability to do this directly, we use the batch file PushPinListReset.bat to do the work.
The batch file C:\GPS\PushPins\PushPinListReset.bat contains these commands:
ECHO # My Push Pins > C:\GPS\PushPins\PushPinList.txt
CALL C:\GPS\PushPins\PushPinListBuild.bat House
CALL C:\GPS\PushPins\PushPinListBuild.bat Work
|
Notice the second and third lines. You may have some special pushpins that aren't caches in your GSAK database. In my setup, my
house and place of employment are two such locations. I want them on my map so that I can plan a quick cache run after work or
plot a route from my home. These data files are created by hand. I used Notepad to create the CSV files (an example is shown below
for HOUSE.CSV). The first line should remain unchanged. It tells MSST what data fields are being imported. The second and following lines have
the actual details with one pushpin location per line. Coordinates are WG84 datum in the DDD.dddd format (with negative numbers
for western hemisphere longitudes or southern hemisphere latitudes)
Name,Latitude,Longitude
HOME,34.123456,-85.123456
MOTHER-IN-LAW,35.123456,-85.234567
|
LINE 2: Lines 2 through 7, with slight modifications, are repeated for each pushpin type we want to export. Line 2 simply cancels any filters that
may be in effect.
LINE 3: Apply the filter named "Benchmark" (that was created in the preparatory step above). If none of records in our GSAK database pass the filter, then processing skips to the nearest ENDFILTER command (line 6).
This way, we don't create an empty pushpin data set or a control file entry, which would confuse the MSST import! A filter may contain embedded spaces, so I always enclose the filter name in double quotes.
SEQUENCE IS IMPORTANT: Lines 2 through 7 are repeated, with slight modifications, for each pushpin type we want to export. The order in which these types are listed in
the GSAK macro determines in what order they will appears in the control file that is created. The order in which the data files are listed in the
control file determines the order in which they will be imported into MSST. The order in which data files are imported into MSST determines how
push pins overlap. If you have a dataset that overlaps, the last dataset will be on top. Below is a closeup of a pushpin map that shows what I mean:
There are three pushpins in this screen shot. Two "found it" icons, and one DNF (did not find) icon. I've clicked the smiley (found) on the far left and MSST shows me that there are actually two push pins stacked on top of each other. The names associated with these pushpins are identical, so I know that there is a data set overlap and not simply two different caches that are really close together. You can see from the "Select a Place" dialog that the cache type is a micro. It's below the "found" icons because my GSAK export macro created the MICROS.CSV file before it created the FOUND.CSV data set.
Also note the frowny in the upper left of the screen shot. If I were to click this pushpin, the "Select a Place" dialog would show that there are THREE pushpins stacked. The first is for the cache type (micro), the next is for the DNF status, and the last shows the "archived" status (the red circle with a slash). These overlaps are by design, and I have purposely placed the DNF export near the end of my GSAK macro, while the Archived export follows that in the macro.
This in essence tells a story: Someone placed a micro cache, I searched for it, but I didn't find it. I didn't find it, because it'd just recently been archived.
LINES 4 and 7: If no caches meet our criteria, then we do not want to confuse the PushPin program by importing an empty file. This line
causes processing to skip to the nearest ENDIF statement and continue processing if the filter returns an empty data set (line 7 in our example).
LINE 5: If the filter successfully identifies a subset of our GSAK database, we export that subset as a MSST type file (TYPE=SNT). MSST can import CSV files (comma or tab separated values). We will put all the CSV files in the G:\GPS\PushPins\ directory. The CSV file will have the SAME name as the pushpin graphic, and that name will not contain any embedded spaces. Therefore for the "Benchmark" filter we will create a file named Benchmark.CSV that will use a graphic called Benchmark.BMP
Optional Settings for Advanced Users
Not shown (and not used in the example file for download) is the optional SETTINGS parameter. When creating an export you can control aspects
(e.g., the Waypoint name or Description format) of the export and save these to a name. Personally, I created and saved an export setting named PushPins.
That setting uses the following special tags for waypoint names: %drop2_%typ1%con1_%dif1a/%ter1a %notGC %code
See the GSAK help file for the different "Special Tags" available. Here is what all those funky codes in my settings do:
If the waypoint doesn't begin with "GC" [%notGC] then I want the waypoint code to remain unmodified [%code].
Otherwise, drop the first two characters [%drop2] of the the waypoint (all caches from Geocaching.com begin with "GC" which isn't informative).
Next append an underscore character for readability ("_" is not a special tag) then a one-letter code for the cache type [%typ1]
then a one-leter code for the type of container [%con1], then another underline for readability.
Then a one-letter code for mental dfficulty [%dif1a] a slash and then a
one-letter code for difficulty of terrain [%ter1a]. So a waypoint named 9999_BR_A/D is GC9999, Letterbox type, Regular size, 1.5 mental difficulty,
and 4.5 terrain difficulty.
LINE 6: Note that the filter can be named anything: it is the data file and pushpin icon that need to have the same name. That name is passed in the "parms=" part of the macro. The name given in parms= is used by PushPinListBuild.bat to create a line in our control file. Below are the contents of C:\GPS\PushPinListBuild.bat
and you can see why it is important that all the staging directories are consistent and that data files and icons have the same name.
|
ECHO C:\GPS\PushPins\%1.csv;C:\GPS\PushPins\icons\%1.bmp;%2 >> C:\GPS\PushPins\PushPinList.txt
|
Also note the "YYYNYYYY" in the PARMS= entry. This controls which balloon fields will be displayed (right-click a pushpin and
select "Show Information". There is one Y or N for every possible balloon field. A "Y"
means "yes, it will be displayed" while an "N" means "no, it will be hidden." Most people will use the settings
I show below (which displays everything except the meaningless and space hogging URL). The data exported by GSAK
includes these fields (in this order): Name (of cahe), Latitude, Longitude, Description, URL, Type, Container, Diff (difficulty), and Terr (terrain)
|
RUNPGM pgm="C:\GPS\PushPins\PushPinListBuild.bat" parms=Benchmar,YYYNYYYY WAIT=YES
|
The WAIT=YES tells GSAK that it must wait until each pushpin data set is built before starting the next.
LINE 7: See notes for line 4
LINE 8: Cancel any filters. The end.
mssticons.zip
pushpins.txt
Whoo Hoo! Once the preparatory setup is finished, you can forget about it. Now you're ready to create the data files. Every time you want to create a new pushpin map, run the GSAK export macro to create new pushpin data sets. To run the macro press Ctrl-M or navigate to /Macro /Run and specify your GSAK export macro (C:\GPS\GSAKmacros\PushPins.txt in my setup). A typical database will take several minutes to process. You can tell that GSAK is done when the windows stop popping up, the "Run Macro" dialog window closes, and "Subset: None" appears in the lower left status bar.
[Advanced user note: I used the Macro menu to create a button called "PP" for my tool bar]
