Technical Specification - Duncan Harbor · Version 0.90 NavRuleSim Technical Specification Page 4...

Technical Specification

Product: NavRuleSim

Current Revision: 0.90

Date: 1/24/20

Architect: Robert Duncan

Overview:

This document is written primary for the engineer(s) tasked with maintaining or developing

new features for the application. It should be used as the starting point in learning the design

details. This document can also be used to understand the architecture of the application, but

the UML document is probably a better starting point for those wanting to understand the

overall structure without having to spend time understanding the details.

Summary of Specification Topics:

1) Overall Architecture

2) Description of Design Decisions

3) List of Technical Resources in Addition to this Specification

4) Project Development Structure

5) Details on Source Code

6) Characteristics of the Simulator 3D Nautical World

7) Developer Notes

Note: Instructions on how to build the application are located in the “Project Development

Structure” section under the sub-section “Distribution Package Builds”

Version 0.90 NavRuleSim Technical Specification

Overall Architecture:

“NavRuleSim” is built using Java and JavaFX. The application is compiled to bytecode which runs

on the Java Virtual Machine (JVM). JavaFX provides the framework to support the GUI interface

and the 3D representation of the virtual nautical world in which the simulations occur. The

application is delivered as a complete jlink package which includes the “NavRuleSim” bytecode

and the appropriate Java Runtime Environment (JRE) modules to run the bytecode. A “Getting

Started” guide which explains how to install the application is included with the package. An

icon image for use when creating shortcuts to the program is also included.

The application starts with the display a Main Screen which allows the user to choose one of six

screens to which to proceed. The six screens consist of three primary GUIs (Simulator, Learn

and Test) and three support GUIs (Reference, Settings, and Help). The same underlying

structural framework is used for all three primary GUIs. The support GUIs leverage the primary

GUI structure with modifications needed to meet their unique requirements.

The primary GUIs consist of a console on the right side of the screen display. The console

displays text and provides control buttons with which the user manages the GUI display. The

GUI also provides the ability to display 2D images and a 3D nautical world. Animation can be

presented within the 3D world. The control buttons are used to move between the display of

different 2D images and 3D worlds. If animation is supported for the currently displayed 3D

world, a “play” button will appear in front of the world to control the start of animation.

The Simulator GUI is the interface of greatest interest to most users. In addition to the function

already described, the Simulator GUI contains “control icons” within the 3D world. While the

animation is running, the user can use the “control icons” to control the movement of a “first

person” boat within the 3D world. The movement of the “first person” boat within the 3D

world is monitored by simulation management software. The movement of the vessel is

compared against US Coast Guard boat handling requirements. Feedback is provided to the

user. If the “first person” boat violates any boat handling rules, the simulation stops and the

user is informed of the error. Otherwise at the end of the simulation, the user is informed of

the successful completion.

All the information and knowledge needed to successfully complete the simulations is included

within the application. The Learn GUI provides information grouped into lesson topics. To teach

the subject, text, 2D images and 3D images including animation are presented. The user is

informed when sufficient study has been performed to successfully complete testing on a given

group of knowledge. The user would then proceed to the Test GUI in which questions would be

presented in the form of text, 2D images and 3D images including animation. Control buttons

within the console are used to select answers to the questions. Successfully answering all the

test questions unlocks addition simulations covering the tested knowledge. If unsuccessful, a

user may retake the test as often as desired. The user may return to the Learn GUI at any time

and access any lesson topic.


How the text, 2D images, 3D images and animation is presented in the Lesson, Test and

Simulation GUIs is configured using XML files.

The state of “NavRuleSim” is saved in two serialization files, “settings.ser” and

“selectionMenu.ser”. The “settings.ser” file contains how the application has been configured.

For example, if the automatic sail trim checkbox has been selected. The “selectionMenu.ser”

file contains which simulations are available based the user’s successful testing and the use of

the “erase” button which removes simulations. The serialization files are saved when exiting

the application. When the application is started, the state information from the serialization

files is read. This allows the state of the application to persist between usage.


Description of Design Decisions:

First and foremost, “NavRuleSim” was created as a project to demonstrate the ability to design,

develop and manage a software product. Aside from the conclusion that there appears to be a

lack and need for a low-end sailing simulator, market research and customer requirements

were not part of any design decision. A determination of interest in the product will be

determined as part of beta testing. This will occur after a significant portion of the product has

already been developed.

Since the application is a simulator, support for 3D display and animation is a primary

requirement in the selection of the development language and libraries. Also, since the project

is a demonstration and is not expected to generate revenue, low development cost is another

primary factor in the language selection. Java and JavaFX were selected as the development

language and library because they are open source and available without cost. The language

and libraries have been available and used by many different groups for many years. They are

reliable and stable. JavaFX has extensive support for GUI interfaces, 3D display and animation.

In addition, JavaFX is supported by Gluon as part of the company’s business model to provide

the tools by which JavaFX code can be built into executables which run on all major platforms

(Windows, Linux, Mac, IOS and Android). If beta testing indicates there is interest in the

simulator, the Gluon infrastructure provides an existing, supported environment which can be

used to distribute the application on a broad range of devices including tablets.

It should be noted that node js and python were also considered as potential languages and

libraries. Because of node js’ increasing usage in desktop and device applications, the decision

between Java and node js was difficult. Oracle’s decision to drop support of JavaFX and charge

for future versions of Java created an uncertain future adding to the difficulty of the decision.

The final decision was based on Java’s current popularity and the assumption that knowledge

and experience learned while developing with Java would be applicable in more areas than that

which would be acquired working with node js.

Because the product is being used as a demonstration of design and development skills, the

source code is not open source. This ensures the application code is a complete and accurate

representation of the developer’s programming style and skills.

To allow the application to be adaptable, the simulations are defined using XML files. In the

future this could allow the creation of additional simulations by others. It could also be possible

to create new lesson topics should additional information be need to execute newly created

simulations. The application would have to be modified to include a new group called “custom”

simulations. This group would be enabled via the Settings GUI. The creation of additional test

groups will not be supported. All newly created simulations would be contained in the

“custom” group. Separating the custom simulations into different test groups is not practical.

The current testing groups cover the majority of navigation and boat handling knowledge. The


effort to create a generic testing structure for the application would not be justified by the

limited usage. If and when the support is included for “custom” simulations, the user would be

required to ensure they had sufficient knowledge to successfully complete any new custom

simulations added to the application.

To allow the application to be usable on tablet devices (should these devices be supported in

the future), the application is designed to a default display size of a width of 900 pixels and a

height of 450 pixels.

The application is a simple simulator for navigation and boat handling with a primary goal of

being able to be run on many devices. The visual effects are sufficient to clearly display the

movement of vessels in a nautical landscape but nothing more. For example:

• The simulator boat does not “heel” when propelled under sail.

• Anti-aliasing is not used. (This make the edge of objects less smooth but reduces

resource requirements.)

• The size of the spheres defining lights change in abrupt steps to remain visible at long

distances in the 3D nautical world. (Having the lights gradually change size would be

more appealing but would use more resource.)


Additional Technical Resources:

In addition to the source code and this technical specification, the following additional technical

resources exist to support the continued development and maintenance of “NavRuleSim”:

1) “Blue print” UML (Unified Modelling Language) – This is a complete UML description of

the “NavRuleSim” application. The UML document provides a complete layout (aka

“blueprint”) of the application. The UML document can be found at the same location at

which this technical specification was obtained.

2) Power Point Presentations were the source for the 2D images used in lesson, test,

simulation and help sections – The 2D images were created using Power Point.

Screenshots were then taken of the Power Point slide and converted into the GIF

format. Because of the large number of images used in the application, the Power Point

slides are contained in two presentation files. One file contains the lesson and test

image slides. A second file contains simulation and help image slides. The Power Point

document are stored with the application source code.

Note: The source code is well commented. The source code has over 22,000 lines of code.

But it also has over 10,000 lines of comments. A ratio of one comment for every two lines of

code is a good indication that the intent of the coding statements are well explained. This

specification, the UML document and the comments within the source code should be

sufficient to allow anyone maintaining or enhancing “NavRuleSim”, the ability to

understand the programming operations without too much effort.

Note: While not containing technical information, the “NavRuleSim” product specification

may be of value to engineers since it defines what features the application is expected to

support. The product specification can be found at the same location at which is technical

specification was obtained.


Project Development Structure:

Development Environment Setup:

“NavRuleSim” is developed, compiled and built with the netbeans IDE on a Windows 10

operating system using the following directory structure:

• crosscompile – directory of files for creation of non-windows distribution packages

• presentationModule – directory for files which are open and read during run time by the NavRuleSim application. These include presentation XML file and image files using in presentations as well as bitmap used on nautical objected created at runtime and icon which are configured for different screen settings which are defined at runtime

• src – directory for the application source code

• technicaldocs – directory for documents related to but not required for the application build. These documents are included in the build packages.

• .git – directory for git revision control

plus these additional files separate from their own directory:

• nb-configuration.xml – Contains the configuration for netbeans’ java hints (Tools -> options -> editor, then select the Hints tab to see which hints are configured)

• pom.xml – This is the maven configuration file used for build, run and debug

• nbactions.xml – Configures netbeans IDE actions such as run and debug into maven phases.

• .gitignore – configuration file for git revision control

At the time of this writing, the nebean IDE version was 11.

The project references the Java-JDK libraries and the JavaFX-SDK. Maven manages obtaining

these libraries. The Maven pom.xml file defines the build configuration. Some items in the pom

file can be managed using the netbeans GUI pull down (right click the NavRuleSim project and

select properties).

At the time of this writing, the java libraries and jmod are version 11 and the JavaFX libraries

and JMODs are version 13.

The latest JDK can be obtained at https://openjdk.java.net/

The latest JavaFX libraries can be obtained at https://openjfx.io/

NOTE: While “NavRuleSim” is currently being built using the netbeans IDE and the Window 10

operating system, nothing prevents the source code from being compiled, build and packaged

in a different environment. The project configuration would simply have to modified for the

new IDE and OS.

https://openjdk.java.net/

https://openjfx.io/


Code Revision Control:

The git remote repository is managed by Amazon Web Services as part the code commit

services. The remote repository is located in East US 2(Ohio):

https://git-codecommit.us-east-2.amazonaws.com/v1/repos/NavRuleSim

The “.gitignore” file is configured to ignore files created in the “crosscompile” and “target”

directories during package build. The serialization files are also ignored.

Git repository contains tagged which match the product release. Refer to the product

specification for the release history.

IMPORTANT: It is necessary to be logged into AWS at the East2 region to manage the code

commit git repository.

Distribution Package Builds:

Overview:

The creation of distribution packages leverages the jlink tool which is a Java development

feature starting with JDK 9. First, a PowerShell script is run to the build of the windows

distribution package and create the Linux and OSX distribution packages using the Maven

structure. Finally, processes are performed with an editor and compression tools. First, the end

of line (EOL) characters in text files which are processed under Windows are converted from

the Windows defaults to the Linux/OSX defaults. Second, each of the distribution package

directories are compressed into a compact folder for easy download and distribution.

The packages are created with the debugging symbols removed.


Create Icon Files:

These steps only need to be performed if the NavRuleSim icon is changed:

OSX uses a special file structure to define icons. The following steps are used to create the file.

1) Create 7 icon png bit maps files with the following pixel resolutions.

1024 x 1024

512 x 512

256 x 256

128 x 128

64 x 64

32 x 32

16 x 16

The icon bit maps should have a transparent background

2) Save the 7 bitmaps as 10 files with the following names in a folder named

“navrulesim.iconset”:

File in “navrulesim.iconset” folder Original bit map

[email protected] 1024 x 1024

icon_512x512.png 512 x 512


icon_256x256.png 256 x 256


icon_128x128.png 128 x 128


icon_32x32.png 32 x 32


icon_16x16.png 16 x 16

3) Download the folder onto the desktop of a Mac system with OSX

Select the folder and press the spacebar to inspect the bitmap files

4) Open a terminal and use the following command to create the navrulesim.icns file:

iconutils -c icns ~/Desktop/navrulesim.iconset

5) Place the navrulesim.icns file in the “technicaldocs” directory in the NavRuleSim project.

Windows and Linux use an ico file.

1) Create a NavRuleSim icon using a 48x48 pixel gif bitmap

2) Use the following Website to convert the gif bitmap into an ico file for Windows 10 http://icoconvert.com/

http://icoconvert.com/


Windows Preliminary Distribution Package Creation:

1) The PowerShell script uses Maven commands to create a preliminary Windows package

at the following location

PROJECT DIRECTORY> NavRuleSim > target > NavRuleSim

2) Additional steps are then performed to complete the Windows distribution package:

a. The presentionModules directory tree containing the presentation module XML

configuration files and images used by the presentation modules must be added

to the package.

b. The batch file which starts Java with the “NavRuleSim” jar is modified to

minimize the command prompt window while “NavRuleSim” is running. Below is

a initial batch file with the modifications in blue:

@echo off

if not DEFINED IS_MINIMIZED set IS_MINIMIZED=1 && start "" /min

"%~dpnx0" %* && exit

set JLINK_VM_OPTIONS=

set DIR=%~dp0

"%DIR%\bin\java" %JLINK_VM_OPTIONS% -m

org.duncanharbor.navrulesim/org.duncanharbor.navrulesim.NavRuleSi

m %*

exit

c. A “Getting Started Guide” pdf file and icon file are added to the package.

d. The release file with build version information is deleted from the package.

(Version control is contained within the application and the “Getting Started

Guide”. The release is not needed. It existence will simply confuse the user.)

These additional steps are performed as part of the same PowerShell script which builds

the distribution packages for the Linux and OSX operating systems.


Linux and OSX Distribution Package Creation:

The creation of the Linux and OSX packages by the Powershell script leverages the “jmod” and

“jlink” executable available in the Java JDK.

The script assumes the following directory structure exists: NavRuleSim target NavRuleSim – Windows distribution package NavRuleSim-0.9.jar Jar File – Windows Jar file needed for Linux and OSX creation crosscompile linux jlink – contains the Linux distribution package modules – contains modules for Linux JRE osx jlink – contains the OSX distribution package modules – contains modules for OSX JRE

Create_Dist_Packages.ps1 – Powershell script The NavRuleSim/linux/modules and NavRuleSim/osx/modules directories contain all the modules needed to support the JRE for the NavRuleSim application for the Linux and OSX operating systems. The navrulesim build requires the following modules (Note: these are listed in the project’s module-info.java file): Java: java.base.jmod java.logging.jmod java.xml.jmod JavaFX: javafx.base.jmod javafx.controls.jmod javafx.fxml.jmod javafx.graphics.jmod The Java modules above require the additional Java modules: java.datatransfer.jmod java.desktop.jmod java.prefs.jmod java.scripting.jmod jdk.unsupported.jmod These jmod modules can be obtained at the following sites: Java: https://openjdk.java.net/ JavaFX: https://openjfx.io/ Note: The command "jmod describe <jmod module>" can be used to determine what other modules a given module requires.

https://openjdk.java.net/

https://openjfx.io/


As an example, given that the “NavRuleSim” application is built from jdk-11 and java sdk-13

library for Windows, the version 11 java jmods and version 13 javafx mods would be obtained

for Linux and OSX. The jmod directory within each of the libraries would contain the modules

for the given operating system. The appropriate modules would be copied into the appropriate

directories in the structure defined above.

IMPORTANT: Should any of the Java libraries being used to build the “NavRuleSim” application

be updated. ALL of the libraries and modules must be updated. The Windows Java JDK and

