Installation Instructions for Priism 4

The instructions below describe the installation of Priism.

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 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.

The easiest way to run post_install.sh is to use the Finder on Mac OS X or a file manager on Linux to open the directory where Priism is installed and then double-click on the file with the name, post_install.command. You could also run it from the command-line as follows:

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 to the server (setting the DISPLAY to :0.0 is generally appropriate for clients connecting to an X server running on the same machine). In Mac OS X 10.5 or later, Apple's X11 will start on demand, so you do not need to start it before starting Priism.

On Mac OS X 10.5 or later or Linux with an X server already running, you can use the Finder or file manager to double-click on the Priism.command file in the Priism installation directory and that should start Priism. From the command-line, you can use the following to start Priism if csh or tcsh is your shell:

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

In all cases, a thin dialog containing a menu bar should appear (some window managers may expect you to select a location for the dialog before is 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 241-247 in Priism_setup and line 233 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 Mac or 32-bit Linux 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 185-210 in the original Priism_setup and lines 175-202 in the original Priism_setup.sh) and the default of 96 megabytes when the amount of RAM could not be determined (line 155 of the original Priism_setup and line 149 of the original Priism_setup.sh).

If you change the working set to be something close to or larger than the maximum size of the shared memory file (the value of IVE_SIZE environment variable which is in units of megabytes or 300 megabytes if IVE_SIZE is not set), you must 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:

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 except on x86_64 Linux systems where a default is set based on that amount of memory the system has. If you increase the working set to something close to or greater the maximum size of the shared memory file, you must also increase the maximum size for Priism to work well. To change the maximum size, set the environment variable IVE_SIZE to the size in megabytes. This must be done after reading Priism_setup or Priism_setup.sh and before Priism is started. The absolute maximum size is 1000 megabytes for the 32-bit Mac OS X version (at 1000 megabytes, Priism can not start), 2000 megabytes for x86 Linux or x86_64 Linux when using the 32-bit Priism executables (at 2000 megabytes, Priism can not start), and 1048575 megabytes for x86_64 Linux or Mac OS X when using the 64-bit Priism executables.


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.


Related Priism Topics

Priism | Priism requirements for x86 Linux | Priism requirements for Mac OS X | Known problems | Recent changes | Priism download site


IVE Development Team (ive@msg.ucsf.edu)