Chirographum Design Document

Chirographum Project October 21, 2008

2

Contents

1 Overview  5
2 Pipeline  7
2.1 General Description . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.2 Pipeline Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.3 Pipeline Module Interface (IPipelineModule) . . . . . . . . . . . 7
2.3.1 void setData(Object) . . . . . . . . . . . . . . . . . . . . . 9
2.3.2 Object run() . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.3.3 Object run(Object) . . . . . . . . . . . . . . . . . . . . . 9
2.3.4 void setReporter(IReporter) . . . . . . . . . . . . . . . . . 9
2.3.5 Object getData() . . . . . . . . . . . . . . . . . . . . . . . 9
2.3.6 Object getResult() . . . . . . . . . . . . . . . . . . . . . . 9
2.3.7 void setOptions(Object) . . . . . . . . . . . . . . . . . . . 9
2.4 Status Reporter Interface (IReporter) . . . . . . . . . . . . . . . 9
2.4.1 void setStatus(String) . . . . . . . . . . . . . . . . . . . . 10
2.4.2 void setProgress(int) . . . . . . . . . . . . . . . . . . . . . 10
3 Preprocessing  11
3.1 Preprocessing Modules . . . . . . . . . . . . . . . . . . . . . . . . 11
3.1.1 Image Loading . . . . . . . . . . . . . . . . . . . . . . . . 11
3.1.2 Black and White Conversion . . . . . . . . . . . . . . . . 12
4 Image segmentation  13
4.1 Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
4.1.1 ImageSegment . . . . . . . . . . . . . . . . . . . . . . . . 13
4.1.2 SegmentLayout . . . . . . . . . . . . . . . . . . . . . . . . 13
4.2 Layout Detection . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
4.3 User Verification . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
4.4 Image Splicing . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
5 Processing  15
5.1 Training . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
5.2 Processing Algorithms . . . . . . . . . . . . . . . . . . . . . . . . 15
5.2.1 FindDots . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
5.2.2 FindLines . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
5.2.3 FindAreaBlocks . . . . . . . . . . . . . . . . . . . . . . . . 16
5.2.4 Dimensions . . . . . . . . . . . . . . . . . . . . . . . . . . 16
5.2.5 OutsideArea . . . . . . . . . . . . . . . . . . . . . . . . . 16

5.2.6 DifferencesClassifier . . . . . . . . . . . . . . . . . . . . . 16
6 User Interface  17
6.1 Main GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
6.2 Training GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
6.3 Testing GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
7 Data store  19
7.1 Stored Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
7.1.1 ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
7.2 Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
7.3 DataStore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
7.3.1 Loading . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
7.3.2 Saving . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
7.3.3 Interface IDataStore . . . . . . . . . . . . . . . . . . . . . 20
7.4 DataItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
7.4.1 Loading . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
7.4.2 Saving . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
7.4.3 Access to Data . . . . . . . . . . . . . . . . . . . . . . . . 22
7.4.4 Interface IDataItem . . . . . . . . . . . . . . . . . . . . . 22
7.4.5 Reference Keys . . . . . . . . . . . . . . . . . . . . . . . . 24
8 Output  27
8.1 Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
8.1.1 Severity . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
8.1.2 ILogger . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
8.2 Program Output . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
8.2.1 Training . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
8.2.2 Normal Mode . . . . . . . . . . . . . . . . . . . . . . . . . 29
8.2.3 Testing Mode . . . . . . . . . . . . . . . . . . . . . . . . . 29

Chapter 1

Overview

ChiroGraphum is a framework and suite of tools for writer-dependent handwriting recognition. It will provide facilities for the developers to experiment with algorithms, as well as an interface for the user to apply combinations of algorithms to recognise their handwriting. It will use a pipeline architecture, and collections of feature detectors and classification algorithms.

6 CHAPTER 1. OVERVIEW

Pipeline

2.1 General Description

A Pipeline is a list of modules. The pipeline will be given data which will be passed through associated pipeline modules. The result of the final pipeline modules execution will be passed out of the pipeline as the pipelines overall result.

Within the pipeline, the result of one modules execution will be passed as the input data for the next module.

2.2 Pipeline Modules

A pipeline module is a unit of work done in a pipeline. All pipeline modules must implement the IPipelineModule interface.

