Map weighting and location choosing applet (v2.4)

Centre for Computational Geography
University of Leeds

This Applet displays a greyscale image which is generated by allowing the user to weight various different images/maps. This is usually used for determining which of several factors influencing a decision should be most important. The user can then choose locations on the image using various tools, and send them to the server for recording. The same applet can then be used from a newly generated webpage to display back the user's position and the position of other users.

For an example see the interactive and display mode examples.

To use the applet, you'll need the archive file weighter2_4.jar (note: please check changes for important info on the "frame" PARAM: many updates expected by June - check back frequently), and a set of greyscale image files. The applet can take in any number of image files. In interactive mode, for each one a control will be generated (eg. a scrollbar) that will allow the user to weight the images' importance in the final shown image. In display mode, the combined maps will be displayed with results rather than controls. At present images can be 0-255 greyscale, which should get a scrollbar, or 0-1 black and white, which should get a checkbox to turn the black areas on or off. All images should be the same size. You can add an optional 0-1 black and white mask file, the black areas of which will show through the applet background colour when displayed, allowing for irregular shapes. The files used for the example are pro255.gif, nopro255.gif, altitude.gif, popacc.gif for the main data, and coast255.gif for the mask.

Look at the source code of the example to see how to broadly set up the applet. The details are given for an applet set up with the archive, webpage and data files in the same directory. Note that to work in Netscape 6 you need the APPLET attribute "mayscript".

The PARAM tags control the applet, and can be used as follows (default values given)...

Essential tags

<PARAM name="numberOfFiles" value="">
This is the number of greyscale images to be pulled in, not including the optional mask. The value should be an integer number and must match the number of weighting components needed and labels. Each image gets its own weighting component with a label (see below).

<PARAM name="fileX" value="">
The files holding the images (gif or jpeg). X should be replaced by numbers between 1 and numberOfFiles, e.g. file1, file2...etc. The value should be the actual filename with any file extension.

<PARAM name="typeX" value="">
The type of weighter component each image should have. This can be either "scrollbar" or "checkbox". Scrollbars should be used with continuous images, and checkboxes with black/white ones. Again X should be replaced by numbers between 1 and numberOfFiles, e.g. type1, type2...etc. "type1" is associated with "file1" and has "label1" etc.

<PARAM name="labelX" value="">
The label for the weighting components. Usually this is a description of the related file data. Again X should be replaced by numbers between 1 and numberOfFiles, e.g. label1, label2...etc.

<PARAM name="imageWidth" value="">
The width of the images to be displayed and the mask. These must be identical. The value should be an integer.

<PARAM name="imageHeight" value="">
The height of the images to be displayed and the mask. These must be identical. The value should be an integer.

Additional tags: Interactive mode

<PARAM name="mask" value="">
Optional image file (gif or jpeg) to be used as a mask. The value should be the actual filename with any file extension. The mask should be black in areas where you want the background colour to replace the images, and white elsewhere.

<PARAM name="foreground" value="#000000">
The colour for the Applet foreground (most notably used to colour text). The value should be a web-style hexidecimal colour, starting with a hash, as above. The default is black.

<PARAM name="background" value="#ffffff">
The colour for the Applet background, which is used for the general background, as well as the colour for masked areas. Any scrollbars will pick up the colour and either brighten or darken it for their background, depending on the background darkness. The value should be a web-style hexidecimal colour, starting with a hash, as above. The default is white.

<PARAM name="urlX" value="">
The url of a webpage that will be accessed via the weighter component labels. The labels will highlight in the chosen "shade" (see below) when the mouse is over them if there is an associated webpage. Again X should be replaced by numbers between 1 and numberOfFiles, e.g. type1, type2...etc. "type1" is associated with "file1" and has "label1" etc. The URL can't start "javascript:" so you can't directly produce a popup window, you have to open a new browser window or through to a frame using the optional "urlframe" PARAM. You can however, use a hidden frame and put into in an HTML page which opens a visible popup window using the "urlframe" PARAM.

