Greenstone Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Collage ======

===== Download the Collage =====
 
   * [[http://www.nzdl.org/download/collage/GsdlCollageApplet.jar|Collage 1.0 ]]

The collage applet dynamically displays a given set of images. When an image is clicked, a new browser window opens and the associated URL is displayed.

The applet can be used in two different contexts: either within the Greenstone Digital Library Software or externally using a directory of images and associated links.

====Using Greenstone====

The collaging applet will be including in the upcoming Greenstone release (version 2.50). A collage can be incorporated into a Greenstone collection by adding these lines into the collection configuration file:

    classify  Collage  -buttonname Collage 

    format CL# "[link]documentlink[/link]<br>"

(where # is the number of the collage classifier).

In Greenstone, a new classifer is associated with the collage applet -- for example CL4. Behind the scenes a list of all documents in the collection is created -- in this case, called CL4.1. The user never sees this list of documents. The collage begins by searching for images at the URL of this secondary page. As they are found, images are displayed in the applet. Clicking on an image takes the user to the document that contains this image.

====Using an Image Directory====

Outside Greenstone, a collage can be implemented on a directory of images. These images may be associated with different locations on the internet. The image directory should contain a file called externallinks, of the format:

<code>  [image name] [hyperlink]</code>

For example:

<code>nzdl-ad.gif http://www.nzdl.org/</code>

Images in the directory are matched with the names in the //externallinks// file, and when an image is clicked the corresponding URL is displayed.

To run the collage, an html page should be created that displays the collage applet. Assuming that this html page resides in the same directory as the GsdlCollageApplet.jar file, here is an example page:

<code>
    <html> 
      <head> 

        <title> 
    	My Image Collage 
        </title> 

    </head> 
      <body> 


    <applet code="GsdlCollageApplet.class" archive="GsdlCollageApplet.jar" 
    width="645" height="780">

    <param name="imageURL" value="http://www.mycollage.com/images/"> 
    <param name="hrefMustHave"  value="http://www.mycollage.com/images/"> 

    <param name="imageMustNotHave" value="ugly%bald%fat"> 
    <param name="imageType" value=".jpg%.png%.gif"> 
    <param name="verbosity" value="5"> 
    <param name="maxDepth" value="1"> 
    <param name="refreshDelay" value="1500"> 
    <param name="isJava2" value=auto> 

    </body> 
    </html> 
</code>

Where //http://www.mycollage.com/images/// is the directory of images that includes the //externallinks// file.

=====Applet Parameters=====

The collage applet has many parameters. At present, in Greenstone these are hardcoded at the point where the applet is called, which is in the macrofile //document.dm//. (Eventually, it will be possible to specify these parameters in the collection configuration file.)

The parameters for the applet are:

  *     //hrefMustHave// - while searching for an image, links are filtered using this string. Links that do not contain this string are not followed. In Greenstone this parameter ensures that collage images are not sourced from outside the collage classifier. In an image directory implementation it ensures that images are not sourced from outside the specified directory.
  *     //imageMustNotHave// - a list of values that an image name may not contain. Used to prevent any irrelevant images from appearing in the collage, for example the navigation bar images in Greenstone. The % symbol is used to separate items in the list.
  *     //imageType// - a list of image file extensions used to filter the types of image that may be included in the collage. The % symbol is used to separate items in the list.
  *     //verbosity// - controls the amount of output to the java console to help debugging.
  *     //bgcolor// - the background colour of the applet screen. This defaults to the Greenstone green. The colour should be specified as an RGB color where the digits are separated by commas: for example, "255,100,40".
  *     //maxDepth// - the number of nested links that should be followed. Prevents an infinite depth traversal from occurring.
  *     //refreshDelay// - the amount of time that should pass before the next image is displayed on the collage.
  *     //isJava2// - controls whether or not the user's browser supports java2 capabilities. Default value is auto; however, it can also be set to true or false. 

A further parameter, when using a directory of images, is the //startingURL//.

=====How the code works=====

The main class of the collage application is //GsdlCollageApplet//. This class processes the applet parameters and then spawns three threads. The first thread begins downloading images, the second displays the images on the applet and the third paints the applet.

====The download thread====

The downloading thread is passed a starting URL. This URL is first searched for any <img> tags. Any images found are filtered by the //imageMustNotHave// and //imageType// parameters. The images are saved into a buffer of downloaded images for retrieval by the display thread. Then the URL is searched for any links. Each link found is filtered by the //hrefMustHave// parameter before being passed as the starting URL for a new downloading process, with an incremental depth. This process continues until the maximum depth, as specified by the maxDepth parameter, is reached. Once all the links in the starting URL have been explored, the download thread stops.

====The display thread====

The display thread is responsible for updating the appearance of the applet onscreen. The time between updates is specified by the //refreshDelay// parameter.

At each update the download buffer is checked for a new image. If the buffer is empty, the vector of images that have previously been displayed but are not currently onscreen is checked for an image. If this vector is also empty the oldest image currently onscreen is removed. This is so that at the next update if there are still no new images that have been downloaded, the second condition will fire and this image will appear back on the screen.

Next the onscreen display is updated. New images are assigned a position onscreen. Image positions are generated randomly, however a new image is required to cover as much whitespace as possible. Existing images are gradually faded as they age. Images are removed from the display if they are too faded, or if excessive overlap is occurring.

====The painting thread====

The sole task of this thread is to repaint the applet onscreen.

====Acknowledgements====

This application was based on the work of Andruid Kerne. David Bainbridge wrote the basic collaging program and Katrina Edgar incorporated it into Greenstone in January 2004.