Linux/OSX jmods must be of the same version, the Windows JavaFX SDK and Linux/OSX mods

must be of the same version. JAVA_HOME environment variable must also match the JDK.

Note: The following command can be used to obtain information about a given module:

jmod describe <name of jmod module for example java.base.jmod>

Important Note:

The PowerShell script in the “crosscompile” directory is under revision control.

The Java and JavaFX libraries used by netbeans are provided by the Maven build structure. BUT

the Linux and OSX modules are not under revision control. If the project is downloaded from

Git, as part of configuring the project, the appropriate modules would have to be placed into

the “crosscompile” subdirectories.

The following steps are taken to run the PowerShell script to finalize the Windows package and

create the Linux and OSX packages:

1) Open a PowerShell terminal

2) Go to the NavRuleSim/crosscompile directory

3) Verify that PowerShell is enabled to execute scripts using the following command:

Get-ExecutionPolicy

4) If not, set the policy to RemoteSigned using the following command:

Set-ExecutionPolicy RemoteSigned

5) Execute the PowerShell script with the following command:

Create_Distribution_Packages.ps1

6) The “NavRuleSim” distribution directories will be created in linux/target and osx/target

directories.

Note: the script is well commented. It can be reviewed to determine the exact steps

which are taken to create the packages


IMPORTANT NOTE: Additional steps which cannot be easily performed via the

PowerShell script need to be performed to complete the distribution package build.

a) When Windows writes files, the EOL (End of Line) characters are both a carriage

return and line feed. The Linux and OSX environments expect only a linefeed. This

conversion must be performed.

b) The distribution package for each Operating System needs to be compressed into a

distribution folder for easy download.

Final Steps to Create the Compressed Distribution Folders:

1) Convert EOL characters

For linux/target/NavRuleSim/Start-NavRuleSim file

Using notepad++ convert characters and save file

Select Edit -> EOL Conversion -> Unix (LF)

Repeat for osx/target/NavRuleSim/Start-NavRuleSim file

2) Compress directories

a. For ../target/NavRuleSim

Right click on NavRuleSim directory

Select Send to -> Compressed (zipped) folder

Rename the new compressed folder NavRuleSim-Windows.zip

b. For linux/target/NavRuleSim

Open the 7-Zip File Manager application

Select the NavRuleSim directory

Select Add (The green plus sign symbol at top of application)

Select tar from the Archive format: pull down menu

Select okay

Select the tar file which was created

Select Add (The green plus sign symbol at top of application)

Select gzip from the Archive format: pull down menu

Select okay

Rename the new compressed folder NavRuleSim-Linux.tar.gz

Delete the intermediate tar file which was created

c. For osx/target/NavRuleSim

Repeat the above procedures for linux/jlink/NavRuleSim with the

following variations:

Use osx/jlink/NavRuleSim instead of linux/jlink/NavRuleSim

Rename the new compressed folder NavRuleSim-OSX.tar.gz


Details on Source Code

Overview:

This technical specification is NOT intended to explain in detail the entire “NavRuleSim”

architecture. Instead this specification is designed to provide the background information

needed to understand the application design so that the “blueprint” UML and comments within

the specific sections of code can be used to determine the exact details of operation.

Nomenclature:

Below is a summary of the application architecture with focus on the terminology used to

describe the application. When an important term first appears in the summary, it will be

highlighted with bold italic text.

“NavRuleSim” leverages JavaFX also known as openJFX. It is a set of open sourced Java

modules and SDKs to support applications on desktop and mobile devices. The company Gluon

is very involved in the development of JavaFX. Gluon provides tools and services which allow

Java code using JavaFX to be built to operate on many different devices. The “NavRuleSim”

application manages the appearance of content. JavaFX manages the display of content.

“NavRuleSim” is an application which simulates the interaction between vessels according to

the United States Coast Guard Navigation Rules also known as USCG colregs (an abbreviation

for United States Coast Guard Collision Regulations). In addition to being a simulator, the

application contains sections in which to learn and test oneself about the knowledge on

collision regulations needed to successfully complete the simulations. The application also has a

settings section which is used to configure the operation of the application.

The application begins execution with the main screen. From the main screen, the user may

proceed to one of six user screens. These user screens are the simulator screen, learn screen,

test screen, reference screen, settings screen and help screen. For each user screen, the GUI

layout is defined by an fxml file and user interaction with the screen is managed by a screen

controller.

The simulator, learn and test user screens are the primary user screens. These screens present

information to the user using the same structural framework. The framework displays the

contents of a presentation module. Presentation module manages the display of the following:

1) text

2) 2D images

3) 3D nautical worlds

4) animated movement of nautical objects within the 3D worlds


The information displayed in the presentation module is configured using an XML file. The

module definition generator reads the XML elements defining presentation configurations in

the XML file and converts them into a list of Java definition classes which define presentation

modules. The module presentation generator converts the definition classes into presentation

modules which can be loaded into the primary user screens for display. The display of the

presentation modules within the user screens is managed by the presentation manager.

A set of lesson presentation modules on a single subject (for example, nautical terminology) are

called a lesson topic. The lesson topics are presented to the user in the learn screen as different

sections. Each lesson topic is its own section. The user selects the different lesson sections from

a pull-down menu. If a lesson section is selected, the learn screen pull down menu is updated

with a list of presentation modules for that lesson topic. The user can use the previous and next

buttons to step through the modules in a lesson topic. After the recommended, related lesson

topics have been reviewed, the user is informed that sufficient knowledge has been acquired to

pass the next test group. Successfully answering all the question in a test group enables access

to a set of simulations associated with the test group.

Simulations are designed and grouped to cover a specific area of boat handling knowledge.

There is a one to one correspondence with a set of simulations and its associated test group.

Test groups are presented to the user in a defined order. A test group consists of presentation

modules which test knowledge on a specific boat handling subject. Each presentation module

defines one question. Answering all the presentation module questions correctly enables access

to the associated simulation set and allows access to the next test group. The user can proceed

with testing in the next test group or return to the test screen and perform testing at a later

time.

In the simulation screen, the motion of the “first person” boat during 3D animation is

controlled by the user. The “first person” boat does not exist as an object within the source

code structure, it is a visual effect. The user is lead to believe they are in a boat as they look out

at the 3D nautical world. To allow the maximum amount of visibility into the 3D nautical world,

a separate control pane exists. Similar to the other primary screens, the pane is on the right

side of the application window. The control pane GUI layout is defined with an fxml file and a

controller is used to manage the control icons located in the pane. But the control pane GUI is

not visible when a simulation is running. The control pane GUI is visible when the simulation is

not running. The control pane GUI is used to manage the selection of the simulations.

Presentation modules are used to display and manage the simulation animation. While the

simulation is running, a simulation manager monitors how the user controls the “first person”

boat. If any boat handling rules are violated, the simulation ends with an error being displayed

in the control pane.

The object toggle is a control icon which is used to toggle the display of the 2D image / nautical

chart and the timer (a.k.a stopwatch). Depending on whether the feature is displayed or not


displayed, the object toggle button will display a different icon and label. The different icons

and labels indicate whether selecting the button will make the feature visible or invisible.

The timer pane GUI provides a stop watch feature. Just like the control pane, the timer pane is

defined with an fxml file and a controller.

The root user screen defines the window into which the user screens are placed. The overall

pane defines the size of the screen GUI. Within the screen GUI on the right side are the

following items: combobox (pulldown menu), toggle button, next button and previous button.

These items are used to control the selection of presentation modules. On the right side of the

screen GUI is also located a text area in which the text component of a presentation module is

displayed. On the left side of the screen GUI is the display pane. The display pane contains the

“first person” pane, upper boundary pane and lower boundary pane. The width to height ratio

of the “first person” pane remains fixed. The width in pixels of the area on the right for the

control items also remains constant. If the overall pane size changes, the width to the right will

remain unchanged, the display pane width will change in size to accommodate the change in

size of the overall pane. The width of the “first person” pane will adjust to match the display

pane. The height of the “first person” pane will adjust to maintain the fixed ratio. If the height

of the display pane is greater than the height of the “first person” pane, the upper and lower

boundary panes will adjust in size to create equal areas of a grey background color above and

below the “first person” pane. The “first person” pane “looks” into a nautical world subscene.

What is visible of the 3D nautical world through the “first person” pane is dependent upon the

“first person”. The first person is an object which exist within the 3D nautical world. It consists

of a camera and light. As the “first person” moves and changes direction within the 3D world,

the view from the “first person” pane also changes accordingly.

The image viewer, centering pane and “first person” window exist within the “first person”

pane. The image viewer is used to display the 2D images such as diagrams to explain concepts

or nautical charts. The centering pane is used to position items such as the image viewer and

animation play button in the center of the “first person” pane. The “first person” window

contains the “first person” vessel which is a group of overlays. The combination of the “first

person” object in the 3D world and the “first person” vessel overlay is what the user perceives

as the “first person” boat.

The “first person” vessel overlay is a group of 2D representations of components of the “first

person” boat on which the user is perceives to be located and through which the 3D world is

observed. Each overlay represents different components of the boat. For example, one overlay

will display the boat itself and another overlay will display the boat’s sails. As the “first person”

virtual boat moves in the 3D virtual world, the display of the components which are part of an

overlay will change. For example, the display of the sails will change as the boat moves in

relation to the virtual wind. An overlay manager manages the display of overlays.


The available simulations are all the simulations from the enabled groups which have been

selected. Enabled groups are typically the result of successful testing, but it is possible to enable

all the groups via the settings screen. The active simulations are the available simulations with

the erased simulations removed. Simulations are typically erased using the erase button in the

simulator control pane. It is also possible to erase simulations via the settings user screen.

The order the active simulations are presented is defined by the presentation mode. The

presentation mode can be either random or playlist. Playlists are created via the setting user

screen. The active simulations are stored as the selection menu list. The selection menu list is

used to create playlists. The user selects simulations from the selection menu list and places

them into the playlist.

The application settings, selection menu list and playlist are saved in serialization files. The

contents of the serialization files are read when the application is started. Simulations which

were obtained via successful testing will be available when the application is used at a later

time.

When the simulation is run, the simulation manager monitors the movement of the “first

person” virtual boat for conformance to USCG colregs. When the simulation has been

successfully completed or the simulation is terminated because of a USCG colregs violation, an

end condition is displayed. An end condition defines the reason the simulation was terminated.

For the most part, vessels in the 3D nautical world conform to the USCG colregs. One exception

is vessels which are “locked on course”. These vessels will not deviate from their course even if

this means violating USCG colregs.

Vessels which are “hunting” will modify their speed so they will collide with any vessel on an

intersecting course.

Application Start and Termination:

JavaFX is used to display the application GUI. The NavRuleSim class is the entry point for the

application. The NavRuleSim class creates a “stage” into which the “scene” is placed. “Stage”

and “scene” are JavaFX nomenclature. The “stage” is the window in which the “NavRuleSim”

application resides. The “scene” is the pane in which the user screens reside.

When the application is started, the serialization files are read to determine the state of the

application when it was last terminated. If the serialization files do not exist, the applications

settings are reset to the initial defaults.

Next a root user screen is constructed. When this class object is constructed, the main screen

GUI is created and stored in memory as part of the root user screen object. Since the main user

screen is always in memory, it can be quickly loaded when returning back to the main screen


from other user screens. The simply layout of the main screen and its central point in the

movement between screens means that its appropriate to be constantly stored in memory.

The main screen is loaded into the root user screen.

When the main screen is initialized, a check on the system on which the application running to

determine if the JavaFX 3D feature can be supported. If the system cannot support the feature,

a warning is displayed and all buttons on the main screen are disabled with the exception of the

quit button.

The “NavRuleSim” application creates a “scene” consisting of the root user screen. The root

user screen is an anchor pane. This means the sides of the root user screen are “attached” to

the sides of the application window. When a user screen in loaded into the root user screen,

the loaded screens sides are “attached” to the root user screens sides. As a result of these

“attachments”, when the window size is changed, the displayed user screen size is adjusted

accordingly. Following the creation of the “scene”, the application creates the “stage” which

contains the “scene”.

When the main screen is loaded into the root user screen, the main screen controller is linked

with the main screen. The main screen controller manages the transition to the display of the

different user screens when the appropriate button is selected on the main screen.

When the application is terminated either by selecting the quit icon on the main screen or

selecting the close button on the application window, the current application settings and

simulation list is written and stored in the serialization files.

Settings:

All the settings which are used to configure the application are stored as static values in the

settings class. The settings are

1) values which can be modified by the user via the settings screen

2) values which are indirectly modified by the screen controllers as results of user actions

3) constant values which define the build and operation of the application. The constant

values are set directly in the settings class file by the developer and do not change once

the application has been built.

User Screens:

There are seven screens in the “NavRuleSim” application. The main screen and six user screens.

For all screens, the layout of the screen GUI is defined with fxml configuration files. For each

screen there are two configuration files, one which defines a medium layout for a screen of 900


X 450 pixels, and another which defines a large layout for a screen of 1200 X 600 pixels. The

application is designed primarily for the medium layout to allow the application to be useable

on tablets with medium sized display screens as well as laptops with large sized display screens.

On large screens, the application with the medium layout can be run in a 900 X 450 pixels

window within the display or maximized to fill the entire screen. The large layout configuration

builds an application with a large text font. The large fonts improve readability for those having

difficulty seeing small text or when the application used on a projection screen. The large text

font results in large text boxes. The application with the large configuration will not fit into a

medium display. Therefore, the default is the medium layout configuration. This allows the

application to be used on both medium and large displays. The initial window size is defined by

the layout setting. The application will start in a window at the initial screen size, but the pixel

size of the application window can be changed using the standard system GUI controls, the GUI

layout will adjust to the different pixel sized window. This is possible, because the overall pane

in each screen is an anchor pane whose edges are “attached” to the sides of the root user

screen when the user screen is loaded into the root user screen. As the window changes size,

the overall pane, display pane, upper boundary pane and lower boundary pane change size

accordingly.

The transition to different user screens always occurs from the main screen. To transition from

one user screen to another, it is necessary to return to the main screen. The buttons on the

main screen execute the “goToScreen” method with a user screen configuration appropriate for

the labelling of the given button.

The “goToScreen” method uses root user screen class “create” and “load” methods which

leverage the JavaFX “FXMLLoader”. The fxml configuration file defines a graph of GUI objects

and the controller to manage the GUI objects. When the “create” method is called, the

“FXMLLoader” creates the graph as defined by the fxml file and then constructs and initializes

the controller to manage the GUI objects defined by the graph. The “load” method places the

graph of GUI objects into the root user screen pane. To ensure the GUI buttons remain

responsive, the transition to a new user screen is performed on a separate thread as a

background process.

CSS (Cascading Style Sheets)

Cascading style sheets (CSS) are used to define the appearance of the user screens. The CSS

files are located in the settings sub-directory under the presentationModules directory. There

are two files. One file defines the appearance for the medium screen layout, the other defines

the appearance for the large screen layout. The files are named “navrulesim.css” and

“navrulesimLarge.css”. The use of the CSS files is defined in each of the the fxml files.

Separate CSS files are each of the operating systems. The css files for windows exist in the

presentationModules directory by default. The other operating system css files exist in the css


sub-directory under the crosscompile directory. When packages are built for Linux and OS X,

the default Windows CSS files are deleted and the css files are moved into the settings sub-

directory under the presentationModule directory as part of the PowerShell script which builds

the packages.

The css files are added to the JavaFX scene when the application is first started.

Primary User Screens (Learn, Test, Simulator):

The learn, test and simulator user screens are collectively referred to as the primary user

screens. The primary user screens have the same structural framework. When the screen

controller is constructed, information relevant to the screen is read from configuration files.

Examples of this information is the bit maps for icons or the contents of pulldown menus

managed by the controller.

Most of the GUI objects in the user screen are defined by the fxml configuration file and

managed by the JavaFX methods. These are object such as buttons whose location remains

unchanged and whose appearance varies in standardized patterns. The remaining GUI objects

whose appearance or placement varies in non-standard ways are created during initialization of

the controller.

For the screen controller to manage a user screen, it is necessary to be able to access the

properties of GUI objects which were defined in the fxml file for the given user screen. For

example, to ensure the “first person” vessel is being displayed correctly, the screen controller

needs to know the size of the first person display in which the “first person” vessel is displayed.

This link is performed with the @FXML annotation.

During screen control initialization the following occurs:

1) A subscene is create to contain the 3D nautical world.

2) The “first person” pane width and height are bounded to each other to maintain a

constant ratio. This allows the perspective of the 3D world to remain accurate when the

size of the window is changed.

3) The display of the 3D nautical world is shift in relationship to the “first person” pane.

This is to allow more ocean and less sky to be observed. Since the 3D nautical world is

no longer vertically centered with the “first person” pane, it is necessary to “mask” the

sky which should not be displayed with a border rectangle. This border rectangle is the

same color as the upper and lower boundary panes. Since the mask matches the

boundary panes, the 3D nautical world appears centered in the “first person” pane.

Note: The height of the lower boundary pane is equal to the height of the upper

boundary pane PLUS the height of the upper boundary pane.

4) The nautical subscene, first person window, centering pane and border rectangle are

added to the “first person” pane.


5) A play button is placed over the 3D nautical world and made invisible. (Note: If

animation is supported in the 3D world, the button will be made visible at a later time.)

6) An image viewer for images and nautical charts is created and added to the “first

person” pane.

7) The text area is configured.

8) The “first person” vessel is created and added to the “first person” window.

9) The image toggle is created.

10) The overlay manager is created.

11) The presentation manager is created.

12) The module presentation generator is created.

13) The presentation modules are loaded. This procedure varies between the different

primary user screens. More information will be provided in the “Management of

Presentation Modules” section.

14) At this point, user interaction with controls objects will define what is displayed in the

user screen.

The return icon is selected to transition from one user screen to another user screen. Prior to

exiting, the user screen will perform housekeeping to terminate any background processes

which may be running and remove any listeners which are no longer needed. Once the

housekeeping is complete, the main screen which exists in memory is loaded into the root user

screen. From the main screen, the appropriate button can be selected to transition to the

desired new user screen.

Help User Screen:

The structure of the help user screen is similar to primary user screen structure which have

already been described but only text and 2D images are displayed. Similar to the learn user

screen, the help images are grouped into topics. But unlike the learn user screen, the

information is NOT configured in XML files which are converted to presentation modules.

Instead the information is defined within the help user screen controller. The help information

is directly related with the application source code and does not need to be configured with

separate files. The information can be contained in the source code screen controller file.

Settings User Screen:

The settings user screen consists of control objects such as buttons, radio buttons, checkboxes,

and pulldown menus to manipulate the application settings. The entire GUI layout is configured

with the graph defined by an fxml configuration file. The settings user screen controller simply

manages the JavaFX control object in the screen. Similar to the primary user screens, the


control objects defined by the fxml file are linked to the controller using @FXML annotations.

During initialization, the control objects are set to match the settings data which was read from

the serialization files when the application was started. For most of the control object, this is

done by simply setting the control object value to match the static setting value read from the

serialization file. When the settings screen is constructed, all the setting values are set to their

default values. The application reads the saved settings values from the serialization file and

updates the settings with the stored values. If the settings serialization file does not exist, the

setting will remain at their default values. Therefore, settings values at which to initialize the

control objects always exist.

The selection menu is a list of available simulations. Management of this list is a little

complicated. The selection state of the checkboxes which define what simulation groups can

be accessed is called the simulation group setting. The management of the selection menu is

tightly associated with the simulation group setting and the selection state of the “Under Power

Only” checkbox.

A checkbox for a simulation set / test group can be “enabled” or “not enabled”. If a checkbox is

enabled, its state can be selected/not selected. Simulation group checkboxes become enabled

as a result of successful testing for that group. In addition, by selecting the “Enable All Groups”

checkbox, it is possible to override this test process and enable the not enabled simulation

group checkboxes.

The following states are used to manage the simulation group checkboxes. Unselected

checkboxes can be NOT_ENABLED, ENABLED or OVERRIDE_ENABLED. Enabled simulation

groups checkboxes which are then selected can be SELECTED or OVERRIDE_SELECTED

depending on their enabled state prior to being selected.

• NOT_ENABLED checkboxes are displayed with greyed-out test and the box is not

checked

• ENABLED checkboxes are displayed with dark text and the box is not checked

• SELECTED checkboxes are displayed with dark text and the box is checked

• When the “Enable All Groups” checkbox is selected:

o OVERRIDE_ENABLED checkboxes are displayed with dark text and the box is not

checked

o OVERRIDE_SELECTED checkboxes are displayed with dark text and the box is

checked

• When the “Enable All Groups” checkbox is not selected:

o Both OVERRIDE_ENABLED and OVERRIDE_SELECTED are converted to a state of

NOT_ENABLED.

The selection menu is dependent on the simulation group setting and the selection of the

“Under Power Only” checkbox. If the “Under Power Only” checkbox is selected, the selection

menu will only contain simulations in which the “first person” boat is propelled under power. If


the “Under Power Only” is not selected, simulations may include a “first person” boat propelled

under power or under sail. The selection menu contains the simulations from the selected

simulations groups.

In addition to being grouped according to boating knowledge. Simulations are also grouped

according to whether the “first person” boat is under power or under sail.

Because the simulations in the selection menu is closely associated with the simulation group

setting and “Under Power Only” setting. The state of these checkboxes is saved when the

selection menu is saved. (The state of the simulation group setting is saved as a hash code.)

When the selection menu is initialized, the current state of simulation group settings and

“Under Power Only” is checked. If the current state is different from the state in which the

selection menu was saved, the selection menu is updated to reflect the current state.

If a user no longer wishes to run a simulation, the user may erase it. The erased simulation set

contains all the simulations which have been erased.

The active list is all the simulations in the selection menu excluding the simulations in the

erased simulation set. The list of available simulations is also called the selection menu because

this is the list of simulations which appears in the selection menu in the settings user screen.

Erased simulations appear greyed-out in the pulldown menu list.

Reference User Screen:

The reference user screen does not display presentation modules, the screen only displays

nautical vessels. Its structural framework is different from that of the primary user screens.

The only commonality is the 3D nautical world in the overall pane, display pane, first person

pane, upper boundary pane and lower boundary pane use the same framework as the primary

user screens.

The reference user screen only displays one nautical vessel at any given time. Instead of being

configured by a presentation module and corresponding XML file, the selection and display of

the vessel is defined by the user using pulldown menus, radio buttons and checkboxes in the

reference user screen GUI.


Buffer for Presentation Modules:

The performance settings define the size of two array lists which are used as buffers in the

creation of presentation modules before they are loaded into the 3D subscene for display. The

first buffer / array list is the module definitions list. The second buffer / array list is the module

presentation list.

The buffers allow module presentation to be created in advance and be quickly loaded. The

module definition list contains definitions of presentation modules referencing JavaFX

structure. The presentation module list contains the presentations built from the JavaFX

objects. The presentation modules require much more memory than the definitions, therefore,

the size of the presentation list is always smaller than the size of the definition list.

The performance setting defines the size of the module presentation list. It also defines the size

of the module definition list used by the simulator. The size of the module definition list for the

learn and test screen is not controlled by the performance setting.

The definitions for the module presentations displayed by the simulator will vary depending on

which simulations the user has enabled and erased. Therefore, it is necessary to create the

simulation definition list one simulation at a time based on the selection list or playlist. Creating

the definition list may require opening several configuration files.

The definitions for the presentation modules used by the Lesson and test screen do not vary. To

optimize reading of definitions from the configuration files, the XML file which defines the

lessons or test is opened once and all the module definitions in the file are placed into the

module definition list.

The difference in the creation of the definition list between the simulation user screen means

that it is practical to vary the size of the module definition list and well as the module

presentation list.

The typical module presentations used for lessons and tests is much simpler than a typical

module presentation used for a simulation. Low memory is more of a concern for the simulator

user screen. Hence the learn and test user screens can have a larger definition list to optimize

the reads of the XML configuration files.

Management of Presentation Modules:

Presentation modules define what is presented in the primary user screens. They are not

related to Java modules in any way and should not be confused with Java Modules.

The presentation modules are defined using XML files. The XML configuration files are stored in

a directory separate from the source code. The directory is called “presentationModules”.


Within this directory are the XML configuration files along with the 2D images which are used

by the presentation modules. Separate sub-directories exist for the XML files used by the Learn,

Test and Simulator user screens. The sub-directories are “lessons”, “tests” and “simulations”.

The 2D images which are shared by the lesson and test presentation modules are located in a

sub-directory called “images”. The 2D images used by the simulation presentation modules are

in a separate “images” sub-directory which exists within the “simulations” sub-directory. The

2D images used in the help user screen are in a sub-directory called “help”. The serialization

files which store the state of the application are stored in the “presentationModule” directory

in a sub-directory called “settings”. The icons images which are placed into the GUI screens by

the JavaFX fxml configuration files are also located in the “presentationModule” directory in the

sub-directory “icons”.

The names of the XML configuration files used to define lesson and test presentation modules

begin with the prefix “SectionDef_”. The names of the XML configuration files used to define

simulation presentation modules begin with the prefix “SimDef_Power_” when the simulation

includes a “first person” vessel propelled by power or the prefix “SimDef_Sail_” when the

simulation includes a “first person” vessel propelled by sail.

The presentation definition generator converts a module defined by elements in an XML

configuration file into a module definition based on Java variables and java class structures. A

module presentation generator then creates a presentation module based on the module

definition.

A Java based presentation module definition contains the following:

1) Module Type Definition (How the module is presented to the User. For example, is the

module part of a lesson, test, simulation and how controls are configured accordingly.)

2) Definition of “First Person” Conditions (How the user observes and interacts with the

virtual 3D nautical world.)

3) List of terrestrial objects in the 3D nautical world

4) List of nautical objects in the 3D nautical world

5) List of animation events (How nautical objects will appear to move within the virtual 3D

nautical world.)

6) List of regions (Areas on the ocean surface in the 3D world which have significance if

occupied by moveable nautical objects.)

The presentation definition generator is created when a primary user screen is constructed. The

definition generator contains static methods which are called to create the module definitions.

The presentation module generator is created when the primary user screen is initialized.

Different variations of the presentation module generator are created for the different primary

user screens. For example, the presentation modules in the test user screen require control by

answer buttons were as presentation modules in the simulator may require control by the


motor throttle position. Different presentation module generators are created to handle these

different primary user screen control conditions.

The module definitions are stored in an array named “modulesDefinitionList”. The presentation

modules are stored in an array named “modulePresentations”. How the Java based definitions

and presentation modules are created and placed in these arrays is different for each of the

primary user screens.

Learn User Screen:

Each XML configuration file in the “lessons” sub-directory defines a section of related lesson

presentation modules on a given topic. The file also contains a description of the section topic

and the dependencies for the section. A dependency is what knowledge from other lesson

sections is required to be able to successfully understand the lessons defined in XML file. The

first time the learn user screen is initialized, two maps are created. One to link the section titles

to the XML file names and another two the section descriptions to the XML file names. The

dependencies of all the files are compared and an order list is created so that the other sections

upon which each section is dependent appear in the list before the section. Static methods

from the module definition generator are used to perform this task. The ordered list is called

the topics title list. The topics title list and maps are then saved in a serialized file which is

stored in the “lesson” sub-directory. Every time the learn user screen is create, the topics title

list and maps are read from the serialized file. The list and maps are compared with the current

XML files in the “lessons” sub-directory. If the lists and maps do not match the information in

the XML files, they are regenerated. Since the lesson XML configuration files rarely change, this

saves the time of creating the topics list every time the learn user create is created.

This structure exists to allow custom lessons to be created to support custom simulations.

Currently, “NavRuleSim” does not support custom user created simulations, but the framework

is designed to allow support for this feature in the future.

The serialized file is created when the application is tested and not removed when the

distribution packages are built. Therefore the maps exist in the distribution and rarely need to

be created again.

When the learn user screen is initialized, the topics title list is loaded into a pulldown menu on

the learn user screen, when the user selects a given topic from the menu, the XML

configuration file mapped to that title is used by the presentation definition generator to create

the list of definitions. The presentation module generator then uses the definition list to create

all the modules which will be displayed as part of that section.


Test User Screen:

The groups into which simulations are sorted is defined in the settings class. The test user

screen contains a test groups list defining the order in which knowledge to access groups of

simulations will be tested. The order of the list is defined in source code and matches

information displayed on images that are part of the test user screen. This order should not be

changed. For each group, there is an XML file which defines the questions which need to be

answered to successfully run the simulations within the group. The file also contains a

description of knowledge which will be tested as part of this group. When the test user screen

is initialized, two lookup tables are created. One table to link the group titles to the XML file

names and another table to link the group descriptions to the XML file names. Since the entire

list of test groups is known, the lookup tables can be constructed quickly. There is no need to

save the tables in a serialization file. The resource to manage the file is greater than that

required to create the lookup tables.

When the test user screen is initialized, the current test group index is obtained from the

settings. This index defines which test group in the test group list is currently queued for

testing. The title of the group is used to determine which XML file in the “tests” sub-directory

should be used by the presentation definition generator to create the list of definitions for the

presentation modules. The presentation module generator then uses the definition list to

create all the modules which will be displayed as part of testing knowledge on that group.

Simulator User Screen:

How the presentation modules are managed depends on the setting for presentation mode.

When the simulator user screen in initialized, a list of active simulations is obtained by making a

call to the “getActiveList” method in the static “SelectionMenu” sub-class within the

“ScreenControllerSettings” class. The active simulations consist of the set of available

simulations from which the erased simulations have been removed. While the user is in the

simulator, a temporary set is created. Any simulations which are erased while in the simulator

are stored in both the settings class “erasedSimulations” set and the temporary set. Since the

list of active simulations is only obtained upon initialization, it is necessary to use the temporary

set to remove simulations which are erased during the simulator session from the available list.

If the presentation mode is set to playlist, the simulations will be presented in the order as

listed in the simulator playlist pulldown menu on the settings user screen. The simulation at the

top of the list will be presented, first followed by the subsequent simulations in the list. Note:

the top most item in the playlist pulldown menu is not a simulation. It is a “All Simulations”

string. It is used to remove all the simulations from the playlist.

The application defaults to playlist mode with a preset playlist consisting “getting started”

simulations designed to teach the fundamental skills need to operate the simulator boat.


If the presentation mode is set to random, all the active simulations will be displayed in a

random order. The active simulations are the simulations which are listed in the selection menu

pull down menu that are not greyed out.

When testing is successfully completed on a simulation group. The presentation mode is set to

random and access to the group is enabled and selected. For the first group of simulations, this

behavior is required. The “getting started” simulations have been presented in the order

defined in the playlist. This is required because the skills build upon each other. Once testing

has been completed, the focus is on simulations from the first group. The “getting started”

simulations are no longer presented and the simulations related to “basic conduct” need to be

presented in a random order. The presentation mode is changed from playlist to random. The

playlist of “Getting Started” simulations remains unchanged but is not used.

The user steps through the available simulations using the “next” and “previous” button in the

simulator user screen. The user can also mark simulations as erased using the “erase” button.

When all simulations in a group have been erased, the simulation group is deselected and the

simulations in that group are no longer available. The simulation group remains enabled should

the user wish to access the simulations in the future via the settings screen.

The user can change the content of the playlist, the selected simulations and the presentation

mode at any time via the settings user screen. Refer the section on the settings screen for

further details.

If the presentation mode is set as playlist, for each title in the playlist, the title is used to

determine the XML configuration from which the presentation module definition is created and

placed in the module definition list array. The presentation module generator then uses the

definition list to create all the modules which are placed in the presentation modules array. The

modules are placed in the array in the same order as which they are defined in the playlist. The

display of modules is controlled by the “next” button. When the end of the presentation

modules is reached, display repeats from the top of the list.

If the presentation mode is set as random, upon initialization of the simulator user screen, the

selection list is shuffled. For each simulation in the selection list, the title is used to determine

the XML configuration from which the presentation module definition is created and placed in

the module definition list array. For the number of simulations equal to the maximum size of

the play list, the definitions are taken from the presentation module definition list and used to

create presentation modules which are placed in the presentation modules array. An index is

recorded for the next definition in the presentation modules definition list. The display of

modules is controlled by the “next” button. When the end of the presentation modules is

reached, the next number of module definitions is taken and used to create new simulations

which are placed into the presentation module array. The process continues until all the

definitions in the module definition list have been taken. At the point, the selection list is

shuffled again and the entire process repeated.


Creation of Presentation Modules:

The nautical utilities class contains static array lists of the navigation aids, lighted navigation

aids and vessels. The terrestrial utilities class contains static array lists of the landforms and

landmarks. These lists of classes available to create objects for use in the 3D nautical world is

used by the presentation module generator.

IMPORTANT NOTE: When inspecting the source code for the creation of a presentation module,

attention should be given to the use of arrays verses array lists. The lists of placeable,

moveable, lighted and “constructable” items created for the presentation module are arrays.

An array is a primitive structure of a fixed size. Items within the array can be quickly located

using an index. Array lists are container objects whose size can be modified as needed. Array

lists are used in the creation of the arrays in the presentation module.

The presentation module is created from the definition using the following steps.

1) Create an array list and add an “end of animation” event to the list.

2) If any other animation events exist within the presentation module definition add them

to the animation event array list.

3) Create an array list for moveable objects and add the “first person” to the list. (Note:

the “first person” is perceived in the overlays, not in the 3D world. A “first person”

object does not need to be created within the 3D nautical world. Therefore, the “first

person” moveable object can be added to the list without any other build activity.)

4) If nautical objects exist within the presentation module definition:

1. Create array lists for placeable objects and lighted objects.

2. Create a map. If an item in the nautical items list is moveable, the map will be

used to record the location of the moveable item in the nautical list and its

location in the moveable list into which it is placed.

3. For each nautical item in the definition:

i. The nautical utilities class array list which will contain the item is

determined.

ii. The correct class for the nautical object within the list is determined.

iii. An object for the nautical item is created using the determined class.

iv. If the object is placeable, its position and direction are set and used to

define the location of the object in the 3D world. The placeable object is

added to a list of placeable objects.

v. If the object is moveable, in addition to the location, the speed, any

change in course and if the object is “locked on course” or “hunting” is

also defined. The moveable object is added to a list of moveable objects.

Update the map with the location of the object in the moveable list.

vi. If the object is lighted, the object is added to a list of lighted objects.


vii. Create arrays of placeable and lighted objects from the placeable and

lighted array lists.

viii. Create array of moveable objects from the moveable array list.

5) Only an array of nautical items exists in the presentation module definition, therefore

animation events in the definition reference objects in nautical items array. When the

presentation module is created, moveable nautical objects are placed in the moveable

objects array. The animation events in the presentation module are updated to

reference objects in the moveable array location. (Note: An array of nautical objects

does not exist in a presentation module. Animation events will only change the speed

and course of objects in the moveable array. There is no need for the animation events

to access objects in the placeable array.)

6) If regions exist in the presentation module definition create an array of region objects.

7) If terrestrial objects exist:

a. Create an array list for “constructable” objects

b. For each terrestrial item in the definition:

i. The terrestrial utilities class array list which contains the item is

determined.

ii. The correct class for the terrestrial object within the list is determined.

iii. An object for the terrestrial item is created using the determined class

and added to the “constructable” array list.

iv. Create an array of “constructable” objects from the “constructable”

objects array list.

8) return a presentation module containing the object arrays which have been generated.

Display of Presentation Modules:

A Presentation Module consists of the following:

1) Objects to control the display of the 3D world and 2D image overlays.

2) “Constructable” Objects Array

3) Placeable Objects Array

4) Moveable Objects Array

5) Lighted Objects Array

6) The “first person”

7) Regions Items Array

8) Animation Events Array

The items in a presentation module are provide in arrays. Items in arrays can be quickly

accessed using an index.


When a presentation module is displayed, the items listed above are loaded into the 3D

nautical world.

The control objects are special icons. The user selects and manipulates these icons to interact

with the 3D nautical world. For example, the orange-red circle at the end of the throttle handle

is a control icon used to adjust the speed of the simulator boat.

“Constructable” objects are typically terrestrial objects. They can be placed next to or on top of

each other to create a landscape. For example, landforms which are cylinders and cubes of

different colors could be stacked to create a hill. On top of this hill, a radio tower, which is a

landmark could be placed. “Constructable” objects are decoration. They do not interact with

other items in the 3D nautical world. In other words, nothing prevents a simulator boat from

driving through the hill which exists in the 3D world. “Constructable” objects must be “fenced”.

This will be discussed further when describing regions.

Placeable objects do not move once placed in the 3D world. They are typically navigation aids

or vessels which not moving. These objects interact with other objects. For example, using

methods associated with placeable objects, it is possible to determine if a moving vessel has

collided with a placeable object.

Moveable objects are typically vessels. In addition to having all the traits of placeable objects,

they can move in the 3D world. For example, based on a moveable object’s current speed and

direction, methods associated with moveable objects can be used to determine how their

position changes over time.

Placeable and moveable objects can be lighted items as well. These objects display lights when

the simulation takes place at night. Besides color, the lights on a lighted object have three

fundamental properties, the distance to the observer at which they can be seen, the angle

relative to the observer at which they can be seen and the pattern at which they turn on and

off. Methods are called to manage the first two properties. Background process are used to

manage the third property.

The “first person” is a moveable object. It contains the camera and light which “observe” and

illuminate the 3D world. The position and direction of the “first person” will determine how the

3D nautical world is displayed in the “first person” pane.

Regions are areas on the 3D world ocean which are significant when occupied by the “first

person”. Regions are of four different types: waypoints, speed, channel and fenced. Waypoint

regions may occur individually or consist of a set. If an individual waypoint, the region defines

when the “first person” has reached the required destination. If the regions are a set, the

regions define the course which the “first person” vessel must follow to reach the required

destination. Speed regions define areas in which the “first person” vessel must travel at or

below a defined speed. Channel regions define areas in which the “first person” vessel must

remain. Fenced regions define areas into which the “first person” vessel may not entry.


The movement of objects is controlled by animation events. Objects will only move in the 3D

world during an animation event. Moveable objects have the property of speed, direction and

course change. These properties are part of the object’s original definition, but can also be

changed at the beginning of each animation event. The speed and direction change for the

“first person” is changed by user interaction instead of via an animation event. Animation

events exist for a defined period of time. Only one animation event will exist at any given time,

but a presentation module may contain a list of animation events. When one animation event

terminates, the next event will start until the last event is reached or the animation is

terminated by the user or simulation manager. While an animation event exists, moveable

object will move in the 3D nautical world according to their defined properties.

The “constructable”, placeable, and moveable objects are contained in a presentation module

as arrays. When the presentation module is loaded, all these objects are placed into the 3D

nautical world subscene. JavaFX manages the display of these objects as the camera

representing the “first person” view is moved within the world.

The movement of the objects and the display of the lights is handled by the “play” method. The

start of the “play” method is triggered by the “play” icon. If animation is available in a

presentation module, the “play” icon will appear in the front of the nautical world.

3D Nautical World

The nautical world consists of landscape, navigation aids, vessels and the “first person”. The

display of these objects handled by the JavaFX framework, but the appearance of the objects is

managed by the “NavRuleSim” application. For example, depending on whether it is night or

day and the direction of the wind, the application will determine the color of a sailboat and the

position of the boat’s sails. The shape components which make up the sailboat are adjusted

accordingly. The JavaFX framework will manage the display of the shapes in the 3D nautical

world sub-scene. The conditions of the nautical environment: day/night, wind speed/wind

direction and time are stored and managed by static variables and methods in the nautical

environment class. This allows any nautical object to easily obtain the environment conditions

and adjust their appearance to the environment. Because the variables are static, only one set

of conditions can exist at any given time. Each time a presentation module is loaded in a

primary user screen, the static environment variables must be set to the conditions of the

presentation module. For the reference user screen, the environment variables are set by the

user using controls which are part of the reference user screen GUI.


Coordinates:

When the user “looks into” the 3D nautical world, three dimensions are perceived:

1) Up and Down 2) Right and Left 3) Depth into the world

Two different sets of coordinates are used to define location in the 3D nautical world. The first

set of coordinates is defined by the JavaFX framework. This coordinate system is used within

the source code. The second set of coordinates is defined by the “NavRuleSim” application and

is used by the XML configuration files.

In the 2D environment used for the JavaFX GUI layouts and the 2D overlays, the upper, left

corner is the origin. The X axis extends to the right and the Y axis extend down. The JavaFX 3D

environment extends this coordinate structure with a Z axis which extends into the screen. The

axes comply with the geometric “right hand rule” for axis layout. The 3D environment has six

degrees of freedom. An object can be translated in the directions of the X, Y and Z axes. An

object can also be rotated around the X, Y and Z axes.

When there is no rotation, the user perception of the 3D world aligns with the JavaFX

coordinate system as follows: Up and down are translations along the Y axis. Up is positive

translation and down is negative translation; Right and left are translations along the X axis.

Right is positive translation; Depth is translation along the Z axis. Movement away from the

user is positive translation. Movement towards the user is negative translation.

The surface of the ocean in the 3D world is the plane defined by the X and Z axis.

When the “first person” object is created, the rotation axis for the camera and light is set to the

Y axis. The camera and light are translated along the Y axis to align with the height of the

observer. The camera and lights are “grouped” as part of the “first person”. Translation of the

“first person” object along the X and Z axes results in movement of the “first person” along the

surface of the ocean. Any rotation of the “first person” object results in a change in direction.

The unit of translation in the JavaFX coordinate system is pixels. The unit of direction is degrees.

The coordinate system used in the XML configuration files translates the JavaFX coordinate

system into system which is a little more intuitive to what the user perceives. Direction is

rotation around the JavaFX Y axis. Change is direction is perceived by the user as turning on the

surface of the ocean. Position X and Position Y are coordinates on the surface of the ocean.

When the direction is zero, the Y axis of the XML coordinate system is direction which the user

perceives as moving away into the 3D world. The X axis is to the user’s right. The direction angle

is referenced for the Y axis extending into the 3D world. What the user perceives as turning to

the right (starboard) is an increase in the direction angle.

The unit of translation in the XML coordinate system is meters. The unit of direction is degrees.


True north in the 3D nautical world aligns with the Y axis of the XML coordinate system.

Changes in JavaFX rotation correspond to changes in direction and orientation in the XML

coordinate system. Nautical objects have direction. “Constructable” objects have orientation.

Elevation in the XML coordinate system is distance above the ocean surface. “Constructable”

objects can have elevation as a property. Nautical objects, such as vessels and navigation aids

do not have elevation. They are always located on the ocean surface.

Landscape:

The landscape consists of landforms and landmarks. These are “constructable” objects which

can be placed next to and on top of each other. All “constructable” objects have the properties

of position X, position Y, elevation and orientation. A “constructable” objects location is

defined in the XML configuration file. Landmarks are fixed in shape, only their location is

defined. Landforms have the properties of height, width and length of landforms can be

modified. These are defined as part of the presentation module definition. Width is defined

along the XML X axis. Length is defined along the XML Y axis.

Nothing prevents a vessel from moving into the landscape. When defining presentation

modules, it is necessary to plan the course of moveable objects to ensure that they will not

travel into the landscape. Any landscape which could be approached by the “first person”

vessel, must be “fenced” with a region to prevent such occupation from occurring.

Navigation Aids:

Navigation Aids are placeable objects. Collision between navigation aids and vessels can be

detected in the simulator. (In the learn and test user screens, a collision is not detected, the

presentation module definition must ensure that vessels do not collide with navigation aids and

other vessels.)

The abstract navigation aid base class defines the methods necessary to support the placeable

interface. The navigation aid objects extend the base class and contain the shapes which define

the appearance of the navigation aid in the 3D nautical world.

For some navigation aids, such as regulatory bouys, a 2D image is “wrapped around” the

surface of 3D objects. These bitmaps are stored in the “presentationModules” directory in the

“bitmap” sub-directory.


Vessels:

Vessels are moveable objects. Correct interaction between vessels according to USCG colregs

can be detected in the simulator. (In the learn and test user screens, interaction between

vessels is not monitored, the presentation module definition must ensure that vessels interact

as intended.)

The abstract navigation aid base class defines the methods necessary to support the placeable

and moveable interfaces. The base class also divides the shapes which define the vessel’s

appearance into different groups. These group are associated with different modes of motion

and operation. For example, the appearance of a power boat at anchor and engaged in diving is

different from the appearance of the boat when moving under power and not engaged in

diving. The appearance (or non-appearance) of the shapes of the vessel to conform to these

different modes of motion and operation is managed as groups. In addition to motion and

operation, whether it is day or night will also affect the appearance of a vessel. The groups are

structured, so the vessel’s appearance for these three conditional states can be manage by

enabling the appearance of shapes as organized within groups.

The vessel objects extend the base class and contain the shapes which define the appearance of

the vessel in the 3D nautical world. Characteristics about that specific vessel, such as max

speed, are also defined in its vessel class.

A vessel has a base whose area on the ocean surface is greater than that of all the shapes which

make up the vessel. The base is needed to prevent jerky, unexpected movement. The vessel is

positioned at the center of the area occupied by its shapes. If the base defines the maximum

area of the vessel on the ocean surface, the vessel’s position will always be centered on the

base. If the base did not exist, the movements of shapes, such as the sail, could result in a

change in the area projected onto the ocean by the vessel. The center of the vessel would

change accordingly, the vessel would appear to jump in location. The existence of the vessel

base prevents this from occurring.

First Person:

The “first person” is a special moveable object. It moves in the 3D nautical world and its

interaction with other vessels and nautical objects can be monitored, but the “first person”

appearance is not defined by 3D shapes.

The “first person” exists in the virtual 3D nautical world as a camera. The location and direction

of this camera determine how the 3D nautical world is displayed. The appearance of the “first

person” vessel is defined by 2D shapes which appear in the front of the “first person” pane and

through which the virtual world seen by the user.


Placed within the “first person” pane on each of the primary user screen is the 3D nautical

world subscene, followed by the “first person” window and finally the centering pane. The

order in which these items are placed is important. The centering pane contains items such as

the image viewer and “play” icon. The “first person” window contains the 2D shapes which

define the appearance of the vessel. As the user “looks into” the 3D world, the order of

placement ensures the vessels and navigation aids on the water appear behind the mast and

sails of the simulator boat. The “play” icon appears in front of everything and can selected.

The “first person” vessel is placed into the “first person” window. The vessel is a group which

contains different overlays. Similar to the way different groups of shapes are managed to define

the appearance of vessels to match their mode of motion and operation, different overlays are

managed to define the appearance of the “first person” vessel to match its mode of motion and

operation.

The “first person” pane is anchored to the display pane which is anchored to the overall pane.

As the size of the application window is changed, the “first person” pane changes size. The

JavaFX framework is aware of the change in the pane in which the 3D nautical world subscene

is located and adjusts the display of the world accordingly.

The “first person” vessel 2D overlays are located outside the 3D nautical world subscene. The

application must monitor the pane for changes in size and adjust the 2D shapes in the overlays

accordingly.

The origin of the “first person” vessel is moved from the default location of the upper, left hand

corner of the “first person” pane to the bottom, center of the pane. This matches the origin in

the overlays from which their 2D shapes are positioned. Since the origin of the overlays and

pane are the same, as the size of the pane changes, the shapes in the overlays must simply be

scaled to accommodate the change in pane size. It is not necessary to translate the location of

shapes. Every shape in a 2D overlay has a scale transform which is bound to the display window

width. When the display window width changes, the 2D shapes are scaled accordingly.

IMPORTANT: The “first person” window is a group within the “first person” pane. The “first

person” vessel is a group within the “first person” window. The reason for the group within the

group relates to the translation of the “first person” pane to allow the view of the 3D world to

display more ocean and less sky. (Refer to step 3 of screen controller initialization in the user

screen section of this document.) The horizon line where the sky meets the ocean is in the

vertical center of the “first person” pane. The translation of the “first person” pane does not

make less sky appear in the display of the 3D nautical. All it does is move the vertical centerline

of the “first person” pane above the vertical center line of the display pane. The “first person”

pane is no longer symmetric with the display pane. The horizon line in the “first person” pane

is above the vertical center line of the display pane. When the upper part of the “first person”

window is masked out, so the area displayed in the “first person” window above the display

pane centerline is the same as the area displayed below, the result is a display of less sky. The


sky in the upper part of the “first person” pane has been masked out. The color of the mask is

the same as the upper and lower border panes. The sizes of the mask, upper border pane and

lower border pane are set so the “first person” pane appears to be vertically centered with the

display pane with the ocean horizon line above the centerline of display pane. The height of the

lower boundary pane is equal to the height of the upper boundary pane PLUS the height of the

boundary rectangle.

Unlike other moveable object whose properties are completely defined by the presentation

module definition or animation events, the “first person” speed and course change properties

can be modified by the user. The user can change these properties when in the simulator user

screen. The “first person” move method must monitor for changes in speed and direction

when the “first person” exists in the simulator user screen.

Nautical Components:

The JavaFX framework supports the following primary 3D shapes: sphere, cylinder and cube.

These shapes can be used to construct many nautical objects, but some objects require special

shapes. For example, the hull of a vessel cannot be defined using the primary shapes. JavaFX

allows the creation of special shapes using a mesh. The special shapes created to define

nautical objects are contained in the nautical component class. Details on the mesh layout for

these special shapes are in the “Characteristics of the Nautical World” section of this

specification.

Lighted Objects

Nautical lights in the 3D world are black spheres surrounded by a bitmap to define the light’s

color. In JavaFX, when an object is self-illuminated, a bit map image defines the illumination

color pattern. Most nautical lights are one color and therefore surrounded by a single-color bit

map. JavaFX manages the display of the light sphere. As the distance between the observer and

light increases, the sphere becomes smaller and smaller. When the light is near to the observer,

the sphere needs to small enough so the size of the light is representative of how the light

would appear in relation to object of which it is part. When the light is far from the observer,

the sphere must be large enough so the light remains visible. The distances at which nautical

lights must be visible in the 3D world is too great to allow one sphere size to meet both of the

above requirements. When the nautical light is near the observer, the sphere size is set to allow

the display of the light to align with nautical objects on which it is located. As the distance

increases, the size of the sphere is increased in steps to allow the light to remain visible. These

three steps are the following: near distances; mid distances; and far distances. A more realistic

approach would have the sphere gradually increase in size but this would place a greater

demand on the platform resources to manage the light display than the use of the three steps.


Nautical lights have the property of a display arc. When the angle from the light to observer is

between the start of display arc and the end of display arc, the light is visible. Otherwise the

light is not visible.

Nautical lights also have the property of a range. This is a distance in nautical miles in which the

light is visible. If the distance between the observer and the light exceeds the range, the light is

no longer visible.

The JavaFX framework has methods to allow an object to be visible or not. The nautical light

has two abstract methods, “displayLight” and “obscureLight”, which are used to control the

visibility of the light based on the observer’s angle and distance.

Navigation Aid Lights extend nautical lights. These lights have the additional property of an

illumination pattern. This is a repeating pattern by which the nautical light turns on and off.

The illumination pattern is defined as an array of integers. The integer values define duration in

half second increments between when the light toggles from on to off or from off to on. Having

the light remain continuously on is also a valid pattern.

The illumination pattern for each navigation aid light is managed by a separate background

process which toggles the visibility of the light. When the current illumination pattern for the

light is created, the light is visible, an active flag is set to true and a listener for the light is added

to the nautical environment half second property.

When the illumination pattern is started, while the active flag is true, the background process

will continuously, repeat to step through each integer value in the illumination pattern. For

each integer, the process will go into a nautical sleep with a duration of the half second

increments defined by the integer value. When returning from the nautical sleep, the process

will toggle the display of the navigation light.

During the nautical sleep, the background process sets a delay counter to the current integer

value and then waits for a notification from the half second listener. When the notification

occurs, the background process decrements the delay counter. If the delay counter is greater

than zero and the active flag is true, the wait process is repeated. This results in a delay equal to

the number of half second increments defined by the integer value.

In addition to the wait being ended by notification from the half second property, the wait is

configured to also end after a duration which is defined in reference to the system time. The

wait will end by either a notification from the listener or duration of the system time period,

whichever occurs first. When animation is running, the system time period is set at a value that

is greater than that of a half second increment. Therefore, waits will end with notifications from

the listener and the nautical sleep will be synchronized with the half second increments of

nautical time. The system time period prevents the background process from “hanging” should

the half second property notifications fail to occur.


When the “displayLight” method is called for a navigation aid light, if the light characteristic is

continuously on, the light is made visible. Otherwise a new illumination pattern is created and

started as the current illumination pattern background process. This background process will

run until it is terminated by a call to the “obscureLight” or “stopBackgroundTask” methods.

When the “obscureLight” method is called, if the light is continuously on, the light is made not

visible. Otherwise, the current illumination pattern process is stopped. The active flag is set to

false and the half second listener is removed. The current illumination pattern is set to null. The

illumination pattern which had been assigned as the current pattern process will continue to

run. Since the listener no longer exists, the current wait state will end after the system time

period. The false active flag will terminate the nautical sleep and illumination pattern’s loop.

The background process will then terminate.

Vessel lights also extend nautical lights. Similar to navigation aid lights, vessel lights have the

property of an illumination pattern. Unlike navigation lights whose pattern period must

conform to a defined duration of time for identification, vessel lights must conform to their

pattern, but the exact period of the pattern may vary within a given tolerance. For example, a

hoover craft displays a flashing yellow light. The light flashes at around two flashes per second

but it does not have to flash at exactly two flashes per second. The simple flashing of the yellow

light along with the other continuously illuminated lights on the vessel is sufficient to identify

the vessel. Vessel lights implement an illumination background process similar to navigation aid

lights, but do not synchronize the pattern with nautical time. System time is sufficient to define

the pattern and results in a reduced resource demand for the management of vessel lights.

The visibility of navigation aid lights and vessel lights to the observer is managed as follows:

First the “setObservability” method is called to determine the arc angle from the light to the

observer. If the observer angle is within the visible arc, the light is displayed. Otherwise it is

obscured.

Next the “setIntensity” method is called. The distance between the observer and the light is

calculated. The size of the light sphere is set as defined by the light’s near, mid and far distance

step values.

Finally, the “setNotVisibleIfOutOfRange” method is called. If the distance from the observer to

the light is greater than the light’s visibility range, the display is obscured.

The order in which the methods are called is important. The “setNotVisibleIfOutOfRange”

method only turns a light off, therefore it must be called last.

The half second periods of navigation time only increment when animation is running. In a

presentation module without animation, the display of navigation lights will be synchronized

with the system time period. When animation does not exist in a module, the wait will end at

the duration of the system time period. Notification does not occur, so ensuring that system

time period is greater than the notification period is not required. Therefore, the system time


period is set to a half second of system time. The navigation lights will illuminate to a pattern

synchronized with system time.

Overlay Manager

The overlay manager is loaded when the presentation manager is loaded. When the overlay

manager is loaded, the following components of the 2D display are defined:

1) Type of Vessel 2) Wind Affected Components 3) Instruments 4) Controls 5) Bearing Gradients

Whether the point of view and cabin access features are enabled is also defined. If either

feature is enabled, the required control icons and event handlers are implemented for the

feature.

The “first person” properties such as observer height are updated to match the vessel which

has been loaded as the overlay. Listeners are added to the “first person” speed and direction

property. When changes occur to these properties, the update overlay method is called to

determine if changes are required in the display of the sails, flags or outputs of instruments.

If controls are displayed, events are defined for the control icons.

Sail Control

Wind affected components must support an interface with a method to adjust sail display and a

method to set the telltale. A telltale indicates if a sail is positioned in the optimal setting to

propel the vessel. (Note: For a flag component, the method to display the sail would be

implemented where the flag is considered a sail. The set telltale method would also be

implemented, but it would be a “dummy” method which would perform no operations.)

When displayed in the learn and test user screen, sails are automatically adjusted. When

displayed in the simulator user screen, sails may be automatically adjusted. Or the user may be

required to adjust the sail manually.

When the automatic sail adjust is enabled, the overlay manager records the current sail tack

and current point of sail. The overlay manager listens to the “first person” speed and direction.

When changes occur to these properties, the overlay manager updates the overlay.


To update the overlay, the overlay manager determines the apparent wind speed and angle in

relation to the “first person” vessel. The overlay manager calls the adjust sail display and set

telltale methods to adjust the appearance of the sail.

Management of Time and Movement

Animation (Object Movement):

The device on which “NavRuleSim” runs has a system clock which is aligned with the time of the

real world. The time in virtual world is synchronized with animation frames. JavaFX animation

controls the display of nautical objects which are moving in the 3D world. The animation period

is the time between frames as measured on the system clock. This period is defined by the

application settings. It determines approximately how many frames will occur in a second of

system time. A background process, called a timeline, is created and run. Each time a frame

occurs at the defined period, the appearance of the objects is modified as defined by the

timeline process and the display of the objects is updated. The period between frames will

define how much resource is required to run animation in the application. This period can be

adjusted via the application settings user screen. The period will always be set to a value so that

an even number of frames occur within a second.

The nautical time resolution is one half second. The requirement that an even number of

frames occur within one second, ensures that a discrete number of frames will correspond to

the half second resolution. In other words, the frames per second can always be divided in half.

How the objects within the 3D world are moved and monitored depends whether the nautical

condition is night or day and if the primary user screen is the simulator. Moveable objects will

always be moved after each frame and their appearance and display modified accordingly. If it

is night, the light objects will have to be adjusted for any changes in observer angle and

distance. If the presentation module is a simulation, the moveable object will have to be

monitored for conformance to motion according to USCG colregs. The resulting four animation

configurations are defined as the following timelines: animationEventatDay”;

“animationEventAtNight”; “animationEventSimulatorAtDay” and

“animationEventSimulatorAtNight”. When each of the above timeline is created, the period

between frames is define using the setting performance value. The appropriate event handler

to manage the nautical objects a is also defined.

The event handlers which manage the appearance of the objects after each frame of the

timeline are the following: “eventHandlerDay”; “eventHandlerNight”;

“eventHandlerSimulatorDay” and “eventHandlerSimulatorNight”.

The movement of objects in the 3D nautical world for a given presentation module is defined by

a series of events. The series of events is managed by the “playEvents” method.


Animation is started by a call to the “playAnimation” method which calls the “playEvents”

method. Each of the four timelines is configured to call the “playEvents” method when the

timeline terminates. The resulting animation is a continuous series of animation events until

the final “end of animation” event is reached.

The array of animation events created for the presentation module is the

“animationEventConfigs” matrix. Each row in the matrix is an animation event. The columns in

each row are the parameters for the event. When the presentation module is initialized, the

current config index is set to the value of the last row in the matrix. The current event variable

defines a row in the matrix. The animation event config matrix always contains an “end of

animation” event in the first row of the matrix.

All animation events define a duration. The duration is defined in the XML configuration file in

seconds which is converted into a number of frames when the presentation module definition

is generated.

When the play events method is called, it sets the current event matrix row to the value config

index and then decrements the index. If the current row consists of an “end of animation”

event, the animation is terminated. Otherwise, if defined in the event, the speed and/or course

change properties for the given vessel are modified. Then, the correct timeline is selected for

the nautical environment and user conditions. The timeline is configured with the frame count

(duration) defined for the animation event and the timeline is played.

JavaFX manages the timeline as a background process. While the timeline is playing, after the

period between two frames passes, the timeline event handler is called. This continues until the

timeline has incremented through all the frames. Upon ending the timeline calls the play event

method.

During the creation of a presentation module, the initial start conditions of the moveable

objects are recorded in an array named moveable objects start conditions.

When the animation ends, the animation event index is reset to the last animation event in the

matrix. Additional reset operations differ between the different primary screens.

learn user screen: The play animation button is made visible and the moveable objects are reset to their start conditions.

test user screen: The play animation button is made visible, but the moveable objects are NOT reset to their start conditions. In the test environment, animation is used to show the movement of vessels before some decision needs to be made. When the animation end, the vessels need to remain in the positions at which the decision needs to be made. This allows the user to refer to the vessel positions before submitting the answer to the test question. In the test user screen, the resetting of moveable objects back to their start position is trigger by selecting the play animation button.


simulation user screen: The simulation manager is terminated with a “timed out” end condition. Refer to the “Management of Simulation” section in this document from further details.

Nautical Time:

Time resolution in the nautical world is 0.5 seconds. All the event handlers for the animation

timelines call the synch nautical time method. This method counts frames, when the number of

frames equivalent to a half a second of nautical time have incremented, the frame count is

reset to zero and a half a second is added to nautical time.

The period of time between frames is defined in system time. JavaFX attempts to keep the

duration between frame at a duration which matches the defined system time, but cannot

guarantee the accuracy. How and when operations are performed in the timeline background

process depend upon other process resource load outside its control. Therefore, nautical time

is not guaranteed to be in synch with system time.

The clock and stop watch are synchronized with nautical time using listeners on the nautical

minute property and nautical half second property. This allows the period of navigation

illumination patterns, the distance travelled by a vessel and other movement activity to be

accurately measured within the nautical world.

Fast Advance:

The overlay manager can provide the ability to load an overlay which presents the interior cabin

within the “first person” boat. While the interior cabin overlay is displayed, the 3D nautical

world is no longer visible. From the cabin interior, it is possible to load the overlay of the vessel

cockpit and return to the typically display from which the 3D nautical world is observed. This

feature is called cabin access. Cabin access supports the fast advance feature. When animation

is running, objects are moved after each frame. This is synchronized with nautical time which is

close to the system time. Fast advance will move objects in the 3D nautical world in increments

