User Manual

From LagoonWiki

Jump to: navigation, search

Contents

Lagoon User Manual

Download the Lagoon User Manual in PDF format: 12M

Abbreviations

  • CAT - Controller Authoring Tool
  • GUI - Graphical User Interface
  • SP - Strategic Planner

Introduction

Overview

Lagoon is a 3D environment for naval surface simulation and training. Its main purpose is to help navy officers and trainees better prepare against potential attacks by swarms of small boats. To achieve this, two major modes of operations are supported in Lagoon:

  • Authoring, during which scenarios involving a variety of entities (ships) are created and saved as learned behaviors (internally, these are represented as behavior networks), and
  • Execution, during which recorded behaviors (scenarios) are played back under the user’s control.

In both authoring and execution modes of operation the users can select individual entities or groups of entities in Lagoon and maneuver them using a set of commands available via Lagoon’s GUI. Details of these commands as well as of the other features provided by the environment are given throughout this user manual.

As shown in Fig. 1, the main parts of Lagoon’s GUI are: (i) Lagoon 3D world, (ii) CAT controller, (iii) SP. In addition, some Lagoon functions are available through the software’s menu bar.


Specific details of operations for the first three (Lagoon World, CAT, and SP) are further given in their dedicated sections.

Image:Lagoon_um_fig1.jpg

Menu Bar

Lagoon’s menu bar (Fig. 2) allows access to a number of operations, as follows:

  • The File menu (Fig. 3) allows saving and loading files as well as exiting the system;
  • The VShipComm menu (Fig. 4) I used in connection with COVE, specifically for getting harbor information from the COVE world as well as for connecting and disconnecting with this external environment (COVE);
  • The Exec menu has (Fig. 5) has only one menu item, Execute, which is used for executing a plan (further details are given in Section 4);
  • The Formations menu (Fig. 6) is used as an alternative for grouping entities (units) into three types of formation: column formation, V-formation, and row formation (grouping entities can be performed directly using Lagoon World’s petal menu detailed in Section 2 of this manual);
  • The Flags menu (Fig. 7) provides access to two types of umpire cues: start scenario and target query.
  • The Tools menu (Fig. 8) gives access to advanced explorer features of the environment. These are used mostly for debugging purposes but could also provide good insight to users into the status of the Lagoon environment, as follows:
    • Option Explorer submenu (Fig. 9), with the following subcategories:
      • Boolean Options submenu (Fig. 10), allowing various binary settings such as enabling/disabling fire, enabling/disabling weapons doing damage, enabling/disabling “sticky select” option, and so forth;
      • Tools submenu (Fig. 11), containing facilities for exploration such as logexplorer, evaexplorer, and soundexplorer;
      • Cove submenu (Fig. 12), with details on connecting to Cove such as the IP of the Cove server;
      • Game submenu (Fig. 13), with settings such as plan loaded, side selected, and skybox used;
      • Networking Options submenu (Fig. 14), with information on current machine and its networking characteristics(e.g., is it working as a server or as client);
    • Eva Explorer submenu (Fig. 15)
    • Sound Explorer submenu (Fig. 16)
    • IM Explorer (Fig.17)

Lagoon 3D World

The Lagoon World is the actual graphical 3D domain in which ships are created and maneuvered by users. Detail of its characteristics and operational capabilities are given in Section 2 of this manual.

CAT Interface

CAT allows authoring and execution via direct control of individual entities (users control are given via CAT’s Command panel). In addition, visualization of the current state of a behavior’s execution is also possible via CAT’s Visuals panel. Details of CAT’s capabilities are provided in Section 3 of this manual.

Lagoon World

Overview

The main elements present in Lagoon World’s GUI are a compass and an indicator of simulation speed (Fig. 8). An essential interface device for operating within Lagoon is the Petal menu, which gives access to a variety of user operations. This menu is detailed next.

The Petal Menu

The Petal Menu, whose name comes from its resemblance with a round-shaped flower with symmetrical petals, is an innovative interface device that uses a compact form to give access to a variety of user operations.