A Pipeline Module will be passed input data in the form of an Object. It is the modules responsibility to ensure that the Object can be converted to what it requires.

A module may also be passed a second Object to be used as its configuration settings. Like with input data, it is the responsibility of the module to make sense of this object.

A Pipeline should be able to be paused and continued as appropriate. This will be provided by sleeping the current thread.

2.3 Pipeline Module Interface (IPipelineModule)

The IPipelineModule interface is to be implemented by all classes will be used as a module in a pipeline.

1 package comp314 . i n t e r f a c e s ;

2

3 /∗∗
4 ∗
5 ∗ @author Daniel Buchanan

6 ∗
7 ∗/
8 public interface IPipelineModule {
9  /∗∗
10  ∗ Sets the module ’ s input data .
11  ∗ @param data Input data
12  ∗/
13  void setData ( IData data ) ;

14

15  /∗∗
16  ∗ Runs the module and r e t u r n s i t s r e s u l t .
17  ∗ @return r e s u l t
18  ∗/
19  IData run ( ) ;

20

21  /∗∗
22  ∗ Set input data and run module .
23  ∗
24  ∗ @param data Input data
25  ∗ @return Output data
26  ∗/
27  IData run ( IData data ) ;

28

29  /∗∗
30  ∗ Sets the s t a t u s r e p o r t e r .
31  ∗ @param r e p o r t e r S t a t u s Reporter
32  ∗/
33  void setReporter ( IReporter r e p o r t e r ) ;

34

35  /∗∗
36  ∗ Gets the input data .
37  ∗ @return the input data
38  ∗/
39  IData getData ( ) ;

40

41  /∗∗
42  ∗ Gets the r e s u l t , a f t e r you have c a l l e d run () .
43  ∗ @return the r e s u l t
44  ∗/
45  IData getResult ( ) ;

46

47  /∗∗
48  ∗ Sets module o p t i o n s .
49  ∗ @param o p t i o n s Module Options
50  ∗/
51  void setOptions ( IData options ) ;
52 }

2.3.1 void setData(Object)

This method sets the input data for the pipeline module. It takes a single object to be used as data. The module will convert this to what ever data type it is designed to operate on. Should it be given incorrect data type it will thrown an exception.

Every time this method is called it will change the previously set data object to the one specified.

2.3.2 Object run()

This method causes the module to perform its task and then return the result as an Object.

2.3.3 Object run(Object)

Overloaded method which combines the functionality of the run() method and the setData(Object) method.

2.3.4 void setReporter(IReporter)

Sets a class which implements a status reporting function. This is used by the module to report status information (task progress, etc).

If the reporter is null it will not report anything.

2.3.5 Object getData()

Returns the data object set with either run(Object) or setData(Object) methods.

2.3.6 Object getResult()

Returns the result of running either run() or run(Object). It can only be called after one of the two methods has completed execution. If called before then it will return null. If called after execution it will return the same value as returned by run() or run(Object)

2.3.7 void setOptions(Object)

Sets options for the modules options. The object parameter is to be interpreted by the module - its content is not specified by this specification.

2.4 Status Reporter Interface (IReporter)

The IReporter interface is used to report status and progress information about a modules execution.

1 package comp314 . i n t e r f a c e s ;

2

3 /∗∗
4 ∗

5 ∗ @author Daniel Buchanan ( r e p l a c e with whoever a c t u a l l y
c r e a t e d t h i s )
6 ∗
7 ∗/
8 public interface IReporter {
9  /∗∗ Set s t a t u s message .
10  ∗
11  ∗ @param s t a t u s S t a t u s message
12  ∗/
13  void s e t S t a t u s ( S t r i n g s t a t u s ) ;

14

15  /∗∗ Sets p r o g r e s s l e v e l .
16  ∗
17  ∗ @param p r o g r e s s Progress l e v e l
18  ∗/
19  void s e t P r o g r e s s ( int p r o g r e s s ) ;
20 }

2.4.1 void setStatus(String)

This method sets a status message. Possible uses include logging.

2.4.2 void setProgress(int)

This method is used to set the progress of the modules execution. Possible uses include driving a progress bar.

Preprocessing

The softwares input image will be passed through a series of (some optional) preprocessing modules. The pipeline will be started off with the input images filename. This will be passed through image loading modules before being passed through any optional extra preprocessing modules.

