CHARLIE

CANAL ROUTING PROGRAM

 

 

 

 

 

 

 

USER MANUAL

 

February 2000

 

 

Contents

1.0 Introduction *

2.0 Facilities *

2.1 Terrain Generator *

2.2 Route Finder *

2.3 User Interface to Route Finder *

3.0 Methods of Modelling *

3.1 Optimum route finding facilities *

3.2 Modified Dijkstra’s Algorithm *

3.3 Dijkstra's - No Tunnels *

3.4 Simple Algorithm *

4.0 File Formats *

4.1 The Terrain *

4.2 The Route *

5.0 References *

6.0 Tutorials *

Example 1 *

Example 2 *

Index *

1.0 Introduction

 

Welcome to Charlie !

Charlie is a canal routing program written in Java, attempting to find the most economical route for a canal from start point O to end point C. It generates the geographical data, finds the route and displays the results.

A matrix gives the level in metres of each one kilometre square in the countryside through which a canal will pass. Each kilometre square tile is assumed to be level. Points O and C are considered to be at the centres of two identified square tiles.

The cost of building a canal is highly dependent on the terrain it travels through and as such the most direct route from point A to point B is not always the cheapest to build, or the quickest for boats to traverse. Finding the most economical route involves time-consuming and repetitive calculations, the computer system, Charlie aims to find the most economical route within reasonable time. The cost of construction is proportional to the length of the canal and depends on its level relative to the surrounding ground . The program models this as follows :-

 

Level difference d relative

to the surrounding land

Types of Construction

Cost in pounds

per horizontal metre

-10 R d R 10

surface

p

10 < d < 30

embankment

q

-30 R d < -10

cutting

r

d < -30

tunnel

s

d R | 10 |

lock

t (per number)

Locks can be constructed for a level change of a canal by up to 10 metres. The length of locks are ignored and locks are not permitted in tunnels.

The program refers "most economical" as the lowest construction cost, and social, environmental or commercial factors are not taken into consideration. A graph-based algorithm is used to obtained the optimum route between two points. The problem is considered to be a single-pair, shortest-path one, and Dijkstra's algorithm has been chosen. It allows the search for shortest paths to be terminated once the shortest path between the two desired points has been found. It is also quite efficient being O(V2 ), where V is the number of vertices in the graph.

Charlie disallows negative cost rate for the construction of the canal, as the algorithm chosen does not cope with negative weighted edges.

Impassable square tiles are permitted to cater for disallowed terrain such as a village, SSSI, privately owned land, contaminated ground etc. Tunnels are not permitted in these square tiles.

 

2.0 Facilities

Charlie is a user friendly canal route finding program, which finds the most economical route between two points, displays the best route and its corresponding total cost.

As a user, you can input the grid size, you can specify details of the terrain or randomly generate it by a separate module within Charlie. A grid of the specified size can be saved and loaded into the program. Each grid square tile indicates terrain height.

The terrain will be displayed with the canal routing colour coded to represent different types of construction : level, embankment, cutting, tunnel or lock. The start and end points can be entered by clicking on appropriate square tile. The costs for different types of canal structures can be entered. Details can be submitted. Charlie will calculate to give the best route, will display it and its corresponding total cost.

Information available to the user from the results are :-

 

2.1 Terrain Generator

Max height (m)

Min height (m)

Dimension (tile x tile)

Random generator seed

Corner Seeds (m)

 

2.2 Route Finder

 

 

2.3 User Interface to Route Finder

 

 

3.0 Methods of Modelling

3.1 Optimum route finding facilities

The method of modelling used by the algorithms has made the following simplifications :-

Other simplifications

 

3.2 Modified Dijkstra’s Algorithm

The algorithm was designed as an entirely separate module that can be "unplugged" and replaced, so that changing it has no effect on the rest of the code. The algorithm used is a modified Dijkstra’s Algorithm run over the graph, taking O as the start point.

The modifications are as follows:-

 

3.3 Dijkstra's - No Tunnels

Dijkstra's - No Tunnels Algorithm Option calculates a route based on Dijkstra but ignores all tunnels in order to speed the calculation up. This route, in general, can be generated more quickly than the above option, and can be used to compare complex algorithms.

 

3.4 Simple Algorithm

Simple Algorithm Option is calculating a route by a very simple algorithm, and generates a route that works. The route goes in a straight line until it reaches a point where it can go directly to the finish with a diagonal of 45 degree gradient. This route can be generated quickly and therefore good for a preliminary trial, and can be used to compare complex algorithms.

 

 

 

