NRL Dual Task Software
Software Requirement Specification

Detailed Description of Requirements

Functional Requirements

  1. [FR 1]Participant identification
    1. [FR 1.1]The system shall collect participant number, date and time of experiment, scenario files used, calibration accuracies, (what else ???).
    2. [FR 1.2]The participant ID must be associated with all data collected.
    3. [FR 1.3]It must be possible to specify the participant ID at the start of a set of trials.
  2. [FR 2]Participant calibration verification
    1. [FR 2.1]The system shall present a brief calibration verification test at predetermined points in time. These points can be determined either pre-compilation or in a configuration file.
  3. [FR 3]Experimenter control and monitoring
    1. [FR 3.1]Ease of use
      1. [FR 3.1.1]The experimenter should be able to skip a scenario without using the mouse.
      2. [FR 3.1.2]A straightforward keyboard command (such as <ESC> and/or Command-period) will end the experimental trial.
    2. [FR 3.2]Start up time
    3. [FR 3.3]Configuration files
      1. [FR 3.3.1]The system shall use configuration files that will contain the settings for the tracking and tactical tasks, whether to use one or two monitors, and whether to use eye tracking or spatialized audio.
      2. [FR 3.3.2]The system should not have to be restarted between experiments in order to change any mode.
      3. [FR 3.3.3]The experimenter should be able to load all scenario data for all scenarios a participant will use with a single open dialog box.
  4. [FR 4]Input files
    1. [FR 4.1]Post-compilation auditory configuration
      1. [FR 4.1.1]<see Experimenter control and monitoring>
    2. [FR 4.2]Prototyping and demos
      1. [FR 4.2.1]Mono and stereo sound
        1. [FR 4.2.1.1]The input file events for specifying sounds should specify a default sound that will be played if the spatialized audio system is not connected.
      2. [FR 4.2.2]Use without eye tracking
        1. [FR 4.2.2.1]It should be possible to run the experiment without an eye tracker. There will be two non-eye-tracking modes: (a) Both subtask displays are visible at all times. (b) A button press, such as the spacebar or joystick button, will simulate the gaze contingent switching of displays.
  5. [FR 5]Pre-task display
    1. [FR 5.1]The system shall display the application in full screen mode.
    2. [FR 5.2]The system shall display the menu bar up until the experimental task begins.
    3. [FR 5.3]The software should adapt to all screen resolutions above 1280x1024, which will be the standard screen resolution for this application. If run on a smaller display, a dialog box will inform the user of the required screen size and that system behaviour on smaller displays is unknown.
    4. [FR 5.4]Some instructions or task indication should be displayed before each task (e.g. tactical classifying rules and icons before the tactical practice task, or simply that the tactical-only task is about to start).
    5. [FR 5.5]Just before the experimental task starts, some indication of the task displays should be visible.
    6. [FR 5.6]The participant should be told before a scenario begins how long the scenario will take.
    7. [FR 5.7]When a task is about to start, the participant should be given some indication, such as a countdown.
  6. [FR 6]Data collection
    1. [FR 6.1]Correct responses and errors
      1. [FR 6.1.1]The system shall record all participant actions, including all joystick, keypad, and eye movement data.
      2. [FR 6.1.2]The system shall record correct and erroneous responses, including what was the correct response, what was the user's response, and the timing (and location if appropriate).
      3. [FR 6.1.3]All joystick, keypad, and eye movement data should be time stamped so that the analyst can know when the data occurred with respect to the start of the scenario.
      4. [FR 6.1.4]The system shall use 7-bit ASCII for output file format.
  7. [FR 7]User feedback and incentive
    1. [FR 7.1]Payoff matrix
      1. [FR 7.1.1]Integration of subtask payoffs
    2. [FR 7.2]Time to completion
      1. [FR 7.2.1]Time and score should be visually displayed at all times for motivation, vigilance, and pacing. It should appear on both sides of the display so that the user can look at it without turning off that side of the display (when gaze contingency is turned on).
      2. [FR 7.2.2]The time-to-completion display should be visually non-intrusive. I.e. the participants should be able to get a rough idea of the time-to-completion without moving their eyes.
    3. [FR 7.3]Current earnings
      1. [FR 7.3.1]The system shall visually display the participant's current earnings for this scenario as an incentive to perform as quickly as possible while maintaining a 97% accuracy level.
    4. [FR 7.4]Performance feedback for every response
      1. [FR 7.4.1]The system shall provide instant feedback, with audio, visual, or both, for all correct and incorrect actions.
      2. [FR 7.4.2]Details for tactical and tracking task feedback are discussed within their respective subtask sections in this document.
  8. [FR 8]Practice sessions
    1. [FR 8.1]Single task
      1. [FR 8.1.1]The system shall provide the means to run either task (tactical and tracking) separately for practice sessions.
      2. [FR 8.1.2]Practice session data will be recorded.
      3. [FR 8.1.3]It should be possible, when running the software in single-task mode, to turn on the gaze-contingent mode and record if and when stray gazes caused the task display to hide itself.
    2. [FR 8.2]Dual task
  9. [FR 9]Tactical task
    1. [FR 9.1]Task window
      1. [FR 9.1.1]The task window shall have a light gray background that conforms MIL STD watch station display standards.
      2. [FR 9.1.2]The mouse cursor will be removed from the screen during the task.
    2. [FR 9.2]Icons
      1. [FR 9.2.1]A facility will permit the use of standard military icons for all blip characteristics including shape, color, and others.
      2. [FR 9.2.2]Blip characteristics will clearly indicate a blips current status, such as hostile, neutral, or unknown.
      3. [FR 9.2.3]A facility may be created to add vectors to blips to indicate direction and speed.
      4. [FR 9.2.4]Blips will be numbered from 1 to 9. Blips with letters may be used as distractors.
      5. [FR 9.2.5]Optionally, incorrectly classified or confirmed blips will be superimposed with a large red X.
    3. [FR 9.3]Movement
      1. [FR 9.3.1]Insured spacing for eye tracking
        1. [FR 9.3.1.1]The icons in the tactical task should never come within 1 degree of visual angle of each other, measured edge to edge. [Note: The maximum average bias error of the eye tracker is 0.7 degrees.]
        2. [FR 9.3.1.2]The system shall provide a means to notify the experimenter when two or more blips come within one degree of visual angle for a given scenario file. This will be used in a scenario file development phase.
    4. [FR 9.4]System responses to user input
      1. [FR 9.4.1]The system can optionally respond to every user input with either visual or auditory cues or both, such as the current "Neutral 1" text that appears.
      2. [FR 9.4.2]The system should visually or aurally indicate an incorrect tactical response and also possibly a correct response. E.g. A buzzer for incorrect and also possibly a quick chime for correct. This feedback should be instantaneous. If it is auditory, all error sounds should be spatially consistant and presented in parallel with all other sounds.
      3. [FR 9.4.3]The user will not be permitted to correct an incorrect response.
    5. [FR 9.5]Feedback and incentive
      1. [FR 9.5.1]If a blip is classified early, a penalty must be imposed, recorded, and immediately reported.
    6. [FR 9.6]Auditory display
      1. [FR 9.6.1]When a blip changes color from black to amber, red, or blue, sounds corresponding to any subset of those blip characteristics may be sent to the auditory display. (Note that the spatialized audio system may constrain the number and/or variety of sounds that can be displayed.)
    7. [FR 9.7]Configuration file control
      1. [FR 9.7.1]Possibly permit the tactical task display to be completely reset at a given point in the scenario while the tactical display is hidden.
  10. [FR 10]Tracking task
    1. [FR 10.1]Task window
      1. [FR 10.1.1]The task window shall have a light gray background that conforms MIL STD watch station display standards.
      2. [FR 10.1.2]The mouse cursor will be removed from the screen during the task.
    2. [FR 10.2]Icons
      1. [FR 10.2.1]The graphics used for the various visual indicators such as plane position and reticle (in its various states) must be easy to modify by the experimenter, such as with a configuration file. The motivation for this is so that the experimenter can iterate through various possible settings. Flipping the reticle between black and yellow, for example, may be a bit jarring, and peripheral salience may not be necessary given that the task will not be peripherally visible when not looking at the task.
      2. [FR 10.2.2]The system shall use standard military icons for all targets used in the scenarios.
    3. [FR 10.3]Movement
      1. [FR 10.3.1]The system shall provide both an easy and difficult mode for the tracking task, and optionally other difficulty levels in between.
    4. [FR 10.4]System responses to user input
      1. [FR 10.4.1]The system shall provide visual or auditory feedback, or both, for accuracy during the tracking task.
    5. [FR 10.5]Feedback and incentive
      1. [FR 10.5.1]In the tracking task, it must be clear to the user where the reticle must be placed on the target plane for the most accurate performance, and whether keeping the reticle in its "on target" visual state (i.e. yellow) is good enough for a 97% payoff.
      2. [FR 10.5.2]A visual meter placed near the reticle or adjacent to the tracking task window. The meter will indicate the extenct to which the participant has accurately tracked the target for the duration of the scenario. For example, it may show on a 0 - 100% scale the percentage of time that the reticle has been in on-target mode. Perhaps better, the meter will also indicate the mean error in pixels. This performance will be tied to user earnings.
  11. [FR 11]User input
    1. [FR 11.1]Keypad entry
      1. [FR 11.1.1]Allow easy reconfiguration of response keys in the source code.
      2. [FR 11.1.2]The number of the blip should be typed in before "hostile" or "neutral" classification (or confirmation). There should be a variable that can be set (pre-compilation) that will require the the classification to be entered within a certain time frame (such as 500 ms) for a correct classification to be made; otherwise it is an error.
      3. [FR 11.1.3]Correct user input should proceed as follows: digit, hostile/neutral; digit, hostile/neutral; ....
      4. [FR 11.1.4]Possible incorrect keypad entry
        1. [FR 11.1.4.1]The system should recover more gracefully from incorrect user input than the current system, in which the user could see a series of "Incorrect Input" responses. This improvement shall be accomplished in part by moving hostile and neutral responses to unique keys, and in part by more tightly controlling correct and incorrect user inputs.
        2. [FR 11.1.4.2]If a user types two digits in a row, the first digit was an error and the key-entry error signal (probably a buzzer) will sound at the entry of the second digit, even though the second digit can be the start of a correct entry.
        3. [FR 11.1.4.3]If the first digit corresponds to a black blip, then the buzzer will sound immediately when the digit is pressed. The blip stays black and the user will have a later opportunity to classify.
        4. [FR 11.1.4.4]If the first digit corresponds to a red, blue, or amber blip, then the buzzer sounds when the second digit is pressed and the first digit blip was classified incorrectly and turns white. This creates the awkward situation in which the user can get buzzed when pressing the second digit even though the second digit is the start of a correct classification. We will live with this. It should happen infrequently.
    2. [FR 11.2]Joystick
  12. [FR 12]Eye tracking
    1. [FR 12.1]Gaze contingent
      1. [FR 12.1.1]The subtask window (i.e. tactical vs. tracking) that the user is not currently looking at, as determined by the eye tracker, can be blanked out or have other images superimposed on it. This feature can be turned on and off via the configuration file.
      2. [FR 12.1.2]A window's gaze contingent region extends in all directions one degree of visual angle beyond its physical borders. This implies the following: Between the two subtask windows, there will be a strip of unused space that is two degrees of visual angle wide.
      3. [FR 12.1.3]A subtask window is defined as "looked at" up until two consecutive samples occur within the other window.
    2. [FR 12.2]Data collection
      1. [FR 12.2.1]For collecting and analyzing eye movement data, a region of interest must be defined for each blip, and that region of interest will move with the blip.
      2. [FR 12.2.2]For the purpose of eye tracking data analysis, it will probably be necessary to be able to play back a scenario exactly as it occurred, at least for all system and user events outside of the eye movements.
    3. [FR 12.3]Calibration and recalibration
      1. [FR 12.3.1]The system should show the calibration points when the experimenter (or automated calibration) initiates a calibration.
      2. [FR 12.3.2]Automated calibration accuracy checking
        1. [FR 12.3.2.1]Immediately before the start of each scenario, and immediately following the final sceario, eye tracker accuracy will be verified by having the participant look, in turn, at four cued locations on the screen. These cued locations will be located near the four extreme corners of the task displays. If the accuracy for any location does not fall within one degree of visual angle, a recalibration will be triggered, except for the final verification. For any post-scenario verification that is found in error, the preceeding scenario's eye tracking data will be marked as questionable.
        2. [FR 12.3.2.2]Before a recalibration is initiated, a dialog box will instruct the user to tell the experimenter that the eye tracker is about to be recalibrated. The dialog box will have two buttons: <Calibrate> and <End Experiment>.
  13. [FR 13]Spatialized audio
    1. [FR 13.1]It must be very easy to modify the sound configurations, such as by having a configuration file that has a slot or descriptor for every possible unique sound event that could occur. That slot or descriptor will point to a sound file that will be used for that event, or be blank indicating that there is no sound for that event.
    2. [FR 13.2]HRTF selection
    3. [FR 13.3]HRTF validation
    4. [FR 13.4]Preventing overlapped sounds
      1. [FR 13.4.1]An output data file will indicate when two sounds overlap.
    5. [FR 13.5]Configure audio level
  14. [FR 14]Post-task display
  15. [FR 15]Scenario playback
    1. [FR 15.1]The software will provide an option to display the user's gaze point on a layer behind task stimuli. This will permit video capture and playback for conference audiences. The gaze point will be indicated by a circle whose stroke is one color and whose fill is another. The size of the circle will be roughly one degree of visual angle in diameter.
  16. [FR 16]Task dynamics

