Peter H. Vanderwaart
Cautions
1. boatCalc is a program. It can read and write files on your computer's disk drives. Running any program that you download from the Internet is an act of trust. I can depend on my own efforts, but I cannot keep someone else from creating a malicious program with the same name. If you download the program from the Yahoo group "boatdesign", be sure that I am listed as the person who posted it there. If you wish additional assurance that you have the correct program, I will send you, by e-mail, additional information that can be used to verify the file. Or, if you wish, I will send you a copy of the latest version of the program by e-mail.
2. boatCalc is still under development. The calculations have not been independently verified, nor have they stood the test of time. In fact, significant errors are still being discovered and corrected. Do not use the calculations from this program for anything important without independent corroboration. In the same spirit, I solicit both examples of errors (all kinds) and of examples that confirm calculations.
Generally speaking, boatCalc is well-behaved with respect to trapping errors without crashing, prompting users about saving changes to data, etc. However, some data conditions cause it to crash, and some other niceties may be missing.
3. boatCalc is being developed to be what I want it to be, which may not be what you expect it to be. And, it is incomplete.
4. As suggested by the title, this is not a well-crafted document. It would be accurate to call it an all-purpose information dump. Cautions are in red. Areas of future development are in blue.
1. Purpose
The purpose of boatCalc is make yacht design calculations based on the linesplan of a boat hull. It is programmed to accept hull lines data in the form usually employed by yacht designers: waterlines, buttocks, and diagonals. It is intended for use by amateur designers and builders.
This program is not a tool for creating a linesplan. It assumes the data entered represent a complete set of faired lines.
Note: It is assumed in this document that the reader is familar with yacht design terminology. See References for more information.
2. Permission (license)
This program is released for public use with the following restrictions:
- Copyright is retained by the author.
- The programmer(s) and distributor(s) of the program are released from all liability for any damage consequent to the use of boatCalc. This includes, but is not limited to, damage done to computers or computer files by the program, and damage or harm resulting from the building or use of any boat for which calculations were done in this program.
- The user may distribute the program to others, but may not change
it, nor charge money (or other compensation) for it. Nor may he take credit
for it or do anything else that infringes the copyright.
boatCalc is programmed in Java. As a practical matter, it requires an up-to-date installation of Sun Java 2 1.4 which is distributed by Sun Microsystems at no charge. For Windows and Linux operating systems, it should be obtained from Sun(http://www.java.com/en/index.jsp). For Apple computers, it should be obtained from Apple(http://www.apple.com/java/). At this writing, the program has been run on several flavors of Windows, and several of Linux. Partial results have been obtained for the Mac-OS.
Note: If you have a web browser, you probably already have some flavor of Java installed. The Sun install of Java on Windows uses a directory with a name like "c:\j2sdk1.4.2_02". (The 'sdk' may be 'jre'.) The lead digits must be 1.4. If you have the 1.3 version, there is no general reason that I know of not to upgrade to the newer version, except that the routine install does not erase the old version. (One user reported trouble with a company application specific to ver. 1.3.) However, if you have an installed version of Java that is not from Sun (e.g. from Microsoft), it is possible that the Sun installation could cause something that you use to become inoperable. You are pretty much on your own with problems of this sort; I really don't know much about different Java versions, or the effect of different Java plug-ins. Sun Java is as close to a universal 'gold standard' as exists in the Java world. If you wish additional information about determining if you already have Java installed, and what version, e-mail me.
There is a workaround if you have the 1.3 version of Sun Java. The missing link is the SAX parser which is available from the SAX Project web site (http://www.saxproject.org/). You can download SAX separately, as described in the FAQ (http://www.saxproject.org/?selected=faq). Look for information about the Endorsed Standards Override Mechanism.
The program has run on Windows machines barely into the Pentium class, but slowly. Much of the development was done on a several year-old, 300mHz PIII, on which it runs smoothly.
4. Obtaining boatCalc
boatCalc can be downloaded from the Files section of the Yahoo group 'boatdesign', or obtained directly from the author.
Versioning. The current version is 0.2b. A new release with changes and corrections that does not increase the feature set will increment the letter: 0.2c, 0.2s, etc. A release with a significant new feature (e.g. new main menu option) will increment the number and reset the alphabet: 0.3a. When the feature set is complete and the program is judged to be stable, a version will be released (with fanfare) as 1.0. Changes in this document are likely to be erratic.
5. Starting boatCalc
The program is obtained as a file named "boatCalc.jar", which can be put in any convenient directory. The command for starting the program is
| Windows Users: The nominal way to start the program is to open
a Command Window from the Start/Programs menu, navigate to the appropriate
directory, and issue the command above. It may be necessary to set a PATH
to a directory containing java.exe. There are several alternate methods that
are more convenient for repeated use. Some users have reported that simply
double-clicking on boatCalc.jar (e.g. in Windows Explorer) will cause the
program to run because their systems have been configured to recognize the
.jar extension. (This is similar to having MS Word start when a .doc file
is double-clicked.) On my own system this did not work since the .jar extension
has been re-directed to an archiving program. Another possibility is to create a shortcut that can be left on the desktop or put in a menu. Find a copy of java.exe. You may find copies in both a Windows System directory (name depends on OS, e.g. C:\WINNT\System32) or in a directory with a name something like C:\j2sdk1.4.2_02\bin. In Windows Explorer, right click on it and choose 'Create ShortCut'. Find the new shortcut, right-click on it and choose properties. In the 'target' box, add the balance of the command after java.exe, e.g. C:\j2sdk1.4.2_02\bin\java.exe -jar boatCalc.jar and in the 'start in' box, put the directory where boatCalc.jar is located. The shortcut can be renamed, and dragged to the desktop. (These instructions may need some modification, depending on the flavor of Windows.) At least one user found that instead of one file with the extension .jar, he
got many files with the extension .class. The .jar file had been unarchived by
accident. The program can be run directly using these class files using the
command(: of how to run the program on these platforms. Once you get it to run, please
send me a note on how you did it. To run the program, I opened a terminal program (xterm), changed to the application
directory |
boatCalc creates a file named boatcalc.log. Any error messages sent to the screen are echoed to this log file. Examples of known error messages are:
- Format errors caused by the host computer not having the expected fonts.
- File format errors (probably "null pointer" exceptions) , especially with old .hul format files.
- Call stack dumps triggered by major execution errors, e.g. division by zero.
boatCalc does not use a configuration file to save user preferences.
6. Main Screen
The main screen displays the lines of a boat or yacht. boatCalc is not meant to be a primary design tool; it is meant to analyze lines developed or obtained elsewhere. The purpose of the main screen is to display these lines for the user to verify visually that they have been correctly entered and read into the computer, and that they describe the desired shape. For example, one file (.hul format) resulted in a display with a difficult to understand line on the body plan. Looking at the data in the Edit Data function, it was noted that the right end of the the sheer was at 240 inches, but that other lines ended at 239.9 inches. These lines were being excluded from the end section of the boat. Changing all the section values to 240 inches resulted in a clean drawing.
The screen is divided into the following sections:
Top left: a text information block with the name of the design and the designer. There are radio buttons to select fresh or salt water, and to select the desired system of units. Caution: boatCalc was created and most testing has been done using the units of inches and pounds. Calculations in other units have had little testing and are likely to have errors. boatCalc does not convert units; the choices are available to make the program conform to the units in which the data was entered.
Top right: The body plan is displayed with stations according to the master station locations. (see section on data model,)
Center: Lines in plan view.
Bottom: Lines in profile view.
Note: The body plan is not in the same scale as the plan and profile ; it is drawn as large as possible in the space available. For each drawing, the horizontal and vertical scales are the same, i.e a square should appear as a square and not a rectangle. However, monitors differ and the apparent length/beam may differ from the true one. There is no allowance or correction for this type of error.
boatCalc draws all sections with
straight lines, i.e. as chine hulls. Calculations are made on the same basis.
For round bottom hulls, a complete set of lines (e.g. 4 waterlines, 4 buttocks,
4 diagonals) is required to closely approximate curved sections. See examples.
7. Data Model
boatCalc is designed around a "hull object." This is a collection of information for a
particular design. It may include any or all of the following parts: table of offsets, sailplan,
rudder/skeg, centerboard, or keel.
The way that boatCalc treats the table of offsets is straightforward, and compatible with
traditional yacht design practice. However, there are some subtleties that
permit great flexibility. Please read this section carefully.
Stations:
There is a master list of stations locations which are automatically numbered
by the program, beginning with 0 (zero). They must be in ascending
order, and must be distinct (not equal). These define the location of sections
on body plan drawings. The number of stations is a key variable; all hull
lines will be defined by a number of points equal (or, optionally, less than)
to the number of stations.
Usual yacht design practice is to number stations with station 0 at
one end of the waterline. Stations on the LWL are always equally spaced. Station
outside the LWL (i.e. the overhands) may have irregular spacings, and may
have negative labels, e.g. -1. Designers may then refer to
intermediate stations which are not marked on the linesplan. For example,
the spot half way between station 4 and station 5 may be referred to as station
4.5.
boatCalc works a little differently. The lowest numbered station is 0,
never negative. The numbered stations do have not have to be equally spaced.
Intermediate locations are referred to in linear units (in, ft, m, cm) from
station 0. Thus station 127 may be 127 inches from station 0. In this text,
I refer to this as 'station value.'
Hulls may point in either direction, but station values must increase
from left to right. Designers sometimes put the "0" station at the bow for
a right-facing hull. These hulls will face left in boatCalc. The computations
are unaffected.
Lines: Each line is defined by a number of points
equal to the number of stations. Each point is defined by three values: station(fore/aft),
breadth(offset from centerline), and height (vertical distance from baseline).
Optionally, points can be used or not; unused points are ignored. Since each
point has a station value, a point need not fall on a master station.
Lines are assumed to be fair. For station values between the defining points,
breadth and height values are obtained by polynomial interpolation through
four points, 2 on either side of the desired station value. (For station
values near the end of the hull, at least three points are always used.)
Each hull line also has a text name used for identification.
In the program and this document, the coordinates are sometimes considered
as
- station = x-axis = fore/aft
- breath = y-axis = left/right
- height = z-axis = up/down
Therefore, the standard drawings use coordinate systems as follows:
- plan - (x,y)
- profile - (x,z)
- body - (y,z)
Auto-Stems: Since hull lines do not necessarily define the bow profile and transom, the program has a feature to create two additional lines automatically by taking the left (right) endpoints of each hull line. If the end point of a line is not in use, that line is not included. For this reason, lines that do not extend to the end of the yacht, such as buttocks, should have end points that are not in use.
Auto-Stems are optional and are selected using radio buttons on the main screen. They are computed by linear interpolation between the points taken in order of height.
Method of Drawing a Section: Since hull lines run fore and aft, the data does not define sections explicitly. The program constructs sections by examining each hull line. Lines that end before or begin after the section are ignored (i.e. lines are not extrapolated beyond their end points). For other lines, the interpolated (y,z) values are computed. The program constructs the section by connecting them in counterclockwise order as observed from a point presumed to be in the middle of the hull, beginning at 12 o'clock. This method works well for most monohulls from sheer to sheer. It will fail for catamarans (though it will work for a single, symmetrical catamaran hull set on the centerline). It may also fail for some faired-in keels, and for complex deck and coaming arrangements. When the method fails, it is usually obvious from drawings.
Keels: Although some keels can be included using the standard hull lines, others will be very difficult. A tool for design of fin keels is planned for the future.
8. Data Files
boatCalc can save the information about a design in a disk file so that it can be recalled later or moved to a different computer. The file format is based on XML which is a popular scheme for exchanging data between computer programs. XML is a tag-based, markup language similar to HTML. Individual data items are defined by tags (text markers of the form "<tag>data</tag>". Tags may be nested ("<tag1><tag2>data</tag2></tag1>") to any depth. Among the advantages of XML are that these files can be constructed and modified directly via a text editor (e.g. Notepad or Wordpad), and the file format is ignored except for the tags. It seems unnecessary to completely define the format of the file here for several reasons.
- The file format is obvious when directly examined.
- The continued development of the program will lead to the definition of additional tags and other features.
- There is little reason to compile data in XML files outside the program.
boatCalc expects these files to have the extension ".xml".
The program uses standard file dialog boxes to choose or assign file names when files are read or written. The process should be essentially the same as for any standard application. However, this has not been tested extensively for non-Windows platforms. Please report any difficulties so that the program can be corrected.
Note that numeric data is rounded to four decimal places on output. (This might be made a user option.) Hence data may be changed slightly from the way it was read from a file, or input.
Hulls Files: Due to the popularity of Greg Carlson's Chine Hull Designer (Hulls or hull.exe), boatCalc has been programmed to read and write files in the .hul format native to Hulls. Note the following limitations:
On input, boatCalc uses the 'smoothed', 13-station version of the lines from the .hul file. boatCalc and Hulls are based on different concepts with respect to coordinate systems and the Hulls file does not contain a value that corresponds to the baseline offset in boatCalc. This value will have to be set in boatCalc.
boatCalc does write files in a format that is readable by Hulls, based on station locations that are internally calculated and which bear no relation to the stations defined in boatCalc data, or to the values in a .hul input file. In addition, the vertical height is adjusted so that all values are non-negative. Hulls is not designed to handle lines that cross, so shapes defined in boatCalc by waterlines and buttocks may be garbled when read into Hulls.
Note that, by design, the features of Hulls and boatCalc are complementary with minimal overlap. Hulls is optimized for the easy development of a set of lines, but is weak on calculation. boatCalc is not a design tool, and is strong on calculation. There is every reason to move a set of lines from Hulls to boatCalc, but less reason to go in the other direction. Improvement in the reading of .hul files will be done as soon as need is demonstrated and the required change is well-defined. Greater sophistication in the output of .hul files is a possibility for future development, but with low priority.
| Sample datafiles are made available
along with the program. Edmunds.xml is derived from data taken from an example in
Designing Power
& Sail by Arthur Edmunds. The fin keel is not modeled. Pipedream.xml is derived
from data in Skene's Elements of Yacht Design by Francis Kinney. Curiously, the
data for the ends of these boats is not included in the respective tables of offsets; it
was crudely approximated from examination of the lines plan.
|
9. File Menu
This section describes the options on the File Menu.
New: The initial step in creating a new set of lines. It prompts the user for the number of stations, then goes to the Edit function described below. The stations are given arbitrary inital values that can be changed by the user. The station values should be in ascending order, and must be distinct, but need not be equally spaced.
Open: Used to read a data file from the disk. The file dialog displays files with the extensions .xml (boatCalc files) and .hul (Hulls files).
Save: Used to save a data file to disk. If the selected file name has the extension .xml, the data will be changed in boatCalc format. If the extension is .hul, it will be in Hulls format. If neither extension is present, the program will append .xml to the filename and save the data in boatCalc format.
Print: Not yet implemented. I am accepting ideas for the design of printed output.
Exit: Used to end program execution.
10. Edit Menu
This section describes the options on the Edit Menu.
Insert Station & Delete Station: Because the number of stations is basic to the data model, the menu options to change the number of stations are separate from the standard data edit function.
The Insert Station function prompts for input for the new station value. The new station will be entered in the list of stations at the appropriate point. New entries will be created at the appropriate intervals in the other hull lines, also in the appropriate interval, but the points will be invalid (i.e. not in use).
The Delete Station function prompts the user for the number of the station to delete. This is the sequence number assigned by the program, not the station value. The point corresponding to the same station number will be deleted from each hull line.
Edit Data: Used to modify the data of the hull currently being displayed. The Edit Data function displays a tabbed window with separate panes for the stations and for each hull line. Data for each can be displayed by clicking on the desired tab, and data values can be changed directly. There are some controls to prevent bad values from being entered, but they are not exhaustive. Duplicate station values may cause the program to crash!
Along the bottom of the window are buttons for additional features. Design Name and Designer prompt the user for text information used labels. Line Name permits changes to the name of the currently selected line. Insert Line creates a new line displayed at the place in the sequence of the current line. (The sequence does not matter to the calculations.) Add Line creates a new line at the end of the sequence. Delete Line can be used to remove an unwanted line. Apply transfers the current (i.e. changed) data to the main part of the program and cause it to be displayed on the other program windows.
11. Design Menu
Sailplan: This tool is for the design of
sailboat rigs. Provision is made for three sails: main, jib, mizzen. Although the sails are
labeled for convenience, the processing is identical for each. A checkbox labeled 'use'
controls inclusion of each sail in the overall plan. Calculated sail areas and
Center of Area appear in a table.
Basic triangular sails are
defined by the tack location, luff length, mast rake (from vertical), foot length, and foot angle.
The nominal (zero degree) angle for the foot is perpendicular to the mast. (For example, if the mast is raked at
3 degrees, and the foot angle is zero, the foot will be 3 degrees below horizontal.)
A radio button controls whether the boom is to the right or left of the
mast.
For a 4-sided sail, check the box marked 'head' and enter the head length and angle. Head angles
are defined in the same way as foot angles, i.e. in degress above perpendicular from the mast. These angles
are defined in this way so that changing the rake of the mast does not change the shape of the sail.
To include roach on the leech, check the box marked 'roach' and enter the amount of
roach (Max %) and the desired location along the leech. Note that these values are taken as percent
of the leech length. Typical values are 10 for Max%, and 65-75 for height.
Controls on the bottom of the page permit dimensions to be increased or decreased easily. Use the appropriate radio button to determine the value to be changed.
(Label key: X,Z = coordinates, L=length, A=Angle, M=mid-point)
The step size can be selected from a drop-down, or the the desired number may be keyed. Clicking the increment (decrement) button causes the appropriate value to
be increased (decreased) by the step amount. The 'scale' option is an exception. This causes the
luff, boom, and gaff dimensions to changed by the step interpreted as a percentage, thus
preserving sail shape.
Clicking the button marked 'Apply' will cause the design in the tool to be transferred to
the underlying hull. (It will not be saved to disk until the hull is saved.) Clicking 'Close'
will discard the changes and the hull will have the pre-existing sailplan data.
Rudder/Skeg: The Rudder/Skeg tool is similar to
the sailplan tool. It is used to define the shapes and areas of the rudder and/or skeg. The two foils
are labeled for convenience, but the calculations are identical (in this tool).
Each foil is defined as a quadrialteral by four corner points labeled upper left, upper right, etc.
The program does not enforce this orientation, nor rely on it for calculations. The user must be
careful that the "permeter" does not assume an hourglass shape.
Controls on the bottom of the page permit the corner points to be moved easily.
Use the appropriate radio button to determine the value to be changed.
The step size can be selected from a drop-down, or the the desired number may be keyed. Clicking the increment (decrement) button causes the appropriate value to
be increased (decreased) by the step amount. The 'scale' option is an exception. This causes the
foil sides to be changed by the appropriate perent, preserving foil shape,
and keeping the center of the foil in the same place.
Clicking the button marked 'Apply' will cause the design in the tool to be transferred to
the underlying hull. (It will not be saved to disk until the hull is saved.) Clicking 'Close'
will discard the changes and the hull will have the pre-existing sailplan data.
12. Analysis Menu
Displacement: Calculations
of volume, displacement, etc. See the notes
on calculation below. Errors in this section are especially likely for choices
of units other than inches & pounds.
In the upper left are two panes showing the body plan for the left and
right ends of the hull. (They are not marked fore & aft because the hull
lines could show the vessel going in either direction).
The pane in the upper right has several controls, described below.
At the bottom of the window is a tabbed pane display. These computation
panes display data as described below.
The controls are as follows:
- Baseline Offset Slider - sets the vertical offset betweent the waterline and the "zero" point of reference for the hull lines. Moving the slider left and right effectively moves the hull up and down. The slider can be moved by mouse. Once the slider has been selected by clicking, it can be moved using the left/right arrow keys. A single step is either 1/4" for English units or 1cm for metric units. It is easier to get fine control with the arrow keys than with the mouse.
- Angle of Heel Slider - set the angle of heel between
zero and ninety degrees. As programmed, calculations are only valid until
the sheer reaches the waterline. Computation with the sheer below the waterline
are unreliable. This may be improved in the future.
The finest degree of control is 1 degree. The displacement is not adjusted when the angle
of heel is changed. A change in angle of heel will cause a change in displacement.
To adjust for the desired displacement, use the Baseline Offset slider, noting
displacement calculation on the displacment pane.
- "Set Compare" button - used to capture data for
a current setting for comparison to alternates. The purpose is to see how
the Curve of Areas (for example) changes with change in displacement or heel.
- "Set Weights" button - used to enter the weights
and CoG's of the hull, ballast, rig, crew, etc for stability calculation.
See the section on Weights Computation
The computation panes are as follows:
- Displacement - shows the curve of areas and related computations such as displacement, location of the center of buoyancy, prismatic coeffecient. If "Set Compare" is on, the current line is captured and displayed for comparision to other baseline offset and heel settings.
- Waterplane - shows the shape of the waterplane and related computations such as waterplane area, center of area, immersion, waterplane coeffectient, etc. Observes the "Set Capture" button.
- Wetted Surface - shows the distribribution of wetted surface by station, and related values. Oberves "Set Compare" button.
- Weights - displays a tabluar computation of the location of various weights and computed moments. See the section on Weights Computation.
- Station Area - displays the section area calculation at any desired station graphically. The station can be selected using the slider which works in increments of 1% of the waterline (as computed for the current baseline offset and angle of heel). The section area calculation is done using the triangles shown in blue and can be relied on to be the same as used for the displacement calculations. Thus, this pane is a visual check that the calculation is being done as intended, and that the lines correctly represent the desired hull shape. (They also indicate the problems that arise when the angle of heel puts the sheer under water.)
Notes on Weight Calculation. This is a comparison of two views of the weight and flotation of the hull. The first is the displacement of the hull and the associated center of buoyancy from the displacement calculation. The second computation yields the weight and center of gravity of the hull and equipment as computed outside the program based on the construction plan. The data entry screen is activated by the "Set Weights" button. Up to ten items can be entered with weight and the location (in 3 dimensions) of the center of gravity. Note the vertical dimension is on the same coordiante system as the hull lines (i.e. before addition of baseline offset). The first six items have been given suggested labels. These can be changed if desired. Each item entered will be represented by a blue square on one of the body plan panels (depending on station value) in the upper left of the window. The combined center of gravity will be shown as a blue circle. This will be shown on the same body panel as the center of buoyancy even if the station value would put it on the other panel. The horizontal and vertical differences between the center of buoyancy and center of gravity are shown by straight lines.
The same information appears in tabular format on the weights pane. Note that the heeling moment is the product of the weight determined by displacement (which may be different from the weight entered) and the horizontal difference (righting arm) in the locations of the centers.
Various sorts of experimentation are possible. For example, to determine the amount of heel that would result from a crewperson sitting at the sheer, put in the crew weight at the desired height and offset from the centerline. The body plan is a useful guide. Then the sliders can be adjusted until the displacment is correct and the heeling moment is zero.
13. References
Links:
Understanding Yacht Design, by Ted Brewer.
Books:
Edmunds, Arthur, Designing Power & Sail, Bristol Fashion Publications, Enola, PA, 1998
Kinney, Francis S., Skene's Elements of Yacht Design, Dodd, Mead & Company, New York, NY, 1981
Teale, John, How To Design a Boat, Sheridan House, Dobbs Ferry, NY, 1992