These are illustrated next, starting with the Petal Menu’s main layer (or main menu) (Fig. 9) and then continuing “top-down” inside the hierarchy of layers (or submenus) that make up the Petal Menu’s structure: Battle Master (Fig. 10), Camera Controls (Fig. 11), Time Controls (Fig. 12), Create Entity (Fig. 13), Create Large Entity (Fig. 14), Create Medium Entity (Fig. 15), Create Small Entity (Fig. 16), Battle Master Miscellaneous (Fig. 17), Move Entity (Fig. 18), Entity (Fig. 19), Groups (Fig. 20), Assign to Group (Fig. 21), Entity Set Side (Fig. 22), Target (Fig. 23), and Target Group (Fig. 24).


Entity and Group Markers

The following visual circular markers, each with a specific contour color (as specified next) are used in Lagoon (QQQ Fig. 24A):

  • BLUE - Cursor over entity
  • YELLOW - CAT selected
  • GREEN - SP selected
  • RED - Target selected

In addition, for easier “at sea” identification from a distance, additional markers are attached to entities (these are visible only at a higher level of zooming out):

  • TRIANGLE - Small size entity
  • SQUARE - Medium size entity
  • POLYGON - Large size entity

Other visual markers in Lagoon World are:

  • Target line - ORANGE line from an entity to its selected target (Fig. 36)
  • Distance trigger line - YELLOW line between two entities (Fig. 37)
  • Current heading - BLUE line from the entity (Fig. 38)
  • Move-to point - LIGHT GREEN glowing point the entity is moving to (Fig. 38)

CAT

Overview

CAT allows authoring and execution via direct control of individual entities. As shown in Fig. 39, CAT’s GUI consists of two panels, accessible via the tabs Command and, respectively, Visuals. Specifically, user control and entity information are available via CAT’s Command panel (Fig. 40 – Authoring mode and Fig. 41 – Execution mode) while visualization of the current state of a behavior’s execution is available via CAT’s Visuals panel (to be included in future versions of the Lagoon environment).

The structure of the Command panel varies in time depending on the chosen mode of operation – the Mode Toggle buttons of the Mode (sub)panel (top of Command panel, as pointed out in Fig. 40) can be used to switch between Authoring and Execution.

Mode Panel

The Mode panel (Fig. 26, top) serves for switching between Authoring and Execution. The mode shown (Execution in Fig. 26) is the current mode of operation for the selected entity.

Entity Panel

The Entity panel (Fig. 40, second from top) displays information about the selected entity and allows setting the desired heading (by using the knob’s red needle), the desired speed (by using the vertical slider on the left-hand side of the panel), the desired “safety factor”, i.e. the weight of avoiding collision (by using the horizontal slider on the left-hand side of the panel), and the desired “objective factor”, i.e. the weight of achieving the entity’s objective (by using the horizontal slider on the right-hand side of the panel).

Behavior Control Panel

The Behavior Control panel (Fig. 40, center) serves for controlling the behavior of the selected entity. The small, 2-letter marked buttons on top of this panel provide the interface for accessing one of 7 possible primitive behaviors. When the cursor is over such a button a tool-tip indicates the full name of the primitive behavior the button is associated with. For easier identification 2 letters are assigned to these behavior buttons as follows:

  1. AP - Approach (Fig. 42 and Fig. 43)
  2. MA - Maintain Station (Fig. 44 and Fig.45)
  3. RA - Ram (Fig. 46 and Fig. 47)
  4. MO - MoveTo (Fig. 48 and Fig.49)
  5. FI - Fire (Fig. 52)
  6. AL - Avoid Land (Fig. 50)
  7. AE - Avoid Entity (Fig. 51)

In addition, a small red button is used to clear (stop) all entity’s primitive behaviors. The Behavior Control Panel has a sub-panel, the Target panel (Fig. 53), which provides information about the selected target, if any, of the selected entity.

Triggers Panel

This panel (Fig. 54 and Fig. 55) allows creating and firing various types of triggers. In Authoring mode a new trigger can be created, deleted, fired, and queried for its detailed information (Fig. 54) while in Execution mode an existing trigger can only be fired and its detailed information displayed (Fig. 55).

