What is it all about?

FSGPlugin_CacheMap is a plugin extension macro for the GSAK macro FindStatGen (FSG). It normally runs when "called" from one of the notes sections of FSG. In this case you must have installed FSG version V4.1.12B or better.

Since macro version 3.0 macro can run in direct mode as well. In this case it doesn't read FSG's database tables, but active GSAK table to retrieve cache data.

FSGPlugin_CacheMap generates maps showing your found or placed (own) caches as small logos on it. The macro is using "Google Static Maps" interface and places logos (depending on cache type) to the according positions based on coordinates from GSAK databases.

What and how to display on the map, location and scaling of the generated map you can tell the macro via parameters.

List of macro parameters:

MAPTYPE	Google offers 4 types: roadmap, satellite, hybrid and terrain. Default: terrain.
LATITUDE	Latitude value of the center point of the map. Default: my (Doblinus) home location
LONGITUDE	Longitude value of the center point of the map. Default: my (Doblinus) home location
HOME	For taking values for longitude and latitude of center map position from your GSAK home position. Remark: When using this parameter your home position must be defined in GSAK. This parameter doesn't need any asigned value, use only &HOME
ZOOM	Zoom factor for the map. Possible values are: 1 to 21. Default: 11 Remark: This type of scaling is defined by the "Google Static Maps" interface. With zoom=1 you can map whole world with size 512x512. Every increment of zoom zooms into the map by factor 2 in both axes.
WIDTH	Width (pixels) of the generated map, min=100, max=640. Default: 640
HEIGHT	Height (pixels) of the generated map, min=100, max=640. Default: 640
SIZE	for setting height and width to same value, to make life easier when using squares. Remark: Maximum values for height and width will be cut by the macro when zoom=1 (and only then). This is due to Google's limitation of the "world map".
LOGO	Size for the used square cache logos on the map (pixels). Default: 16 Remark: If logo size set smaller than 17 pixels the "small" logo set of gc is used, otherwise the "large"' set is used. However, logos are allways scaled to given value.
LEG	With parameter leg=n you can switch off displaying map's foot note. Default: leg=y
TYPE	to tell macro what to show, might be placed or found. Default: found Remark: When not running in i>direct mode (see above) you select which FSG table to use. If you use type=placed you have to be sure that the corresponding FSG table is available. This can be done in one of three ways: 1. The 'Placed' section being used (selected) in FSG 2. The string '<placed>' found in any of the Notes sections of the current Setting group of FSG 3. The string '<placed>' in any of the Section 'Plug-in' notes sections of the current Setting group
COUNTRY	to select only caches from dedicated country. Remark: With f.e. ...&country=Germany... you can limit map only showing caches located in Germany, country names must be written as in GSAK but are not case sensitive. Country parameter filters caches only. It doesn't postioning of the map. Latitude/longitude or home have to be set anyway.
CORRECTED	When set macro uses "corrected" coordinates instead of "originals". Remark: This might make sense if you store the final location of puzzle caches as corrected coordinates and don't want to give that information away.
ARCHIVED	With parameter archived=n you can suppress displaying archived caches. Default: archived=y
LIGHTNESS	Lightness of Google map colors. -100 to +100 (defaults to 0 - negative numbers darken the image, positive lighten it)
SATURATION	Saturation of Google map colors. -100 to +100 (defaults to 0 - negative numbers reduce color saturation, positive increase it) Remark: Lightness and Saturation do not apply if MAPTYPE=Satellite
FILTER	Filter caches by extending SQL query statement (default: no filtering) Remark: Should only be set by users who are familiar with SQL and FSG's database tables. See example below.
SMALLMAPS	When this parameter is set, resulting map will not be centered. This can be used to group a couple of small maps by HTML table structure. See examples section. Remark: User should have some basic knowledge of HTML structures.
USESMILIES	When this parameter is set, resulting map will not show cache type icons, but smilies instead
FAVPOINTS	When this parameter is set, cache icons' hover text will contain number favorite points this cache has obtained. Remark: Due to limitation the actual API the favorite points information can be read for 30 caches per minute! The macro takes care of this limitation, but it may increase macro run time dramatically when FAVPOINTS is used on maps with large amount of caches to display.
OUTFILE	This parameter is meaningful only when macro is running in direct mode. So you can define a filename where macro should write it's out to. It default to CacheMap_output.htm.

