worldKit will work right out of the box. Unpack the files from the download, and place them in a single directory on your webserver. Load the url for this directory in your browser, and you should see the introductory app. Easy huh?

The next three sections of this manual detail the core steps for setting up worldKit: editing the configuration file, finding and using images for base maps, and writing geocoded RSS. Additonally, there is a section on integrating worldKit into weblogging systems, and a section on topics beyond the basics.

It's not necessary to read the entire manual before starting to work with worldKit. Try stuff out as needed. Support is available from here.

• worldkit.swf: This flash movie is the core mapping engine. You don't need to worry about it - just make sure it's on your server.
• config.xml: Configuration file for appearance and functionality. Read about setting up options in the Configuration section.
• day.jpg and night.jpg: These images are courtesy the Blue Marble satellite imagery. Read about finding and configuring map backgrounds in the Images section.
• rss.xml: Geographic annotations are read in the RSS syndication format. Read about making annotations in the RSS section.
• index.html: A sample HTML page containing worldKit. Read about setting up worldKit in HTML in the next subsection.

The following HTML demonstrates how to include worldKit within a web page.

Most folks can just copy this markup into their HTML and be set. Both the <object> and <embed> tags are necessary for cross-browser support. To change the size of the map, the WIDTH and HEIGHT of the map must be set in both tags.

If the location of worldkit.swf is in a different directory from the containing web page, set that location in both the OBJECT tag's "movie" param, and the EMBED tag's "src" attribute. The "id" and "NAME" parameters should also match.

You can download all of this documentation in a single file, from here.

config.xml is a simple XML file, which sets the parameters of worldKit. It is requested from the same directory as the HTML file that embeds worldKit.swf.

The following is the sample config.xml included in the package.

The root node of config.xml is <worldkitconf>. The rest of the file is simply child nodes, specifying the values of the configuration paramaters. The parameters relating to visual appearance are described in the next sections. Other parameters are described throughout the manual.

Important: Two parameters always required are <width> and <height>, and their values should match the WIDTH and HEIGHT attributes in the HTML. (This repitition is required because worldKit.swf does not have access to the HTML attributes.)

Sizes and Colors

• <plotshape>: The shape of an annotation marker. Accepted values are "square", "circle", and "triangle", The default value is "square".
• <plotsize>: A numeric value specifying the size of the annotation point. The default value is "3".
• <textsize>: The size, in pixels, of annotation text. The default value is "10".
• <textboxsize>: The width, in pixels, of the text box visible when an annotation is activated. The default value is "200".
• <singletextfield>: If set to true, text is displayed at the top of the map, rather than adjacent to the annotation. The default value is "false".
• <initialplotcolor>: A hex color value. New annotations will be displayed in this color for 60 seconds. The default value is "0xFF0000".
• <restingplotcolor>: A hex color value. Annotations will change to this color after 60 seconds. Set to the same value as "initialplotcolor" if you don't want the change. The default value is "0x00FFFF" (cyan).
• <activatecolor>: A hex color value. Annotations will change to this color when activated by the JActComm Javascript API. The default value is "0xFF0000".
• <track>: Set to "true" to display lines between successive annotations, as in a GPS track log. Default value is "false".
• <linecolor>: A hex color value. Points, tracks, lines, and polygons will be displayed in this color. The default value is "0x000000" (black).
• <linealpha>: A numeric value, 0-100, specifying the degree of transparency of lines in points, tracks, line and polygon annotations. "0" is invisible, "100" is full visible. The default value is "100".
• <linethickness>: A numeric value, specifying the thickness of lines in points, tracks, line and polygon annotations. The default value is "0".
• <fillalpha>: A numeric value, 0-100, specifying the degree of transparency of fill in points and polygon annotations. "0" is invisible, "100" is full visible. The default value is "100".
• <visible>: Set to "false" and annotations will be invisible on load. They can be made visible via Javascript. Default value is "true".

Zoom and Pan

Besides the toolbar options below, the keyboard can be used to control zoom and pan. The arrow keys control pan, Z zooms in, and A zooms out.

• <zoomselect>: Set to "true" to enable Zoom and Pan by drawing a red selection box on the map. By default, it is "false".
• <grabber>: Set to "true" to enable click and drag Pan. By default it is enabled.
• <toolbar>: Set to "true" to display the Toolbar. The default value is "false".
• <controlscale>: A numeric value specifying the scale of the Toolbar. The default value is "100".
• <controlalpha>: A numeric value, 0-100, specifying the degree of transparency of the Toolbar. "0" is invisible, "100" is full visible. The default value is "70".
• <maxscale>: A numeric value, 1 or greater, specifying the maximum level of zoom permissible. The default value is "64".
• <panc>: A numeric value controlling the speed when panning across the map. Higher values correspond to slower panning. The default value is 16.
• <zoomc>: A float value, greater than 1, controlling the speed of zoom in and out of the map. Higher values correspond to faster zoom. Default value is 1.5.
• <maxzoom>: If set to "true", the map will zoom and pan to a bounding box surrounding the area where annotations are initially present. The default value is "false".
• <initialzoom>: On startup, the map will be zoomed to this magnitude, set from 1 to "maxscale". The default value is 1.
• <initiallat>: On startup, the map will pan to center on this latitude. By default, it is midway between north and south.
• <initiallong>: On startup, the map will pan to center on the longitude. By default, it is midway between east and west.
• <zoomto>: If set to a numeric value, annotation clicks will zoom to the level specified, centered on the annotation, rather than opening a url.