<PARAM name="urlframe" value="_parent">
The frame or window to throw the data/page at the URLs associated with weighter controls to. The default is the applet page itself.

<PARAM name="scrollbarWidth" value="100">
The prefered width of the scrollbars. If the Applet is smaller than the layout needs the Image takes first preference, then the weighter components, and space is first lost from the labels. The value should be an integer. The default is 100.

<PARAM name="toolX" value="weighter">
The tools to add. Again X should be replaced by numbers from 1 upwards, but doesn't have to be up to numberOfFiles (indeed, probably won't). The tool1 will be the first to appear. Subsequent tools can be reached by checkboxs. If there's just one tool, the checkbox option's won't appear. Can take the values "topSlicer", "weighter" or "pointLocation". Weighter is the basic weighting screen. TopSlicer adds the ability to topslice this in "imageShade" colour (see below). "PointLocation" allows you to pick a single location on the weighted image. For the tools with results, the results are given with the other weighting tool results.

<PARAM name="prefixText" value="">
The prefix text for any topSlicer scrollbar label. Typically something like "Land area equals ". Note a space is put at the end and that the default is nothing.

<PARAM name="suffixText" value="">
The suffix text for any topSlicer scrollbar label. Typically something like "metres". Note a space is put at the beginning and that the default is nothing.

<PARAM name="maxDecimalPlaces" value="1">
The power of ten you want your decimal places to in the labels.

<PARAM name="conversion" value="1.0">
A factor for converting pixels highlighted in tools like the top slicer into map units. For example, if each pixel in your images was 2km by 2km your conversion factor for km sq. would want to be 4.0. Note that you can also use this to get rid of the display of highlighted pixels to the user by setting the factor = 0.0. The user will then just see the highlighting tool and no text feedback about the areas selected. The default is 1.0.

<PARAM name="imageShade" value="blue">
Shade to colour highlighted areas of map, Can be "red", "green" or "blue" (default).

<PARAM name="outputUrl" value="">
The URL to pass the results to - usually a CGI script. If this is given, a button appears with the "submitLabel" label (below). The URL must start with the protocol string "http://". Details of the URL request encapsulating the results are given below. In the absence of a URL the button doesn't appear and the tool values are not recorded. Details of how to get rid of the applet using the submit button are also given below.

<PARAM name="outputframe" value="_parent">
This gives the frame to send the page returned by the outputUrl request to. By default this is the whole browser.

<PARAM name="submitLabel" value="Submit">
A label allowing changes to the text on the submit button.

<PARAM name="passThrough" value="">
This PARAM can be used to pass information through the application. For example, to pass information from a FORM into a log file with the results from the applet, use a CGI script write the Applet webpage with the FORM results written into the applet passThrough PARAM tag, and unscramble it with the results passed to outputUrl CGI scripts.

<PARAM name="order" value="a">
This allows you to set up the controls and tools shown in an order. String together the following... "m": just the map and map tools, "w": just the weighting tools (scrollbars and checkboxes), "a": all the controls and tools. For example, "wma" will show the weighting controls first, then the map without the weighting controls, then all of them. Note that the labels and messages associated with these can be set (see below), and that if the "outputUrl" PARAM is present, the last set displayed will have the "submitLabel" button, below. For details of how the outputs are differenciated for each stage, see details after this PARAM list.

<PARAM name="allShownMessage" value="Pick a place or weights.">
Message for the users when all the controls are shown. To get rid of this, set it as a blank space.

<PARAM name="allShownUrl" value="none">
Url that can be attached to the allShownMessage text as a hyperlink. The page is opened in the urlFrame (above).

<PARAM name="showMapLabel" value="Show map">
A label allowing changes to the "Show map" button if which shows under the "w" order, when the map is missing, as detailed above.

<PARAM name="mapHiddenMessage" value="Your map will appear here.">
Message for the users when the map is initially hidden. To get rid of this, set it as a blank space.

<PARAM name="mapHiddenUrl" value="none">
Url that can be attached to the hideMapMessage text as a hyperlink. The page is opened in the urlFrame (above).