If none of the parameters is set, then macro centers map to your home location (which in this case must be defined in GSAK). All oher parameters are set to defaults as mentioned above. This was made that you can start using the macro quite simple when start testing. However, there should be some finds in your home area. Otherwise you will get an error mesage or will see an empty map w/o any caches.

Direct mode (how it works):
The macro detects if being called by FSG or not. If FSG is the caller, CacheMap behaves like version 2.x and reads cache data from FSG database and returns it's output to FSG.

If macro is NOT called by FSG it reads cache data from active GSAK database and writes output to file. This then can be imported to FSG's output stream by <file>...</file> tags. The output file name can be set by parameter OUTFILE.

When executing CacheMap directly, problem comes up to define macro parameters. There are at least two possibilities to solve that:

(1) You can define macro button in GSAK and set parameters to call definitions. You then have to select desired GSAK database and hit the macro button, or

(2) a bit more comfortable, especially if you have multiple usage of CacheMap in direct mode, is to use a caller macro.

An can download an example of such a caller macro from here.

Some examples to make understanding more easy

The following example are based on my (Doblinus) found and placed caches
Lets start with simple case, using all the defaults.

Result will be a map arround my home coordinates, showing may found caches, on terrain map, with 640x640 pix size, using 16x16 pix logos, zoom=11, saturation and lightness set normal.

Macro call

<plugin>FSGPlugin_CacheMap</plugin>

will result in this map:

Now bit more interesting example: showing my own caches
Center of the map is set in this way, that all of my caches are shown.
Result showing placed caches, on roadmap, with 640x400 pix size, using 24x24 pix logos, saturation and lightness set normal, a bit more zoomed out than first map.

Macro call

<plugin>FSGPlugin_CacheMap?longitude=9.5&latitude=54.72&type=placed &width=640&height=400&zoom=10&logo=24&maptype=roadmap</plugin>

will result in this map:

Next example is same as above, but lightness set to 30 and saturation set to -70 to show cache logos more clearly, and favorie points are beeing retrieved from geocaching.com via API by setting parameter FAVPOINTS (see caches' hover text).

Macro call

<plugin>FSGPlugin_CacheMap?longitude=9.5&latitude=54.72&type=placed &width=640&height=400&zoom=10&logo=24&maptype=roadmap&lightness=30&saturation=-70&favpoints</plugin>

will result in this map:

Next example shows usage of filtering caches with FILTER parameter. The SQL query for fetching caches is extended by "and <filter>", here for selecting FTFs only. <filter> is set "FTF=1", where "=" has to be substituted by ":" due to parameter syntax reason.

Filtering should only be used if familiar with SQL and FSG's database tables! Setting incorrect parameters will let macro fail!

Macro call

<plugin>FSGPlugin_CacheMap?longitude=9.4&latitude=54.62&type=found&maptype=roadmap &size=640&zoom=10&lightness=20&saturation=-20&filter=(FTF:1)</plugin>

will result in this map (showing most of my FTFs):

Similar as last example, but now filtering for mysteries (Unknown caches) which aren't archived. <filter> is set "CacheType='U' and archived=0", where "=" has to be substituted by ":" due to parameter syntax reason.

Macro call

<plugin>FSGPlugin_CacheMap?longitude=9.4&latitude=54.62&type=found&maptype=roadmap &size=640&zoom=10&lightness=20&saturation=-20&filter=(CacheType:'U' and archived:0)</plugin>

will result in this map:

Now filtering for my day with most finds (2011-04-15). <filter> is set "(FoundByMeDate='2011-04-15')", where "=" has to be substituted by ":" due to parameter syntax reason. Smilies are used instead of cache icons (parameter USESMILIES).

Macro call

<plugin>FSGPlugin_CacheMap?longitude=9.267&latitude=54.75&type=found&maptype=roadmap &width=640&height=300&zoom=13&filter=(FoundByMeDate:'2011-04-15')&usesmilies</plugin>

will result in this map:

Now showing my finds in the world
Doesn't make so much sense - only for demonstration. Center of the map is set to "0/0".
Result showing found caches, with satellite view, with 512x300 pix size, using 16x16 pix logos, maximum zoom out, saturation and lightness set normal.

Macro call

<plugin>FSGPlugin_CacheMap?longitude=0&latitude=0&type=found&width=512&height=300 &zoom=1&maptype=satellite</plugin>

will result in this map: