SailRule -
Sailing Race Rules for PDAs

See the download page to obtain this program

Description

The SailRule program supports the rules for sailing races. It allows diagrams to be drawn of scenarios in which the rules have to be checked. The program runs on a variety of hand-helds like PalmOS devices (such as Palm or Handspring) and WinCE devices (such as PocketPC). To get an immediate feel for what the program does, consider the figure below:

This is a plan view of three boats trying to pass a mark. They are in danger of collision, so who has right of way? If the figure is entered into the program, it will check the applicable rules and report:

Boat B must give room to Boat A: Rule 18.2(a): When boats are overlapped the outside boat shall give the inside boat room to pass the mark or obstruction, and if the inside boat has right of way the outside boat shall keep clear. Other parts of Rule 18 contain exceptions to this rule.
Boat C has right of way over Boat B: Rule 10: When boats are on opposite tacks, a port-tack boat shall keep clear of a starboard-tack boat.

Limitations

The program supports the main rules for when boats meet (ISAF 'Racing Rules of Sailing, 2001-2004' Part 2). Currently the program has some restrictions:

rules 15, 16, 18.4, 18.5 and 19 are not supported (i.e. acquiring right of way and special rules for obstructions)
to limit calculation times, only one mark and four boats are allowed.

The following are due to inevitable limitations of SuperWaba and the way SailRule has been programmed:

The program does a lot of complex calculations, not using native code. On a small device, please be patient with it! In particular the program will take several seconds to deal with scenario files, and when determining the applicable rules.
The screens are 160 by 160 pixels. If the device has a larger screen size, this may not be used to the full.

Although tested carefully by the authors, the output of the program is purely indicative and must not be regarded as authoritative. For example, do not blame the authors if a protest based on the program is not upheld!

PalmOS

This program was developed at a point when Palm screens were 160x160 and does not work well on larger screens

The program does not contain native code. Instead it is executed by the SuperWaba Virtual Machine (a kind of Java VM). If you have not already installed this, download the SuperWaba VM for your hand-held device. Once you have done this you can run a variety of SuperWaba programs, and not just this one. Although the program should run on a large variety of devices, it has been tested only on a couple of Palm devices.

The program has been developed with version 3.0 of the SuperWaba VM. It should work with similar SuperWaba versions, but past experience suggests that other versions may be incompatible. There are several VMs for various devices so it is not so feasible to include them with the distribution, but they can be easily downloaded. Note that the SuperWaba file organisation has changed in version 3.0. For example, PalmOS needs the following to be installed:

    ...\SuperWaba\bin\palm\SuperWaba.prc
    ...\SuperWaba\bin\palm\SWNatives.prc
    ...\SuperWaba\bin\xplat\Libraries\SuperWaba.pdb

The distribution provides the binary code of SailRule for PalmOS (SailRule.prc and SailRule.pdb) and WinCE (SailRule.lnk and SailRule.pdb). Install the relevant pair of files as you would for any other program on your hand-held. Launch SailRule as a normal app. It will call the SuperWaba VM automatically to run the code. (The link file SailRule.lnk may need to be adjusted according to where you have SuperWaba installed.)

The distribution also includes SailRuleDB.pdb. This is a (PalmOS) database of pre-drawn scenarios that you can load and use with the program. This database contains many examples of the rules, so it should be useful for you to check your understanding of them. Due to the number of examples, it takes some time for the program to read the database initially. You can, of course, define your own scenarios instead of using those supplied. The rules database is backed up to your desktop computer during a hot sync. Since version 1.3 of SailRule, the database creator ID has been changed to SlRl. As a result, older databases will not be read by the program. If this is a problem for you, ask how to fix it.

The SuperWaba system requires about 300 KB of storage on the PDA, though once you have installed it you can download and run lots of other SuperWaba programs. In addition, the SailRule program itself requires about 90 KB of storage, plus a working memory of about 50 KB.

