The MPIRE Users Manual

Parameter Files

Parameter files are used to set the values of the widgets of the MPIRE interface, and to control non-interactive rendering sessions. The following is an example of an MPIRE parameter file. This file is used in conjunction with CT data of the upper portion of a dog thigh.

  400 300
  /usr/mpire/Dogleg
  0
  4.0
  golden.sdsc.edu
  16
  splatter
  1 16 1 256 256
  1.0 -1.0 1.0
  /usr/mpire/materials/dogleg.full.mats
  1 1 1 1 0

The first line indicates the desired size (in pixels) of the rendered image. The first number represents the width of the image, and the second number the height of the image. So for this example, MPIRE would generate images 400 pixels wide by 300 pixels high. Acceptable values for these fields range between 1 and 4096.

The second line gives the absolute pathname to the directory which contains the raw data slices on the render host.

The single value on the third line indicates the type of data slices contained in the previously defined directory. A value of "0" indicates that the slices are in a CT format that includes a header. "1" indicates the slices are in a headerless CT format. "2" indicates the slices are in CT format available from the Visible Human Project. "10" indicates the slices are in RGB format available from the Visible Human Project. "21" indicates the slices are pre-colored MRI data.

The single value on the fourth line represents the z-spacing value and may be a floating point number. This number defines the inter-slice distance for the particular data set you are studying. As newer scanning devices are capable of recording slices closer together, this value affects the apparent scale of the scanned subject along the slice axis. If the width to height ratio of a subject in a rendered image does not appear correct, it is likely that the z-spacing value used is incorrect.

The fifth line contains the official hostname of the render host that you have access to.

The sixth line contains the PE group size to use.

The seventh line contains the name of the rendering engine to use. Acceptable values include splatter and caster.

The eighth line has the range of slices to render (from slice, to slice, and step) and the slice resolution in x and y.

The three values on the ninth line indicate the direction of the light source relative to the volume. Appropriate values are between 1 and -1 inclusive.

The tenth line is the full pathname of the file containing the material description file on the render host.

Finally, the last line contains a 0 or 1 for each of the information widgets: configuration data, shading times, rendering times, transfer rate, and debug.

Material Files

MPIRE material description files provide the rendering engine with the information required to complete the shading stage of the rendering process. Specifically, material description files define the number of distinct materials (such as tissue types) present in the scanned object, the density ranges associated with each material, and the opacity and color of each material as it should appear in the rendered image.

Different material description files can be used to highlight particular characteristics of the volume data. For example, in studying a fracture in a femur, a user may wish to view only the bone, so a description file which makes all materials except bone completely transparent (alpha = 0.0) is used. Note that a user could also create a description file with only the bone materials given.

The following is an example of an MPIRE material description file. This file is used in conjunction with CT data of the upper portion of a dog thigh and is included in the distribution.

  7
  -119  0.037  0.042 0.090 0.042   0.420 0.900 0.420
   -32  0.060  0.074 0.074 0.042   0.740 0.740 0.420
    -7  0.03   0.074 0.074 0.042   0.740 0.740 0.420
    30  0.15   0.065 0.025 0.023   0.650 0.250 0.230
   130  0.03   0.065 0.025 0.023   0.650 0.250 0.230
   200  0.4    0.082 0.080 0.076   0.825 0.800 0.765
  2000  0.4    0.082 0.080 0.076   0.825 0.800 0.765

The single value on the first line indicates the number of transitions defined in this description file. 7 transitions implies that there are 6 distinct materials defined in this example. The next 7 lines have a density (in the range -1000 to 2000), an alpha value (0.0 to 1.0), an ambient RGB color, and a diffuse RGB color. The first line means that all voxels from -119 to -31 have alpha = .037 and diffuse color = (.42,.9,.42). An alpha value of 0.0 is completely transparent, while an alpha value of 1.0 is completely opaque. Any voxels less than -119 or greater than 2000 are not shaded and therefore never rendered.

Glossary

caster: One of the rendering engines that can be used with MPIRE. The name comes from the algorithm used to perform the rendering of an image (the ray casting algorithm).
colored sample: An atomic element from a slice of a volume data set, which has been colored (or shaded) based on the density of the tissue at that location.
Java applet: A small application written in the Java programming language that can be run using your web browser.
MPIRE: The name given to the interactive direct volume rendering system described in this manual. The acronym stands for Massively Parallel Interactive Rendering Environment.
MPIRE applet: A Java applet containing the graphical user interface for the MPIRE application.
MPIRE module: An AVS module containing the graphical user interface for the MPIRE application.
processing element (PE): A single processing unit belonging to a multiprocessor computer.
raster: A two dimensional array of picture elements (pixels).
raw data slice: A slice from a volume data set, as delivered by the original scanning device or computer simulation (uncolored and unshaded).
raw sample: An atomic element from a slice of a volume data set, as delivered by the original scanning device, or computer simulation (uncolored and unshaded).
shaded slice: A slice from a volume data set in which every element has been colored based on tissue type, and shaded using a Phong reflection model.
splatter: One of the rendering engines that can be used with MPIRE. The name comes from the algorithm used to perform the rendering of an image (the splatting algorithm).
UNICOS: A Cray Research, Inc. derivative of AT&T's System V UNIX operating system.
UNICOS/mk: A Cray Research, Inc. derivative of AT&T's System V UNIX operating system specifically for use with the T3D and T3E parallel supercomputers.
volume data set: 3D array of voxels
volume rendering: The process of converting a volumetric data set into a viewable image.
voxel: Volume element - a position and a value
viewing plane: Refers to the virtual plane in a projection model, which is co-planar to the raster and used as a basis for determining the relative orientation of the viewer to the volume being viewed.