Currently, the three types of triggers that can be created are Alert, Distance, and Damage (Fig. 56). While Alert is a boolean flag, Distance and Damage need be further defined as either “less than”, “greaterThan”, or “approx” (Fig. 57). Additional details are needed to create specific triggers, as shown in Figs. 58, 59, and 60. Information on a trigger can be obtained by clicking the Info button (Fig. 61) and, in Authoring mode only, a trigger can also be deleted (Fig. 62).

Visuals Panel

The Visuals panel will be incorporated in the near future into CAT’s GUI.

SP

Overview

SP is responsible for organizing entities into groups, and assigning CAT tasks to those groups. In addition, it displays a variety of information about the state of the Lagoon world. This section details information on the usage of SP, describing the interface and all of its components. The main component of SP’s GUI are shown in Fig. 44.

Information Panel

The Information panel (Fig. 44, left hand-side) shows information on what is currently selected. This can be helpful in selecting a particular entity or in getting information about an entity. Furthermore, it has two buttons that allows loading (Fig. 45) and, respectively, saving a plan (Fig. 46). In Fig. 45, notice that if the Run Immediately checkbox is checked then all entities of the plan are loaded as quickly as possible. Otherwise, the entities are loaded at the same speed they were created when constructing the plan.

Assignment Info Panel

The Assignment Info panel (Fig. 47) displays information on the currently selected group. It shows the name of the group and what it has been assigned to do, including its target.

As shown in Fig. 48, the colors attached to the entities in groups can be either GRAY (neutral entities), BLUE (own entities, or friendly), or RED (enemy entities).

Groups Panel

The Groups panel (Fig. 63, center) is used for creating new empty groups, as well as for splitting and merging existing groups. Dragging a box in the 3D world over units designates them to be added to this new group. The user can control-click on the entity list to select or deselect individual entities. He or she needs to choose a side for this group to belong to as well as a name, and then hit a group number button (digits between 0 and 9). Entities will be removed from any groups they currently belong too, and added to the new group.

Individuals Panel

The Individuals panel (Fig. 44, center-right) shows the list of individuals in the world - entities that have not been assigned to a group.

Tasks Panel

The Tasks panel (Fig. 44, right-hand side) contains all available tasks. New tasks created through CAT will be added to this list.
 To designate which task a group should follow select the group from the list, then click on the appropriate task. 
Some tasks require a point, target or both. These can be designated by right clicking in the 3D world.

Minimap

The minimap (Fig. 49 and Fig. 50) shows the positions of units in the world from a top down view. It is useful to survey the situation in Lagoon. In the future support will be included for right clicking in it to command units.

Scenarios

Authoring Scenarios

In Authoring mode scenarios can be recorded and saved using the recorder device available in the CAT’s Command panel (Fig. 49). From left to right the buttons available on the Recorder panel are:

  • SAVE
  • START RECORDING
  • PAUSE
  • STOP

When saving a scenario the dialog that opens (Fig. 50) prompts the user for a name of the behavior (network) to be saved as well as for the name of the file which will store that behavior.

Executing Scenarios

In Execution mode scenarios can be loaded and executed using the playback device available in the CAT’s Command panel (Fig. 70). From left to right the buttons available on the Recorder panel are:

  • STOP
  • PAUSE
  • RUN
  • DELETE

To load a scenario the user has to select the behavior network to be executed from a drop-down list (Fig. 71).

Ship Models

Following there are 17 ship models that can populate the Lagoon system (Figures 54 to 70). These ships can be created through the Petal Menu under the “Battle Master—Create Ent” submenu option (details are given in Section 2). Ships can be controlled independently or in groups. Once a ship is created, its velocity and heading can be specified through the CAT interface (described in Section 3).

Connecting Lagoon with COVE

The following is a series of steps to connect Lagoon with COVE. You will need to know the IP address of the Windows machine where COVE is installed, or where COVE is planned to run.

  1. Start COVE.
  2. Open the “ConnectToLagoon.py” script on the script editor in COVE.
  3. Load and start the desired scenario and or exercise in COVE.
  4. Run the script loaded in the script editor in COVE.
  5. Start Lagoon with the “covehost” command line option, along with the IP address of the machine where COVE is running. The IP address given in the following example is a dummy IP address. You would replace the IP address shown with your corresponding address. Example: go covehost=192.134.0.1
  6. In Lagoon, go to the VShipComm menu option on the menubar and select the “Connect” option.
  7. This will connect Lagoon with COVE. The ship entities are controlled in Lagoon. If the speed of a ship is set in Lagoon, the corresponding entity in COVE will have its speed set to the same speed. Similarly, the heading of any entity is controlled in Lagoon.
  8. When done, in Lagoon, go to the VShipConn menu option on the menubar and select the “Disconnect” option.
  9. End the simulation by pressing F12. This will terminate Lagoon.
  10. End the COVE exercise by stopping the scenario, closing the script editor window, and exiting COVE.