much quicker than the animation frame period and then adjust the nautical time for the period

equivalent to the total number of frames which would have been incremented had the

movement of the objects occurred as part of animation. In other words, the fast advance

feature provides the ability to quickly advance the passage time within the nautical world.

Part of the cabin access overlay, is an icon used to execute fast advance. If cabin access is

enabled, the fast advance lambda function is set to the control icon when the presentation

module is loaded.


Objects have position and location. Position are the values at which an object should be

located with the 3D nautical world. The location is where the object actually resides within the

3D world. JavaFX displays objects as defined by their location.

When animation is running, at each frame, objects positions are updated. Then using the new

position values, object are placed at their new location using either a set location method or

“setTranslateX” and “setTranslateZ” methods. When fast advance is executed, a loop is run

incrementing and adjusting position for the nautical objects as quickly as the loop will execute.

The loop runs for the number increments equivalent to fast advanced time interval. The fast

advance time interval is defined in the application settings. At the end of the interval, the

location of the objects set using to the final position values. The objects will change locations in

big distance steps. This is the reason fast advance can only occur within the cabin interior

where the unrealistic movement is not displayed.

Control of First Person

In the simulator user screen, the speed and course of the “first person” boat is controlled by

the user. The overlay manager and “first person” are closely linked to manage this activity.

Orange-Red circles next to the tiller, throttle and winch handle define the control icons. The

control overlay defines events which manage how control icon selection, movement and

release defines the “first person” properties.

When the overlay is loaded, the overlay manager configures the events with the appropriate

control icons.

When automatic sail trim is enabled, clicking the left mouse button while the mouse pointer is

over the winch control icon will toggle the sail position between sail trimmed/sail not trimmed.

Holding the left mouse button down while the mouse pointer is over the winch control when

the automatic sail is disabled will make that control active and allow the location of the control

icon to be dragged.

Holding the left mouse button down while the mouse pointer is over the tiller control or the

throttle control will make either of those controls active and allow the location of the control

icon to be dragged.

Only one control can be active at any given time. How dragging the icon affects the ‘first

person” depends on the control. Releasing the mouse left button makes a control no longer

active, if one was active.


tiller:

The control icon can be dragged along a horizontal line. For the catboat, the maximum

positions in either direction are from the center to the seat edge in the cockpit. How far the

control icon is dragged from the center as a percentage of maximum travel distance defines the

percentage of maximum course direction change to which the “first person” course change is

set. The direction of change is opposite the direction of the motion of the tiller icon. When the

control icon is released, its location returns to the center.

throttle:

The throttle icon can reside in 5 locations which correspond to reverse, neutral, slow, standard

and full speeds. When dragged, the icon will “jump” to the location closest to the mouse

position while the control is active. When the control icon is released the icon will remain at the

current location. The motor speed will be modified to match the current throttle location.

winch:

If automatic sail trim is enabled and the sail is trimmed, the sail is set to be optimized for the

calculated wind angle. If the sail is not trimmed, the sail is set to a boom angle which matches

the apparent wind angle.

If automatic sail is not enabled, dragging the winch control icon around the center of the winch

icon adjusts the boom angle. Four square areas are defined around the winch. How the mouse

moves between these four areas determines if the control icon is being moved in a clockwise or

counterclockwise direction. When moved in clockwise direction, the boom angle increases.

When moved in a counterclockwise direction, the boom angle decreases. The boom angle must

remain between 90 and 180 degrees.

Manipulating the throttle or the sail position will modify the motor and sail speed. The “first

person” boat speed is a factor of both the motor and sail speed. Normally the “first person”

vessel is propelled by either the sail or the motor, but not both.

Simulator Console

In the simulator user screen, the box to display the next button to control the movement

through simulations is contained in a separate simulator console screen which is not visible

when animation is running. This allows a bigger field of view of the 3D nautical world. When the

play button is pressed, the simulator console is made not visible. When the simulation

terminates, the simulator console is made visible.


Similar to the other screens, the simulator console has an fxml file which defines the layout of

the GUI and a controller which manages the functions performed by the GUI.

Management of a Simulation:

When animation is executed in the simulator, a simulation manager monitors the movement of

the “first person” boat for conformance to USCG colregs. The simulation manager also monitors

progress towards accomplishing the goal required to complete the simulation.

The overall simulation management activity is divided up into small analysis steps which are

performed after each animation frame increment. When all the steps in the overall

management process have been performed, the series of steps is repeated. This loop through

the analysis steps continues while the animation is running.

The simulation management process steps are grouped into the following three activities:

monitoring entry into or out of regions; monitoring potential collision with other nautical

objects; and monitoring potential interaction with other vessel which may violate USCG colregs

or require a change in course to conform to USCG colregs.

The analysis performed at each step determines if the simulation can continue or if it should be

terminated. If the simulation manager determines the simulation should end, the simulator

console is updated with information about the end condition. The simulation manager also

sends a termination request to the simulator user screen controller. The simulator user screen

controller manages the termination of the simulation.

The simulation management activity loop consists of the following steps: • Beginning of loop

• At the next frame increment – Monitor Regions

• At the next frame increment – Monitor Potential Collision

• At the next frame increment – For first moveable object (if it exists) – Monitor Potential Interaction

• At the next frame increment – For next moveable object (if it exists) – Monitor Potential Interaction

• ……….

• Once potential interaction has been monitored for all moveable objects, repeat the loop

Below is a summary of the activity performed as part of the processing loop steps:


Monitoring Regions Activity:

1) Set the channel flag to indicate the “first person” is not in the channel.

2) For each region in the presentation module, if the “first person” is in the region:

Determine the type of region and process accordingly:

channel: Set channel flag to indicate the “first person” is in the channel.

fenced: Terminate with “Entered Forbidden Area” message.

speed: If “first person” speed is above the defined limit:

Terminate with “Excessive Speed” message. waypoint:

If the waypoint been reached, but not in the defined order: Terminate with “Course Not Followed” message.

If the waypoint is an end waypoint: Terminate with “Objective Accomplished” message.

Update index used for monitoring the order in which waypoints are reached.

3) If all the regions in the presentation module have been processed:

If “first person” should be in a channel and is not in a channel:

Terminate with “Left Safe Water” message.

Monitoring Potential Collision:

A list of placeable objects which should be monitored for potential collision is generated

as part of the activity which monitors moveable objects for potential interaction. Two

separate list arrays are used. The list arrays are named

“potentialCollisionsBeingMonitored” and “potentialCollisionsBeingPackaged”. While the

objects in the “…Monitored” list are being analyzed for collision, the “…Packaged” list is

being used to hold objects which have been “marked” for collision analysis. Once all the

nautical objects have been reviewed to determine if they should be on the collision

analysis list, the two lists are swapped. The objects in the new “…Monitored” list will be

analyzed to determine if the first person and object are colliding using the following

procedure:

For each of the objects in the “potentialCollisionBeingMonitored” list:

1) Using Java shape methods, a rectangle corresponding to the “first person” boat rectangular boundary is constructed and positioned in a 2D space at a location and orientation which corresponds to its location on the 3D world ocean.

2) A similar rectangle is created for the nautical object being monitored. 3) A Java method is used to determine if the two rectangles intersect. 4) If an intersection exists:

Terminate with “Approached Too Close” message.


Monitoring Potential Interaction:

Because of the resource required to analyze for potential interaction, the analysis is performed

on only one moveable object per each frame increment.

1) If the object is placeable and the separation distance is small enough for the potential of

a collision, add the object to a list to be packaged for monitoring for collision. The

calculation is based on the boundary radius of the “first person” and object. (Note: Refer

to the Monitoring Potential Collisions Activity section for more detail on the list.)

2) else (the nautical object is moveable):

1. Based on the boundary radius of the “first person” and object, if the separation

distance is small enough for the potential of a collision, add the object to a list to

be packaged for monitoring for collision. (Note: Refer to the Monitoring

Potential Collisions Activity Section for more details.)

2. If the moveable object was in the process being overtaken:

If the moveable object is now behind the “first person” or the distance

between the vessels is sufficient - set the state of the moveable object as

no longer in the state of being overtaken.

3. Determine if a violation of the USCG colregs (privilege violation) is possible.

(Refer to the note at the end of this procedure list for details on how the

potential for a privilege violation is determined.)

If a privilege violation is possible perform the following analysis:

i. If the moveable object is not underway, anchored or not under command

- The processing of the moveable object is complete.

ii. If the moveable object is changing course - The processing of the

moveable object is complete.

iii. If the “first person” is clearly establishing a new course - The processing

of the moveable object is complete.

iv. If the “first person” is overtaking the moveable object - The processing of

the moveable object is complete.

v. If the “first person” is in the process of overtaking the moveable object

and is failing to stay clear while moving around the object - Terminate the

simulation with an “failed to stay clear message”. The processing of the


vi. Determine privilege between “first person” and the moveable object.

vii. If the moveable object has privilege over “first person” and the moveable

object is overtaking the “first person” - Terminate the simulation with a

“impeded motion” message. The processing of the moveable object is

complete.

viii. If the moveable object does not have privilege over “first person” and the

moveable object is overtaking the “first person” and not locked on course


- Reduce the moveable object’s speed. The processing of the moveable

object is complete.

ix. If the “first person” is privileged and the moveable object is not locked on

course and the distance is small enough that a course adjustment is

required - Adjust the moveable object course. The processing of the


x. If the “first person” is not privileged and not moving away from the

moveable object - Terminate the simulation with “failed to giveway”

message. The processing of the moveable object is complete.

xi. If the privilege between the “first person” and moveable object is equal

and the “first person” is under sail. Determine if the “first person” has

violated any sailing USCG colregs. If so - Terminate the simulation with a

“Failed to Giveway” message. The processing of the moveable object is

complete.

xii. If the privilege between the “first person” and moveable object is equal

and the “first person” is under power. Determine if the “first person” has

violated any power USCG colregs. If so - Terminate the session with a

“Failed to Giveway” message. The processing of the moveable object is

complete.

Note - How to determine if a privilege violation is possible (step 2, sub-step 3):

For a violation to be possible, the “first person” and moveable object must be approaching each

other in a way that one vessel could interfere with the movement of the other vessel. The

following steps are performed to determine if this condition exists:

1) If the “first person” vessel and moveable object are on courses parallel to each other:

If the vessels will pass each other:

If the distance between vessels as they pass could be small enough for

the potential of a USCG colregs violation – Report a privilege violation is

possible. Processing is complete.

2) If the “first person” vessel and moveable objects are on courses to intersect:

(Note: Depending on direction of travel and calculation tolerance, it is possible for the

analysis of both parallel and intersect courses to occur.)

a. If the moveable vessel is “hunting” - Adjust the moveable vessel speed so that

the moveable vessel will arrive at the intersection point with the first person at

the same time.

b. If the distance between vessels as they pass each other at the intersection point

is small enough for the potential of a USCG colregs violation – Report a privilege

violation is possible. Processing is complete.

3) Report a privilege violation is not possible. Processing is complete

Simulation Management During Fast Advance:


When the simulation is running under the fast advance condition, the criteria used by the

simulation manager to monitor for interaction with regions is no different from the process

used when animation is running. The processes to monitor for potential collision with nautical

objects or potential interaction with vessels is different.

If the distance based between the “first person” vessel and placeable object based on

boundary radius values is small enough for the potential of a collision, the simulation is

terminated with a “Failed to Keep Lookout” message.

If the distance based between the “first person” vessel and moveable object based on

boundary radius values is small enough for the potential of a USCG colregs violation, the

simulation is terminated with a “Failed to Keep Lookout” message.

Summary of End Conditions:

The following is a summary of all the conditions which can terminate a simulation. Should the

condition need to be tested or demonstrated, a brief description on how create each condition

is also included in the summary.

1) Objective Accomplished

Successfully completing any simulation will display this end condition message.

2) Simulation Terminated

Selecting the quit icon during any simulation will display this end condition

message.

3) Excessive Speed

a. Load the simulation titled:

“Conduct (Power): Power Vessel Interaction”

Module 1 in “Power_Conduct” simulation XML file

b. Begin simulation

c. Have “first person” vessel travel at FULL speed.

d. Avoid other vessels

e. When “first person” vessel speed reaches 4.9 knots, the “excessive speed” end

condition message will be displayed.

4) Entered Forbidden Area


“NavAids (Sail): Follow motor boat to destination”

Module 1 in “Sail_NavAids” simulation XML file

b. Begin simulation

c. Follow motor boat


d. Do not follow channel

e. When “first person” vessel leaves the channel, the “entered forbidden area” end


5) Left Safe Water


“NavAids (Power): Return from Ocean with Traffic”

Module 8 in “Power_NavAids” simulation XML file

b. Begin simulation

c. Have “first person” travel between day marks 1 and 2.

d. Then turn to starboard and travel out of channel

e. When “first person” vessel leaves the channel, the “left safe water” end


6) Course Not Followed


“Conduct (Power): Vessel In Distress”


b. Begin simulation

c. Have “first person” vessel travel forward at full speed to the yellow bouy.

d. Avoid the small boat to prevent unwanted “fail to give way” message

e. As the “first person” vessel approaches the yellow bouy, the “course not

followed” end condition message will be displayed. (The “first person” vessel did

not travel to the vessel in distress).

7) Approached Too Close


“Conduct (Power): Overtaking”


b. Begin simulation

c. Have “first person” vessel travel at standard speed towards the small power

boat.

d. Travel to collide in the rear of the small boat.

e. As first vessel approaches the small boat, the “approached too close” end


8) Failed to Stay Clear


“Conduct (Power): Power Vessel Interaction”


b. Begin simulation


c. Have “first person” vessel travel forward at stand speed.

d. Pass the small power boat in front on its port side (the boat being passed is on

the “first person” vessel’s starboard side.

e. As the “first person” vessel is moving in front of the small power boat (but NOT

after it has completely moved in front), the “first person” vessel makes a sharp

turn to starboard moving in front of the small boat.

f. As the “first person” vessel moves in front of the small boat, the “failed to stay

clear” end condition message will be displayed.

9) Failed to Give Way


“Conduct (Power): Overtaking”


b. Begin simulation

c. Have “first person” vessel travel at standard speed towards the yellow bouy.

d. As the small power boat approaches from the starboard side, the “failed to give

way” end condition message will be displayed.

10) Impeded Motion


“Conduct (Power): Vessel Travelling in Channel”


b. Begin simulation

c. Have “first person” vessel travel at FULL speed at direction of 3 degrees.

d. Use port view to observe the approaching tanker.

e. When the masthead light poles are aligned, in other words the “first person”

vessel is directly in front of the tanker, sharply turn the vessel to starboard onto

a new course direction of 93 degrees.

f. Once the turn is completed and the rudder released, the “impeded motion” end


11) Failed to Keep Lookout


“Lights (Power): Tanker and Sailboat Approaching on Starboard”

Module 1 in “Power_Lights” simulation XML file

b. Begin simulation

c. Enter cabin

d. Advance Time

e. As time advances to 4 minutes, the “failed to keep lookout” end condition

message will be displayed.


Characteristics of the 3D Nautical World:

Lesson Topics / Simulation Test Group / File Names

Lesson Topic

Lesson File Name Test Group Test File Name

Simulation File Name

Terminology SectionDef_Terminology

Getting Started

SectionDef_Started

Getting Started (Testing Not Required)

SimDef_Power_Start SimDef_Sail_Start

Basic Day Shapes

SectionDef_Shapes

Basic Conduct

SectionDef_Conduct

Basic Conduct Section_Def_Test_Conduct

