PEACH Library Documentation

1.0.2

Author:: Yury Petrov

Introduction

The PEACH library provides C++ functions for programming experiments in visual psychophysics. PEACH contains an extensive collection of visual primitives (Gabors, Disks, Bars, Text, Images, etc.) as well as a set of experimental functions, which allow to code a complicated experiment in a few dozen lines. The library provides a full support for:

in-window and full-screen rendering
subpixel resolution
gamma correction
nominal 10-bit pixel depth (via 2x2 pixel dithering) and 13-bit pixel depth (via Cambridge Research Systems BITS++)
stereoscopic presentation via anaglyphic glasses, mirror stereoscope, or shutter glasses
proportion correct, response time, and response location measurements
Method of Constant Stimuli and the Kontsevitch & Tyler (1990) adaptive algorithm for threshold measurements
finger-error correction
multiple-task experiments
graphical user interface for setting default and user-defined experimental parameters
OpenGL programming of complex 3D objects and scenes
automatic storage of a complete experimental session in a human-readable file
command-line (Perl) script for averaging and analyzing the data between multiple experimental sessions

Only basic knowledge of C is required for programming experiments with PEACH. If you are a complete stranger to C try A Little C Primer. You'll probably get a working knowledge of C by just following the examples in the PEACH Tutorial. Essentially, PEACH functions can be viewed as a set of high-level commands implementing paradigms and stimuli commonly used in visual psychophysics. The little C that you'll use is to glue these commands together into a coherent experiment.

peach.h is the only header file for external linking. The file is located in the root PEACH directory, the rest of the header files in this directory are not meant for external access. Source files are located in the same directory. The PEACH documentation files are located in the html subdirectory. Point your browser to index.html to open this page. The examples subdirectory contains code for all the experiments discussed in the PEACH Tutorial.

Warning:: PEACH is covered by the GNU Lesser General Public License and is distributed "as is" without any guarantees or liabilities. A copy of the license is in the Licence.txt file in the PEACH directory

News

October 2, 2008: PEACH 1.0.0 released.
December 15, 2008: PEACH 1.0.1 released. The changes include:
1. Implemented BITSPP support for MONO++ regime of the CRS BITS++ device.
2. Corrected several bugs in the MakePattern() function.
3. Added BinRan(), PoissonRan(), NormalRan(), and GammaRan() random number generators.
4. Added error reporting Error() function.
5. Added float-to-string F2S() and integer-to-string I2S() converters.
February 27, 2009: PEACH 1.0.2 released. The changes include:
1. Added global view masking with rectangular MaskRectangle(), circlular MaskCircle(), and arbitrary shaped MaskShape() objects. This allows to create various viewing apertures, for example.
2. Added WinFramerate() function, which returns the current screen framerate.
3. Experiment starts on any key press now, not just on a mouse click. This is useful for external synching, e.g. the stimulus can be triggered by a USB event sent by a MRI scanner.
4. VIEW_3D_PERSP viewing volume extends from -0.9 of the ViewingDistance in front of the screen to 100x ViewingDistance beyond the screen now.

Quick Start

For a quick start install PEACH as described in Installation. Then follow the PEACH Tutorial. You are encouraged to click on any variable, constant, or function name shown in blue to view the linked documentation.

All the experimental details are covered in the Experimental module. Various PEACH object functions are documented in the Objects module. Image display and stereoscopic display are documented in the Images and the Stereo modules respectively.

Release notes

PEACH has been tested on Mac OS 10.4 and 10.5 and on Fedora Core 6. To use it on Linux you'll have to install glut-3.7, because full-screen rendering will not work with Freeglut. You'll need both the regular package (to get libglut.so) and the developer package (to get glut.h header file). Also, GLUT GameMode is not working on Linux, so you won't be able to set your screen resolution and refresh rate from PEACH UI. Use your Linux distribution screen preferences dialog instead. Everything else should work.

Requirements

Linux OS or Mac OS X with Xcode Tools installed (get it from Apple downloads or from your Mac OS X DVD). For Mac OS X after the XCode installation is completed verify that the UNIX make command works by running it in the terminal window (you might need to open a fresh one). If the command is not found look for the command in /usr/bin, i.e. ls /usr/bin/make. PEACH will not compile without the make utility properly installed.

Download

Download PEACH here

Installation

Move peach-x.x.x.tar.gz file into your installation directory, for example, ~/src, where '~' is the Unix alias for your home directory.
Open yor file browser and click on peach-x.x.x.tar.gz to unzip it, OR: open a Terminal window and change directory to the installation directory: cd ~/src. Unzip peach-x.x.x.tar.gz: tar xvzf peach-x.x.x.tar.gz. This will create the PEACH directory and put all the goodies into it.
For easy installation run the install_peach.command script in the PEACH directory by clicking on the file in your file browser or by typing install_peach.command in the Terminal window. The script will compile all libraries and examples, and will setup the shell variables required for using the library.
Copy Makefile from the work directory into the directory where you will be compiling your experiments (or just use the work directory for this purpose). Restart your terminal window (or terminal tab) to reload shell variables. You are ready to go!

For manual installation:

cd into the PEACH/glui-2.35/src directory and type make. This will compile the GLUI library and will create a libglui.dylib (MacOS) or a libglui.so (Linux) library file in the same directory.
Return to the root PEACH directory and run make from there. This will compile the PEACH library and will create a libpeach.dylib (MacOS) or a libpeach.so (Linux) library file in the PEACH directory.
cd into the examples directory and run make again. This will compile the example files for the tutorial.

Edit your shell startup file. Depending on your terminal shell (type ps -p $$ to find out information on the shell that you are running):
For C shell (csh) or TENEX C shell (tcsh) add the following lines to .cshrc or .tcshrc:

  setenv LD_LIBRARY_PATH ${HOME}/src/PEACH:${HOME}/src/PEACH/glui-2.35/src:${LD_LIBRARY_PATH}
  setenv DYLD_LIBRARY_PATH ${HOME}/src/PEACH:${HOME}/src/PEACH/glui-2.35/src:${DYLD_LIBRARY_PATH}
  setenv PATH ${HOME}/src/PEACH:${PATH}

For shell (sh) or Bourne-Again shell (bash) add the following lines to .profile or .bashrc:

  export LD_LIBRARY_PATH=${HOME}/src/PEACH:${HOME}/src/PEACH/glui-2.35/src:${LD_LIBRARY_PATH}
  export DYLD_LIBRARY_PATH=${HOME}/src/PEACH:${HOME}/src/PEACH/glui-2.35/src:${DYLD_LIBRARY_PATH}
  PATH=${HOME}/src/PEACH:${PATH}

Copy Makefile from the work directory into the directory where you will be compiling your experiments (or just use the work directory for this purpose).
Restart your terminal window (or terminal tab) to reload shell variables.

Todo:: Port this library to Windows. This should be easy, since all the essential code is platform-independent.

Todo:: Add TCP/IP signaling capabilities to communicate stimulus onset/offset events and observer responses to an external application (e.g. an EEG recording software).