Window and Plot Timing

• <window>: Specifies the name of the window links are opened in. Use "_self" for the same window, "_blank" for a new window, etc. The default value is "_blank".
• <plotinterval>: The number of seconds between plots of successive annotations. For simultaneous display of all annotations, use "0". The default value is "5".
• <textinterval>: The number of seconds the text box is visible after an annotation is first plotted. The default value is "5".
• <visinterval>: The number of seconds the text box is visible after mouse activation. The default value is "5".
• <fade>: Specifies a number seconds for an annotation to fade to transparent. Useful for visualizing transient information. The default value is "-1", which means no fade.
• <showload>: Set to "true" to display messages while images and RSS are loading. Default value is "false".
• <loadimgmsg>: Specify a string for display while images are loading. Must set to "true" for this to be effective. Default value is "Loading Images...".
• <loadrssmsg>: Specify a string for display while RSS is loading. Must set to "true" for this to be effective. Default value is "Loading Points...".
• <zlevel>: Set to "-1" to plot newer annotations below older ones. Default value is "1", meaning newer annotations are positioned above older ones.

Base map images for worldKit must be JPEG images. The images can be of any dimension; worldKit will scale them to the specified width and height. Map images can cover the entire Earth, or a few blocks of the neighborhood.

There are four types of map images supported. The type is specified in the <displaytype> configuration option.

• day: A normal rectangular projection. Specify the url of the map image in the <dayimg> configuration option. If <dayimg> is set to blank, no image is loaded.

• daynight: The current solar illumination of the earth is displayed. This requires both a <dayimg> and <nightimg> specified in the config.xml.

• zoomify: For very large map images, Zoomify tiles the image and only retrieves sections necessary for the current Zoom and Pan. Read more about Zoomify here

• polar: A polar projection of the Earth, centered on the North or South pole. Here is an example. Must specify a <polarimg> configuration option.

The "bounding box" of the map image must be known. This is specified in the configuration options <north>, <south>, <east>, and <west>. By default, worldKit assumes that the map covers the entire Earth (north=90, south=-90, east=180, west=-180). For "polar" maps, it is only necessary to specify the northern or southern extent of the projection.

It is permissible for the bounding box to cross the line of longitude at 180 east, -180 west. If the value of <east> is the same as <west>, then it is assumed that the map crosses this line.

Here are a few pointers for finding basemap images.

MapProxy is a free service, retrieving maps for any US address, zip code or lat/long, or International city, and providing the N/S/E/W boudning box for that map. Maps are available as aerial photographs (some in high quality color), topographic maps, or street maps.

There are many interesting whole Earth images in Flatplanet Maps catalog.

This package contains a "Zoomify" image of the high resolution Blue Marble satellite image. Read about using Zoomify here.

This South Pole Image can be used with the "polar" projection. North is -60.

Blue Marble satellite images are stunning, highly detailed whole earth images produced from satellite data. Two Blue Marble images are included with the worldKit download.

One strategy for producing basemaps on the scale of continents or countries is to download a large 8192 by 4096 Blue Marble image (located here : warning! very large 26.5 MB), crop it to the desired area, and save as a JPEG.

In the cropping, it is necessary to determine the exact pixel bounding box of the crop, in order to set up the N/S/E/W values in configuration. Assuming the origin is in the upper left hand corner, use the following formulas. "Hieght" and "Width" refer to the original image.

Another option is to use the <maxzoom> or <initialzoom> options, to focus a whole Earth image on the area of interest.

Instead of a small shape, it is possible to a small image to mark annotations. Supply the url of an image in the configuration option <icon>, and that image will be used as a marker. This is especially useful when combined with Categories. An icon for an individual item can also be specified directly in RSS.

Zoomify is an image processor and Flash viewer, for creating fast, high-res, interactive zoom and pan images on the Web. It saves bandwith by only requesting imagery required for the current viewing resolution of the image. worldKit integrates Zoomify to present high resolution base map images.

To use Zoomify with worldKit, follow these steps.

1. Download and install the Mac or Win Zoomifyer EZ.

2. Run the Zoomifyer EZ Application. It will prompt you to select an image for processing, and will produce a subdirectory in the same directory as the image.

3. Upload the contents of this directory (ImageProperties.xml and TileGroup*) to a directory on your server.

4. Configure worldKit to use Zoomify. Set <displaytype> to "zoomify". Specify the directory containing your Zoomify image in <zoomifydir>.

5. The <width> and <height> of the map must be in the same ratio as the width and height of the zoomified image.

6. You may want to consult the Zoom and Pan options. By default, <toolbar> is set to true for zoomify display.

Also, available for download is a Blue Marble Earth image, Zoomify'd and ready for use with worldKit. Get that from here.