SimDef_Power_Conduct SimDef_Sail_Conduct

Navigation Aids

SectionDef_NavAids

Regulatory Navigation Aids

SectionDef_RegulatoryNavAids

Navigation Aids Section_Def_Test_NavAids

SimDef_Power_NavAids SimDef_Sail_NavAids

Vessel Lights SectionDef_Lights

Basic Vessel Lights Section_Def_Test_Lights

SimDef_Power_Lights SimDef_Sail_Lights

Lighted Navigation Aids

SectionDef_LightedAids

Lighted Nav Aids Section_Def_Test_LightedAids

SimDef_Power_LightedAids SimDef_Sail_LightedAids

Projections SectionDef_Mercator

Chart Symbols

SectionDef_Symbols

Bearings SectionDef_Bearings

Navigation Techniques

SectionDef_Navigation

Navigation Techniques Section_Def_Test_Navigation

SimDef_Power_Navigation SimDef_Sail_Navigation


Lesson Topics / Simulation Test Group / File Names - Continued

Note: The framework and file structures exist for the following groups, but support for the

topics or groups has not been implemented in the current application version.

Lesson Topic Lesson File Name Test Group Test File Name

Simulation File Name

Advanced Day Shapes

SectionDef_AdvShapes

Advanced Conduct

SectionDef_AdvConduct

Advanced Conduct Section_Def_Test_AdvConduct

SimDef_Power_AdvConduct SimDef_Sail_AdvConduct

Advanced Lights SectionDef_AdvLights

Advanced Vessel Lights Section_Def_Test_AdvLights

SimDef_Power_AdvLights SimDef_Sail_AdvLights

Towing SectionDef_Towing

Towing Section_Def_Test_Towing

SimDef_Power_Towing SimDef_Sail_Towing

Sound and Light Signals

SectionDef_Signals

Sound & Light Signals Section_Def_Test_Signals

SimDef_Power_Signals SimDef_Sail_Signals

Parallel Travel SectionDef_Parallel

Parallel Travel Section_Def_Parallel

SimDef_Power_Parallel SimDef_Sail_Parallel

Naval SectionDef_Naval

Naval Section_Def_Naval

SimDef_Power_Naval SimDef_Sail_Naval


Listing of Simulation Times

Note: All times are in seconds

Simulation Group:

Basic Conduct

Simulation Index:

Max Allowed Time (Nautical Time)

Typical Completion Time (System Time)

Typical Completion Time (Nautical Time)

1 85 83 Cabin Access Not Enabled




















Total Average 114.3


Listing of Simulation Times - Continued


Simulation Group:

Navigation Aids

Simulation Index:
























Total Average 110.9




Simulation Group:

Basic Vessel Lights

Simulation Index:




1 1200 502 862




















Total Average 176.4




Simulation Group:


Simulation Index:






3 1200 180 900



6 1200 200 900

7 900 150 600






13 1200 250 1050



16 1200 220 660

17 840 180 600



20 720 240 300

Total Average 186




Simulation Group:


Simulation Index:




1 7200 300 6300

2 3600 230 2520




6 3000 345 1260

7 2000 480 1440


9 2500 200 1980


11 5400 378 4800

12 4500 360 3900

13 3800 390 3300

14 4500 570 3150


16 2500 240 1260

17 3000 360 2220

18 900 360 540

19 1200 120 900

20 1200 180 840

Total Average 308.9


Listing of Simulation Content

Basic Conduct

Content Simulation Number 1 2 3 4 5 6 7 8 9 10

At Night N N N N N N N N N N

NavAids 1 1 1 1 1 1 3 1 1 1

Lighted NavAids 0 0 0 0 0 0 0 0 0 0

Vessels 3 3 2 3 2 3 2 2 3 2

Terrestrial Objects 0 0 0 0 0 0 0 0 0 0

Events 1 1 1 1 1 1 1 1 1 1

Regions 2 3 1 1 1 1 1 2 1 1

11 12 13 14 15 16 17 18 19 20

At Night N N N N N N N N N N

NavAids 1 1 1 1 1 1 1 1 1 1


Vessels 2 2 3 2 2 2 2 1 1 2


Events 1 1 1 1 1 1 1 1 1 1

Regions 1 1 1 1 1 1 1 1 1 1

Navigation Aids


At Night N N N N N N N N N Y

NavAids 8 8 8 8 10 11 1 6 7 8


Vessels 0 1 0 0 0 0 0 1 1 0


Events 1 1 1 1 1 1 1 1 1 1

Regions 9 7 9 10 2 6 6 5 7 9

11 12 13 14 15 16 17 18 19 20

At Night N N N N N N N N N Y

NavAids 7 7 3 4 5 3 3 3 4 5


Vessels 1 0 1 0 0 0 0 1 1 0


Events 2 1 1 1 1 1 1 1 1 1

Regions 5 9 4 5 6 3 3 6 7 6


Listing of Simulation Content (continued)

Vessel Lights


At Night Y Y Y Y Y Y Y Y Y Y

NavAids 0 0 0 0 0 0 0 0 0 0


Vessels 2 2 2 2 3 2 3 5 3 6


Events 1 1 1 1 1 1 1 1 1 1

Regions 1 1 1 1 1 1 1 1 1 1

11 12 13 14 15 16 17 18 19 20


NavAids 0 0 0 0 0 0 0 0 0 4


Vessels 2 2 2 2 2 3 2 2 3 3


Events 1 1 1 1 1 1 1 1 1 1

Regions 1 1 1 1 1 1 1 1 1 1




NavAids 2 5 2 2 4 0 0 0 0 0


Vessels 1 0 2 3 0 0 0 0 0 0


Events 1 1 1 1 1 1 1 1 1 1

Regions 6 10 6 2 5 2 2 2 6 8

11 12 13 14 15 16 17 18 19 20


NavAids 1 4 2 4 4 0 0 0 1 0


Vessels 0 0 0 0 2 0 0 0 1 3


Events 1 1 1 1 1 1 1 1 1 1

Regions 5 9 7 10 5 1 2 2 5 1


Listing of Simulation Content (continued)



At Night N Y N Y N N Y Y N N

NavAids 0 2 5 5 1 0 0 0 4 0


Vessels 2 4 0 0 1 0 0 0 0 0


Events 1 1 1 1 1 1 1 1 1 1

Regions 4 2 9 8 5 3 2 4 6 3

11 12 13 14 15 16 17 18 19 20

At Night N Y N Y N N Y Y N N

NavAids 0 0 2 2 1 0 0 1 4 0


Vessels 2 0 0 0 1 0 0 0 0 0


Events 1 1 1 1 1 1 1 1 1 1

Regions 3 2 8 8 6 2 1 1 7 1


Listing of Navigation Aids

Note: Greyed-Out navigation aid are not available in the current version, but are required to

support future simulations

Type Day Mark Bouy Lighted Day Mark

Lighted Bouy

Small Light

Tower

Medium Light

Tower

Light House

Feature: port side X X X X

starboard side X X X X

preferred starboard X X X X

preferred port X X X X

safe water X X X X

isolated danger X X X X

special X X X X

special nun X X X X

no lateral - white X

no lateral - red X

no lateral - green X

port side (intercoastal)

starboard side (intercoastal)

preferred starboard (intercoastal)

preferred port (intercoastal)


Listing of Vessels

Characteristics

Vessel: Length (meters)

Boundary (ratio)

Max Speed (Knots)

Max Turn Rate

(degrees)

Notes

Tanker 300 0.5 15 5

Medium Trawler

60 1.5 18 15 Trawling – engaged in fishing with net

Small Fishing 15 0.75 8 15

Large Power Boat

30 0.75 12 15

Medium Power Boat

15 0.75 9 15 Can display diving flags and lights

Recreational Fishing Boat

15 0.75 9 15 Is NOT privileged as engaged in fishing

Small Power Boat

7 0.75 25 20 Uses combo light and all round masthead light not on centerline

Large Sail Boat

25 0.75 12 12 Uses red and green mast top light

Medium Sail Boat

15 0.75 9 20 Side lights in front of masthead light. Under sail, uses tri-light

Sail Boat (Jib Only)

15 0.75 9 20 Can be used as upwind vessel indeterminant main sail

Catboat 5 0.75 6 15

Kayak 4 0.75 4 20 Uses all round white light

Hoover Craft 12 0.75 30 25 Non displacement mode uses flashing light


Listing of Vessels

Note: Vessels not available in the current version. Required to support future simulations

Characteristics

Vessel: Length (meters)

Boundary (ratio)

Max Speed (Knots)

Max Turn Rate

(degrees)

Notes

Cruise Ship 250

Container 200

Freighter 100

Cable Layer Displays restricted movement lights

Great Lakes Cargo

150 Uses all round white stern mast head light

Small Cargo 49

Large Tug – Pull

Small Tug – Pull

Tug – Alongside

Tug – Push

Tug – Composite

Tug Partially

Submerged

Large Trawler 150 Trawling with nets and outrigging over 150 meters

Large Patrol Boat Can support mine sweeping operation

Medium Patrol Boat

Small Patrol Boat

Pilot Boat Displays pilot flag and lights

Dinghy Uses flashlight yellow light

WIG Uses flashing red light

Submarine Uses amber light

Square Rigged Sail Boat

Can be used to test knowledge on determining

sail tack from yard arm positions

Naval Ship Can be used to ensure “first person” maintains

required distance


Nautical Chart Conventions and Information

The following conventions are used when creating nautical charts for use with simulations:

Size of Chart Image: 2400 X 1200 pixels Size of Chart Itself on Image: 1900 X 950 pixels Chart Number Font: Calibri 32 Chart Title: Calibri 34 Location Names on Chart: Calibri 32 Nautical Mile Legend: Calibri 20 Join Chart Notes: Calibri 22 Navigation Aid Identification Text: Calibri 22 Depth Values: Courier 22

Chart Scale Area Coverage

24 Chart include 1 degree and 50 minutes of longitude

6 Chart include 27 minutes of longitude

4 Chart include 18 minutes of longitude

3 Chart include 13 minutes of longitude on chart

2 Chart include 9 minutes of longitude on chart

Chart Scale Meters per Pixel

24 231.6

6 57.9

4 38.6

3 29.0

2 19.3


Coordinates of features on Rectanguland

Location Latitude Longitude North West Corner of Rectanguland 26° 09' 10" N 89° 36’ 55” W

South West Corner of Rectanguland 24° 22' 10" N 89° 36’ 55” W

North East Corner of Rectanguland 26° 09' 10" N 85° 57' 10" W

South East Corner of Rectanguland 24° 22' 10" N 85° 57' 10" W South West Corner of Square Island 25° 00’ 00” N 85° 32’ 55” W North East Corner of Square Island 25° 15’ 50” N 85° 13’ 50” W North Corner of Big Bay Entrance 25° 35' 00" N 85° 57' 10" W South Corner of Big Bay Entrance 25° 09' 15" N 85° 57' 10" W North West Corner of Big Bay 25° 35' 00" N 87° 55’ 00” W

North West Corner of City Harbor 25° 49’ 10” N 87° 41' 55" W

North East Corner of City Harbor 25° 49’ 10” N 87° 15' 05" W South West Corner of City Harbor 25° 35' 00" N 87° 41' 55" W South East Corner of City Harbor 25° 35' 00" N 87° 15' 05" W North East Corner of City Harbor Breakwater 25° 35’ 35" N 87° 15' 05" W South West Corner of City Harbor Breakwater 25° 35’ 07" N 87° 22' 00" W (Breakwater Height is 8 meters) South East Corner of Big Bay 24° 56’ 30" N 86° 21' 20" W North West Corner of South Bay North East Corner of South Bay 24° 49' 15" N 86° 27' 00" W

(East Shore of South Bay Height is 10 meters) South West Corner of Alpha Island 24° 33' 05" N 86° 32' 40" W North East Corner of Alpha Island 24° 35' 55" N 86° 31' 00" W

(Alpha Island Height is 25 meters) South West Corner of Beta Island 24° 31' 00" N 86° 41' 30" W North East Corner of Beta Island 24° 29' 10" N 86° 31' 55" W

(Beta Island Height is 15 meters) South West Corner of Charlie Island 24° 25' 45" N 86° 35' 50" W North East Corner of Charlie Island 24° 29' 10" N 86° 31' 55" W

(Charlie Island Height is 8 meters) South West Corner of Large Inlet 24° 22' 10" N 87° 14' 05" W North East Corner of Large Inlet 24° 23' 10" N 87° 08' 10" W South West Corner of Medium Inlet 24° 22' 10" N 86° 56' 50" W North East Corner of Medium Inlet 24° 23' 10" N 86° 55' 00" W South West Corner of Small Inlet 24° 22' 10" N 86° 38' 00" W North East Corner of Small Inlet 24° 23' 10" N 86° 37' 15" W

(Land Around Inlet Heights is 10 meters)


Developer Notes:

Creating Simulations

If there is demand for “NavRuleSim”, the long term plan is to create a python based GUI editor

for the simulation configurations. The editor will allow sections of Rectanguland to be selected

and then nautical objects would be placed into the simulation using the GUI. Control objects

such as pulldown menus, radio buttons and text boxes will allow the assignment of properties

to the nautical objects as well as the definition of the animation events. But this will be in the

future.

Currently simulations must be manually written as XML files. The allowed elements are defined

in the “template.xml” file which is located in the “navrulesim” package of source code.

Since any errors in an XML file will occur as run time errors, it is important to test that an XML

configuration file correctly defines presentation modules.

At the current version of the application, no checking of the XML files for correct syntax is

performed. It is recommended to use and existing XML configuration file as a template when

creating new XML configuration files.

Development Mode Window:

The “NavRuleSim” has a developer mode feature that by default is not included in the

application build. To include, ENABLE_DEVELOPMENT_MODE must be set to true in the settings

configuration when the application is built.

To access the developer mode, while in the reference user screen, press the ‘d’ key. A separate

development console screen will appear. Normally when viewing vessels in the reference user

screen, the mouse control only allows the rotation of the vessel view. The console contains a

check box which allows the mouse to control both rotation and pitch. This allows the angle of

view from the ocean surface to change. A vessel can be observed from any angle. This feature is

useful when creating a new vessel to use in simulations. It allows the vessel’s appearance to be

inspected for correct construction. The console contains text boxes to define the vessel’s speed

and direction as well as the true wind’s speed and direction. These can be used to control the

appearance of sails and flags. After entering values, select the refresh button to adjust the

vessel appearance to the new values. (The apparent wind values are derived from the vessel’s

and true wind’s values. The apparent wind values cannot be adjusted. They are only displayed.)

When the ocean is included in the reference screen it is not possible to observer the vessel

from below. All that will be seen is the bottom of the ocean plane. The vessel display buttons

can be used to control if the ocean and vessel base is included with the view of the vessel.


The development console modifies the camera position as currently configured in the reference

user screen. The reset button will return the camera view to the reference configuration.

Selecting the quit button will close the development mode window and return the reference

screen to the original settings prior to enter into the development mode.

Editing FXML files:

The CSS files are not associated with the FXML files. (The CSS files are added to the Scene when

the application is first started.) When editing a JavaFX GUI using scenebuilder, the layout will

appears without css formatting. Temporarily adding the relative location of the css file to the

FXML fill will allow the layout to be edited while observing the correct css style. Once editing is

complete the reference to the css file must be removed. Otherwise a fail to load css file will be

displayed when the application is run. (When the package is built the reference to the css file

from the FXML file changes. This is the reason, the css files are added directly to the scene by

the application.) The following tag can be used to associate the css file:

stylesheets="@../../../../../../presentationModules/settings/navrulesim.css"

