PXLab Manual

[Home]    [Content]    [Previous Chapter]    [Next Chapter]


Stimulus Elements

The main building blocks for defining experimental stimuli are objects of the class Display. Every Display contains a set of primitive stimulus elements. These are elements like geometric objects (bars, disks, arrows), text paragraph objects, images or other more complicated elements. Actually the primitive stimulus elements can be rather complicated since every primitive stimulus element corresponds to a Java class whose properties are only limited by what is possible using the Java programming language. Note, however, that all stimulus primitives must be derived from the class DisplayElement which gives them some common properties.

General Properties of Display Objects

Every Display object has some parameters which describe its timing and its response properties. There also are some procedural parameters which control execution, computation, and the display mode. Here is a list of those experimental parameters which are properties of every Display object.

Timer
defines the timer type which controls the duration of the Display object's main timing group. If the Display object has more than a single timing group then each timing group will usually have its own timer being defined. Possible Timer values are defined in class TimerCodes.
Duration
is the intended display duration of the Display object's timing group which has Timer as its timer type.
TimeControl
contains the actual times when this display's timing groups have been shown. This parameter is set after the display has been shown and uses PXLab' high resolution clock.
TimeError
contains the timing error for every timing group of this display object which has a CLOCK_TIMER. The timing error is derived from the value of Duration and TimeControl.
ResponseTime
stores the actual display duration. For response driven timers this will also be the response time. For clock driven timers this parameter is derived from TimeControl.
ResponseCode
is a code generated by the event which stopped the display time interval. For response driven timers this will be a code generated by the response device. These codes are defined in class KeyCodes. For clock driven timers the code will be TIME_OUT. For media timers like MEDIA_START_TIMER the code will be one defined in class MediaEventCodes. If the parameter ResponseSet is defined then the response codes correspond to the position of the respective response code in the ResponseSet array.
ResponsePosition
contains an integer array with the xy-position of the response device when a response was detected.
ResponseSet
gives the set of response codes (see ResponseCode) which are acceptable as responses for stopping the respective timer. If this parameter is defined then it also installs a code conversion table such that the actual ResponseCode values are no longer the response device codes but the indices of the respective device code in the ResponseSet array.
Execute
is a flag which by default is set to a non-zero value. If non-zero then this Display object is actually computed and shown during stimulus display. If the flag is zero then this Display object is not shown. This flag may be used to switch off parts of a stimulus definition without changing the stimulus definition itself. Thus it is a mechanism which makes it possible to modify display lists at runtime depending on parameter values. This enables conditional execution of display objects. Note that if the execution of a display depends on a preceding display in the same display list then the display must have its JustInTimeparameter being set. See an earlier section for a more detailed description and some examples. The section 'Response Collection During A Clock Timer Interval' in chapter 'Stimulus and Response Timing' contains another example of how to use this feature.
Overlay
makes a Display object transparent when it is non-zero. In general this parameter will be zero. Since every Display object contains a background element which covers the whole display screen any previous Display object is erased when a new Display is shown. This makes it impossible to simultaneously show more than a single Display object. Thus all primitives which are to be visible simultaneously must be contained in a single Display object. However, if we set the Overlay flag of a Display object then its background is not drawn and thus the screen is not erased before its primitives are shown. This makes it possible to simultaneously show the primitive elements of more than a single Display object. See an earlier section for a more detailed description.
JustInTime
controls the point in time when this display object's properties are computed. If true (has a non-zero value) then this is done immediately before the Display object is shown. If this is false (is zero) then most properties are computed before the DisplayList is started. Use this flag only if necessary, since it may reduce timing precision. Setting this flag is necessary whenever a Display parameter value depends on the current value of a parameter of a Display contained in the same DisplayList. See an earlier section for a more detailed description.
Screen
selection code for the screen where this Display object should be shown in multiple screen systems. Possible code values are defined in class ScreenSelectionCodes. This parameter is ignored on single screen systems.

Available Display Objects