Changes: zoomifyViewer.swf is no longer required. And the configuration option <zoomifynav> is no longer supported following changes in how zoomify is integrated into worldKit.

Map annotations are specified in the RSS XML format. RSS is a widely supported format for syndication of news and weblogs, and is extendable to publish any sort of itemized data. Publishing geographic annotations in RSS has several advantages: there are a large number of tools available to write RSS, and other services, besides worldKit, can make use of the geographic metadata. Most important for the basics, RSS is a simple format and easy to edit by hand.

worldKit supports three flavors of RSS: RSS 2.0, Atom, and RSS 1.0. Geographic data is assigned to RSS <item>'s by additional tags in the georss namespace. Also, worldKit accepts geoannotations within certain standard RSS tags, for users of hosted services that prohibit adding new tags to RSS.

An example RSS 2.0 file is included with the worldKit package.

Within the <channel>, there are multiple <item>'s each specifying an annotation. The <title> and <description> are displayed in the annotation's textbox, and the <link> is loaded on mouse clicks. The point is plotted at the latitude/longitude specified by <georss:point>.

Important: The georss namespace must be specified in the root <rss> tag, so make sure to add the "xmlns:georss" attribute.

Both GeoRSS Simple and GeoRSS GML are supported. And though the georss namespace is recommended, worldKit is permissive and supports all known varieties: <geo:lat>, <geo:long> (W3C Geo), <icbm:lat>, <icbm:latitude>, <geourl:latitude>, <icbm:lon>, <icbm:longitude>, <geo:lon>, <geourl:longitude>. Also accepted is a <geo:Point> element, with <geo:lat> and <geo:long> child elements.

If there is no access to the structure of the RSS feed (for example, services like TypePad and Blogger), it is possible to geocode within existing RSS items. By default, this feature is not enabled; the configuration option <locfield> is described below.

To specify a location, simply type geo:lat= and geo:long=, followed by the value, within a tag. For example,

Tags supported are <description> in RSS 1.0 and 2.0, <summary> & <content> in Atom, <category> in RSS 2.0, and <dc:subject> in RSS 1.0 and Atom. worldKit expects to find the geotags in the field specified by the <locfield> config option. Its value is the name of the tag containing the annotations; or the value "any", which will have worldKit search through any of the four fields above.

Additional information on using this method in practice is in Typepad and Blogger.

There are some drawbacks to this method. This is not strictly "correct" usage of a namespace. The annotations show up as plain text (though this may be desired by some) or interfer with other functions (<category> sometimes has specific uses in weblog software). Still, on the whole, it is a useful compromise.

There are a few configuration options (in config.xml) associated with retrieving the RSS feed.

• <dataurl>: This url specifies the location of the RSS file containing annotations. It can point to a static file or dynamic CGI. It can be an absolute or relative path, but can not reside on different server from worldKit (due to the Flash Player security model). If set to NULL, then no RSS is requested. The default value is "rss.xml".
• <updateurl>: This url specifies the location of the RSS feed retrieved repeatedly after the first RSS feed in dataurl is retrieved. This is useful for transferring only new annotations on each update. By default, this value is the same as dataurl.
• <update>: The time, in seconds, between retrievals of the RSS feed. If set to 0, the RSS is retrieved only once. The default value is 60.
• <uniqueurls>: Set to "true" to insure that RSS requests are unique and avoid hitting any cache. The current timestamp will be appended to the url. The default value is "false".
• <showonlynew>: When set to "true", only annotations present in the last RSS update will be displayed. Default value is "false".
• <locfield>: Set value to the name of the RSS tag to look for annotations. Values accepted are "description", "summary", "category", "dc:subject", or "any" (all four fields will be examined). By default, this option is not set, and no tags are examined.
• <rssbbox>: Set to "true", the bounding box of the current view is appended to the RSS feed url. url&bbox=WEST,SOUTH,EAST,NORTH. This is useful for displaying only part of a large data set. Default value is "false".

Multiple feeds can be specified for dataurl and/or updateurl. Use a new element for each additional feed. This can be useful if your GeoRSS comes from multiple sources, or you wish to cut the size of your data into more "digestable" chunks.

These are a few suggestions for web sites to determine latitude and longitude for an annotation.

• worldKit Geocoder: Integrates several geocoders into one easy interface.
• Maporama: Search for nearly any address in the world. Lat/Long are listed at the bottom of the left column on the map page.
• Geonames

It's also possible to use worldKit for geocoding. See Annotation Input.

Images can also be displayed at an annotation, instead of text . Add a <media:content> to any <item>, with the "url" attribute set to the url of an image.

The annotation itself can be a small image, rather than a shape. This can be specified for an individual item with <media:thumbnail>.

You must specify the "media" namespace by addng xmlns:media="http://search.yahoo.com/mrss/" to the root rss node.

<photo:thumbnail> used to be the recommended format for sepcifying images. It's still supported, but the media namespace is recommended to be inline with current web practices. Make sure you have the most recent version of worldKit.