3.1 Preprocessing Modules

3.1.1 Image Loading

This is a required module which will be at the start of the pre-processing pipeline. It takes a filename string as input and passes out the loaded image file in bitmap format.

Reading File

Possible options for this include:

1. Reading the file entirely into memory at the beginning before any operations are attempted.

2. Reading the file into memory as required for each read, i.e. memory mapped IO.

The option that will be used however depends on how the higher level image classes work, they may require the image to be loaded into memory entirely befire processing can occur, if this is the case the amount of memory used could become an issue.

Format Conversion

The file once loaded into memory should be converted into a format which the program is able to manipulate or work with easily, this could be for example a simple black and white bitmap.

The image file should be in one of the following formats:

1. JPEG format (jpg).

2. Graphics Interchange Format (gif).

3. Tagged Image File Format (tiff).

4. Portable Network Graphics (png).

The file format converter should be able to detect what format the input image is in, and covert it to an intermediary format such as BMP and the perform the conversion to whatever the internal image format is.

This should all be accomplished without modification of the original file

3.1.2 Black and White Conversion

This module will take in a color image (in memory) and convert it into a black and white binary image, which is able to be used internally.

It also performs noise reduction on the image by checking adjacent pixels to the current pixel and taking an average of those pixels.

Image segmentation

In order to easily provide the user with the option to review the document layout automatically detected by the software, image segmentation is done in multiple stages. These consist of layout detection, user verification and splicing.

4.1 Data Types

4.1.1 ImageSegment

This data type stores information about an image segment. These fields include:

1. Co-ordinate for the top left corner of the segment (required)

2. Co-ordinate for the bottom right corner of the segment (required)

3. The bitmap image segment taken from the co-ordinates (optional)

Instances of the ImageSegment class will normally be produced by the Layout Detection stage of image segmentation. The bitmap field will be left as null until the Image Splicing segmentation stage.

4.1.2 SegmentLayout

This data type stores ImageSegments in the order they appear in the Source Image. It divides ImageSegments into lines in the order they appear in.

4.2 Layout Detection

This stages purpose is to detect each word in the input image. Its input consists of only the Source Image and it outputs a SegmentLayout. The SegmentLayout is an ordered list of lines detected in the Source Image. Each line is an ordered list of the detected words, each represented as an ImageSegment.

The ImageSegment instances produced by this stage will contain nothing more than the two co-ordinates which make up the box around the represented image segment. These co-ordinates may be adjusted in the User-verification stage before being used to splice the image in the Image Splicing stage.

We will use a custom algorithm (which uses the black-and-white version of the image):

1. To segment into lines:

(a) Scan rows of pixels until you find a row with some pixels on.

(b) Keep scanning until you find an empty row.

(c) Everything between those is one line.

2. To segment those lines into words:

(a) Within a line, scan vertical columns of pixels until you find a column with some pixels.

(b) Keep scanning until you find an empty column.

(c) scan for another column with pixels in it.

(d) If the distance between those is above some threshold, interpret it as a space.

Try making the threshold proportional to the typical line height, to adjust for writing size.

4.3 User Verification

An optional stage, this allows the user to correct any layout detection errors from the first stage. It is to take the Source image and the previously generated SegmentLayout as its input. As output it will return the input SegmentLayout which may or may not have been modified by the user.

4.4 Image Splicing

This stage takes the same input as the User Verification stage. That is, the Source image and the SegmentLayout (either modified by the User Verification stage or straight from the Layout Detection stage). Its output is the input SegmentLayout with the segment bitmaps filled in by splicing the image using the specified co-ordinates.

Processing

5.1 Training

We will need to build a collection of training data and test data. This will make it possible to automatically test the accuracy of new or modified algorithms. For word-by-word methods, the training data and test data will need to include many of the same words.

It will be necessary to be able to store pipeline results. Especially results that receive manual feedback, so that this wouldn’t be necessary every time.

It should be possible to save pipelines and sets of pipelines as well.

It may be much more convenient to be able to store internal classifier data (where applicable). Brute-force methods will still need to store the features detected during training.

The pipeline for training saves the features detected to the datastore. The pipeline for classification passes the features to the classifier; the brute-force classifier (DifferencesClassifier) compares them to all of the examples in the datastore (which can be from several images).

