Difference between revisions of "WaterMaze"

Latest revision as of 13:17, 4 December 2013

Running WaterMaze

• Enable WaterMaze in mycalvr.xml
• WaterMaze is set to automatically load on start up.
• Launch the Water Maze android app.
• Navigate to the Connectivity tab.
• Select the appropriate Cave to connect to.
• Terminal will output New Socket upon successful connection.
• Switch to Control tab and begin.

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

Joystick Operation and Audio Server

• Joystick Start-up
• Audio Server Start-up

Android Controller

Android Controller was last updated on Dec 4, 2013. Verify that your controller is running the most up to date version before running the application.

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.