Download the Visapult Source Code!

February 9, 2003
Access to the Visapult source will resume after we complete some Tech Transfer paperwork. Please check back after 1 March 2003. Sorry for the inconvenience.

July 9, 2002
Note: at this time, the version of Visapult source linked on this page is out-of-date, and has some known compilation problems. Following up from the recent 10Gig demonstration, efforts are underway to bring the information and software distributions on this page up-to-date. Look for more information on or about July 12, 2002. Sorry for the inconvenience.

Index

Quick Links

Components of the Distribution

In order to run the bare-bones version of the LBL Visapult system, you'll need to make sure you have the following components.

  1. LBL Visapult Source
    This is the implementation of the LBL Visapult viewer, and a sample MPI-based data rendering engine.



    The source code is a rooted subtree that looks like this: 
    	visapult/
	visapult/viewer
	visapult/backEnd
	visapult/common
    There are no restrictions upon the placement of the Visapult tree, it can be under your home directory, in /tmp, or wherever.
    At this time (16 November 2001), the back end data engine is capable of reading data in one of four formats: AVS-format "volume files", by connecting directly to a DPSS, a file-based version of the DPSS volume data format (called FDPSS), or an experimental data format used by UCSF for confocal microscopy data (called UCSF). Support was added for a custom UDP-based protocol for the SC01 Bandwidth Challenge, which is not documented on any of these pages.



  2. Pthreads
    The viewer uses a pthreads-based parallelization model. The backEnd uses a combination of MPI and pthreads. Pthreads was "already on" all the machines we used for development and testing, so you may already have this on your machine. We have built and run the viewer on: Solaris 2.6/2.7, IRIX 6.5, Linux RH 7.2/7.3.
  3. MPI
    The host that runs the data back-end needs to either have native MPI, or you need to grab, build and install MPICH. Mpich is a free, buildable implemenation of MPI that runs on a wide variety of machines. Note that you are free to write your own data engine that uses some other parallel programming model.
  4. OpenRM Scene Graph
    The guts of the renderer is a scene graph API. You can grab source or binaries for this tool for free from the OpenRM website. This tool is an Open Source project, and provides many of the same features as something like Performer or Inventor.
    We usually install the libraries & header files for OpenRM into a semi-public location on the workstation, such as /usr/local. Many of the Visapult Makefiles assume this location. This version of Visapult (16 November 2001) is built using the 1.4.2 version of OpenRM (note: OpenRM 1.4.2 was released in late June 2002, but the current Visapult tarball has been tested against both the 1.4.2 and 1.4.1 versions of OpenRM - both those versions are API compatible as far as Visapult is concerned).
  5. The Fast Light Toolkit
    The Fast Light Toolkit (FLTK) is an Open Source GUI layer that provides GUI services on Win32 and X11 platforms. It may be downloaded for free from www.fltk.org. We used version 1.0.11 with the Nov 2001 release of Visapult, and have not tried newer versions of FLTK. Check the viewer Makefile's to see where we install this stuff on our development platforms.

The Visapult core contains hooks to two other useful resources, Netlogger and DPSS. Should you wish to use either of these resources, please visit the links below. Use of Netlogger and DPSS is optional, and the IBRAVR prototype will compile and run without the need to obtain either DPSS or Netlogger.

Building and Running Visapult

This distribution is a snapshot of a working prototype. It is not intended to be a finished product, nor intended to install and build smoothly on all machines. We assume that you are intimately familiar with building complex programs on Unix systems, and a working knowledge of "make".

Building Visapult Core

Following are instructions for building the Visapult core. We're going to assume that:

  1. OpenRM is installed in /usr/local/rm142
  2. MPI is available as MPICH in /usr/local/mpich
  3. Pthreads is already on your machine (solaris, Irix or Linux).
  4. The Visapult tarball is located in /tmp/visapult-postSC01.tgz
  5. FLTK includes are located in /usr/local/include, and libfltk.a is located in /usr/local/lib.
  6. We're going to unpack and build the Visapult package under our home directory in $HOME/visapult