4.0 File Formats

4.1 The Terrain

Each row of the matrix will be represented by one line in the local file encoding format. Data values in a row will be separated by commas. After the last value there will be a new line character ('\n') but no comma. The whole file will be terminated by an EOF marker.

The file should be in the local file format (UNIX/Windows) for the OS, Charlie will be running under. This should make little difference when the program generates terrain, but could be crucial when editing terrain by hand or transferring terrain generated under one OS to another.

The first row will set the number of columns, if there is a different number on any subsequent line, Charlie will inform the user that the file format is invalid and not load the terrain.

The data values will be integers representing height above sea level, so negative numbers indicate distance below sea level. A number followed by an X char indicates that a square contains some impassable terrain for the canal, such as a village, SSSI, etc. It is not possible to tunnel under impassable squares.

An example

27,10,34,35,17,12,8\n
28,12X,36,32,15,18,-5X\n
EOF

4.2 The Route

Charlie will have a binary (non-readable) output using the serialisable interface to allow the route to be loaded and saved. It will also have an output in a readable format, which can be used for exporting and printing the route. The readable format is described below.

Example

(0,0)(50,50) 

 

Start as Embankment 

Height27m  

 45DEG-N

(1,1)(0,0)   

Lockup (10m)      

Height 9m

-

(1,1)(0,0)   

Change to Standard 

Height 9m

45DEG-N

(1,1)(50,50)

 

Change Direction

Height 9m 90DEG-N

(2,1)(0,50) 

Change to Cutting

Height –23m

90DEG-N

(2,1)(50,50)

 

Change Direction

Height –23m 45DEG-N

(3,2)(0,0)   

Change to Tunnel

Height –35m 

45DEG-N

(3,2)(50,50)

 

Change Direction 

Height –35m 0DEG-N

(3,3)(50,0) 

Lock down (10m) 

Height 35m

-

(3,3)(50,0) 

Lock down (10m)

Height 25m 

-

(3,3)(50,0) 

Change to Embankment 

Height 25m 

0DEG-N

(3,3)(50,50)

 

End  Height 25m     

-

 

 

 

5.0 References

This references section is a series of running instructions. It contains detailed descriptions on how to use every feature in the interface, to help you to learn how to run the program, and to obtain the reqiured results and output. It introduces you to make the most efficient use of this manual. It is designed to guide you step by step of how to run the program Charlie.

 

Step 1 Start the Program

To run the program type : "Charlie"

A window "Charlie the Canal Router" will display

(frame1.gif)

(frame2.gif)

 

The program Charlie requires you to provide a terrain map. You can simply load an Ordnance Survey map file stored in the required format described in Step 2b, generate a terrain using a facility provided by Charlie TerrainGen as described in Step 2a, or to create a terrain file as described in Step 2b.

Step 2a To generate a terrain

Terrain Generation

Click "File" or type "Alt F", a pull down menu will display, then Click "New" or type "Alt N"

A dialogue box "Terrain generation utility" will display

Enter Grid size (x,y) [default 129,129]

Minimum height [default -30]

Maximum height [default 100]

Corner seed (1-4) [default 0]

Random seed [default 0]

(frame3.gif)

 

 

Click "Generate", a dialog box will popup

Type in a filename [ .ter]

The generated terrain can be saved as a file.

 

 Step 2b To create a terrain file

The terrain file has to be in the format described here :

 

An example

27,10,34,35,17,12,8\n

28,12X,36,32,15,18,-5X\n

EOF

If the terrain map files do not comply with the required format, an IO Exception warning will be given.

 

Menu Bars

There are 4 choices on the Menu Bars

File / Route / View /Algorithms

 

Step 3 To load a terrain from a file

Click on "Load" or type "Alt L"

A window will be opened. Load the required Terrain file by highlighting on the required filename, then Click "Open" (frame4.gif))

 

To get rid of the current terrain, Click "File" then "Close" or type "Alt F" and then "Alt C". Repeat Step 2 for other terrains.

Alternatively, Click "File" or type "Alt F" for the pull down menu, Click "Load" or type "Alt L"

Step 4 To overlay or remove a grid on the terrain (frame5.gif)

 

Click on "View" for the pull down menu

then Click on "Show Grid" or type "Alt G" (frame6.gif)

 

 

Step 5 Input Cost Rates

The Cost Rate for each type of construction must be entered. The defaults are

Canal (per metre) - 1.00

Tunnel (per metre) - 100.00

Cutting (per metre) - 10.00

Lock (per number) - 100.00

Embankment (per metre) - 10.00

 Click on the appropriate box and enter the Cost Rates (e.g. XX.XX) for :-

Canal (per metre) -

Tunnel (per metre) -

Cutting (per metre) -

Lock (per number)

Embankment (per metre) -

The cost unit rates entered will be displayed in the appropriate boxes. (Cost.gif)

Some Quick Buttons

Load

To load a new terrain or canal route from a binary file

Click " Load" or type "Alt L"

Save

Save the current route to a binary file

Click " Save" or type "Alt S"

Generate

To generate the optimum canal route using the Dijkstra algorithm

Click "Generate Route" or type "Alt G"

Export Route

To export Routing Instructions to file

Click "Export" or type "Alt x"

Print Route

To print the Routing Instructions

Click "Print" or type "Alt P"

 

Step 6 View Display

Check on the appropriate boxes for the following display :-

Show Costs

Show Terrain Info

Show Key

Show Zoomer

Show Buttons

Show Start and Finish

Show Results

Show Grid

Use 3D View  

 

 

When the "Show Key" is checked, a dynamic key will be displayed on the screen. The height (in metres) of the terrain above the principal datum will be shown against the colours used in the terrain map. The dynamic key also indicates the route of the canal showing what form of construction for each section. An example of the key is shown below. (key.gif) key.gif

 

 Key for the Route

Type of Construction

Symbols / Colours

Impassable Square

red square

Embankment

cyan line

Surface Canal

royal blue line

Cutting

magenta line

Tunnel

black line

Lock

red dot

Start/End

yellow dot

Display

When the "Show Terrain Info" is checked, the height (in metres) of a particular location shown in (x,y) coordinates on plan when the cursor is, will be displayed.

Step 7     Input Start and Finish Points

The Start and Finish points have to be entered in order that the route be generated.

Click 'Set' button

Click on square tiles on the map to set Start and End points.

The x,y co-ordinates will be shown in the Start and End boxes.

 

OR

Click the box labelled Start

Enter the x and y co-ordinates for the Start (The starting square for the algorithm) 14,0

Click the box labelled End

Finish Points (The end square for the algorithm)  14,11

(startend.gif) 

 

An example of an IO Exception warning for loading a file with incompatible format. (exception1.gif)

 

 

Step 8 Algorithms

To generate a route using the modified Dijkstra Algorithm

Click on "Algorithms" or Type "Alt A", a pull down menu will be displayed.

There are a 3 algorithms in the current version of the program Charlie :

Dijkstra - run the modified Dijkstra algorithm

Dijkstra - No Tunnels - run the modified Dijkstra algorithm ignoring tunnels

Simple - run the simple algorithm

(algorithm1.gif)

 

 

 

Click and check " Dijkstra " or type "Alt D" to choose, or

"Dijkstra - No Tunnels " or

"Simple" or "Alt S" whichever appropriate.

 

The Default is "Dijkstra"

 

Click "Generate Route" or type "Alt G" to start generating the route (generate1.gif)

 

 

Zoomer

Zoomer is an exponential scroll.

Zoom range - 10 to 1,000 (%)

To zoom in drag the slider to the right, and vice versa for zooming out.

 

Output Facilities

Export Route

To export routing instructions to file

Click Route or type "Alt R", a Export window will be displayed

Enter the filename with extension .txt, and click "export".

Save Route

To save a current route in a binary file

Click Route or type "Alt R", a Save window will be displayed

Enter the filename with extension .rte, and click "save".

 

Print Route

The cost of the most economical route will be printed The route of the most economical route in the same format as the "Export" function.will be printed. (print1.gif)

 

 

Overwrite check.

If there is an attempt to overwrite an existing file there will be a warning and change is allowed.

 

Alternative Facilities

3D View

Show the terrain using a 3D view

Click " Use 3D View" or type "Alt V" (3Dview.gif) 3Dview.gif

 

 

3D View

To show the route in 3D view.

Click "View" or type "Alt V"

A pull down menu will be displayed. (3DView2.gif)

 

Sliders for viewing adjustments :-

