Installation Instructions for Priism 4

The instructions below describe the installation of Priism. If Priism was packaged with version 3.2 of the VolumePro 1000 driver, the compressed archive containing the driver is in the vp1000 directory of the Priism distribution. Follow the instructions in vp1000/VP1000ReleaseNotes-Linux.txt to install the driver (ignore the final step in the installation instructions and the verification procedure since the include files and silver demonstration application are not included).

1. Unpack the downloaded archvive

Uncompress the files from the downloaded archive. From the command line this can be done as follows where archive should be replaced with the full path name of the downloaded file:

gunzip -c archive | tar -xf -

This will place the files in a directory called priism-version where version is the version number (for example, 4.2.3). You can move that directory or change its name.

Some browsers will automatically uncompress the archive when you download it. In that case, gunzip will complain that the file is not in gzip format, and you would want to use the following commands instead:

tar -xf archive

Other browers will automatically uncompress the archive and extract the component files into a new directory. In that case, simply move or rename that directory so it is where you want Priism to be installed.

2. Run post_install.sh

post_install.sh fixes up the paths in the Priism setup files. On Mac OS X it also updates the symbol tables of the archive libraries included with Priism. On IRIX, Linux, and Mac OS X systems, post_install.sh will also ask about the location of Matlab (if it is installed) to configure the Priism to .mat file converters. post_install.sh should be run from the directory in which Priism is installed; i.e. at the command line enter

cd install_dir
./post_install.sh

where you would replace install_dir with the path to where you put Priism in the first step.

3. Try it out

Before starting Priism, an X server must be running and the DISPLAY environment variable must be set appropriately so clients can connect the server (setting the DISPLAY to :0.0 is generally appropriate for clients connecting to an X server running on the same machine).

If you use csh or tcsh as your shell, then you should now be able to start Priism by entering the following at the command line:

source install_dir/Priism_setup
Priism

If you use sh or an sh-compatible shell like bash, the you should now be able to start Priism by entering the follow at the command line:

. install_dir/Priism_setup.sh
Priism

The result in either case should be that a thin dialog containing a menu bar should appear (some window managers may expect you to select a location for the dialog before it is shown). If the dialog does not appear, check that you did run post_install.sh and have installed the other required libraries.

4. Customize Priism_setup and Priism_setup.sh (optional)

The setup files, Priism_setup and Priism_setup.sh, contain settings that should work for most systems. Some settings that you may want to modify or override are discussed below; others are mentioned with comments in Priism_setup and Priism_setup.sh.

Location of the shared memory file

The default versions of Priism_setup and Priism_setup.sh cause the shared memory file and related temporary files to be put in whatever directory the environment variable TMPDIR contains or, if TMPDIR is not set, /var/tmp. Because these files may be large (their size is related to the amount of image data loaded into Priism; this can easily be hundreds of megabytes), you will want to override or change the default if the default location does not have much space. To override the default, set the environment variable IVE_SHMDIR to the directory where the files are to be placed. This must be done before Priism is started (it can happen before or after reading Priism_setup or Priism_setup.sh). To change the default, alter the logic for how IVE_SHMDIR is set in Priism_setup and Priism_setup.sh (in the original versions this happens at lines 191-197 in Priism_setup and line 203-204 in Priism_setup.sh

Working set size

There is a limit, the working set size, on how much space the image data and the scaled images derived from that data can take up in the shared memory file. When that limit is exceeded, Priism will start discarding scaled images or moving image data out of the shared memory file and into other temporary files. There is a crude heuristic in Priism_setup and Priism_setup.sh which sets the working set based on how much RAM your machine has. This heuristic may not be optimal for your system. For instance, the working set is set at 256 megabytes for systems with more than 320 megabytes of RAM; for systems like that you may want Priism to use more memory so you can load more image data without incurring the performance hit when the working set size is exceeded.

To override the default working set size, set the environment variable IVE_WORKING_SET to the number of megabytes that the working set should be. This must be done be done before Priism is started and after Priism_setup or Priism_setup.sh is read since they will reset IVE_WORKING_SET. To change the default, you can alter the heuristic (lines 162-172 in the original Priism_setup and line 173-183 in the original Priism_setup.sh) and the default of 96 megabytes when the amount of RAM could not be determined (line 124 of the original Priism_setup and line 137 of the original Priism_setup.sh).

If you change the working set to be something close to or larger than 300 megabytes, you should also change the maximum size of the shared memory file (see below for details).

Working unit

Priism divides the working set into blocks of a fixed size called the working unit. For versions prior to 4.1.5, the default working unit is 6 megabytes; for versions 4.1.5 and later, the default working unit is 16 megabytes. The effect of the working unit is:

In versions of Priism prior to 4.1.2, any attempt to load a data set whose full 2D section size is greater than the working unit would fail.
For Priism versions 4.1.2 and later, if it is possible to allocate new blocks from the working set, then Priism is can use a multiple of the working unit to accommodate data sets where a section is larger than the working unit. However, Priism can not coalesce blocks from the working set once they are allocated so that, depending on what data sets have been loaded previously, it may be not possible or inefficient to load a data set with a section size greater than the working unit.

You can set the working unit by setting the environment variable IVE_WORKING_UNIT. The units of IVE_WORKING_UNIT are megabytes and the value must be an integer.

Maximum size of the shared memory file

The shared memory file has a maximum size that is fixed when the file is created. This maximum size defaults to 300 megabytes. If you increase the working set to something close to or greater than 300 megabytes you should also increase the maximum size. To change the maximum size, set the environment variable IVE_SIZE to the size in megabytes. This must be done before Priism is started. The absolute maximum size is 1000 megabytes for IRIX and Mac OS X (at 1050 megabytes, Priism can not start) and 2000 megabytes for x86 Linux (at 2050 megabytes, Priism can not start).

5. Configure batch execution environment and queues (optional)

Some parts of Priism can submit a script to perform a task offline with the choice to either run it locally or submit it to a batch queue. BatchRegion.html in the HTML directory of the Priism distribution describes how you configure the batch queues and the environment for locally executed parallel jobs.