This section gives an overview on the Display objects which currently are available. The Display objects are collected into small groups of objects which have something in common. Note, however, that several Display objects have overlapping functionality such that it makes sense to check more than a single group of Display objects if a certain property is required. All the classes described herein are subclasses of the class Display which is the top level class of Display objects.

Text Paragraph Objects

The class TextParagraph is the superclass of several subclasses which contain paragraphs of text. Some of them contain more than a single paragraph and some have special methods to compose the paragraph from single elements which may be read from a file.

TextParagraph
is the top level class for paragraph of text. The paragraph's width, position, line skip and alignment may be defined by experimental parameters. A single string of text is broken into lines at carriage return characters. If line wrapping is switched on then the text is broken into lines such that it fits the given width but explicit line breaks are preserved.
TextFile
allows the subject to page up and down in a text file. Pages in the text file are marked by some marker string. This is intended for presenting multiple page instructions where the subject should have the possibility to page backwards.
TextParagraphMultiple
shows multiple paragraphs of text. The paragraphs' text content and positions are independent and may be defined by setting the respective parameters to array valued objects. Note that in this case an array valued parameter Text is interpreted to mean different paragraphs instead of different lines as it is done by the class TextParagraph.

TextParagraphComposed
makes it possible to read the text from a separate file. Different elements of the text may be composed by simply using codes which represent these elements.

Message
is a subclass of TextParagraph which by default uses a rather large font and centers the single lines of text at the screen's center.
Instruction
is a subclass of TextParagraph which by default shows a paragraph of text left aligned and prints the first line in bold face. Font and size are set such that it fits most instruction texts.
TextInput
for text input responses which are closed by the Return key.
SessionStartMessage
default message for starting a session.
SessionEndMessage
default message for the end of a session.
BlockStartMessage
default message for starting a block.
BlockEndMessage
default message for the end of a block.
TrialMessage
default message for a trial.
CmdMessage
a text message which is not shown on the subject's display screen but in the command line window which started the experiment. May be used to print messages for the experimenter while a trial is running.

Letter Matrix Objects

Objects which contain a matrix of letters as their major stimulus element are subclasses of LetterMatrix. Additional elements are a cue and a mask. Also included are matrices which collect responses and show feedback.

LetterMatrix
a matrix of letters.
CuedLetterMatrix
a matrix of letters witha cue.
MaskedLetterMatrix
a matrix of letters followed by a mask.
LetterMatrixResponse
a matrix of letter positions for letter responses.
LetterMatrixFeedback
a matrix of letters for feedback.
NavonPattern
a pattern of letters which itself forms a large letter.

Sequences of Text Objects

A series of single line text objects which are presented sequentially or with a certain SOA. These objects have more than a single timing group and thus have additional timer and duration parameters.

SerialLearningList
is a serially presented sequence of items.
TwoStrings
are two strings possibly presented with an SOA.
RapidSerialPresentation
a fast sequence of text strings.
GrowingText
an animated Display with a growing line of text which is used for delayed recognition experiments.

Questionnaire Objects

Multiple choice and rating scale type of lists.

MultipleChoiceQuestion
is a subclass of TextParagraph which shows the paragraph of text and also shows a list of selectable alternatives to chose from.
RatingScaleQuestion
is a subclass of TextParagraph which shows the paragraph of text and also shows a numbered scale with an adjustable pointer.
ChoiceResponse
contains only a multiple choice response element which may be overlayed on top of other Display objects whenever a multiple choice response is required.
ItemRanking
is a series of single lines of text which constitute 'items' which are shown simultaneously. Single items may be selected in order to create a ranking of the items.

Geometric Objects