worldKit (and the Flash Player generally) can display any characters encoded in "UTF-8". This covers everything from Swedish to Chinese toCyrillic.

To display annotations in international characters sets, make sure that the RSS file is saved in the UTF-8 encoding. Many text editors support UTF-8: Notepad on Windows, BBEdit on Mac, vim on unix. Also most software development packages will have support for writing UTF-8 files.

For certain advanced features (like the Javascript API), it is useful to assign known identifiers to RSS items. You can assign a unique id to a RSS 1.0 item with <dc:identifier>, a RSS 2.0 item with <guid> and an Atom entry with <id>.

If you don't assign an item an id, worldKit generates an internal identifier. This is perfectly fine generally, so don't worry about id's unless you have to.

Here's an example of geocoding in RSS 1.0.

Here's an example of geocoding in Atom.

Here's an example of geocoding within <dc:subject> tags.

Annotations can be assigned to categories, corresponding to different groups of configuration settings. For example, annotations in different categories can be displayed in different colors. Additionally, categories are used in the Javascript API.

Categorizing configuration parameters is a two step process. First, annotations in the RSS file need to be assigned categories. <dc:subject> can be used in RSS 1.0, 2.0, and Atom. Be sure to include the xmlns:dc="http://purl.org/dc/elements/1.1/" declaration in the root node. Alternatively, <category> can be used in RSS 2.0.

Here's a sample RSS 2.0 item, categorized with <dc:subject>.

Then, configuration options need to be categorized. Add subtags to configuration parameters, with the node name as the Category and the node value as the associated configuration value.

For example, the following assigns different plotshape's depending on category. Any annotation not assigned to "category1" or "category2" will receive the default value, here "square".

The following configuration options are categorizable:
<icon>, <initialplotcolor>, <plotshape>, <plotsize>, <restingplotcolor>, <activatecolor>, <window>, <linecolor>, <linealpha>, <linethickness>, <fillalpha>, <zoomto>, <visible>.

It is possible to assign an annotation to multiple categories, to independently control multiple configuration options. For example, in a plot of recent earthquake activity, the size could vary according to the mangitude of the earthquake, and the color could vary according to how recently it occurred.

The concept of categorized <track> display works slightly different. If the config option <trackcats> is set to "true" (as well as <track>) then lines are drawn between successive points belonging to the same category.

For example, say there are three successive points listed in RSS. The first and third are assigned "category1", and the second "category2". Without <trackcats>, the track line is drawn to connect all three; with <trackcats>, the track line is drawn between only the first and third.

Also note, <trackcats> ignores multiple categories; only the first, primary category is considered.

To enable Moveabletype to publish Geocoded RSS, use Timothy Appnel's Meta Plugin. Its described as "a simple lightweight Movable Type plugin for displaying embedded meta data in either keywords or text_more fields represented in a basic XML format". That XML format has root tag meta, with a single layer of XML tags and values, which are then available as key-value pairs to any MoveableType template.

Install the plugin on your Moveabletype server, and choose to use either the keywords or text_more field for entering geographic metadata (well assume keywords from here on). Make sure that field is visible on the Edit Entry screen, by the "Customize the display of this page" link. When writing an entry, you enter that small bit of markup, indicating the lat/lon of the entry.

You'll next need to edit one of the RSS templates on the Edit Templates screen. There are several MoveableType tags implemented by the Meta plugin. Used as follows within an RSS <item>, a lat/lon will be added to the RSS feed whenever they are present.

Finally, dont forget to declare the geo namespace, by adding the following attribute to the root rss tag (xmlns:georss="http://www.georss.org/georss").

The Location tool uses Radios callback mechanisms to add latitude and longitude inputs to the post form, and includes those entries in the RSS file. Just download and install the tool, and its all set.

The tool also defines a tag to include in itemTemplate.txt, locationlink, which displays a small globe linking to a map of the location specified. Use it like this.

Zope/Plone: PloneWorldKit is an out of the box web mapping solution for ZOPE/Plone.

WordPress: There has been a bit of work on integrating WordPress and worldKit. Check in with the progress on WordPress Wiki: worldKit

Drupal: Likewise with Drupal: Geourl & mapping module

Joomla: An Exclusive G.I.S. Solution for Joomla

del.icio.us: mapping del.icio.us is an experiment in using del.icio.us as a collaborative geo-annotation database. worldKit can use geocoded del.icio.us RSS feeds, via proxy.

flickr: Try out the mapping flickr service. This perl script is used to translate flickr urls into geocoded RSS, via the Flick API.

To install worldKit for use with a TypePad weblog is straightforward, but differs slightly from a standard install due to limitations at each TypePad subscription level. See an example of TypePad and worldKit at this weblog and this map.

Typepad Basic and Typepad Plus

At these subscription levels, there is no direct access to the templates for the RSS feeds. So, geolocation must be added using the Geocoding Without Addditional Tags method. In short, when writing a post you'll include the latitude/longitude directly in the Post Body. For example,

It must be insured that the entire post, including any geotags, is present in the RSS feeds. From the TypePad app, go to Weblogs > Configure > Publicity & Feeds, and select "Yes, offer a feed of the entire post." under the Feeds section.

