Difference between revisions of "WaterMaze"

Revision as of 14:51, 22 November 2013

Running WaterMaze

• Enable in mycalvr.xml
• In WaterMaze submenu of CalVR, hit Load

Commands

l - load geometry
n - next trial
r - repeat trial
b - back to previous trial
p - play/pause
h - help
1-9 - reset position

To run the game, after you have loaded CalVR, press 'l' to load the game, then press 'p' to start the first trial. After the trial has completed, press 'n' to go to the next trial in the sequence, 'b' to go to a previous trial, or 'r' to repeat current trial. After you have selected a trial, press 'p' to start the trial.

When the game is paused, you may press the numbers 1-9 to reset the position of the subject to a predefined position (currently the 4 corners and the center).

Running States

• disconnected: Initial running state in CalVR. In the android controller this indicates that the device is not connected to CalVR.
• connected: CalVR is connected to an android controller and ready to start an experiment.
• experiment start: State used to indicate the beginning of a paradigm.
• geometry loaded: Scene has been loaded, ready to begin a trial.
• starting trial: Starting procedure has begun, but trial has not begun and data is not being recorded.
• running trial: Test subject is navigating the Water Maze and data is being reported to android controllers.
• ending trial: Trial is over and the trial ending procedure is being run.
• trial end: Trial ending procedure has terminated and the application is now awaiting a command.
• paradigm end: The paradigm has run the maximum number of trials and there are additional paradigms to run.
• paradigm end continuous: The paradigm either has no trial limit, or the minimum number of trials has been run, but less than the maximumum, and there are additional paradigms to be run.
• experiment end: Equivalent to paradigm end, but there are no additional paradigms to be run.
• experiment end continuous: Equivalent to paradigm end continuous, but there are no additional paradigms to be run.

Note: In the android controller source code, available operator actions are detailed inside StateManager.java

Configuring WaterMaze

WaterMaze Main Config File

Which paradigms are being run during the experiment, along with other experimental setup data, are defined inside WaterMaze.xml in the data directory.

The config file should be structured accordingly:

<?xml version="1.0">
<Plugin>
  <WaterMaze>
    ...
  </WaterMaze>
</Plugin>

Inside this section the following values are required to be specified.

• DataDir: path to the data directory for WaterMaze (note: should be the same directory that WaterMaze.xml exists in)
• WidthTile: width of a single grid space. (1 unit = 1mm)
• HeightTile: height of a single grid space. (1 unit = 1mm)
• WallHeight: ceiling height of maze. (1 unit = 1mm)
• StartingHeight: height of the head above the floor of the maze. default value: 300

There are then three sections that should be included.

• AndroidController: This specifies configuration data for the android controller.

<AndroidController>
  <UpdateRate value="?"/>    Rate at which WaterMaze will inform android controllers of path data.  default: 0.016666 (60Hz)
  <JavaIntSize value="?"/>   Used to indicate the size of the integer primitive in Java.  Used for network communication protocol.
</AndroidController>

• Textures: This is where the application will specify which texture files will be used for the walls and the floor.

<Textures>
  <Wall value="?"/>
  <Floor value="?" />
</Textures>

Note: Since the floor texture is rendered on each grid space individually, it is necessary to have the texture file be continuous.

• Paradigms: This specifies the paradigms to be run.

<Paradigms>
  <Paradigm0 path="Paradigms/?.xml" value="?" />
   ...
  <ParadigmN path="Paradigms/?.xml" value="?" />
</Paradigm>

Note: There must be a fixed number of Paradigms.  A paradigm can appear more than once in the paradigms list, but every paradigm specified in this list must have a unique identifier specified in the value field.

The experimental variables are specified inside the config file for the individual paradigms and placed inside the Paradigms subdirectory.

Paradigm Configuration

Configuration of the paradigms requires specifying certain key values, and specifying the list of all the cues that will be rendered in this paradigm.

Below details the critical data for a paradigm configuration.

<Paradigm>
  <Width value="?" /> Number of tiles in the x-axis the maze is wide.
  <Length value="?" /> Number of tiles in the y-axis the maze is long.
  <Time value="?" /> Maximum amount of time allowed for the test subject to complete a trial
  <StartingType value="?" /> 0: Starting position is constant across all trials.  1: Starting position is randomly generated for each trial.
  <FinishingType value="?" /> 0: Finish position is constant across all trials.  1: Finish position is randomly generated for each trial.
  <NumTrials value="?" /> Maximum number of trials allowed.  Values less than zero will result in no trial limit.
  <MinTrials value="?" /> (Optional) Minimum number of trials that must be run in order to move to the next paradigm.
  <AutoLoad value="true/false" /> Whether or not the application the geometry (note: cues can only be toggled before geometry is loaded)
  <Cues>
    <Cue0 type="?" value="Cues/?/??.xml" /> 
     ...
    <CueN type="?" value="Cues/?/??.xml" />
  </Cues>
<Paradigm>

Cue Configuration

The geometric rendering of a paradigm is handled by including all of the cue configuration files. Inside the Paradigm configuration file, the type of cue (Wall, Floor, Start, End) is specified with the type parameter and the corresponding configuration file is specified inside the appropriate sub directory.

Wall Cues

Floor Cues

Start Cue

End Cue

Doxygen API Generation

The WaterMaze CalVR contains doxygen comment tags. To enable the build of the WaterMaze API, set the value, MAKE_WATERMAZE_DOCUMENTATION to ON inside cmake. The API is included in the git repository and building WaterMaze with the MAKE_WATERMAZE_DOCUMENTATION value ON will regenerate the API. The documentation is located inside the root directory of the WaterMaze project folder inside the folder labeled doc.