These are simple and complex geometric objects. Some of them have multiple elements which all have their own color parameters.
Arrow
is an arrow with arbitrary orientation.
MaskedArrow
is an arrow which is followed by a mask.
SimpleBar
a rectangular bar.
SimpleDisk
a filled disk.
PolyArea
a filled polygon area.
Chevron
shows a Chevron type of circularly arranged wedges.
MunsellColorBar
is a bar whose color may be defined by Munsell notation for the reflectance function and an illumination device.
DeviceColorBar
is a bar whose color is defined by device coordinates.
CIELabMaximumChroma
shows two adjacent bars comparing a color with another color having the same lightness and hue but having maximum chroma in CIELab.
ShowWhitePoint
shows and sets the current color device's white point.
DisplaySizeMeasurement
is a pattern to visually measure the size of a display screen.
HorizontalVerticalIllusion
an inverted T figure to show the horizontal-vertical illusion.
MuellerLyer
the Müller-Lyer-Illusion figure.
RandomDotMotionField
shows a field of random dots which has a moving subset.
RandomDotMotionThreshold
shows a field of random dots where a certain proportion will move in the same direction while the rest of the dots moves at random.
RandomDotMotionContrast
shows a set of static dots mixed with a set of moving dots which induce virtual motion for the static dots.
SpatialAttentionFrames
A Left and a right square frame with a fixation mark as it is used for spatial attention experiments.
SpatialAttentionTarget
A Left and a right square frame with a fixation mark and an attention cue or target as it is used for spatial attention experiments.
GenericDisplay
a Display whose content is determined at runtime.

Colorimetry and Photometry

Methods for doing photometric measurement.

FlickeringBarsPhotometry
photometry with flickering bars.
TeemingPhotometry
photometry with a flickering random line pattern.
VisualGammaTarget
shows a pattern for visual gamma measurement by adjustment.

Color and Brightness Contrast Objects

Objects which generally have some target and some context element.
BrightnessInductionDisks
BrightnessInductionSquares
InductionMatching
CrispeningEffect
ComplexColorContext
ComplexColorContext2
ComplexColorContextAnimated
CrossContextMatching
CrossContext3DMatching
CrossContextMatchingMixed
CrossContextMatchingRectMixed
MunsellColorBoard
RandomContextColorMatching

Color Discrimination

Color discrimination objects contain multiple color fields and the task usually is to select a single color field with a certain property.

RandomTilesColorVisionTest
shows a color vision screening test pattern.
ColorDiscrimination
shows two adjacent rectangles whose colors are to be discriminated.
ColorSelection
contains a small number of circular color patches and the subject's task is to select one of them like in the odd man out paradigm.
PointLightsMixed
simulates point light sources mixed on a projection screen.
PointLightsAnimation
simulates point light sources mixed on a projection screen with amplitude animation.

Color Samples and Selection

Selection of one or more colors from a larger sample.

ColorSampleSelection
allows selection from an arbitrary sample of color patches defined by their Yxy-coordinates.
CIELabColorSampleSelection
shows a rectangular pattern of color patches which contains a CIELab color sample of constant lightness and allows for selection of a subset of color patches.
MunsellColorSampleSelection
shows a rectangular pattern of color patches which contains a sample from the Munsell Book of Colors with maximum Chroma and allows for selection of a subset of color patches.
RandomColorSampleSelection
shows a random sample of colors and allows selection from the sample.
ColorCircleSelection

Search patterns

Patterns which are used for search tasks in attention research. They include position randomization and independent definitions of target and distractor properties.
SearchPattern
is a superclass for pop out search patterns with various target and distractor types.
LetterSearch
searching for letters.
GeometrySearch
searching for geometric objects.

Apparent Motion Stimuli

Objects which may be animated and show some type of motion.

MovingDot
apparent motion of a dot.
MovingDotPair
apparent motion of a pair of dots.
TrackingTarget
a tracking target.
WertheimerBar
the classical Wertheimer bar which demonstrates apparent motion.
ContractingBar
GrowingText
an animated Display with a growing line of text which is used for delayed recognition experiments.

Pictures

PXLab can read all bitmap image types which are supported by the package javax.imageio. This includes JPEG, PNG, BMP, WBMP, and GIF. Also supported are static Scalable Vector Graphics images. These need the Apache Software Foundation Batik package being installed.