5.2 Processing Algorithms

There are many modules that detect various features (specified as algorithms, rather than learnt). Each of these has a difference measure, that specifies how different it should regard two word images based on those features.

The program also detects width and height as another feature of the image. The final module is a DifferenceClassifier, which combines the difference

measures from several other modules, and does a brute-force search for the word in the dictionary which has the least difference to the word currently being classified.

5.2.1 FindDots

Scans the image pixel by pixel. When a black pixel is found it is added to a new blob or added to an existing blob if it is adjacent to that blob. Any adjacent blobs are then joined. When the scan has finished, any blob above a minimum size and below a maximum size is added as a ’dot’.

Any dots found that are close to the right hand side of the image are classified as full stops rather than dots (such as on ’i’s and ’j’s).

5.2.2 FindLines

Segments the image into rectangles. For each rectangle, if the total number of black pixels in the rectangle are above a certain threshold it is added to the start of a line. It continues scanning and adds any adjacent blocks to the line if their area is above the threshold. For the resulting lines, any that have length above a threshold are added to the list of lines.

5.2.3 FindAreaBlocks

5.2.4 Dimensions

5.2.5 OutsideArea

Finds whitespace areas around the edge of a word. Produces a set of rectangles of at least a minimum height and width. It scans along the top and bottom edges to find a place where it can fit such a rectangle, then extends it as far as possible to the right, then extends the result as far as possible upwards.

5.2.6 DifferencesClassifier

Adds up the difference measures for each module. Does a brute-force search to find the word in the training data with features least different to the current word, and guesses that.

User Interface

The GUI will evolve over the course of the application development, and we will add things as we require them, this is merely a base specification.

6.1 Main GUI

The main GUI should allow the user to select the input image (preferably a page of handwritten text) and then allow the user to select the algorithms that are run. Once this is done the user should be able to select if they would like to be allow to change the image segment boundaries, as mentioned in the Image Segmentation chapter. This should allow the user to change the boundaries for each word visually, by modifying the box surrounding the word. In the case of multiple input images, this should be done before running the processing algorithms. The use should also be presented with feedback while the program is processing the handwriting, this is done through the use of classes which implement the IReporter class.

6.2 Training GUI

The user can select the input image(s), and text file(s) containing the same text as in the image(s). The user would select one or more pipelines, which would be run on this data; processing algorithms would run normally, and classifiers would run their training algorithms on the data, with the text files providing the classes for classification.

There should be a GUI section for training, which allows specifying multiple separate pipelines for comparison.

6.3 Testing GUI

The testing GUI should allow the user to specify an image and a text file like with training. The user would be able to specify multiple pipelines (algorithm congurations). It should be possible to save and load pipelines and groups of pipelines. The testing system should automatically re-run training (or parts 18 CHAPTER 6. USER INTERFACE

of training) when algorithms have been updated or added. The appropriate sequence would be this:

1. The user specifies multiple pipelines

2. The user specifies the image and text file

3. The user is allowed to correct the image segmentation

4. All of the algorithms combinations are run, separately, with output about progress (and preferably also information about which features they detected etc, displayed visually if appropriate).

5. The program displays an accuracy comparison for each pipeline

Data store

The data store stores information about known words. This includes sample images, features detected, word frequency information, etc. The DataStore interface will attempt to abstract away how everything is actually stored so that the initial filesystem-based storage can be replaced at a later date by something like serialization should it be required.

7.1 Stored Data

An item of data (DataItem class) in the Data Store will contain the following:

1. A unique ID (a number)

2. Zero or more sample images

3. Data such as features detected, etc, in string form.

7.1.1 ID

The Unique ID will just be a number starting at 0. Gaps will occur if items are removed from the data store. Any such gaps must be handled in such a way that iteration using something like a for loop would not encounter them. How this is done is up to the implementation.

One such way would be to fill gaps with “blank” DataItems which would also be in an internal list of unallocated items. When a new item is added to the data store rather than creating the DataItem at max + 1 it would just pick the first one from the list of gaps.

This way a remove would generate a gap and an add would remove it:

Items:  0  1  2  3  4
Start  allocated  allocated allocated  allocated allocated
Remove Item 2 allocated  allocated unallocated allocated allocated
Remove item 0 unallocated allocated unallocated allocated allocated
Add new item allocated  allocated unallocated allocated allocated
Add new item allocated  allocated allocated  allocated allocated