To build the Visapult package, please do the following:

  1. Unpack the tarball. 
    	% cd $HOME
	% gunzip -dc /tmp/visapult-postSC01.tgz | tar xvf -
    The sources are rooted in a visapult subdirectory, so you don't need to explicitly create that directory.
  2. Make links from visapult/backEnd/ and visapult/viewer to visapult/common. 
    	% cd $HOME/visapult
	% ./makelinks.csh
    This script creates symbolic links inside of the viewer and backEnd directories, since the networking code is shared by both client and server.
  3. Configure the makeinclude file used in subdirectories. 
    	% cd $HOME/visapult
	% ./config.csh [-dpss=/dpss/dir] [-netlog=/netlog/dir]
    This script creates a file in $HOME/visapult called makeinclude. The purpose of this file (at this time) is to set make flags that will be used to conditionally compile in either DPSS or Netlogger.
  4. Build the viewer.
    The $HOME/visapult/viewer subdirectory is the location of the viewer code. Unfortunately, to build the viewer (and the backEnd) you have to start swimming through makefiles. There are two Makefiles, one for X11 and one for Win32. This discussion focuses on the X11 Makefile, which is just called "Makefile." Inside the Makefile are includes that pick up architecture specific definitions, e.g., makeinclude.linux. Pick the include that is the closest fit to your environment and start changing pathnames to in that makeinclude to match your environment. You should only need to change pathnames, not the list of libraries, etc. Then, build the viewer using your new makefile.
  5. Build "backEnd," the MPI data client.
    The $HOME/visapult/backEnd subdirectory is the home for the MPI data engine. Again, pick the makeinclude that most closely matches your environment, make a copy, and start changing pathnames. We have both MPICH 1.1 and MPICH 1.2 Makefiles, and they are pretty verbose. Then, build the back end using your new Makefile.

Running The Two Components, the Viewer and the BackEnd

From a high level view, the viewer needs to be started (run) before the back end is started. The reason is that the viewer does the listen() and accept() calls, while the back end attempts to connect() to the viewer over the network.

Running the Viewer

After making sure that your LD_LIBRARY_PATH variable is set to include OpenRM (and optionally the DPSS libraries, and to Mesa on Linux for the OpenGL libraries), cd into $HOME/visapult/viewer.

Starting with the November 2001 version of Visapult, two versions of the viewer are created: viewer and viewerFltk. The latter uses FLKT for GUI, and is not documented here at this time. It does run, and in fact, is what we use here at LBL more than we use the non-FLTK version of the viewer. Documentation is not being included at this time because we are in the midst of a major rewrite.

Next, run the viewer from the command line with: 

	% cd $HOME/visapult/viewer
	% ./viewer [args]
or 
	% cd $HOME/visapult/viewer
	% ./viewerFltk [args - not documented]

All of the following command line options are optional. (note that some or all of these may not work with the FLTK-enabled viewer)

Running the Back End

Since the backEnd is MPI based, you will launch this program like any other MPI job, using mpirun. Thus, launch the job thus: 

	% cd $HOME/visapult/backEnd
	% mpirun -np NN ./backEnd [args]

Where "-np NN" specifies the number of PEs to use. The "-np" syntax varies between implementation, check your local documentation. Also, beware that many builds of MPICH use rsh to start up processes even on the local machine, so you you get a "Permission denied" error after this job starts, that's probably the problem (remedied with an ~/.rhosts file).

Configuration and Arguments

There is a file called mpiclient-config in the mpiclient directory that contains text like the following: 

#set useHostName 0
set useHostName 1

# host name example
set connectString bozo.lbl.gov
# IP address example
#set connectString 192.168.0.2

You must modify this file so that the backEnd program knows the location of the viewer. You can specify either a hostname, such as bozo.lbl.gov, or a dotted-quad IP number. If you want to use a real hostname, make sure the set useHostName 1 line is uncommented, and set useHostName 0 is commented away.

Of the following backEnd command line arguments, you must specify a data source (using either -avs fname or -dpss fname). All other parameters are optional.

Building and Running with Netlogger

Please refer to this page for more information concerning instrumentation of Visapult with Netlogger.

Building and Running with DPSS

The Distributed Parallel Storage System, or DPSS for short, can be thought of as a network cache for data. The DPSS itself is described in more detail at http://www-didc.lbl.gov/DPSS.

For more information concerning Visapult DPSS data and metadata files, as well as information about building and running the DPSS-enabled Visapult, please refer to the Visapult-DPSS page.

Sample Data

AVS Volumes

A number of sample volume are distributed with the AVS system. If you don't have access to this distribution, we can't post these files on the web because they belong to AVS. You might check at the International AVS Center (www.iavsc.org). In the AVS distribution, the sample volumes are located in $AVS/data/volume, and all have a .dat suffix.

However, the file format is pretty simple, so you can create some sample data in pretty quick order. Here's the file format: 

Byte 0: the X size of the volume (varies fastest)
Byte 1: the Y size of the volume (next fastest)
Byte 2: the Z size of the volume (varies slowest)
X*Y*Z bytes of data.

Note that with this format, the largest possible volume you can have is 255*255*255.

F-DPSS Combustion Sample Data, May 15, 2000

The term F-DPSS refers to a file-based representation of the format used on the DPSS. The DPSS is not completely a production system, so a small file-based version of some sample DPSS is being made available in this tarball (~110 Mbytes).

The contents of the tarball are as follows:

  1. Base14-config - This is a small ASCII file containing configuration information: 
    /judgedee/tmp/wes/data/Base14 