Next, you'll need to edit the config.xml to reference the RSS feed, and the background image. Choose either your RSS 1.0 (index.rdf) or Atom (atom.xml) feed, and set <dataurl> to the full path of that feed (e.g. /my_weblog/index.rdf). Set <locfield> to "description" if using RSS 1.0, or "summary" if using Atom. For the image(s), simply set those fields to the image names; it's easiest to install all of worldKit in a single TypePad directory.

To upload worldKit, go to Control Panel > Files, and indiviudally upload the HTML file, config.xml, images, and worldkit.swf to a single directory. Probably a good idea to Create a New Folder to hold all these files. If you later update any of these file with another Upload, you will have to confirm replacing the older file.

Gotcha: For unknown reasons, TypePad will not display config.xml in the File Manager. However, it is still present and accessible from your web browser.

Now your map is ready to go! Any geotagged blog posts will automatically be mapped. You may want to include a link to your map in a TypePad list in the weblog sidebar.

Typepad Pro

With a Pro account, there is access to templates. However, because there is no way to install MoveableType plugins, the MT method is still not possible. It is possible to implement some template processing to parse the Keywords field without MTMeta, and that method may be examined here in the future.

Of course the Basic & Plus method will work just fine too.

Blogger weblogs can use the Geocoding Without Additional Tags method. In short, when writing a post you'll include the latitude/longitude directly in the Post Body. For example,

Since BlogSpot does not offer the ability to upload files, you will need to publish your weblog to another server with that access. Upload the worldKit install to that server, setting <dataurl> to the location of your Atom feed, and <locfield> to "summary".

In addition to points, worldKit can draw polygons, lines, and boxes. In the RSS file, instead of specifying coordinates in <georss:point>, a space seperated list of coordinates is provided in either <georss:polygon>, <georss:line>, or <georss:box>. Each coordinate is a space seperated lat/long pair.

GeoRSS Simple (shown here) and GeoRSS GML are both supported and recommended. The old informal specification of geo:polygon and geo:line is still supported but not recommended.

Here is a simple example of a polygon, a line, and a box in RSS.

As for colors, the line/polygon/box border will be drawn with the hex color listed in config option <linecolor>. The polygon/box will be filled with colors specified in <initialplotcolor> and <restingplotcolor>. The alpha of borders and lines is specified in <linealpha>, and of fill in <fillalpha>.

Annotation textboxes are positioned at the first coordinate in the list. Polygons/boxes are filled with 30% transparency, so annotations plotted before are visible. However, those covered annotations are not clickable. One way to adjust this behavior is through the <zlevel> config option.

If <zoomto> is set, the zoom will be centered on the first coordinate listed in the line or polygon. Alternately, if <georss:point> is specified, the zoom will center to that point.

worldKit supports time navigation. Many processes investigated with GIS have a significant temporal dimension: urban planning and land use, hydrology, fires, ecological change. In addition to being spatially arranged, controls allow annotations to be revealed according to their timestamp. Looking at examples probably does a better job of explaining: History of Urbanziation and Tower Hamlets.

Annotation timestamps for an <item> can be set in subtags: <dc:date> in RSS 1.0, <pubDate> in RSS 2.0, and <updated> in Atom. Most weblog systems will include publication date in feeds automatically.

The format for <pubDate> is defined here, and basically looks like this example:

The format for <dc:date> and <updated> is defined here, and basically looks like this example:

worldKit adds a time navigation control to the bottom of the map. Moving the slider reveals all points occuring before that time. There are also key controls: "p" to Play, "r" to Rewind, "s" to Stop. The configuration options are..

• <timenav>: Set to true to enable time navigation. The default value is "false".
• <startdate>: The earliest date for the time navigation control. This value must be specified, in either of the formats above.
• <enddate>: The latest date for the time navigation control. This value must be specified, in either of the formats above.
• <timenavunit>: The number of steps between the start and end, on the navigation control. The default value is "200".
• <timenavpos>: The preset position of time navigation. This value must be between 0 and the value of <timenavunit>. The default value is "0".

Note!: worldKit will only handle timezone offsets, specified numerically. Any items without a timestamp are given a timestamp of the current time.

In experimental phase, worldKit can also "end events". Events that have concluded relative to the time slider control will be hidden. To set the end time of an event, we are currently supporting the RSS Event Module. As Calendar and Event formats are in flux, a different format may be preferred later on.

The elements are <ev:startdate> and <ev:enddate>. Declare the namespace with xmlns:ev="http://purl.org/rss/1.0/modules/event/". In contrast to the Module Specification, worldKit will support times in either of the formats listed above.

It is possible for worldKit to respond to certain commands from Javascript, and for worldKit to send commands to Javascript. This allows for interesting integrations within web applications.

For Javascript-Flash communication in either direction, make sure that swLiveConnect="true" is set in the embed HTML tag.

It is highly recommended that applications needing Javascript communication use the latest worldKit and require Flash Player 8, as it fixes browser inconstencies.