Key Mappings

Key Action
A Move camera to the left
D Move camera to the right
E Rotate camera to the right
ESC Toggle scripting console
F Decrease simulation speed by half
F5 Output entity information on the console and terminal
F11 Take screenshot of 3D world
F12 Stop game
H Toggle display of collision meshes
G Decrease camera speed
L Toggle camera lock on ship
O Toggle sky active
P Toggle water active
Q Rotate camera to the left
R Double simulation speed
S Move camera up
T Increase camera speed
U Toggle display of axis
V Toggle display of octree
W Move camera down
X Camera zoom out
Y Toggle screen grid
Z Camera zoom in

Lagoon Tutorials

Download the Simple Attack Tutorial in PDF format

Download the San Diego Sneak Attack Tutorial in PDF format


Simple Attack

A. Authoring (recording) a simple attack behavior

  1. Create a DDG51 by right clicking in the Lagoon 3D world and selecting from the petal menu Battle Master -> Create Ent -> Large -> DDG51. Next, create a Cigarette boat behind the DDG51 (not too close to the DDG51, otherwise the scenario will not be as interesting). If needed, move in the Lagoon 3D world by using the move camera keys listed in the Key Mappings chapter of the Lagoon User Manual). Left click anywhere in the Lagoon 3D world, right click wherever you want the Cigarette boat to be created, then select from the petal menu Battle Master -> Create Ent -> Small -> Cigarette. See Fig.1 for ship positions.
  2. Switch to Authoring mode by clicking on the blue button at the top of the CAT interface, on the right-hand side of the screen.
  3. Start recording by clicking on the red round record button in the Recorder panel at the bottom of the CAT interface.
  4. Select the Cigarette boat by left clicking on it in the Lagoon 3D world.
  5. Create a new trigger by clicking on the New button in the Triggers panel of the CAT interface.
  6. Select the AlertSensor trigger type from the dropdown menu of the Triggers panel. Then click the Add button.
  7. Click on the AP (Approach) button in the Control panel of the CAT interface.
  8. In the Approach subpanel that is displayed (part of CAT Control panel) select Maintain speed from the dropdown list (if it is not already selected).
  9. You will have the Cigarette boat approach at maximum speed, so set the speed on the Approach subpanel to the maximum speed by moving the speed Selector slider to the right as far as it goes.
  10. Using the other two sliders of the Approach subpanel, change the New Station Range to about 450 yards and the New Station Bearing to about 90 degrees. For fine-tuning of slider values you can use the regular left and right arrow keys on the keyboard. If the relative option is not selected, make sure to select (by clicking on it) the Rel radio button at the bottom of the Approach subpanel.
  11. In the Lagoon 3D world set the target of the Cigarette boat by right clicking on the DDG51 and then selecting Select Target item from the petal menu. If the target was correctly set, you will see a blue line from the Cigarette boat to the DDG51, as shown in Fig. 2.
  12. Next, click on the Start button of the CAT Approach subpanel.
  13. Wait about five seconds and then, in the CAT Triggers panel, select the trigger previously created. Click next on the Fire button of the same panel.
  14. Click on the RA (Ramship) button in the Control panel of the CAT interface.
  15. You will have the Cigarette boat ram the DDG51 while maintaining speed, so in the Ramship subpanel that is displayed (part of CAT Control panel) select Maintain speed from the dropdown list (if it is not already selected).
  16. You will have the Cigarette boat ram the DDG51 at maximum speed, so set the speed in the Ramship subpanel to the maximum speed by moving the speed Selector slider to the right as far as it goes.
  17. Set the target of the ramship to the DDG51 as explained in step 11. After the target is set, the CAT Target panel will show DDG51 specific information (speed, heading, range, bearing, position XY).
  18. Next, click on the Start button of the CAT Ramship subpanel. The Cigarette will start running the Ramship behavior, as shown in Fig. 3.
  19. Wait about 3 seconds and then click on the Save button (leftmost button) in the Recorder panel at the bottom of the CAT interface.
  20. In the dialog menu that opens in the CAT Recorder panel enter a unique network name for the created behavior to be saved.