If you wish to re-build the code from source, you will need to download the SuperWaba SDK (Software Development Kit). Use the Makefile if you have the Make utility. Alternatively, under MS Windows use the Build and Clean batch files. If you have not already set up PATH and CLASSPATH, you will need to do so in these files. SailRule.mcf is a half-hearted effort to create a project file for Mobile Creator.

If you wish to use the program only on a PC, then again you need to download and install the SuperWaba SDK. Make or Build at the command line will bring up an applet window to run the program. With the current version of SuperWaba, the PC screen display is disappointing (images with the wrong colour of background, slow screen refresh). Unfortunately it is not (currently) possible to use a web browser or the JDK applet viewer because the required classes are scattered across many directories.

The source code needs a modifed form of the TextArea class from the JGUI library. Unpack jgui-ui.tar.gz from the SailRule distribution to get the relevant files in the ui directory. See the 'KJT' comments for the changes made in the original code. The new files must then be copied on top of the corresponding SuperWaba files: ...\SuperWaba\ext\xplat\wgl\jgui\ui. Finally, build the modified code by calling the Make batch file in ...\SuperWaba\ext\xplat\wgl.

User Interface

The program is provided with extensive help, so what follows is only a summary. The user interface appears as a number of screens:

The program begins with the Start screen, where the wind direction is entered. By convention, directions are angles in degrees measuring clockwise from 0 as North (the top of a diagram). The wind direction is a critical parameter because it determines how boats are displayed. The sail position and tack of a boat are automatically determined by its heading relative to the wind. For this reason it is not allowed to change the wind direction while drawing a scenario. If necessary the current scenario can be cleared, returning to the Start screen.

Scenarios are most easily drawn on the Map screen. To keep this clean, there are deliberately no controls on this screen. Instead, simple keystrokes are used to control the actions. (On a Palm device, enter keystrokes or any text using Graffiti only.) For example, 'F' calls up the file screen and 'R' reports the rules that apply. The wind direction is shown by an arrow at the edge of the screen (280 degrees in the map screen above). Boats are added to the scenario by clicking on the screen (enter 'B'), though only four boats are currently allowed. Subsequently, boats may be dragged to the desired position (enter 'P') and may be rotated to the required heading (enter 'H'). The sail position and tack are calculated automatically knowing the wind direction. As boats are entered, they are numbered in sequence.

For a scenario in open water, this is sufficient. However rule disputes usually arise as boats round a mark. The map screen therefore allows a mark to be added (enter 'M'). Certain rules come into play as boats approach a mark. The significant region is that defined by a circle round the mark with a radius of two boat lengths. (Technically this is twice the length of the nearer boat, but this complication is ignored by the program.) The map screen in the figure shows this two-lengths circle. Avast, Cook and Dainty are within it.

An 'S' against a mark indicates that the mark is rounded to starboard (i.e. the boats keep the mark to starboard as they pass it); a 'P' (port) mark is also possible. It is necessary to know the direction to the next mark in the course. The map screen above shows this as 60 (degrees). Avast, Belay and Cook are therefore moving clockwise round the mark, aiming to sail towards the two o'clock position. Boat Dainty has already rounded the mark.

The map screen does not provide fine control of the scenario, though it is much easier to use because it is graphical. The Main screen offers complete control. If desired the tack, heading and name can be entered for each boat. The automatic determination of tack can be partly overridden in this way, e.g. to show a boat sailing by the lee. Boat parameters can be edited. Marks can be added and deleted, though only one mark is currently allowed. The Main screen also allows other screens to be visited such as for filing and boat editing.

The Edit screen allows boat parameters such as heading, name and position to be changed. More importantly, boat status can be declared. A number of rules depend on what boats are currently doing and what their previous relationship was. That is, the rules depend on the dynamics of the situation. Short of animating a scenario, this is difficult to depict. The program solves this by representing current and previous activity.