<PARAM name="showControlsLabel" value="Show controls">
A label allowing changes to the "Show controls" button, which appears under the "m" order, when the controls are hidden, as detailed above.

<PARAM name="controlsHiddenMessage" value="Please choose a location">
Message in the space the controls will appear in for the users when the controls are hidden. To get rid of this, set it as a blank space.

<PARAM name="controlsHiddenUrl" value="none">
Url that can be attached to the controlsHiddenMessage text as a hyperlink. The page is opened in the urlFrame (above).

<PARAM name="force" value="false">
If set to "true", this will force the user to make some selection using a tool prior to moving on. If the "order" PARAM above is used this will apply to each stage where a map is shown, but not weighting controls where it's reasonable for the controls not to be moved in order to express a set of weights.

<PARAM name="forcetext" value="Please choose a location first">
If the "force" PARAM is "true", this text is displayed if the user hasn't yet picked a location using a tool.

Additional tags: Display mode

<PARAM name="mode" value="interactive">
This controls whether the applet is "interactive" (so users can enter their information), or set to "display" mode (so users can see their and other results). In display mode currently only the first toolX PARAM (see above) will ultimately be displayed. Currently only "pointLocation" is available.

<PARAM name="resultsFile" value="">
The file the display should pull the results from. It is the developer's responsibility to make sure this is in the format needed for the appropriate toolX. The value should be given as a full http link with protocol, e.g. "http://www.server.org/myapplet/log.txt" and must be on the same server as the applet. For the pointLocation tool the format should be one user's input per line, in the format: UserID, X, Y. If these aren't generated by the applet in a previous use it is the developer's responsibility to ensure the X-Y coordinates fit in the appropriate image bounds.

<PARAM name="userID" value="">
If the User ID doesn't match a value in the User ID column of the results file, it won't be differenciated from other users' results. If it is, it will be displayed in "userShade" (below), while the others are displayed in "imageShade" (above).

<PARAM name="userShade" value="imageShade">
As for "imageShade" above, but picks out the user's choice. Values can be "red", "green" or "blue".

Setup hints

The results from the applet are passed to the URL given by outputUrl PARAM. The request string is the outputUrl, then a question mark, then a typical CGI variable-value pair string (Note that in the following X is the order stage as outlined in the "order" PARAM tag information above or blank if the controls are activated at the final stage).

First the additional tool controls are given. The current tool is given in the form &currentX=String, Then the tool values. For a topSlicer scrollbar this is in the form &slicerX=value, where value is 0-255. This would then be followed by a YstateX where Y is the tool name. For the slicer the states are: 0 if the tool has been used, 1 otherwise. For a pointLocation the form is &x=value&y=value&state=value, state in this case being...

  • 0 : "ok" - not any of the following states.
  • 1 : "none" - coordinates defaults as the user has yet to pick.
  • 2 : "blanked" - coordinates in an area presently blacked out by a checkbox / some other binary choice.
  • 3 : "masked" - coordinates in an area presently masked.

People recording the values sent from the applet can use the state to determine if the results are worth keeping. Note that if the x,y coordinates are in an unshown area, the user won't see any of the selection area. If they aren't, the user will see those areas of the selection that aren't in a blanked or masked area.

Following this in the results, the control values are given, in the form &XnumberOfControl=value, where numberOfControl goes from 1 upwards, and value is 0-255 for scrollbars and 0 or 1 for a checkbox. Finally the passThrough string will appear.

To get the result out and get rid of the applet, use a CGI script for your outputUrl that records the results to a logfile, and then returns to the web browser a new page (you can put this into the applet frame if you use these using the frame PARAM).

Note that the applet will be destroyed at an undetermined time later, so just removing will not reset it if the user is allowed to go back to it.

This applet may be freely used by academic and non-profit, non-governmental organisations, as well as private individuals. Other organisations should contact the CCG for information on its use.

For further information about this applet and the source code, contact Dr Andy Evans.

[CCG homepage] [School of Geography homepage]