COMMUNICATIONS PROTOCOL

Initiating a connection between an interface and an MPIRE rendering engine is a two stage process. In a production environment, the assumption is that multiple parties could simultaneously be using separate instances of one or more engines, each with one of the two interface types currently available (Java applet, AVS module). To allow for this multi-user capability, the interface first connects to the rendering daemon renderd, and then to the instance of the rendering engine started for it by this daemon. Specifically:

The interface opens a streams socket to renderd. This daemon runs on the host (or the host front-end in the case of the T3D) where the engine will be used. The daemon listens on port 17472.
The interface sends a message to renderd that includes:
- 1 byte unsigned header containing the length of the body of the message (in bytes)
- a character string made up of 3 null-terminated "\0" substrings that include the following elements in the following order:
  - the port number on which the new engine should be listening for this interface
  - the number of processors on which the engine should be started
  - the name of the desired rendering engine; the only values of this string that are currently supported are "caster" and "splatter", though this may change as new renderers become available; specifying the engine type in this way prevents the interface from having to know the location or name of the actual rendering executable
The daemon starts the requested engine on the requested processors if available (renderd will block until the necessary processors become available) and returns a message containing:
- 1 byte unsigned header containing the length of the body of the message (in bytes)
- a null-terminated "\0" character string containing the actual port number on which the engine was started; this may differ from the requested port number if that port is already in use by another engine
The interface closes the connection to renderd.
The interface opens a streams socket to its rendering engine now running on the desired host. The port used in this connection is that returned by renderd. This connection will be used later to transfer the rendering parameters to the engine and the resulting images from the engine.
The interface opens another streams socket to its engine. The port used in this connection is that returned by renderd + 1. This connection will be used later to transfer status information from the engine.

At this point the stage is set for a rendering session. Through the course of the session, the user will make changes to one or more of the rendering parameters and a new image will be rendered. This changed parameter / new image cycle continues until the user exits from the interface. Specifically:

Changes to one or more of the rendering parameters has occurred in the interface. The interface sends a message to the engine via the data connection, containing the elements of the rendering parameters data structure. This message consists of an array of bytes with the following contents:
- a: 4 byte integer 0 or 1 indicating if configuration data should be sent across the status socket
- b: 4 byte integer 0 or 1 indicating if shading times should be sent across the status socket
- c: 4 byte integer 0 or 1 indicating if debugging data should be sent across the status socket
- d: 256 byte array of ASCII characters containing the path to the raw data (on the render host)
- e: 4 byte integer denoting the format of the raw data, supported values include:
  - "0" denotes Computed Tomography data
  - "1" denotes headerless Computed Tomography data
  - "2" denotes Computed Tomography data from the Visible Human Project
  - "10" denotes RGB (microtomed) data from the Visible Human Project
  - "21" denotes Magnetic Resonance Imaging data from General Electric
- f: 4 byte integer containing the interslice increment (the number of slices to skip between those that are actually read in the slice range)
- g: 4 byte integer that encodes (float value * 100.0) a floating point number representing the physical distance between data slices in proportion to the physical spacing between samples within a slice (sometimes referred to as Z spacing)
- h: 4 byte integer containing the number of the first slice in the range that will be rendered
- i: 4 byte integer containing the number of the last slice in the range that will be rendered (inclusive)
- j: 4 byte integer containing the resolution of the slices in X
- k: 4 byte integer containing the resolution of the slices in Y
- l: 256 byte array of ASCII characters containing the path to and name of the file that holds the materials classification information
- m: 4 byte integer that encodes (float value * 100.0) a floating point number representing the X component of the direction of the light source (valid values are between -1.0 and 1.0)
- n: 4 byte integer that encodes a floating point number representing the Y component of the direction of the light source (valid values are between -1.0 and 1.0)
- o: 4 byte integer that encodes a floating point number representing the Z component of the direction of the light source (valid values are between -1.0 and 1.0)
- p: 4 byte integer containing the desired resolution (storage size) of the shaded voxels in bytes (deprecated)
- q: 4 byte integer containing 900 or 901 denoting whether the engine is to shade / reshade the volume and render an image, or just render a new image respectively; the interface must decide this based on which parameters have changed since the previous image was rendered (901 is issued if parameters a, b, c, r, s, t, u, or v have been modified, and 900 otherwise; in cases where both 900 and 901 type parameters have changed, code 900 is always issued)
- r: 4 byte integer 0 or 1 indicating if rendering times should be sent across the status socket
- s: 4 byte integer 0 or 1 indicating if render host-to-interface host image transfer times should be sent across the status socket
- t: 4 byte integer containing the desired resolution of the rendered image in X
- u: 4 byte integer containing the desired resolution of the rendered image in Y
- v: a 4 x 4 array of 4 byte integers that encodes (float value * 10000.0) the 16 floating point numbers representing the camera transformation (viewing) matrix; the elements of the array should be stored in row-major order (array[0][0] first followed by array[0][1] followed by array[0][2], array[0][3], array[1][0], etc.)
The engine returns zero or more messages to the status connection based on the values of the status information parameters (a, b, c, r, s). Each message is an array of ASCII characters.
The engine returns a message to the data connection containing the rendered image. Each pixel in the image is a 4 byte entity, 1 unsigned byte for each of the red, green, blue, and alpha channels. The pixels of an m x n image are ordered in the message as: scanline 0 pixel 0 followed by scanline 0 pixel 1 ... scanline 0 pixel n followed by scanline 1 pixel 0, etc.
The previous three steps may be repeated as many times as are necessary.
The interface stops the rendering engine by closing the status connection and then the data connection.