Javascript communicates with Flash by calling the SetVariable function on worldKit embedded in the browser. "document.worldkit" refers to the "id" and "name" assigned in the <object> and <embed> tags. These are variables worldKit monitors and responds to:

• JSubComm: Annotations categorized under the value of this variable will be activated.
• JLayComm: Annotations categorized under the value of this variable will be switched from visible to invisible, or vice versa.
• JActComm: Annotations categorized under the value of this variable will set to the color speicifed in <activatecolor>.
• JComm: The annotation assigned the id specified in the value of this variable will be activated..
• JItemActComm: The annotation assigned the id specified in the value of this variable will be set to the color specified in <activatecolor>.

• JLoadComm: Set the value to trigger worldKit to load an RSS feed. Pass "dataurl" or "updateurl" to load feeds specified in the config.xml. Pass "clear" to remove all the current annotations. Or alternatively, pass a url to load an arbitrary RSS feed.
• JRSSComm: Set the value to a string containing RSS. worldKit will parse this RSS string, and display any annotations.
• JZoomComm: Set the value to a location and zoom level, and worldKit will zoom and pan to that location. The format is "lat,lon,zoomlevel".
• JInputComm: Set to "true" to turn on Input-Only Mode. Set to "false" to switch off.
• JNavmodeComm: Set the value to "zoomselect" to activate the red selection box tool, and to "grabber" to activate the click and drag tool.

• JGetItemComm: The annotation assigned the id specified in the value of this variable will pass its contents, each field seperated by "||", through the URL or Javascript function specified in <annotateurl>.
• JGetExtentComm: Pass the name of a javascript function, which will be called with the current extent of the map view, similar to "onzoompan" below.

For example, here are snippets of Javascript and HTML using "JSubComm" and "JLayComm" that create a checkbox to switch "layers" on and off, in a GIS style, and a link to activate a category of points.

User clicks on annotations, or clicks in annotation-input mode, can trigger Javascript code, rather than opening a URL. Javascript callbacks can also be set for zoom/pan, new RSS items, or RSS items expired by "fading". This is useful for filling out forms, loading pictures, etc. without reloading the browser, or precisely controlling the parameters of a new window, or many other tight integrations with web applications.

In each case, worldKit will call a specified function with one argument, args, a string containing kay/value pairs URI encoded.

• To enable Javascript for user clicks on annotations, set <window> to "_javascript:", followed by the name of a callback function. args containts the "lat" and "long" of the click.
• To enable Javascript for Input Mode, set <annotateurl> to "javascript:" followed by the name of a callback function. It returns the "lat", "long", "id", and "link" of the annotation.
• To set a callback for zoom/pan events, set <onzoompan> to "javascript:" followed by the name of a callback function. args contains only the W,S,E,N "extent" of the current view.
• Set <newitemcallback> to "javascript:" followed by the name of a callback function, to receive notification of new RSS items. It returns the "title", "url", "summary", "lat", "lon", and "id" of the annotation.
• Set <fadeditemcallback> to "javascript:" followed by the name of a calllback function, to receive notification of "faded" RSS items. It returns only the "id" of the annotation.

The example code below demonstrates how to receive (myCallback) and parse (parseArgs) messages from worldKit. In the config.xml, <window> would be set to "_javascript:myCallback".

worldKit can be used as an input device. A user can click on the map, and worldKit will open a url, appended with the latitude and longitude of the clicked location. With the lat/long, your CGI can add an annotation to the map, or perform other functions like searching a database.

The map must be active and accepting keyboard input, by a mouse click. A user enters into Input Mode by typing the "i" key. All present annotations will be hidden and the cursor replaced by a crosshair icon. Leave Input Mode by typing "i" again. Within Input Mode, a click on a location trigger input.

Alternately, with the configuration option <inputonly> set to "true", the map will always be in Input Mode.

Set the url with the configuration option <annotateurl>. Clicks open this url appended with "&lat=[LAT]&long=[LONG]&zoom=[ZOOM]&extent=[EXTENT]". extent is the west,south,east,north extent of the current map view. If you want to have Javascript handle the click, read here.

If the configuration option <locupdate> is set to "true", worldKit will call the annotation url, with the current center position, any time the map is moved. This can be used with a javascript handler to provide constant updates on the map location.

Note: during Input Mode, the red selection box for zooming (<zoomselect>) will not function.

The worldKit GeoWiki a complete application ready to download, install and use on your server. It is a publicly editable map. Annotations are made directly in the map, can be assigned tags that are displayed as a weighted list, with all submissions and updates data handled in the background with Ajax. There is a working example here

Unpack the files from the download, and place them in a single directory on your webserver. Make sure the files "rss.xml, tags, tags.count" are all writable. Load the url for this directory in your browser, and it's ready to go.

The app can be customized just like any worldKit map. Choose base map imagery, different extents, etc. It can be used as a guideline for other projects, a working tutorial. This has just be released, so there may be some rough spots. Please feel free to send feedback.

• config.xml, day.jpg, index.php, worldkit.swf: These are like the usual files included in worldKit.

• rss.xml, tags, tags.count: These files will be handled by the app. If you do edit rss.xml, make sure to leave at least one <item/> tag; the annotate script is very simple and requires it.

