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]