B. Executing the recorded simple attack behavior

Now you have recorded the simple attack behavior. Quit Lagoon (by pressing the F12 key with the cursor positioned over the 3D world) and then run it again. To run the recorded behavior follow these steps:

  1. Using the petal menu in the Lagoon 3D world, create a DDG51 and a Cigarette boat (see step A.1 for details). You can position them wherever you want. When playing back the recorded behavior the Cigarette boat will approach the DDG51 from the right and then ram it.
  2. Select the Cigarette boat in the Lagoon 3D world. With CAT in Execution mode, select the previously recorded behavior from the dropdown list of the playback (Load/Execute) panel at the bottom of the CAT interface. You will see the network name as you saved it.
  3. Start executing the behavior by clicking on the triangle-shaped play button in the playback (Load/Execute) panel at the bottom of the CAT interface.
  4. The Cigarette boat will start to approach the DDG51. When you decide to ram, in the CAT Triggers panel select the trigger from the triggers list and then click on the Fire button.
  5. When done, either click on the stop button (first from the right) on the CAT playback (Load/Execute) panel or quit Lagoon by pressing the F12 key with the cursor positioned over the 3D world.


San Diego Sneak Attack

A. Authoring (recording) a San Diego sneak attack

  1. Run Lagoon using the command go map=sandiego
  2. Create an FFG7 by right clicking in the Lagoon 3D world and then selecting from the petal menu Battle Master -> Create Ent -> Large -> FFG7.
  3. Right click on the FFG7 and then select from the petal menu Battle Master -> Place. Then hold the right click mouse and move it up and down to turn the FFG7 by 180 degrees. Let go off the mouse when the FFG7 is correctly oriented. The new heading should be 180 degrees.
  4. Now create a Cigarette boat below the FFG7 and to the right (at about 60 degrees) and a Launch boat to the left, so that the three ships form a triangle with the FFG7 being at the top of the triangle, as shown in Fig. 1. To create the two ships left click anywhere in the Lagoon 3D world, then right click where you want the new ship to be created, and select from the petal menu, respectively, Battle Master -> Create Ent -> Small -> Cigarette and Battle Master -> Create Ent -> Small -> Launch.
  5. Select the Cigarette boat by left clicking on it in the Lagoon 3D world.
  6. Switch to Authoring mode by clicking the blue button at the top of the CAT interface, on the right-hand side of the screen.
  7. Start recording by clicking on the red round record button found on the Recorder panel at the bottom of the CAT interface.
  8. Create a new trigger by clicking on the New button found on the Triggers panel of the CAT interface.
  9. Select the AlertSensor trigger type from the dropdown menu of the CAT Triggers panel. Then click the Add button in the same panel.
  10. Click on the MA (Maintain) button on the Control panel of the CAT interface.
  11. In the Lagoon 3D world set the target of the Cigarette boat by right clicking on the Launch boat and then selecting Select Target item from the petal menu.
  12. Using the corresponding sliders on the Maintain subpanel (part of CAT Control panel) set the new station range and the new station bearing to the same range and bearing shown in the CAT Target panel of the Cigarette boat. Round numbers if there are any decimals, and remember the bearing set for a future step (step 24).
  13. Click on the Start button of the CAT Maintain subpanel.
  14. Select the Launch boat by left clicking on it in the Lagoon 3D world.
  15. Switch to Authoring mode by clicking the blue button at the top of the CAT interface.
  16. Start recording by clicking on the red round record button found on the Recorder panel at the bottom of the CAT interface.
  17. Create a new trigger by clicking on the New button found on the Triggers panel of the CAT interface.
  18. Select the DistanceSensor trigger type from the dropdown menu of the CAT Triggers panel.
  19. Select approx from the trigger Subtype dropdown list in the CAT Triggers panel.
  20. Select the FFG7 from the To dropdown list and the Launch from the From dropdown list.
  21. Click on the Add button of the CAT Triggers panel.
  22. Click on the MA (Maintain) button on the CAT Control panel.
  23. In the Lagoon 3D world set the target of the Launch boat by right clicking on the Cigarette boat and then selecting Select Target option from the petal menu.
  24. Set the new station range in the Maintain subpanel to the same range shown in the target panel of the Launch boat. Set the bearing to 360 minus the bearing used previously in the Maintain subpanel of the Cigarette boat. That is, subtract the bearing used in step 12 from 360 and set this bearing using the new station bearing slider of the Launch.
  25. Click on the Start button of the Launch’s CAT Maintain subpanel.
  26. In the Lagoon 3D world, select the FFG7 (by left clicking on it) and make it move somewhere between and past the Cigarette and the Launch. Do this by right clicking on the desired final destination point in the Lagoon 3D world and then selecting the MoveTo item from the petal menu (see Fig. 2 for details).
  27. In the Lagoon 3D world select the Launch by left clicking on it and then in the CAT Triggers panel select the distance trigger previously created for this boat.
  28. When the distance between the FFG7 and the Launch decreases to be about 450 yards, click the Fire button of the CAT Triggers panel.
  29. Click on the RA (Ramship) button on the CAT Control panel.
  30. Using the maintain speed option and the speed Selector slider in the CAT Ramship subpanel set the ram speed to the maximum.
  31. In Lagoon 3D world set the Launch’s ram target to the FFG7 (by right clicking on the FFG7) and then selecting Select Target item from the petal menu.
  32. Click on the Start button of the Launch’s CAT Ramship subpanel.
  33. Click on the Save button (leftmost button) on the Recorder panel at the bottom of the CAT interface.
  34. In the dialog menu that opens in the CAT Recorder panel enter a unique network name for the created Launch behavior to be saved.
  35. In the Lagoon 3D world, select the Cigarette boat by left clicking on it and then in the CAT Triggers panel select the alert sensor trigger previously created for this boat. Next, click on the Fire button in the same panel.
  36. Repeat steps 29-34, this time for the Cigarette boat.