Picture
shows a picture contained in a file.
PicturePages
allows the subject to page forward and backward through a series of pictures. Mainly intended for presenting complicated instructions which mix text and images.
PictureAnimation
presents a short movie made up from a series of image files.
PictureRating
is a subclass of RatingScaleQuestion and adds a rating scale to Picture.
PictureComparison
is a subclass of PictureRating and allows for simultaneous rating or comparison of two images.
PictureMatrix
is a subclass of Picture and simultaneously shows multiple images. It also allows image selection responses.
PictureMasked
is a subclass of Picture and adds an image mask to the picture.
PictureCache
stores a list of pictures in an internal image cache. Pictures contained in the image cache can be presented much faster than reading them from the file system.
TextImage
is a text string drawn as a bitmap image which may be rotated.
ColorTransformedPicture
shows a bitmap image and its transformation into a color subspace.
TwoColorImageProjection
simulates the projection of two independent bitmap images onto a common projection screen with differently colored projection light sources for the two images.
MondrianMixturePattern
simulation of a Mondrian pattern made up from 1, 2, or 3 light source mixtures.

Images are usually specified by experimental parameters named Picture.Directory and Picture.FileName. The Directory may be a local file system directory, an arbitrary URL on the internet or any archive in the Java system's CLASSPATH. If the full access path of an image file is prefixed by an '@'-character then the image is cached in an image cache in memory for later re-use. This may be useful for applications or applets which need short retrieval times for multiple presentations of the same images.

Gratings

Grating patterns which mostly are subclasses of class ModelFest. This is a collection of standardized stimuli suggested by the ModelFest group to investigate basic properties of spatial vision. See http://vision.arc.nasa.gov/modelfest/ or http://www.neurometrics.com/projects/Modelfest/IndexModelfest.htm for a description of this set of stimuli.

All of these define the pattern as a convex mixture of two arbitrary colors A and B. The pattern is a spatial distribution of mixture weights which satisfy 0.0 <= w(x,y) <= 1.0. At every point (x,y) in the pattern the resulting color is w(x,y)*A + (1-w(x,y))*B. All computations are done in the CIE 1931 chromaticity space.

GaborFest
a one-dimensional sinusoidal with phase, amplitude and orientation controlled by experimental parameters. The pattern has a 2-dimensional Gaussian envelope which may be animated such that the maximum amplitude follows a temporal Gaussian.
CollinearGaborFest
a collinear series of Gabor patches.
GaussianFest
a spatial Gaussian with a temporal Gaussian envelope. No underlying wave is present.
ImageFest
an achromatic image whose contrast is multiplied by a spatial Gaussian with a temporal Gaussian envelope.
MultipoleFest
mixture patterns which mostly ar binary: a zero contrast pattern, edge, line, and dipole patterns, a concentric disk. a checkerboard, and static and dynamic white noise. All of these have spatial and temporal Gaussian envelopes.

The following grating patterns are not derived from ModelFest and differ from these mainly by two aspects: The may include harmonic components and they provide spatial motion classes.

GaborPattern
a one-dimensional, complex sinusoidal pattern multiplied by a two-dimensional Gaussian envelope. The pattern's phase, amplitude, orientation and harmonic content are controlled by parameters.
GaborPatternAnimation
same as GaborPattern but the sinusoid's position or amplitude may be animated.
PlaidPattern
a sum of two sinusoidal patterns like those of GaborPattern multiplied by a two-dimensional gaussian envelope.
PlaidPatternAnimation
same as PlaidPattern but the sinusoids may be animated.

Problem Solving and Games

This group contains some very special types of Display objects which are used mainly in problem solving experiments. Some of these are subclasses of the GameBoard class.

Anagram
a sequence of letters which has to be rearranged in order to make it a valid word.
TowerOfHanoi
the well known multi-disk problem.
LinearSystem
requires the subject to control a multi-state system which is described by some linear system model. The structure of the linear system is described by the class LinearSystemModel.
MCGame
the well known river crossing problem.
WaterJugs
the water jugs problem.
VierGewinnt
shows a state of the well known 'Vier Gewinnt' game.
ChineseRings
shows the chinese rings puzzle.
FifteenPuzzle
shows a field of n*m tiles making the tile shift puzzle.