The Map screen above shows some examples of what boats are currently doing. Cook is currently sailing above her proper course (AC) and is gybing (GY). Dainty is currently finishing the race (FN). The map screen also shows some examples of previous relationships. Previously, Avast was overlapped (WO) on Belay. This is important when rounding a mark. Although Belay is not currently overlapped by Avast, she was previously overlapped as Avast entered the two-lengths circle. Another previous relationship is that Dainty was ahead (WA) of the other boats when approaching the mark.

By means of the Map screen, Main screen or Edit screen the user draws the scenario to be analysed. This scenario can be stored in a file by entering the File screen and saving it. Previously stored scenarios can be retrieved and edited. They can be saved under another name, making it easy to create variations on a base scenario. In practice, SuperWaba does not save scenarios as individual files; they are stored as records in the program's database. However the SailRule program refers to 'files' as they behave like normal computer files. The program database is created separately on the hand-held device and is separately backed up. This means that it is possible to provide the user with pre-prepared scenarios. Users can also swap scenarios.

Invoking The Rules

Once a scenario has been set up, selecting the Rules screen will cause the applicable rules to be displayed. For each pair of nearby boats, their relative right of way is stated and justified by reference to the relevant rules. Sometimes more than one rule may apply. The scenario in the map screen above yields the following output:

Boat Avast has right of way over Boat Belay: Rule 11: When boats are on the same tack and overlapped, a windward boat shall keep clear of a leeward boat.
Boat Cook must give room to Boat Avast: Rule 18.2(a): When boats are overlapped the outside boat shall give the inside boat room to pass the mark or obstruction, and if the inside boat has right of way the outside boat shall keep clear. Other parts of Rule 18 contain exceptions to this rule.
Boat Dainty has right of way over Boat Avast: Rule 10: When boats are on opposite tacks, a port-tack boat shall keep clear of a starboard-tack boat.
Boat Cook has right of way over Boat Belay: Rule 12: When boats are on the same tack and not overlapped, a boat clear astern shall keep clear of a boat clear ahead.

Detailed Instructions

Suggested Usage

To enter a scenario, begin by setting the wind on the Start screen. If a mark is required, add it ('M') and tap the heading to the next mark. If necessary, reposition the mark ('P'); the pen defines the centre of the mark. If the port/starboard rounding indication is wrong, set the mark's heading ('H'). You have to drag, starting near the mark. To achieve precise control, drag out to the edge of the screen and then move round the edge of the screen. Drag anticlockwise/clockwise depending on whether you want port/starboard rounding.

Now add each boat ('B'). These will initially be pointed into the wind, and will be numbered from 1. Now set the heading of each boat ('H'). Drag a new heading from near the bow of the boat, moving the pen further away for precise control. If necessary, reposition each boat ('P'); the pen defines the mast of the boat. If you wish to enter the headings more precisely, or wish to name a boat, go to the Edit screen ('E').

Once the scenario is complete, go to the File screen ('F') and save the scenario. Existing scenarios can be loaded from here, renamed or deleted. Click Done to return to the Map screen. Now check the applicable rules ('R').

If you prefer, exit from the Map screen to the Main screen ('X'). You can add boats and marks precisely from there. Other operations can also be invoked.

Start Screen

Use the menu to learn About the program or to Quit it. Note that it is possible to leave the program only via the Quit menu item. If the current scenario is not saved, you will be prompted to do this. Enter the wind direction (its origin as a heading from 0 to 359 degrees inclusive, default 0) and click Done. Headings are given in degrees clockwise from 0 at the top (0 = North, 90 = East, 180 = South, 270 = West).

Map Screen

On the map, the wind direction is shown by an arrow at the edge of the screen. A boat is drawn with its sail in the approximate position relative to the wind. The boat's name is shown, followed by an asterisk if it is too close to another boat or mark. In such a case, the boat or mark must be repositioned. The boat's name is followed by a list of status values as follows:

