PXLab Manual

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

Installation

Three Steps to Run PXLab Applications
1. Make sure that you have the latest Java software installed. You can check this by going to java.com, the download page for the Java runtime environment (JRE). Select 'Verify Installation' (German: 'Installation überprüfen') from the choices offered on this page and press the button labeled 'Verify Installation' on the subsequent page. If the response tells you that you have the latest Java then goto step 2. If you do not have the latest Java software, then go to the download section of java.com and download the latest Java runtime environment. Use the 'Typical setup' installation option and use 'Verify installation' to check whether the installation was successful. [This step is sufficient to run most of the demo applets contained in this manual and on the demo pages.]
2. Download the file PXLabRT.zip and unzip it into a PXLab installation directory of your choice, c:\pxlab say. You will need a program to unzip the archive PXLabRT.zip. If you do not have such a program installed then Windows will offer you to open the zip archive directly. Create your destination directory c:\pxlab with the file explorer in this case and copy the archive content into this directory.
3. Use your file explorer to find the file named pxlab.jar in the PXLab installation directory. Double click on this file and the PXLab ExRun control program starts with its Open Design File dialog. Go into the subdirectory of your installation root named pxd and choose a design file (a file with extension pxd) from this subdirectory and the experiment will start.

Overview

This chapter covers the steps which are necessary to install PXLab for running experiments as local applications.

Running local PXLab applications requires two installation steps:

  1. Get and install a Java runtime environment, and
  2. install the PXLab software package.

Of course, you can skip the first step if you already have a working Java runtime environment installed. The current version of PXLab requires Java version 6. For optimal performance you should always use the latest version of Java.

The Java Runtime Environment

Running PXLab applications and creating experimental design files requires a working Java runtime environment. The Sun Microsystem Java runtime environment (JRE) may be downloaded from Sun Microsystems' Java download site for several different operating systems.

Sun's download site also contains information on how to install the software. Please always download the latest version and install the Java runtime environment (JRE) for your operating system according to these instructions. It simplifies things if you choose the 'Typical setup' option and use the 'Verify installation' option to check your installation.

If the JRE is installed then you should be able to run the applets from the page of PXLab Demonstration Experiments.

The Sun JRE installer installs at least one public command: 'java' which can be used to start Java applications. This command can also be used to start PXLab experiments. On the Windows operating system the JRE installer will also register Java Archive ('jar') files to be executable by double clicking on them. This feature is used by PXLab to make its archive file pxlab.jar executable.

The PXLab Runtime Environment

The minimal PXLab runtime environment package is contained in the archive PXLabRT.zip which contains the following directories:

.
the root directory contains the PXLab Java classes archive named pxlab.jar. This archive contains the complete PXLab software package. This directory also contains a file named pxlab.properties. This file can be used to tell the PXLab system where local startup initialization files may be found. This feature will be treated later.
pxd
contains the experimental design files which also may be found on www.pxlab.de as demos and as a lab course. Subdirectories of this directory contain support files for several demo experiments. Most of these are images needed by some experiments.
bin
contains some executable batch files and dynamic link libraries (DLL) for Windows. These libraries support some native extensions for Windows but are not necessary for standard PXLab applications.

This directory structure is already contained in the zip-file PXLabRT.zip. So the only thing you have to do is to unpack the zip-file PXLabRT.zip into a single directory of your system while preserving the zip-file's directory structure. We suggest to use a directory named pxlab for installing PXLab.

If the JRE is installed properly then double clicking on the file pxlab.jar starts the PXLab experimental runtime controller ExRun. There are several other ways to start PXLab experiments. Some of these methods are used by the batch files in subdirectory bin of the PXLab installation directory. Most of these methods require that the JRE 'knows' where the file pxlab.jar may be found.

There are several ways to tell the JRE where the PXLab classes are. We describe the most simple one only:

Figure out where the JRE installer has installed the software. If you choose the 'Typical setup' option then the current version (JRE 1.6.0) installs the software into a directory like C:\Program Files\Java\jre1.6.0. This directory contains a subdirectory named lib\ext for Java library extensions. Move or copy the file pxlab.jar into this directory and the Java runtime environment will always find the PXLab packages.

Running PXLab Applications

The subdirectory bin of the directory where you have extracted the file PXLabRT.zip into contains some batch files for starting PXLab demos and applications. These are prepared to run under Windows using the latest Sun Microsystem Java runtime environment with pxlab.jar being installed in the JRE's library extensions directory as described in the previous section.

So in this case you may simply open a command window, change to the bin subdirectory of your PXLab installation root and run any of the following command files:

ex.bat
to start an experiment,
ed.bat
to start the PXLab Experimental Design Editor,
vd.bat
to start the Vision Demonstrations program,
de.bat
to start the PXLab Display Editor,
caltool.bat
to start the PXLab Color Calibration Tool.