Default CSS:

When not modified by navrulesim.css file, formatting conforms to the default. The default css

file is in the following locations for the different operating systems:

For Windows: Located in lib folder in the javafx-sdk-13.01 is the Javafx.controls.jar file unzip Javafx.controls.jar file

For Linux or OSX: Located in the javafx-jmods-13.01 folder is the javafx.controls.jmod file

unzip the javafx.controls.jmod file

1) The unzipping will create the extracted javafx.control folder 2) Located in the following directory com/sun/javafx/scene/control/skin/modena 3) The default CSS file is the file modena.css

Creating New Vessels:

A template named VesselTemplate exists within the nauticalworld package. This template can

be used when creating new vessels. In addition to providing a guideline on how to structure

shapes to create a vessel, the template includes checks to ensure the vessel design conforms to

USCG regulations. The output of the checks is displayed to console using System.out.println

commands. Once it has been determined that the newly created vessel conforms to

regulations, the checks should be removed from the new vessel class.


Viewing Nautical Objects Besides Vessels:

The source code only supports the viewing of vessels in the reference user screen, but the code

in the “ScreenControllerReference.java” file can be easily modified to allow other nautical and

terrestrial objects to be viewed. Code should be modified in three locations

1) Around line 20 in the section of code which includes the statement import org.duncanharbor.nauticalworld.VesselBase;

add the packages for the object you wish to observe.

For example, to observer a daymark the following lines would be added: import org.duncanharbor.nauticalworld.NavAidBase;

import org.duncanharbor.nauticalworld.NavAidDaymark;

to observer a church the following lines would be added: import org.duncanharbor.terrestrialobjects.LandmarkBase;

import org.duncanharbor.terrestrialobjects.LandmarkChurch;

2) Around line 140 in the section which include the statement:

VesselBase vessel;

add the definition for the object you wish will be observed.

For example, to observe a daymark, the following line would be added: NavAidBase navAid;

to observe a daymark, the following line would be added: LandmarkBase landmark;

3) Around line 516 in the section which includes line: nauticalWorld.getChildren().add(vessel);

comment out the above line, create the object you wish to observer and add that object

to the nautical world.

For example, to observer a daymark, the line changes and line adds would be made: //nauticalWorld.getChildren().add(vessel);

navAid = new NavAidDayMark

(NavAidBase.NavAidFunction.STARBOARD_SIDE, '4');

nauticalWorld.getChildren().add(navAid);

to observer a church, the line changes and line adds would be made: //nauticalWorld.getChildren().add(vessel);

landmark = new LandmarkChurch

(0,0,0,0, NauticalEnvironment.Condition.DAY);

nauticalWorld.getChildren().add(navAid);

The object defined with the modified code will be displayed when the reference user screen is

initialized.


Viewing Vessels and Their Base:

When inspecting a newly created vessel, it is often necessary to observe the vessel base but not

the ocean. This is possible by modifying the source code in the

“ScreenControllerReference.java” file.

Around line 269, simply comment out the line which adds the ocean to the nautical world.

//nauticalWorld.getChildren().add(ocean);


Overlays:

The 2D overlays used to represent the “first person” vessel are created from 2D shapes. The overlay is initially designed using a

bitmap editor such as Microsoft Paint. For reference, this section includes the images used to layout the overlay designs.

(Note: The purple dash lines mark the edge of the smaller 3D world display pane used in the Learn and Test screens.)


1 MAST_TOP 0.02 windowHeight

2 SAIL_HEAD halfWindowWidth windowHeight

3 BOOM_INNER_TOP 0.00 0.47

4 U boomOuterTop halfWindowWidth 0.47

4 L halfWindowWidth 0.04

5 SAIL_TACK 0.00 0.45

6 U mainSheetEnd 0.26 0.45

6 L 0.26 0.23

7 U SailClew halfWindowWidth 0.45


8 BOOM_INNER_BOTTOM 0.00 0.43

9 U boomOuterBottom halfWindowWidth 0.43


10 ANEMOMETER_TOP 0.03 0.40

11 ANEMOMETER_BOTTOM 0.03 0.31

12 COMPASS_TOP 0.05 0.30

13 COMPASS_BOTTOM 0.05 0.26

14 KNOT_METER_TOP 0.05 0.25

15 KNOT_METER_BOTTOM 0.05 0.21

16 HULL_START 0.00 0.20

17 MAST_BOTTOM 0.02 0.17

18 ROOF_FRONT 0.12 0.17

19 WINCH_TOP 0.00 0.160

20 WINCH_TOP_EDGE 0.02 0.154

21 HULL_PT1 0.13 0.15

22 WINCH_CENTER 0.00 0.148

23 WINCH_BOTTOM_EDGE 0.02 0.142

24 WINCH_BOTTOM 0.00 0.136

25 ROOF_REAR 0.15 0.13

26 DOOR_TOP 0.06 0.12

27 HULL_PT2 0.22 0.10

28 COCKPIT_FRONT 0.15 0.10

29 SEAT_EDGE_FRONT 0.11 0.07

30 SEAT_BACK_FRONT 0.15 0.07

31 DOOR_BOTTOM 0.06 0.04

32 SOLE_FRONT 0.11 0.04

33 THROTTLE_PIVOT 0.18 0.03

34 HULL_END 0.32 0.00

35 SOLE_REAR 0.125 0.00

36 SEAT_EDGE_REAR 0.14 0.00

37 SEAT_BACK_REAR 0.19 0.00

38 COCKPIT_REAR 0.21 0.00

39 RUDDER_PIVOT 0.00 0.06

Winch WINCH_START 0.06 0.175

WINCH_CENTER 0.06 0.150

WINCH_END 0.06 0.125

Throttle THROTTLE_START 0.16 0.12

THROTTLE_CENTER 0.19 0.07

THROTTLE_END 0.21 0.03

Rudder RUDDER_START 0.11 0.05

RUDDER_CENTER 0.00 0.05

RUDDER_END 0.11 0.05

WINCH_RADIUS 0.02 0.008

WINCH_BOTTOM_CENTER 0.00 0.142

WINCH_TOP_CENTER 0.00 0.154

Origin Origin 0.00 0.00

Center 0.00 windowHeight

• When a value, the X and Y coordinate distances define the ratio of the initial OVERALL APPLICATION pane width

• The display window width may be different than the initial overall width. If the window width is different or changes, the overlay is scaled to maintain proper proportions.


• The sail, boom and mast must extend to the edge of the display window, but for different user screens, these edges are different ratio values of the overall application pane width. Therefore, these values are not expressed as ratios. The edge values are expressed as the actual initial display window dimensions.


1 SAIL_TOP -halfWindowWidth windowHeight

2 U sailHead -0.27 windowHeight

2 L

0.27 windowHeight

3 BOOM_INNER_TOP -halfWindowWidth 0.47

4 U sailEdge -0.27 0.47

4 L

0.27 0.47

5 U boomOuterTop -0.25 0.41

5 L 0.29 0.47

6 sailClew -0.27 0.415

7 U mainSheetEnd -0.45 0.44

7 L

-0.21 0.45

8 BOOM_INNER_BOTTOM -halfWindowWidth 0.43

9 U boomOuterBottom -0.25 0.37

9 L

0.29 0.43

10 MAIN_SHEET_EDGE -halfWindowWidth 0.20

11 SIDE_BOW -halfWindowWidth 0.07

12 SIDE_STERN 0.26 0.07

13 COCKPIT_BOW -halfWindowWidth 0.02

14 COCKPIT_STERN 0.16 0.02

15 SEATBACK_BOW -halfWindowWidth 0.00

SEATBACK_STERN 0.16 0.00

16 COCKPIT_CENTER 0.17 0.00

17 STERN 0.33 0.00

18 SIDE_STERN 0.25 0.06

19 RUDDER_POST_BACK_EDGE 0.00 0.04

20 RUDDER_POST_EDGE 0.02 0.03

21 SIDE_BOW 0.30 0.00

RudderPost RUDDER_POST_CTR 0.00 0.06 RADIUS 0.02 0.01

Tiller PIVOT 0.00 0.06 END 0.00 0.00

22

0.45 0.03

23

0.43 0.05

24

0.43 0.04

25

0.41 0.04

26

0.41 0.02

27

0.43 0.032

28

0.43 0.01




1 DOOR_EDGE_TOP -0.37 windowHeight

2 BACK_WALL_UPPER_STARBOARD -0.16 windowHeight

3 COMPANIONWAY_UPPER_STARBOARD 0.25 windowHeight

4 COMPANIONWAY_UPPER_PORT halfWindowWidth windowHeight

5 CLOCK_FRAME_UPPER_LEFT -0.14 0.48

6 CLOCK_FRAM_UPPER_RIGHT 0.02 0.48

7 CLOCK_PANE_UPPER_LEFT -0.13 0.47

8 RADIO_UPPER_LEFT 0.07 0.46

9 CLOCK_PANE_LOWER_RIGHT 0.01 0.42

10 CLOCK_FRAME_LOWER_LEFT -0.14 0.41

11 CLOCK_FRAME_LOWER_RIGHT 0.02 0.41

12 RADAR_FRAME_UPPER_LEFT -0.13 0.34

13 RADAR_FRAME_UPPER_RIGHT 0.21 0.34

14 RADAR_PANE_UPPER_LEFT -0.12 0.33

15 COMPANIONWAY_LOWER_STARBOARD 0.25 0.20

16 LADDER_TOP 0.28 0.20

17 COMPANIONWAY_LOWER_PORT halfWindowWidth 0.20

18 RADAR_PANE_LOWER_LEFT 0.20 0.18

19 CHART_TABLE_BACK_LEFT -0.16 0.16

20 RADAR_FRAME_LOWER_RIGHT 0.21 0.17

21 CHART_TABLE_BACK_RIGHT 0.25 0.16

22 CHART_TABLE_FRONT_LEFT -0.32 0.11

23 CHART_TABLE_FRONT_RIGHT 0.25 0.11

24 UPPER_RUNG_UPPER_LEFT 0.28 0.13

25 UPPER_RUNG_UPPER_RIGHT halfWindowWidth 0.13

26 CHART_TABLE_EDGE_BOTTOM_LEFT -0.32 0.10

27 BACK_WALL_MID_STARBOARD -0.16 0.10

28 CHART_TABLE_EDGE_BOTTOM_RIGHT 0.23 0.10

29 UPPER_RUNG_LOWER_LEFT 0.28 0.10

30 UPPER_RUNG_LOWER_RIGHT halfWindowWidth 0.10

31 LOWER_RUNG_UPPER_LEFT 0.28 0.04

32 LOWER_RUNG_UPPER_RIGHT halfWindowWidth 0.04

33 DOOR_EDGE_BOTTOM -0.37 0.00

34 BACK_WALL_LOWER_STARBOARD -0.16 0.00

35 CHART_TABLE_SIDE_BOTTOM_LEFT 0.23 0.00

36 CHART_TABLE_SIDE_BOTTOM_RIGHT 0.25 0.00

37 LOWER_RUNG_LOWER_LEFT 0.28 0.01

38 LOWER_RUNG_LOWER_RIGHT halfWindowWidth 0.01




1 UPPER_CORNER_UPPER_WALL halfWindowWidth windowHeight

2 UPPER_CORNER_SIDE_WALL 0.33 0.45

3 LEFT_UPPER_CORNER_WINDOW_RAIL 0.17 0.45

4 UPPER_WIRE_END 0.00 0.45

5 RIGHT_UPPER_CORNER_WINDOW_RAIL 0.16 0.45

6 LOWER_CORNER_UPPER_WALL halfWindowWidth 0.45

UPPER_CONE_BASE_CENTER 0.00 0.42

CONE_BASE_RADIUS 0.02 0.01

7 UPPER_CONE_CORNER 0.02 0.42

8 UPPER_CONE_POINT 0.00 0.39

9 LOWER_CONE_CORNER 0.02 0.32

10 LOWER_CONE_BOTTOM 0.00 0.31

11 HULL_START 0.00 0.23

12 HULL_PT1 0.15 0.21

13 HULL_PT2 0.14 0.17

14 DECK_START 0.00 0.15

15 DECK_PT1 0.05 0.14

16 WHEEL_PEG_TOP 0.00 0.18

17 DECK_PT2 0.14 0.12

18 WHEEL_PEG_SIDE 0.01 0.145

19 LOWER_CORNER_SIDE_WALL 0.33 0.10

20 DECK_END 0.17 0.10

21 LEFT_LOWER_CORNER_WINDOW_RAIL 0.17 0.10

22 WHEEL_PEG_BOTTOM 0.00 0.11

23 WHEEL_PEG_CENTER 0.108 0.105

24 RIGHT_LOWER_CORNER_WINDOW_RAIL 0.16 0.10

25 UPPER_CORNER_LOWER_WALL halfWindowWidth 0.10

LOWER_CONE_BASE_CENTER 0.00 0.32

WHEEL_PEG_RADIUS 0.01 0.035 WHEEL_PEG_VERTICAL 0.00 0.145 WHEEL_PEG_45DEG

WHEEL_PEG_HORIZONTAL 0.145 0

RADIO_LEFT_UPPER_CORNER -0.32 0.08 RADIO_RIGHT_UPPER_CORNER -0.16 0.08 RADIO_LEFT_LOWER_CORNER -0.32 0.04 RADIO_RIGHT_LOWER_CORNER -0.16 0.04

SPEAKER_LEFT_UPPER_CORNER -0.20 0.075 SPEAKER_RIGHT_UPPER_CORNER -0.18 0.075 SPEAKER_LEFT_LOWER_CORNER -0.20 0.045 SPEAKER_RIGHT_LOWER_CORNER -0.18 0.045

HANDSET_CENTER -0.29 0.04 HANDSET_RADIUS 0.02 0.025

MIC_CENTER -0.29 0.045 MIC _RADIUS 0.015

WIRE1_START -0.29 0.015

WIRE1_END -0.29 0.00

WIRE2_START -0.26 0.06

WIRE2_END -0.26 0.00

SIGN_LEFT_UPPER_CORNER -0.31 0.495

SIGN_RIGHT_UPPER_CORNER -0.11 0.495 SIGN_LEFT_LOWER_CORNER -0.31 0.455

SIGN_RIGHT_LOWER_CORNER -0.11 0.455




1 Top Left Smoke Section Orange arc1 Arc

2 Top Right Smoke Section Orange arc2 Arc

3 Smoke Section 7 Orange circle7 Circle







10 Flare Black flare Polygon Smoke Outline 1 Black arc3 Arc

Smoke Outline 2 Black arc4 Arc






Smoke Outline 8 Black arc10 Arc Smoke Outline 9 Black arc11 Arc Smoke Outline 10 Black arc12 Arc Smoke Outline 11 Black arc13 Arc Smoke Outline 12 Black arc14 Arc Smoke Outline 13 Black arc15 Arc Smoke Outline 14 Black arc16 Arc



• The top edge of the smoke must extend to the edge of the display window, but for different user screens, these edges are different ratio values of the overall application pane width. Therefore, these values are not expressed as ratios. The edge values are expressed as the actual initial display window dimensions.


Shape Components:

Most of the 3D nautical objects are created using the sphere, cylinder and cube supported by JavaFX. But some objects require more

complicated shapes. These objects are MeshViews contained in the Nautical component class. This section contains details on these

shape components.

Technical Specification - Duncan Harbor · Version 0.90 NavRuleSim Technical Specification Page 4...

Documents

Transcript of Technical Specification - Duncan Harbor · Version 0.90 NavRuleSim Technical Specification Page 4...