B. Executing the recorded San Diego sneak attack

Now you have recorded the simple attack behavior. Quit Lagoon (by pressing the F12 key with the cursor positioned over the 3D world) and then run it again. To run the recorded behaviors follow these steps:

  1. Create a FFG7, a Cigarette boat, and a Launch in a triangle as shown in Fig. 1. To create entities in Lagoon 3D world, see for example step A.2.
  2. Select the Cigarette boat in the Lagoon 3D world. With CAT in Execution mode, select the previously recorded behavior for the Cigarette from the dropdown list of the playback (Load/Execute) panel at the bottom of the CAT interface.
  3. Start executing this Cigarette behavior by clicking on the triangle-shaped play button in the playback (Load/Execute) panel at the bottom of the CAT interface.
  4. Select the Launch boat in the Lagoon 3D world. Select the previously recorded behavior for the Launch from the dropdown list of the playback (Load/Execute) panel at the bottom of the CAT interface.
  5. Start executing this Launch behavior by clicking on the triangle-shaped play button in the playback (Load/Execute) panel at the bottom of the CAT interface.
  6. Orient the FFG7 so that it faces the Cigarette boat and the Launch by setting its heading to 180 degrees. To do this, right click on the FFG7 and then select Battle Master -> Place. Next, hold the right click mouse and move it up and down to turn the FFG7 by 180 degrees.
  7. Make the FFG7 move between and past the Cigarette boat and the Launch as shown in Fig. 2 (see move to details in step A.26).
  8. Select the Cigarette boat in the Lagoon 3D world.
  9. Select the trigger shown in the triggers list of the CAT Triggers panel for the Cigarette.
  10. Click on the Fire button in the CAT Triggers panel to make the Cigarette boat ram the FFG7. The Launch will ram based on its distance trigger.
  11. When done, either click on the stop button (first from the right) on the CAT playback (Load/Execute) panel for both Cigarette and Launch or quit Lagoon by pressing the F12 key with the cursor positioned over the 3D world.
Personal tools