7.2 Storage

The initial implementation of the Data Store will use a directory-based layout to allow easy debugging during initial development. In this initial storage design everything will be sorted into subdirectories under one Data Store “repository” directory. Each directory under the repository directory will represent one data item:

1. The name of the subdirectory would be the items unique ID/number

2. The sample images would be stored as files inside this directory with a name like “sample-000.png”

3. Plain Text data would go in a file like “data.ini” which would have a key-value structure.

The implementation could also store anything it needs to remember inside its own data files directly inside the repository directory. How this is done (if it is done at all) is up to the implementation.

At a later date this could be serialized into a single file inside the repository directory instead.

7.3 DataStore

Access to DataItems would be through the DataStore class. The DataStore class would essentially be nothing more than a wrapper around a list of DataItems. Items would be added/retrieved/removed by unique ID just as with any other list.

7.3.1 Loading

When instructed to load the DataStore would search for saved data items. For each data item it finds it would create an instance of DataItem, instruct it to load the saved data item and then add it to its internal list. This means that it would really be DataItem that is doing most of the work - DataStores load function should be quite easy to implement

7.3.2 Saving

A save method is provided. What this does (if anything) is up to the implementation. The filesystem based data storage method discussed earlier is unlikely to require this but any future serialization based implementations may require it.

7.3.3 Interface IDataStore

1 package comp314 . i n t e r f a c e s ;

2

3 import java . u t i l . ArrayList ;

4

5 /∗∗ Data Store I n t e r f a c e .

6 ∗
7 ∗ @author David Goodwin
8 ∗/
9 public interface IDataStore {

10

11  /∗∗ This l o a d s the DataStore from a s p e c i f i e d
r e p o s i t o r y .
12  ∗ @param l o c a t i o n The l o c a t i o n of the DataStore
13  ∗ r e p o s i t o r y
14  ∗/
15  void load ( S t r i n g l o c a t i o n ) ;

16

17  /∗∗ This saves anything r e q u i r e d . Up to the
18  ∗ implementation .
19  ∗
20  ∗/
21  void save ( ) ;

22

23  /∗∗ Gets the item with the s p e c i f i e d number . Gaps
24  ∗ are to be handled by implementation in a
25  ∗ t r a n s p a r e n t way .
26  ∗ @param number The item number to g e t
27  ∗ @return The s p e c i f i e d item
28  ∗/
29  IDataItem getItem ( int number ) ;

30

31  /∗∗ Adds the s p e c i f i e d DataItem to the DataStore .
32  ∗ This should f i l l the f i r s t a v a i l a b l e gap i f the
33  ∗ implementation a l l o w s gaps . Otherwise i t should
34  ∗ be added at count+1
35  ∗ @param theItem the Item to add
36  ∗ @throws Exception
37  ∗/
38  void addItem ( IDataItem theItem ) ;

39

40  /∗∗ Removes the s p e c i f i e d item from the DataStore .
41  ∗ This may e i t h e r c r e a t e a gap or cause every
42  ∗ item a f t e r the s p e c i f i e d number to be
43  ∗ renumbered . This i s up to the implementation .
44  ∗ @param number The item number to remove
45  ∗/
46  void removeItem ( int number ) ;

47

48  /∗∗ Returns the number of DataItems in the
49  ∗ r e p o s i t o r y .
50  ∗ @return The number of items in the DataStore .
51  ∗/
52  int getItemCount ( ) ;

53

54  /∗∗

55  ∗ Checks i f a word e x i s t s in the d a t a s t o r e and i f so
return the index .
56  ∗ I f i t doesnt e x i s t return −1.
57  ∗ @param key The word to f i n d .
58  ∗ @return The index of the word .
59  ∗/
60  IDataItem e x i s t s ( S t r i n g key ) ;

61

62  /∗∗
63  ∗
64  ∗ @return L i s t of a l l the unique words in teh s t o r e .
65  ∗/
66  ArrayList<String > listWords ( ) ;
67 }

7.4 DataItem

The DataItem class is the container for an item of data that is stored in the Data Store. It is in charge of providing access to that item of data including loading and saving it.

7.4.1 Loading