Non-functional Requirements

  1. [NFR 1]For efficiency of programming and consistency in system performance, the new source code should reuse source code inherited from NRL wherever possible.
  2. [NFR 2]Hardware
    1. [NFR 2.1]The joystick shall be a USB joystick.
  3. [NFR 3]Software performance
    1. [NFR 3.1]Unless otherwise stated, the new software should function and perform similarly to the previous version of the experimental software inherited from NRL.
    2. [NFR 3.2]Metrics, measurement, and validation
      1. [NFR 3.2.1]There should be less than 16ms error in the systems timestamp of eye movement data.
      2. [NFR 3.2.2]The system should play audio files within 3 ms of their initiation.
  4. [NFR 4]Extensibility and resuability
    1. [NFR 4.1]Use without and with other sound systems
    2. [NFR 4.2]Use without eye tracking
    3. [NFR 4.3]Use with head tracker
    4. [NFR 4.4]Use across two displays
  5. [NFR 5]Reconfiguration of experimental design
    1. [NFR 5.1]Auditory and visual stimuli
    2. [NFR 5.2]User response
    3. [NFR 5.3]Both should be easy
  6. [NFR 6]Experimental terminology
    1. [NFR 6.1]Scenario: ...
    2. [NFR 6.2]Task: ...
    3. [NFR 6.3]Blip modes:
      1. [NFR 6.3.1]Black - Has appeared. Will become blue, red, or amber.
      2. [NFR 6.3.2]White - Blip has been confirmed or classified, correctly or incorrectly.
  7. [NFR 7]System documentation
    1. [NFR 7.1]The requirements document must be editable by all developers. A numbering and indentation scheme must be used that permits easy update and modification by all developers.
  8. [NFR 8]Use scenario
    1. [FR 8.1]Initial training and practice for the tactical task will proceed as follows: