THE LUCS-KDD RANDOM IMAGE GENERATOR: THE RanImgGen DIRECTORY

USER GUIDE

AUTHOR: Frans Coenen

DATE: Wednesday 25 Janyaury 2006

UPDATES: Monday 5 January 2009


CONTENTS

1. Introduction.
2. Downloading the software.
2.1. Compiling.
2.2. Running the Software.
2.3. Documentation.
 
3. The image generator in more detail.
4. Image features and objects.
5. Colours.
6. Adding a new image feature.






1. INTRODUCTION

The LUCS KDD random image generator is intended for use with image mining software. It produces a sequence of images all measuring 120x80 pixels of the form shown in Figure 1.

EXAMPLE IMAGE 1 EXAMPLE IMAGE 2 EXAMPLE IMAGE 3 EXAMPLE IMAGE 4 EXAMPLE IMAGE 5
EXAMPLE IMAGE 1 EXAMPLE IMAGE 2 EXAMPLE IMAGE 3 EXAMPLE IMAGE 4 EXAMPLE IMAGE 5
EXAMPLE IMAGE 1 EXAMPLE IMAGE 2 EXAMPLE IMAGE 3 EXAMPLE IMAGE 4 EXAMPLE IMAGE 5

Figure 1: Example Random Images.




2. DOWNLOADING THE SOFTWARE


The system comprises the following java source files (In alphabetic order):

File NameBrief description
Foreground.javaDefines the foreground of an image which may be "sea", "land", "land and sea" or "sea and land".
hill.javaDefines a hill image feature comprised of a left (SW) and a right (SE) triangle back to back. Hill features are located along the horizon image component.
House.javaDefines a house image feature, with up to three windows/doors, made up of rectangular and triangular image objects. Hourse image features can only be located within "land" foregrounds. Four version of the feature are defined according to whether they are distant, middle distant, middle close or close to the viewer. Location is center-base of house.
House2.javaDefines a house image feature, with up to two windows/doors, made up of rectangular and triangular image objects. Hourse image features can only be located within "land" foregrounds. Four version of the feature are defined according to whether they are distant, middle distant, middle close or close to the viewer. Location is center-base of house.
House3.javaDefines a house image feature, with one window/door, made up of rectangular and triangular image objects. Hourse image features can only be located within "land" foregrounds. Four version of the feature are defined according to whether they are distant, middle distant, middle close or close to the viewer. Location is center-base of house.
Image.javaDefines a single random image comprising sky, horizon and foreground components and zero or more image features.
ImageBaseCanvas.javaCreates a "paint" canvas in which to display the image base once generated.
ImageBaseWindow.javaCreates a window in which a "paint" canvas is displayed which in turn is used to depict the image base once it is generated.
ImageFeature.javaGeneric parent class for image features. Examples of image features include: house, tree and boat.
ImageObject.javaGeneric parent class for image objects. Currently only two kinds of image object are defined: rectangles and triangles.
ImageUtilities.javaSet of utility methods to support the random image generation process.
LandAndSeaFG.javaForeground component comprising sea and land, land first and sea towards the horizon.
LandFG.javaForeground component comprising land only.
NEtriangle.javaRight angled triangle with right angle at NE corner.
NWtriangle.javaRight angled triangle with right angle at NW corner.
RandomImageGen.javaThe model for the random image generator.
RandomImageGenApp.javaThe application class for the random image generator.
RandomImageGenControl.javaControl (GUI) class for random image generator.
Rectangle.javaRectangular image object.
SailBoat.javaDefines a sail boat image feature comprised of rectangular and triangular image objects. SailBoat image features can only be located within "sea" foregrounds. Three version of the feature are defined according to whether they are distant, middle distant or close to the viewer. Location is the bottom middle of the hull.
SeaAndLandFG.javaForeground component comprising land and sea, sea first and land towards the horizon.
Sea.javaForeground component comprising sea only.
SEtriangle.javaRight angled triangle with right angle at SE corner.
SingleImageCanvas.javaCreates a "paint" canvas in which to display a single generated image.
SingleImageWindowCreates a window in which a "paint" canvas is displayed which in turn is used to depict a single image selected from the image base.
Sky.javaDefines the image sky component and where the sky image component meets the foreground image component.
SteamBoat1Defines a steam boat image feature comprised of rectangular and triangular image objects. SailBoat image features can only be located within "sea" foregrounds. Three version of the feature are defined according to whether they are distant, middle distant or close to the viewer. Location is the bottom middle of the hull.
SWtriangle.javaRight angled triangle with right angle at SW corner.
Tree.javaDefines a tree comprised of a nuumber of rectangular shapes, one for the trunk and several more for the foliage. Location is base of tree trunk.
TriangleIO.javaDefines a triangle image object

To download the source files a "tarball" is available. Alternatively users can go to here and copy files in the usual manner.


2.1. Compiling

The software has been implemented in Java using the Java2 SDK (Software Development Kit) Version 1.4.0, which should therefore make it highly portable. The code does not require any special packages and thus can be compiled using the standard Java compiler:

javac *.java

2.2. Running the software

The software can be run in the usual manner:

java RandomImageGenApp

A GUI (Figure 2)will appear which is straightforward to use.

EXAMPLE IMAGE 1

Figure 2: Random Image Generator Interface.


2.3. Documentation