The DataItem is to be given a location from which to load itself. What exactly is done when this is called is up to the implementation but it is expected that once the call has been completed the DataStore should be ready for use. In the previously discussed filesystem implementation it would scan its directory for images to obtain a count and make the data file ready for use.

7.4.2 Saving

What is done when this is called is entirely up to the implementation. Once this call has been completed it is expected that the instance could be deleted without any loss of information.

7.4.3 Access to Data

Sample images are to be accessed by number using get, add and remove methods. Plain text data are to be accessed by key using get/set/remove methods.

7.4.4 Interface IDataItem

1 package comp314 . i n t e r f a c e s ;

2

3 import java . u t i l . ArrayList ;

4

5 /∗∗ Data Store I n t e r f a c e .
6 ∗

7 ∗ @author David Goodwin
8 ∗/
9 public interface IDataItem {
10  /∗∗ Loads the DataItem from the s p e c i f i e d l o c a t i o n .
11  ∗ @param l o c a t i o n The l o c a t i o n to load from
12  ∗/
13  void load ( S t r i n g l o c a t i o n ) ;

14

15  /∗∗ Saves the DataItem . The l o c a t i o n i s obtained
16  ∗ from the r e s u l t of a p r e v i o u s save ( S t r i n g ) or
17  ∗ load ( S t r i n g ) operation .
18  ∗/
19  void save ( ) ;

20

21  /∗∗ Saves the DataItem to the s p e c i f i e d l o c a t i o n .
22  ∗ @param l o c a t i o n The l o c a t i o n to save to .
23  ∗/
24  void save ( S t r i n g l o c a t i o n ) ;

25

26  /∗∗ Gets the s p e c i f i e d sample image .
27  ∗ @param number The number of the sample image .
28  ∗ @return The r e q u e s t e d sample image
29  ∗/
30  IData getImage ( int number ) ;

31

32  /∗∗ Adds a sample image .
33  ∗ @param theImage The sample image to add
34  ∗/
35  void addImage ( ITextImage theImage ) ;

36

37  /∗∗ Removes the s p e c i f i e d image .
38  ∗ @param number The image to remove
39  ∗/
40  void removeImage ( int number ) ;

41

42  /∗∗ Returns the number of sample images .
43  ∗ @return The number of sample images
44  ∗/
45  int getImageCount ( ) ;

46

47  /∗∗ Gets a s t o r e d value . Key i s the key under
48  ∗ which the data was p r e v i o u s l y saved . The
49  ∗ d e f a u l t value i s what i s returned i f the key
50  ∗ does not e x i s t . This means t h a t t h e r e i s no need
51  ∗ to check the key e x i s t s f i r s t .
52  ∗ @param key The items key . Keys are in a t r e e . For
53  ∗ example , ” f e a t u r e s / featureA ” or ” ASCIIvalue ”
54  ∗ @param sDefaultValue What to return i f the key
55  ∗ doesn ’ t e x i s t .
56  ∗ @return The value f o r the s p e c i f i e d key i f i t

24 CHAPTER 7. DATA STORE

57  ∗ e x i s t s , o t h e r w i s e d e f a u l t v a l u e .
58  ∗/
59  S t r i n g getValue ( S t r i n g key , S t r i n g sDefaultValue ) ;

60

61  /∗∗ Stores the s p e c i f i e d value under the s p e c i f i e d
62  ∗ key .
63  ∗ @param key The key to save the value under
64  ∗ @param value The value to s t o r e
65  ∗/
66  void setValue ( S t r i n g key , S t r i n g value ) ;

67

68  /∗∗ Removes the s p e c i f i e d key .
69  ∗ @param key The key to remove .
70  ∗/
71  void removeKey ( S t r i n g key ) ;

72

73  /∗∗ Returns a l i s t of a l l keys under the s p e c i f i e d
74  ∗ key .
75  ∗ @param key The s p e c i f i e d key . ”” i s the root key .
76  ∗ @return The l i s t of keys under the s p e c i f i e d key .
77  ∗/
78  ArrayList<String > l i s t K e y s ( S t r i n g key ) ;

79

80  /∗∗
81  ∗ Gets the uid of the item .
82  ∗ @return S t r i n g containing the uid .
83  ∗/
84  S t r i n g getUid ( ) ;

85

86  /∗∗
87  ∗ Sets the unique i d e n t i f i e r of the item .
88  ∗ @param uid A unique s t r i n g .
89  ∗/
90  void setUid ( S t r i n g uid ) ;
91 }

