User Reference:CursorTask

From BCI2000 Wiki
Jump to navigation Jump to search

Synopsis

The purpose of the CursorTask is to provide a BCI2000 User Application module that can realize 1D, 2D, or 3D cursor movement tasks. It displays a box-shaped scene in which a ball-shaped cursor moves, controlled by the output of the Signal Processing Module. In this scene, targets appear as cuboids or rectangles. Box, cursor, and targets may be texturized.

Functional Description

Timeline

CursorTask Timeline.png

Introduction

The CursorTask implements a cursor movement task based on a 3-dimensional control signal communicated to it by an appropriate BCI2000 Signal Processing module. This task progresses through five subsequent stages (as illustrated in the Timeline): In stage 1, the screen shows an empty workspace. This period is called Inter-Trial Interval. Subsequently, a target (that is represented as a cuboid) appears in one out of n possible locations. This period is called Pre-Trial Pause. After the pre-trial pause, the cursor appears in stage 3. It immediately starts to move as determined by the 3-dimensional control signal. During stages 3 and 4, the user's task is to move the cursor towards and into the target. This period of cursor movement is called the Feedback Period or Trial Period. Period 4 can end in one of three ways: Either the cursor hits the correct target, it misses by hitting any other of the defined targets, or the feedback period takes too long and times out. Stage 5, the Reward Period, follows stage 4. The cursor disappears and the target changes its color to indicate completion of the trial period. After a defined duration, the target disappears and the next trial starts with an Inter-Trial Interval.

Visual Representation

CursorTask Screen.png