Attention Signals

These are Display objects which usually are used as attention signals.

CountDown
is a blinking dot.
Counter
an animated numerical counter.
FixationMark
is a simple fixation mark.
RandomNumber
is a text element which only contains a random number.

Feedback Objects

Feedback
is a Message object whose content may be derived from other Display objects' parameter values. These messages are computed just in time such that their parameter values show the real time state of the involved Display objects.
Smiley
is a graphic object which shows a smiley face and has a Smiley.Mood parameter.

Sound Display Objects

PXLab's capability to create sound stimuli is somewhat limited. Currently there are only a few sound objects.

Beep
presents the system beep sound.
SoundFile
plays an uncompressed wave file.
SyntheticSound
plays various synthetic sounds with defined envelopes and wave types.
SoundRecorder
records sound from an arbitrary sound input channel.
SoundRecorderControl
controls recording as a background task which runs concurrently.
VoiceKey
records a voice sound from a microphone and measures the time to threshold.

Sound display objects do not affect screen content. This means that while a sound display object is running the screen remains in the state it had before the sound object started.

General Media Player Objects

These objects use a concurrently running media player to play arbitrary media files. They require that the Java Media Framework (JMF) package is installed on the client. The media type is recognized from media file properties. File location my be specified by any arbitrary URL.

Movie
starts playing a movie and waits until the movie is finished.
MediaPlayerOpen
opens a media player for a given media file.
MediaPlayerStart
starts a media player which has been opened earlier.
MediaPlayerSync
waits until a running media player arrives at a certain media time.
MediaPlayerStop
stops a currently running media player.

Clearing the Screen

Since PXLab's display objects never are explicitly removed from the screen we need display objects which explicitly clear the screen if an empty screen is required. These objects do not contain any DisplayElement objects.

ClearScreen
shows an empty screen with the color being defined by the global parameter ScreenBackgroundColor.
FillScreen
shows an arbitrary full screen color.
ClearScreenRandomTime
shows an empty screen for some random duration.

Communication with External Devices

PXLab can communicate with some external devices which are connected to the serial communication port, a parallel port or a USB port. In general these devices require special drivers being installed. We use the label 'External Control Box' for a device connected to the control lines of the serial communication port. See chapter 'Connecting External Devices' for more information about external devices.

ExternalSignalOn
switches on an external control box signal.
ExternalSignalOff
switches off an external control box signal.
Trigger
sends a trigger puls to an external control box signal line.
IlluminationDeviceControl
controls an illumination device connected to a parallel port.
SerialCommunicationDeviceControl
controls a device connected to a serial port.
ColorMeasurement
controls a color measurement device for measuring color tristimulus values from the screen. See chapter 'Color Calibration' for more information about color calibration.

Response and State Control Objects

Control objects can count errors and control response and procedure states. Some of these also can simulate certain types of responses.

Nothing
does not change the screen content. Its purpose is to provide a new set of response parameters.
StartClock
starts a high resolution clock.
ReadClock
reads a running high resolution clock.
InitCounter
initializes a counter.
IncrementCounter
increments and reads an initialized counter.
SetParameter
sets the value of an arbitrary experimental parameter.
RandomGenerator
computes a random response code.
ResponseRobot
a response simulation robot.
ErrorControl
counts errors and controls series of error free trials.
ConditionalWaitResponse
conditionally waits for a subject response.
PsychometricFunctionSimulator
simulates yes/no responses according to a psychometric function model.
ResponseControlStart
starts a response control interval where spurious subject responses are collected.
ResponseControlStop
stops a response control interval
ResponseControlCheck
checks for spurious responses during an active response control interval.
SessionStateControl
controls the parameter SessionState and allows for response dependent session state control.
SystemProcess
executes a system process of the operating system.
ScreenCapture
captures the display screen of the previous Display object and writes the image to a file.
WhitePointControl
sets the current color device's white point.

[This file was last updated on July 15, 2010, 12:07:01.]

[Home]    [Content]    [Previous Chapter]    [Next Chapter]