Angle - viewing angle (360 degrees0

Distance - distance of the eye to the object (75 to 175%)

Height - viewing height (the larger the value, the higher it is) max 2000%

Height Exaggeration - exaggerating the vertical distance (max. 2000%)

 

 

Help Facilities

Click "File" on the menu bar or type "Alt F"

An online User Manual will be displayed in a separate window.

 

 

6.0 Tutorials

Example 1

Step 1

Create a terrain file

Step 2

Load the terrain file

Step 3

Input Start and Finish Points

Step 4

Input Cost Rates

Step 5

Choose Algorithm

Step 6

Generate Route

Step 7

Change Cost Rates

Step 8

Re-generate the Route

Step 9

Change Finish Point

Step 10

View 3D Display

Step 11

Export Route

Step 12

Save Route

 

 

Step 1

Create a terrain file

-7,-24,-60,-69,-62,-18,-3,-8,-21,-21,0,7,6,17,22\n

1,-7,-40,-49,-40,-19,-22,-10,-7,-32,-24,-14,-10,5,-5\n

23,3,-27,-25,-13,-24,7,-17,-15,-29,-41,-37,-27,-10,-10\n

18,25,28,10,-9,-11,8,1,-2,-5,-23,-41,-43,-32,-27\n

44,53,43,15,17,-16,-17,-23,-3,-23,-17,-32,-49,-66,-59\n

64,57,41,42,11,-13,-19,-26,-29,-50,-60,-50,-59,-77,-40\n

65,54,25,34,19,-33,-50,-58,-88,-95,-102,-89,-91,-63,-45\n

50,37,23,25,-11,-24,-69,-87,-89,-113,-95,-104,-109,-88,-45\n

62,46,31,-4,-24,-47,-59,-84,-111,-96,-117,-116,-122,-81,-50\n

38,18,2,-1,-33,-64,-77,-76,-81,-100,-103,-124,-109,-67,-52\n

25,25,15,-7,-38,-40,-85,-79,-86,-109,-131,-117,-86,-57,-71\n

17,16,7,-27,-32,-31,-50,-56,-78,-100,-88,-84,-68,-67,-58\n

-18,-23,-16,-18,-10,-14,-11,-43,-78,-77,-78,-84,-85,-79,-78\n

-7,-16,-11,-9,-3,19,-9,-10,-29,-35,-42,-64,-41,-44,-63\n

5,5,-15,-4,37,35,12,4,21,-3,-33,-24,-12,-11,-24\n

EOF

Save the terrain file as hillside 3.ter, with extension .ter

 

Step 2

Load the terrain file

Load the terrain file = hillside 3.ter

(hillside3a.gif)

(hillside3.gif)

 

Step 3

Input Start and Finish Points

(instart.gif)

Input Start point (14,0)

Input End point (14,11)

OR

Click "Set" and Click the Square tiles to enter start and end points.

Step 4

Input Cost Rates

Enter cost rates for the following by Clicking the boxes :-

Canal (per metre) = 1.00

Tunnel (per metre) = 2.0

Cutting (per metre) = 20.00

Locks (per number) = 20000.00

Embankment (per metre) = 20.00

Step 5

Choose Algorithm

Click "Algorithm" and Click "Dijkstra"

Step 6

Generate Route

Click "Generate Route"

(generate2.gif)

 

 

 

 

 

 

Step 6

Change Cost Rates

Lock (per number) = 10.00

Step 7

Re-generate the Route

A different route is calculated.

(lock1.gif)

Step 8

Change Finish Point

Change end point to (6,13) (changend.gif)

Step 9

View 3D Display

Click "View" and then Click use "3D View"

(hillside3D.gif)

Step 10

Export Route

 

Step 12

Save Route

Click "save" and enter a file name with extension .rte

Example 2

Step 1

Load a route with terrain from a file

Step 2

Input Start and Finish Points

Step 3

Input Cost Rates

Step 4

Generate Route

Step 5

Print Route

 

 

Step 1

Load a route with terrain from a file

Click "File" and then "Load"

 

Step 2

Input Start and Finish Points

Click the Square (0,1) to enter start point

Click the Square (31,4) to enter end point

Step 3

Input Cost Rates

 

Enter cost rates for the following by Clicking the boxes :-

Canal (per metre) = 1.00

Tunnel (per metre) = 10000.00

Cutting (per metre) = 100.00

Locks (per number) = 10000.00

Embankment (per metre) = 100.00

Step 4

Generate Route

(simple.gif)

Use the simple algorithm to fins a route for comparison

The total cost is 892242.64

cf .The most economical route total cost is 87112.69

 

Step 5

Print Route

 

 

 

Index