The visual representation of the CursorTask consists of a 3-dimensional workspace that can (if selected) be indicated by five bounding rectangles. These rectangles can have a user-selectable texture, which is the same for each rectangle. Targets are represented by cuboids, whose edges can also have a particular texture. Finally, the cursor is represented by a sphere. It also may have a user-defined texture. To facilitate depth perception, the cursor's color provides an additional cue about the cursor's Z position as follows. The operator specifies the cursor's color at the topmost and at the bottomleast Z positions. For any color between these extremes, the cursor's color will be linearly interpolated between the two colors. (Specifically, each of the three color components (i.e., red, green, and blue) will be interpolated to result in the cursor's color for a given Z position.)

Control Signal

Cursor movement is controlled by the output of the Signal Processing Module. In this signal, channels 1, 2, and 3 correspond to dimensions X, Y, and Z, and there is a single value (element) present in each channel, defining cursor speed in the respective dimension.

Additional channels or elements that might be present in the control signal will be ignored by the CursorTask application module.

Parameters

Sequencing

PreRunDuration

The duration of the pause preceding the first trial. Given in sample blocks, or in time units when immediately followed with 's', 'ms', or similar.

PreFeedbackDuration

The duration of target display before feedback begins. Given in sample blocks, or in time units when immediately followed with 's', 'ms', or similar.

FeedbackDuration

Typical duration of feedback. Given in sample blocks, or in time units when immediately followed with 's', 'ms', or similar.

This parameter is not a hard limit to feedback duration but determines cursor speed such that, for a normalized control signal, cursor movement will take the specified time from the cursor's starting point to the screen's edge. Feedback trials will typically have this duration, provided that the cursor starts at the center of the screen, targets are located at the screen's edges, and ignoring cursor and target width (for further details, see User Reference:Normalizer).

PostFeedbackDuration

The duration of result display after feedback. Given in sample blocks, or in time units when immediately followed with 's', 'ms', or similar.

ITIDuration

The duration of the inter-trial interval. Given in sample blocks, or in time units when immediately followed with 's', 'ms', or similar.

NumberOfTrials

The number of trials in a run. If this parameter is set, then MinRunLength should be blank, and vice-versa.

MinRunLength

The duration of a run, i.e. the time corresponding to a continuously recorded data file. A run will not stop during a trial, so its actual length may be larger than this value by the length of a trial. If this parameter is set, then NumberOfTrials should be blank, and vice-versa. Given in sample blocks, or in time units when immediately followed with 's', 'ms', or similar.

NumberTargets

The number of targets on the feedback screen.

TargetSequence

A list of indices, each one being from 1 to NumberTargets. This list specifies an optional fixed sequence of stimuli, through which the presentation will cycle. Leave this parameter blank if you want the default behavior, which is for stimuli to be selected randomly.

MaxFeedbackDuration

Abort a trial after this amount of feedback time has expired. Unlike the FeedbackDuration parameter, this is a hard limit. Given in sample blocks, or in time units when immediately followed with 's', 'ms', or similar.

Visual Appearance

Positions and sizes are given in a percent coordinate system. There, [0 0 0] corresponds to the bottom left corner of the workspace, and its diagonal counterpart has [100 100 100] as its coordinates.

CameraPos

Camera position vector in percent coordinates of the 3D area.

CameraAim

Camera aim point in percent coordinates.

CameraProjection

An enumerated value specifying one of the following camera projections:

  • 0: flat,
  • 1: wide angle perspective,
  • 2: narrow angle perspective.

LightSourcePos

Light source position in percent coordinates.

LightSourceColor

The light source's color in RGB encoding.

WorkspaceBoundaryColor

The workspace boundary color in RGB encoding. The special value of 0xff000000 hides the workspace boundary.

WorkspaceBoundaryTexture

The path to a workspace boundary texture, or empty. Currently, Windows BMP files are accepted as textures. Paths may be absolute, or relative to the executable's working directory at startup, which usually matches the executable's location.

CursorWidth

The feedback cursor's width, given in percent of screen width.

CursorColorFront, CursorColorBack

The cursor's color when it is in the front resp. back of the workspace, given as an RGB value. When different colors are specified for front and back, the cursor's z coordinate will be used to linearly interpolate between the two color values.

CursorTexture

The path to a texture file to be used for the cursor.

CursorPos

The cursor's starting position, given as a vector in percent coordinates.

Targets

A matrix with 6 columns, and rows corresponding to individual targets. The first three columns define the position coordinates of the target's center, given in percent coordinates; the last three columns define the target's three-dimensional extent. Targets are always cuboids aligned with the three coordinate axes.

TargetColor

Target color in RGB encoding.

TargetTexture

Path to a texture file to be used for targets, or empty for none. Currently, Windows BMP files are accepted as textures. Paths may be absolute, or relative to the executable's working directory at startup, which usually matches the executable's location.

TestAllTargets

An enumerated value that determines collision test behavior:

  • 0 to test only the visible current target,
  • 1 to test all targets.

Window Properties

WindowWidth, WindowHeight

The width and height of the subject-visible application window, in pixels.

WindowLeft, WindowTop

The screen position of the application window's top left corner, in pixels.

RenderingQuality

An enumerated value specifying one of the following:

  • 0: low
    2D rendering. Lighting, shading, and textures are switched off, even if specified otherwise for individual objects. Also, collision detection ignores objects' z positions. On machines without OpenGL compatible 3D hardware, 2D rendering is considerably faster than 3D rendering.
  • 1: high
    3D rendering. Lighting, shading, and textures are applied as specified.

States

PreStimulusTime

A 16-bit time stamp in the same format as the SourceTime state. This time stamp is set immediately before the application module is going to update the stimulus/feedback display. Note that a data block is saved together with the state vector that existed immediately after it was acquired. Thus, PreStimulusTime will be the prestimulus time of the block prior to the current block.

StimulusTime

A 16-bit time stamp in the same format as the SourceTime state. This time stamp is set immediately after the application module has updated the stimulus/feedback display. Note that a data block is saved together with the state vector that existed immediately after it was acquired. Thus, StimulusTime will be the stimulus time of the block prior to the current block.

PresentationRequested

This 32-bit state contains a list of ids for all presentations that have been requested during the current block. The list ends with a value of 2^31. A 32-bit presentation id is formed by combining the 16-bit SourceTime state of the presentation request's data block in the most significant bits, with the time difference between that source time stamp and the time when the presentation request happened, in the least significant bits:

PresentationID = SourceTime << 8 | (RequestTime - SourceTime) & 0xff

This definition makes presentation ids unique within the range of a minute, and allows to extract the value of the request's time stamp from its id.

PresentationDisplayed

This 32-bit state contains a list of ids for all presentations that have been displayed during the current block. The list ends with a value of 2^31. Presentation ids appear in the PresentationRequested state when presentation is requested, and subsequently in the PresentationDisplayed state when presentation has occurred.

PresentationTime

A 16-bit time stamp in the same format as the SourceTime state. For each id occurring in the PresentationDisplayed state, this state contains the time stamp of the respective update to video memory. From this point in time, up to two additional frame durations may be required before the display's surface actually shows a difference in signal. This depends on the internals of the display, and cannot be determined from software.

PresentationFrame

A 12-bit state that contains, for each id occurring in the PresentationDisplayed state, the frame number of the respective update to video memory. Frame numbers have an arbitrary offset, and wrap around at a value of 2^11. PresentationFlow.png

AudioBufferTime

A 16-bit time stamp in the same format as the SourceTime state. For each audio presentation that has occurred during the current block, this state contains the time stamp when non-zero audio data were about to enter the system's audio buffer.

AudioPresentationTime

A 16-bit time stamp in the same format as the SourceTime state. For each audio presentation that has occurred during the current block, this state contains the estimated time stamp when non-zero audio data were being played from the system's speakers or headphones. The estimate takes the length of the system's audio buffers into account but will not be able to detect external sources of delays, such as additional audio processing steps.

TargetCode

During a feedback trial, this state indicates the user's task, i.e. the target the cursor is supposed to hit. A TargetCode value of zero indicates that there is no target specified; TargetCode switching from zero to nonzero indicates the beginning of a trial.

ResultCode

At the end of a feedback trial, ResultCode is set to the target code of the outcome, i.e. the target that was hit by the cursor. When a time of PostTrialDuration has passed, ResultCode is reset to zero.

Feedback

This state's value is 1 when the cursor is displayed on the feedback screen. Typically, this also implies that the cursor moves according to the control signal.

PauseApplication

While this state is set to 1, no task processing occurs, i.e. the task is paused, and may be resumed by setting PauseApplication to 0.

CursorPosX, CursorPosY, CursorPosZ

These states record the cursor's position, translated into the 0..4095 range such that the 3D scene's left, down, and top planes all correspond to 0, and the right, up, and bottom planes correspond to 4095.

See also

Programming Reference:3D API, Programming Reference:FeedbackTask Class