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 *
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.
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 :-
Max height (m)
Min height (m)
Dimension (tile x tile)
Random generator seed
Corner Seeds (m)
2.3 User Interface to Route Finder
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:-
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.
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.
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
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 degrees0Distance
- 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.
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
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 |