AC:: Sailing above proper course
BC:: Sailing below proper course
FN:: Finishing
GY:: Gybing
ST:: Starting
TP:: Tacking to port
TS:: Tacking to starboard
WA:: Was ahead of others on entering the two-lengths mark circle
WO:: Was overlapped on the given boat.

A mark is designated P(ort) or S(tarboard) according to the side it is rounded. A number indicates the heading to the next mark. A mark is surrounded by a two boat-lengths circle. On PalmOS, the command letters described below are entered in either case using Graffiti in the writing area. The same functions are also available from the menu.

B (Boat):: Tap on the map to create a new boat. Boats will be numbered sequentially, but can be renamed later. If an automatically assigned number is already in use as a name, add the boat from the main screen.
C (Clear):: Clear the current scenario and restart. If the current scenario is not saved, you will be prompted to do this.
E (Edit):: Edit the current boats.
F (File):: Load, save, rename or delete scenario files.
H (Heading):: Drag near a boat's bow or near a mark. This results in a new heading (meaning, for a mark, the angle to the next mark). A boat will change tack as needed when its heading is altered. A mark will change to starboard/ port rounding if dragged clockwise/ anticlockwise. H/P cancel each other and themselves. Note that dragging an object over others will temporarily disturb their appearance.
M (Mark):: Tap on the map to create a mark. Tap a second time to define the direction to the next mark.
P (Place):: Drag a boat or mark to a new position.
R (Rules):: Display the rules that apply to the current scenario.
X (Exit):: Exit from the map screen to the main screen.

Main Screen

The Boats line gives the current number of boats. To add a boat, enter its heading from 0 to 359 degrees inclusive (default 0) and its name (default is the boat number). Choose whether it is on port or starboard tack (which must be consistent with the wind direction). Click Add, then tap the location of the boat's mast on the map screen. To change any existing boats, click on Edit. Currently, four boats may be entered. The Marks line gives the current number of marks. To add a mark, choose whether it is to be rounded to port or starboard. Click Add, then tap the mark's location on the map screen. A second tap is required to define the line to the next mark. Click Delete to remove the most recently added mark. Note that currently only one mark may be defined. Click Clear to discard the current scenario and return to the start screen. If the current scenario is not saved, you will be prompted to do this. Click File to load, save, rename or delete a scenario. Click Map to see the map screen. Click Rules to see the rules that apply in the current scenario. The Wind line gives the current wind direction.

Edit Screen

Click Prev or Next to select the previous or next boat for editing. The heading, name and status (upper list) of the current boat are shown.

Enter a new heading or name and click Head or Name to change this. Click Place to give the boat a new position using the map screen. Click Delete to remove the current boat. Click on the lower list of status values and then Add to add a status setting to the boat. Note that some of the status settings are mutually exclusive. In the case of 'was overlapped', it is necessary to click the boat that was overlapped using the map screen. Add the status '--' (clear) to indicate that a boat has completed her manoeuvre (e.g. starting or tacking). This has the effect of clearing all status values. Click on the lower list of status values and then Clear to remove a specific status from the boat.

File Screen

Click on a scenario file in the list to extract its name, otherwise enter a name directly. Click Load to retrieve the given scenario. If the current scenario is not saved, you will be prompted to do this. Click Save to store the current scenario under the given name. To rename a scenario, click on it in the list, enter a new name, and then click Name. Click Delete to remove the scenario with the given name. A deleted scenario cannot be recovered.

Rules Screen

The relative rights of way are shown for each pair of boats. The only rules currently supported are for open water and mark rounding (not rules 15, 16, 18.4, 18.5, 19). The program takes as its basis the ISAF 'Racing Rules of Sailing, 2001-2004'. However the output of the program is purely indicative, and must not be regarded as authoritative.

Licence

This program is free software. You can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation - either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful but without any warranty, without even the implied warranty of merchantability or fitness for a particular purpose. See the GNU General Public License for more details.