7.4.5 Reference Keys

Key  Explanation
ascii word  The text representation of the word.

     outsideArea\<edge_id>\<rectangle_id>\x X Coordinate
     outsideArea\<edge_id>\<rectangle_id>\w Width
     outsideArea\<edge_id>\<rectangle_id>\y y Coordinate
     outsideArea\<edge_id>\<rectangle_id>\h Height.

Value Keys

Keys for the setValue/getValue/removeKey/listKeys methods are in a tree form. For the string “key1/key2”, “key2” is a child node of “key1”. listKeys(“key1”)

7.4. DATAITEM 25 should return the list including “key2”. listKeys(“”) should return the list including “key1”

26 CHAPTER 7. DATA STORE

Output

8.1 Logging

The logging should be a static class which is available to all modules and classes, and provides the ability to write to the log file, which should be opened upon program execution and closed upon termination.

8.1.1 Severity

Each log entry will contain the entry severity at the start. The writeLine(String) function uses the “Notice” severity where as the writeLine(Severity,String) allows you to specify the severity.

Available Severity levels

1. Notice - Just a general notice.

2. Debug - A debug message - There shouldnt be too many of these.

3. Warning - A warning that the program state is not quite as expected and something may go wrong later because of it.

4. Error - Something has gone wrong but recovery may be possbile. The program will attempt to continue but a Failure may later occur.

5. Failure - An unrecoverable error has occured. This message should probably include a stack trace and any program state information. After issuing one of these the program should try to terminate nicely.

8.1.2 ILogger

1 package comp314 . i n t e r f a c e s ;

2

3 import java . i o . IOException ;

4

5 /∗∗ I n t e r f a c e f o r l o g g i n g c l a s s e s .
6 ∗

7 ∗ @author David Goodwin , Daniel Buchanan
8 ∗/
9 public interface ILogger {

10

11  /∗∗ The l o g e n t r i e s s e v e r i t y l e v e l .
12  ∗
13  ∗/
14  public enum S e v e r i t y { Notice , Debug , Warning , Error ,
F a i l u r e };

15

16  /∗∗ Opens the l o g f i l e f o r input .
17  ∗ @param filename The output f i l e f o r l o g g i n g .
18  ∗/
19  void open ( S t r i n g filename ) throws IOException ;

20

21  /∗∗ Closes any open l o g f i l e s .
22  ∗/
23  void c l o s e ( ) throws IOException ;

24

25  /∗∗ Writes a message to the l o g f i l e using the Notice
s e v e r i t y .
26  ∗ @param message The message to w r i t e to the l o g
f i l e .
27  ∗/
28  void writeLine ( S t r i n g message ) ;

29

30  /∗∗ Writes an entry to the l o g f i l e using the
s p e c i f i e d s e v e r i t y . This can
31  ∗ throw e x c e p t i o n s
32  ∗ @param sv Log entry s e v e r i t y
33  ∗ @param message Log message
34  ∗/
35  void writeLineE ( S e v e r i t y sv , S t r i n g message ) throws
IOException ;

36

37  /∗∗ Performs the same j o b as WriteLineE e x c e p t does
not throw any e x c e p t i o n s .
38  ∗
39  ∗ @param sv S e v e r i t y Level
40  ∗ @param message Log Message
41  ∗/
42  void writeLine ( S e v e r i t y sv , S t r i n g message ) ;

43

44  /∗∗ Returns the S t r i n g r e p r e s e n t a t i o n of the
s p e c i f i e d S e v e r i t y Level . This
45  ∗ i s the S t r i n g r e p r e s e n t a t i o n used by the l o g
output .
46  ∗ @param sv The s e v e r i t y l e v e l
47  ∗ @return The s t r i n g r e p r e s e n t a t i o n of the given
S e v e r i t y Level .

48  ∗/
49  S t r i n g svToString ( S e v e r i t y sv ) ;
50 }

8.2 Program Output

8.2.1 Training

Will output statistics to the log file on each run.

8.2.2 Normal Mode

Will output a text file containing the recognised contents of the input, wherever the user decides to put it.

8.2.3 Testing Mode

Will output statistics etc to the log file on each run.