640 256 256 3 1 
density 1.345 2.45495
    The first line is a file basename. You will need to modify this line so the part up to "Base14" contains the directory where this tarball is unpacked on your system. The second line says that the grid is of size 640x256x256 points, has 3 timesteps, and one variable. The final line is the name of the species, or variable, and the following two numbers are the minimum and maximum data values contained in the entire dataset (all grid points and timesteps of the Base14 dataset).
    The Base14-config file and it's reader are very fragile: no comments, no extraneous characters, etc. You must modify the path on line 1 of this file to reflect the location of the other Base14-* files on your system. Lines may not be rearranged, etc.
  2. Base14-boxes
    This is a file containing raw, binary box data for each time step. There are no user-configurable knobs in this file.
  3. Base14-boxes-config
    This file contains configuration information about the Base14-boxes file; there are no user configurable options for this file.
  4. Base14-density
    This file contains the raw density data in big-endian, IEEE floating point format. There are 640x256x256x3 data points in this file. There are no user configurable options for this file.
F-DPSS Usage

Unpack the Base14.tgz tarball somewhere on your system thus: 

	% gunzip -dc Base14.tgz | tar xvf -

Uncompressed, it will expand into about 492 Mbytes.

No special steps are needed to use the FDPSS format on the viewer side. However, when you run the Visapult back end, use the following command line arguments (example): 

	% mpirun -np 4 ./mpiDataEngine -fdpss /someDirectory/Base14-config

Note the use of the -fdpss switch. The filename that follows points to the Base14-config file. Inside the Base14-config file, be sure that you've edited the first line to contain the directoy path to the location of the other Base14 files.

Internal to the Visapult back end, a family of filenames is built from the first line of the Base14-config file. Therefore, a value of /someDirectory/Base14 inside the Base14-config file will be expanded into /someDirectory/Base14-boxes, /someDirectory/Base14-boxes-config, and /someDirectory/Base14-density (because the variable name "density" is contained within the config file.

Note that since the species file, "density" in this case, is a flat file, it is possible to concatenate together large blobs of raw data, and to access them as a single blob of data via the config file. Unfortunately, there is no support for file chaining. The Visapult back end has been tested with large files (> 4Gbytes), and will work fine for large files. Beware, however, that most implementations of NFS are not 64-bit safe, so you'll probably want to put your large files on a local disk, and not one that is NFS mounted.

Below are two sample images from the 3rd time step of the Base14 tarball, with and without grid boxes. The command lines used to generate these pictures are: 

Visapult viewer
    % viewer -boxes

Visapult backend
    % mpirun -np 4 ./mpiDataEngine -fdpss /tmp/Base14-config -pal ./sc99Palette
base14-noboxes base14-boxes

DPSS Resident Data

A number of sample data sets are resident on the DPSS at LBL, including the Base14 example (above). In fact, the FDPSS version of the DPSS-resident version was created by first "dpss_get"'ing all the Base14-* files from the DPSS, editing the Base14-config file, then rolling up a tarball.

In order to access the DPSS, you will need to closely examine the instructions for building a DPSS-enabled Visapult backEnd. Those instructions, along with a description of the data format, is listed on the Visapult-DPSS page.

UCSF Format

image of microscopy data

Data in the UCSF format consists of two files: a big wad of binary data, and a small ascii file containing metadata. The binary volume data consists of a header component, followed by raw voxel data stored as big-endian, unsigned shorts. Each short is purported to be a 12-bit voxel stored in a 16-bit word, but examination shows that only 8 significant bits of data are present in the low-order byte of each short. Thus, at this time (23 Aug 2000), the upper 8bits of data is discarded (ignored), and the low-order bytes are converted to floats in the range 0..1.0.

The small ASCII metdata file is something we added to aid in describing the data in the binary wad, and is particular to Visapult. Here's the contents of a sample file: 

/tmp/binaryWad
256 256 64 1
11264

Line one contains the full path name to the raw binary file. Line two contains the dimensions of the raw volume data. In this example, the volume consists of 64 slices of data, each slice is 256 by 256 pixels, and there is only one time step's worth of data. Line three is the number of bytes of header to skip over in the binary data file. All information in the header is ignored - we didn't have any documentation on the contents of this header: it's length may be subject to change from binary file to binary file, and may not work on all files (that's why we call this "preliminary support").

The binary file for this example will consist of 11264 bytes of header data, which we ignore, followed by 256x256x64xsizeof(short) voxels worth of data.

Release Notes Summaries

9 July 2002

This release, referred to as the "Post SC01" release, contains all changes made to support full UDP interaction with Cactus, and was the code used in the 10Gb Ethernet demonstration at Berkeley in July 2002.

16 November 2000

Post SC00 release.

23 August 2000
09 August 2000
09 June 2000
16 May 2000
27 March 2000
24 March 2000
7 March 2000
3 March 2000
22 Feb 2000
21 Jan 2000
Jan 7, 2000

Feedback

Please send any feedback to ewbethel at lbl dot gov.