The code can be documented using Java Doc. First create a directory Documentation in which to place the resulting HTML pages and then type:

javadoc -d Documentation/ *.java

This will produce a hierarchy of WWW pages contained in the Document directory.




3. THE IMAGE GENERATOR IN MORE DETAIL

The gebnerated random images comprise various predefined landscape features and are stored as a sequence of .bmp files. At a high level an image is structured as shown in Figure 2.

IMAGE ::= SKY, FOREGROUND

SKY ::= height, colour=white|blue|light gray, SKY_IMAGE_FEATURES

FOREGROUND ::= SEA | LAND | SEA_AND_LAND) | LAND_AND_SEA

SEA ::= colour=blue, SEA_IMAGE_FEATURES

LAND ::= colour=lightGreen, LAND_IMAGE_FEATURES

Figure 2: Structure of image ("::=" should be read as "comprises", "," an "and", "|" an "or")

From Figure 2 it can be observed that an image comprises sky and foreground. The sky part of the image can contain a number of "sky image features". Currently the only sky features available are hills which "sit" on the horizon, an image may include between 0 and 3 hills. Hills come in three sizes: small. medium and large; and two colours: "light brown" and "lilac". Current possible sky colours "are light blue", "white", "light gray".

The foreground part of the image may comprise either: "land", "sea", "land and sea" or "sea and land" with the distinction between the last two being that the first named is the closest to the viewer. Sea is always "blue" and land "light green". The foreground may also contain between 0 and 5 foreground image features. Currently there are two land image features available (trees and houses) and one sea feature (sailing boats).




4. IMAGE FEATURES AND OBJECTS

Image features are all sub classes of the class ImageFeature. Image features are built up from a number of primitives called image objects. Five kinds of image object are available:

  1. Rectangle.
  2. NE right angled triangle.
  3. SE right angled triangle.
  4. SW right angled triangle.
  5. NW right angled triangle.

each represented by its own class. The NE, SE, SW and NW references refer to the orientation of the triangle, a NE triangle has the right angled corner to the NE etc. The triangle objects are all sub-classes of the class TriangleIO. The TriangleIO class in turn, and the rectangle class, are then sub-classes of the class ImageObject (See Figure 2).

                               ImageObject
                                    |
                     +--------------+---------------+
                     |                              |
                TriangleIO                      Rectangle
                     |
    +----------+-----+-----+-----------+
    |          |           |           |
NEtriangle SEtriangle SWtrainagle NWtraiangle

Fig 2: Image Object (IO) class structure




5. COLOURS


The available colours (currently there are 24 of these) are listed in the ImageUtilities.java file together with the features which they are used for. When creating a new image feature make sure to update the comments in ImageUtilities.java file listing what each colour is used for what.

To add a new colour to the ImageUtilities.java file:

  1. Determine the RGB values for the new colour. A useful WWW site for this can be found at:

    http://www.csc.liv.ac.uk/~frans/Notes/webColours.html

    (33Hex=51, 66Hex=102, 99Hex=153, CCHex=204, FFHex=255.)
  2. Edit the getColor method in the ImageUtilities class by adding the desired colour, note that colours are listed according to their intensity. It is recommended that you insert your new colour according to its intensity as this will reduce the risk of duplication --- note also that this will probably entail adjusting the indexes of the other colours.
  3. Edit the getColourByteArray method, in the ImageUtilities class, in a similar manner.
  4. Add the string equivalent of the colour to the colours array of Strings field (also in the ImageUtilities class) at the appropriate index, note that your chosen colour's name must be unique.



6. ADDING A NEW IMAGE FEATURE


To add a new feature follow the following steps.

  1. Decide whether your image feature is going to be a sea or land feature.
  2. Design your image feature in terms of rectangles and triangles, i.e. the available IOs (refer back to Section 2 for more detail). Do three (or more) versions: (i) distant, (ii) middle ground and (iii) close up. This is best done using squared paper with each square representing a pixel (the origin for each square/pixel is the top left-hand corner). To get some idea of scale a person will be 21 pixels high close up, 14 pixels high in the middle ground and 7 pixels high in the distance. When selecting colours for your feature the ist of available colours is in ImageUtilities.java>
  3. Creata a java class file for your feature which must be a sub-class of the class Image Feature. It is probably easiest to make a copy of an existing feature class source file (Tree.java is quite simple). The Image Feature class contains two fields that your class will inherit:
    1. location --- a two element integer array for the X and Y coordinates describing your feature's location (usually the center of the base), and
    2. (ii) featureType --- a string describing the nature of your object and its variations, e.g "very large tree" (this is used for output purposes).
        These two fields must be set in your class.
      1. Hint: Look at the existing image feature classes (House, Tree, SailBoat) to get a feel for what methods your class will need to include. It needs at least a addIFtoBitMap method and a five argument constructor.
      2. Once your feature class is complete (and compiles correctly!) you are ready to include it within the generator. In the Foreground class include a label for your feature in the FEATURES field, and the same label in either the LAND_FEATURES field or the SEA_FEATURES field according to whether your feature is a land or a sea feature. Also include the label in the createSeaAndLandIF method and either the createLandIF method or the createSeaIF method as appropriate. You will need to study the Foreground class quite carefully to see how to include the labels.

      Now you will able to generate new images that include your feature!