• geowiki.css, geowiki.js, xml.gif: Some support files. geowiki.js contains the logic for interaction between the browser and worldKit, and the browser and server.

• annotate.rs.php, gettags.rs.php: These are the server routines called from Javascript. annotate.rs.php receives annotation submissions, and rebuilds rss.xml and the tag files. gettags.rs.php returns the contents of the tag box after an update.

• jsrsClient.js, jsrsServer.php.inc: Javscript Remote Scripting is one of the granddaddy "Ajax" toolkits. I've been using it for a few years. It's simple and widely compatible.

worldKit supports WMS. WMS is a protocol for supplying a large amount of map imagery over the web; for instance, worldwide satellite coverage.

To set up WMS in worldKit, take the URL of a WMS request and remove the "width" "height" and "bbox" parameters. Set the value of the <wms> config option to this modified url. A unique "id" attribute is also required. A "category" attribute is optional, and can be used to set the visibility of the WMS layer. "width" and "height" attributes optionally set the size of requested tiles; by default they are the size of the map. "maxtiledeg" sets the degrees of longitude per tile, at the highest level; it's used mainly by OnEarth (below) and by default is 360. "minview" and "maxview" attributes optionally set the scale range where the WMS is visible.

Recommended OnEarth configuration listed in the next section. Many other WMS sources are listed at the World Wind Wiki. Example configuration is below.

wms can result in many simultaneous image requests. <maximgload> sets the maximum number of images downloading at one time. The default is 10. If exceeded, zoom and pan is frozen until the download count drops below this limit.

OnEarth is a publicly accessible WMS hosted by NASA, serving high resolution (15m/pixel) imagery produced from the Landsat7 satellite. OnEarth also serves Blue Marble Next Generation, daily snapshots from MODIS satellites, and SRTM topography.

OnEarth is an incredibly valuable resource for open and free web mapping. An optimized tile cache of OnEarth imagery has been assembled, and with proper configuration, worldKit can access this high speed cache. The results are, well, awesome! If global imagery required, the recommendation is to use one of the options below. Do not modify your configuration from the ones seen here -- OnEarth will be overloaded unnecessarily and can potentially result in service disruptions.

First, for Global Landsat Imagery in Pseudocolor..

For the same in the visual spectrum..

Blue Marble Next Generation is a beautiful, cloud free, 500 meter/pixel imagery set.

Blue Marble imagery is available for each month of the year; simply add the month to the styles argument of the WMS url. [Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec]

MODIS Rapid Response provides rapid access to daily updates of 250m satellite imagery. This distribution has proved valuable for accessing active fire information, and other natural hazards like hurricanes.

There are two satellites with the MODIS instruments, Aqua and Terra. A number of mapping products are available.

• daily_aqua and daily_terra are visual color composites.
• daily_aqua_721 and daily_terra_721 highlight recently burnt areas, and flooded areas.
• daily_aqua_ndvi and daily_terra_ndvia is strongly correlated with the density and state of vegetation.

Replace the "layers" argument in the config settings below with the mapping option you prefer.

Tiling schemes for map data sources is a hot topic among open source geo developers. Tiling speeds up access to WMS and other sources dramatically. worldKit already supports tiling schemes for OnEarth, as above. Tile Map Service is a specification under active development, and worldKit now supports the global geodetic profile. A demo is posted here.

Configure a TMS with <tilemap>. An "id" attribute, unique to all configured layers & WMS servers, is required. "global_profile" currently must be set to "1". The value of the option is a URL of a TMS server.

To overlay semi-transparent (or any) images on top of the base map, and below annotations, use the swflayer tag in the config.xml file. The value of this tag is a relative or absolute url of a swf, png, gif or jpeg file. Conversion utilities and software such as Adobe Illustrator, and Flash of course, can output swf files.

A swf layer must be assigned "id", "width", and "height" attributes. The "id" must be unique among all the swflayers, and is used to switch a layer's visibility in the Javascript API JLayComm variable. To import multiple layers, use a single swflayer tag for each. The width and height of the swf file must be passed as attributes to the tag (due to limitations in Flash).

Optional attributes control where and how the layer is displayed.

• "extent": An west,south,east,north bounding box specifying the spatial extent of the layer. It can cover a smaller, larger, or partial area relative to the bounding box of the entire map. By default, the extent is assumed to be the same as the base map.
• "minscale": The minimum zoom level at which the layer is visible. By default it's 1 (ie zoomed all the way out).
• "maxscale": The maximum zoom level at which the layer is visible. By default it's set to the <maxzoom> of the map.
• "category": Assign a Category to a swflayer, and control its visibility at startup and through Javascript.
• "preload": Set to "false" and this layer will load only when it's visible. Default is true.
• "mask": Some swf files may extend over the boundaries of the Stage. Set to "true", and only the area covered by "width" and "height" will be visible. Default is false.

For example...

Templates can be configured, so that under defined regions and scales of the map, an image is requested from a mapping server covering the current viewing area This is basically what supports WMS; Templates allow finer grain control of this feature.