This only works if the location of these batch files is your current working directory and the file pxlab.jar has been copied to the JRE lib/ext directory.

In order to run PXLab applications from every working directory you have to tell the operating system where the executable files are. This is done by adding the PXLab bin path to the system path list contained in the environment variable PATH.

Here is how to modify PATH under Windows XP:

From the Start-menu open the Control Panel, open 'System' and activate the panel named 'Extended'. Open the dialog 'Environment Variables'. Select the variable 'Path' of the panel 'System Variables' and press the 'Modify button. Then add 'C:\pxlab\bin' to your current definition of PATH, assuming that you did install PXLab into directory 'C:\pxlab'. Note that the various paths in PATH have to be separated by a colon. Her is an example how the final Path should look like: 

   ...;C:\WINNT\System32;...;C:\pxlab\bin

The chapter 'Running an Experiment' contains more detailed information on how to run PXLab applications and also on how to integrate experiments into HTML-pages.

Data Files

Note that the demonstration experiments in the PXLab subdirectory pxd are configured such that they write their data files into subdirectories named dat and dtr of that directory from where the PXLab application had been started. The data files will have the root name pxlab with an extension depending on the type of data file.

System Properties

You may skip this section at first reading.

For some experimental applications it is quite useful to tell PXLab something about the physical system it is running on. An example is gamma correction for device independent color. In these cases PXLab needs some information about the physical screen. This type of information should be contained in files named system.pxd and screen.pxd. The location of these files must be defined in a file named pxlab.properties. A prototype properties fiel is contained in the PXLab installation directory. See chapter 'Running an Experiment' where PXLab searches for the properties file.

The file pxlab.properties should at least contain two lines of text like 

 
   pxlab.home=c:/pxlab 
   pxlab.local=c:/pxlab
telling PXLab that both its global home and its local installation directory is c:/pxlab. If the file pxlab.properties is not found then c:/pxlab is assumed to be the PXLab home directory. pxlab.home is the global PXLab installation directory and pxlab.local is a local client installation directory. The differece between the two is necessary for network installations where pxlab.home is installed on a server and pxlab.local contains information about the local client which actualla runs the experiments.

The archive PxlabRT.zip contains this default version of pxlab.properties. If you do not install PXLab into c:/pxlab then you have to manually edit the properties file and enter the correct installation directory.

Native Code Extensions

You may skip this section at first reading or if you do not want to use native code extensions for Windows.

The basic PXLab runtime package PXLabRT.zip includes some native code extensions for Windows. These are not necessary for running experiments but they will provide vertical retrace synchronization for time critical displays and DirectInput methods for special input devices. Vertical retrace synchronization requires that Microsoft DirectX is being installed which usually will be the case. The native code is contained in the dynamically linked library file pxlab.dll and some additional DLLs. This file will only be found by the operating system library loader if it is contained in a directory which is included in the PATH list of directories. Extraction from PXLabRT.zip moves the DLL files into the bin subdirectory of the installation path. If you include this directory into PATH as described earlier then everything is OK and PXLab will automatically use the native extensions. If you do not include the bin subdirectory into PATH then you should move pxlab.dll and the other DLL files into your Windows system directory which usually will be WINDOWS\System32.

Sorry, but currently vertical retrace synchronization is available for Windows only.

Further Archives

The PXLab distribution contains the archive files listed below. Their internal directory structure is such that all of them should be extracted into the PXLab root installation directory.
PXLabRT.zip contains the complete runtime environment for running PXLab experiments as local applications or applets.
PXLabRTX.zip also contains the complete runtime environment for running PXLab experiments and some extensions which are mainly useful for running PXLab applets. This version contains two archive files: pxlabrt.jar and pxlabrtx.jar. The two together have the same content as pxlab.jar. pxlabrt.jar is optimized for applets in the sense that it contains only those parts of PXLab which are necessary to run an experiment as an applet. It does not contain the GUI components which can't be used with applets. Thus pxlabrt.jar can be much smaller than pxlab.jar. The archive PXLabRTX.zip contains additional files which are useful for implementing PXLab applet pages. This includes an optimized starter button and a PHP script for sending collected data to an arbitrary E-Mail address.
PXLabAPI.zip contains the PXLab API documentation. Will be installed into the subdirectory doc of your PXLab root directory.
PXLabSrc.zip contains the complete source tree to rebuild PXLab from source. If you intend to develop your own PXLab applications or extend PXLab classes by writing your own Java source code then you probably should install the source tree into a separate development directory. See the chapter named The PXLab Software API for more information on using the PXLab source code.

If you want to download this manual then use the link which shows the complete manual as a single HTML page and use your browser's 'save as...' command to save the manual files.

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

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