[Home] [Content] [Previous Chapter] [Next Chapter]
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:\pxlabsay. 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:\pxlabwith 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.jarin 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
pxdand choose a design file (a file with extension
pxd) from this subdirectory and the experiment will start.
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:
- Get and install a Java runtime environment, and
- 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
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.
- 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.
- 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
pxlabfor installing PXLab.
If the JRE is installed properly then double clicking on the file
pxlab.jarstarts 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
binof the PXLab installation directory. Most of these methods require that the JRE 'knows' where the file
pxlab.jarmay 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\extfor Java library extensions. Move or copy the file
pxlab.jarinto this directory and the Java runtime environment will always find the PXLab packages.
Running PXLab ApplicationsThe subdirectory
binof 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.jarbeing 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
binsubdirectory of your PXLab installation root and run any of the following command files:
- to start an experiment,
- to start the PXLab Experimental Design Editor,
- to start the Vision Demonstrations program,
- to start the PXLab Display Editor,
- 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.jarhas been copied to the JRE
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
binpath 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 FilesNote that the demonstration experiments in the PXLab subdirectory
pxdare configured such that they write their data files into subdirectories named
dtrof that directory from where the PXLab application had been started. The data files will have the root name
pxlabwith an extension depending on the type of data file.
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
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.
pxlab.propertiesshould at least contain two lines of text likepxlab.home=c:/pxlab pxlab.local=c:/pxlabtelling PXLab that both its global home and its local installation directory is
c:/pxlab. If the file
pxlab.propertiesis not found then
c:/pxlabis assumed to be the PXLab home directory.
pxlab.homeis the global PXLab installation directory and
pxlab.localis a local client installation directory. The differece between the two is necessary for network installations where
pxlab.homeis installed on a server and
pxlab.localcontains 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:/pxlabthen you have to manually edit the properties file and enter the correct installation directory.
Native Code ExtensionsYou 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.dlland 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
binsubdirectory 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
binsubdirectory into PATH then you should move
pxlab.dlland the other DLL files into your Windows system directory which usually will be
Sorry, but currently vertical retrace synchronization is available for Windows only.
Further ArchivesThe 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:
pxlabrtx.jar. The two together have the same content as
pxlabrt.jaris 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.jarcan 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
docof 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]