Each swftemplate divides a region into a number of equal sized tiles. As the map is panned and zoomed, each swftemplate is checked to see if a new swflayer should be requested and displayed. The value of <swftemplate> is the url of a WMS cgi, with the values of the bounding box replaced by "WEST,SOUTH,EAST,NORTH", or a center point with "LAT,LON". All attributes are required, except "category".

• "id": Unique identifier.
• "minscale": The minimum zoom level at which a request is made.
• "maxscale": The maximum zoom level at which a request is made.
• "minview": The minimum zoom level at which the layer is visibile.
• "maxview": The maximum zoom level at which the layer is visible.
• "extent": The east,south,west,north bounding box covered by the entire template.
• "tilewidth": Width of a requested tile.
• "tileheight": Height of a requested tile.
• "spanx": The number of tiles covering the x-axis spread of the region.
• "spany": The number of tiles covering the y-axis spread of the region.
• "category": For categorization and Javascript interaction.

For example, the following swftemplate uses the OnEarth Landsat WMS. It covers the entire globe, in 2x2 tiles, at zoom levels 1 and greater. In practice, remove linebreaks from the value of this option.

swftemplate can result in many simultaneous image requests. <maximgload> sets the maximum number of images downloading at one time. If exceeded, zoom and pan is frozen until the download count drops below this limit.

worldKit has some support for mapping GPS tracklogs, via GPX. GPX is an XML interchange format for GPS data, and many desktop programs that interface with GPS units can output this format. gpsbabel is a free utility for reading many types of GPS, and writing out GPX, and is available for many OS. openstreetmap.org has a decent tutorial on using gpsbabel.

At this point, worldKit has support to draw a single tracklog from any one GPX file. Fuller support of the spec should follow in the future.

To specify a GPX tracklog, use the <gpx> config option. A unique id string must be specified in an id attribute. The value of this tag is a url for accessing the GPX file. Multiple files can be specified.

GPX tracklogs are categorizeable with the optional "category" attribute, and respect the style values of <linealpha>, <linecolor>, and <linethickness>.

There may be scenarios when configuration options are dynamic; for example. if visualizing the results of a search query. In this situation, parameters can be passed into worldKit from the HTML, or the entire config.xml can be dynamically generated.

Most config options can be passed through HTML, rather than the config.xml. Options are specified as HTTP GET arguments on the two worldkit.swf references. The value of the options must be URL encoded.

Categorized options can be dynamically set in this format: option:catgeory=value. For example, "plotsize:metro=20" would set the plotsize for annotations categorized with "metro" to 20.

To have worldKit request another url for config.xml, simply pass "confurl=[URL]" as above. That url can be a dynamically generated file.

If confurl is set to NULL ("confurl="), then no config.xml is requested and all settings are taken as defaults or through dynamic options.

worldKit can be used as a "Component" in your Flash movies. It can be loaded into a movie from Actionscript, positioned and controlled, almost but not quite as a full component. This feature is Beta. We have received some reports of sluggish performance. Investigating.

worldKit will function as usual: requesting config.xml, images, and rss, and building a map, all within your Flash application. The only modification necessary to the config is to set <ascomponent>true</ascomponent>. To include worldKit in your movie, create an empty movie clip then load worldkit.swf. For example..

Note you can pass in dynamic parameters, in the same ways as for HTML.

You can then position worldKit, or set visibility, etc. But do not set the _width or _height, or _xscale or _yscale; these are still set in config.xml.

You can control any aspect of worldKit accessible via the Javascript API, by setting those variables directly in _root.

If you are a current user of worldKit, there are a few changes you should be aware of. worldKit is always designed to be as backwards compatible as possible, but in certain cases it's unavoidable.

To determine the your version of worldKit, press "v" and the number will be displayed. If nothing happens, then you can assume it's pre-2.0 :).

Version 3.2, February 16, 2007

zoomifyViewer.swf is no longer required for zoomify integration. And the zoomifynav config option is no longer supported.

Version 3.1, December 29, 2006

Flash Player 8 is now required.

Version 2.0, March 28, 2005

worldKit to Javascript communication has changed, and this version is not compatible with past implementations. With these changes, javascript communication is now supported on more platforms and browsers; and it should be clearer to implement.

February 3, 2005

swflayer now requires an "id" attribute.

January 27, 2005

Interaction in Input Mode has changed slightly. Typing "i" will toggle Input Mode on or off. Previously, holding "i" enabled Input Mode, and releasing "i" left Input Mode.

January 5, 2005

The recommended namespace for geotags in RSS is now "geo", changed from "icbm" (http://postneo.com/icbm/). The "icbm" tag is still supported, and your feeds will work without change.

The size of points, text, and photos is now accurate. Due to a bug, these sizes were previously skewed. So, if you update worldKit, you may need to make adjustments to the size parameters in config.xml.

If you were a beta user of the Zoomify features, the config option to specify the Zoomify install directory is now <zoomifydir>. <dayimg> will no longer work.

If you were a beta user of the Annotation features, longitude is now passed in vairable "long", rather than "lon".

This is an alphabetical index of configuration options, with links to more information throughout the manual.