Special Interest Area: Visualization

Rendering Data With VISTA On Datastar

—Steven Cutchin

This article explains how to use the SDSC-developed VISTA volume renderer to create high quality images from simple scalar volume data files.

A lot of simulation code that is run on DataStar produces 3D volume data as output. VISTA is a software renderer that will quickly and easily let you generate very nice, high quality images of that data directly on DataStar. By using VISTA on DataStar you can quickly and easily generate a variety of 3D views of your volume data for a broad range of application domains: astronomy, fluid flow, atmospheric—for anything that outputs volumetric data, VISTA can help you create nice snapshots quickly and easily.

First let's talk a little about your output data. For the purpose of this article we are going to work with a sample data set that is a 512^3 scalar block of floats. The data is a regular grid and all stored in a single file as one big block of floating point numbers. VISTA can handle other formats, but how to work with those will be covered in other articles. So for the purposes of this article, we will assume that you have a big block of floats in a single file. VISTA can work with any resolution on any of the axes—1024 by 880 by 22 if you like. However, for this article we will be using an example volume that is 512 on each side.

What is VISTA?

VISTA is a software renderer that does perspective ray-casting to directly render volume data into images. Another way to say this is that it is a ray-tracer designed to work with volume data. It has many features such as multi-threading, arbitrary size images, and user definable cameras. The web page for VISTA, with lots of documentation, is at http://visservices.sdsc.edu/software/vista.

Example Data

The example data set used in this article is a 512 cube block of floats generated by evaluating the mathematical equation for a monkey saddle: x^3-3xy^2-z. This equation was selected because it is a well known equation, has asymmetric properties and generally produces a pleasant image. The example file is in /gpfs/projects/vis/monkey_512by3.raw. We will place more example volumes on DataStar as we put together more tutorials.

Step-by-Step Rendering

Follow these basic steps (explained in detail in the following sections) to start using VISTA to render out your data sets:

Add vistools to your path
Do your first test render: vista -raw 512 512 512 /gpfs/projects/vis/monkey_512by3.raw
Determine the min and max of your volume using rawminmax
Do a collection of other views front, back, left, right , top, and bottom
Changing image resolution
Adjusting rendering quality
Using multiple threads
Using different color functions
Using doubles, ints, or shorts
Converting .ppm files to .jpg or .png

1. Add vistools to your path

In order to use VISTA and the other software tools that come with it, you need to add the directory for the executables to your PATH environment variable.

If you use csh, type the following at the command line:

% set path = ( /gpfs/projects/vis/vistools/bin $path )

If you use sh, use its standard mechanism.

After you have done that, you should be able to type vista at the command prompt, and you should see the following output:

usage: vista [options] <volumefile>

You see this message because vista can not do anything without a volume to render.

2. Do your first test render: vista -raw 512 512 512 monkey_512by3.raw

After you have vista in your path and can run it you are ready to render out your first image of your volume data set. To do this for our example data set, type: img_000000.ppm image (should be all black)

vista --raw 512 512 512 /gpfs/projects/vis/monkey_512by3.raw

This will generate an image filed called img_00000.ppm in your current directory. To display this image, copy it to your local machine and use your favorite image viewing program. The image should look like the image displayed at right. That image looks all black. The reason is because vista by default assumes that all of the data in your file is normalized to the range 0.0 to 1.0. However our data has a different range than that.

3. Determine the min and max of your volume using rawminmax

In order to get a good looking image using vista we need to tell it what the range of the data values in the volume are. If you know what they are, then this step is easy—but what if you don't know? In that case, you can use a simple tool we developed called rawminmax that will read a data file, extract the minimum and maximum values, and print them on the command line. So in this case type:

rawminmax /gpfs/projects/vis/monkey_512by3.raw

This will output the values -33553920.0 and 33554688.0, telling us that the data in our file ranges from -33553920 to 33554688.0. rawminmax will work with data files other than float. Just call it with the --help option to see the other data types it supports.

Now to render out an improved image using this new information, simply execute:

vista --raw 512 512 512 --minmax -33553920.0 33554688.0 /gpfs/projects/vis/monkey_512by3.raw

This will generate a new image in img_00000.ppm. This image looks much better and displays the entire data range of the volume. The new image should look like the image displayed at right.

4. Do a collection of other views: front, back, left, right, top, bottom

Now you have the beginnings of a pretty reasonable looking image; but what if you want to look at it from different viewpoints? vista provides a collection of pre-built camera views. The first --persp is what is rendered by default. Then there are the 6 standard orthogonal views: --front, --back, --left, --right, --top, --bottom andfinally you can give vista a collection of arbitrary cameras in a .cam file using the --cam option. This option will be covered in a later article. You can combine any number of these options on the same command line; e.g., to do all six ortho renders at the same time for our sample data set you would execute:

vista --raw 512 512 512 --front --back --left --right --top --bottom --minmax -33553920.0 33554688.0 /gpfs/projects/vis/monkey_512by3.raw

This should produce the six images from img_00000.ppm to img_00005.ppm shown below:

5. Changing Image Resolution

All of the previous images were rendered out at 320x240 resolution. That is pretty small and not very useful. However, vista supports arbitrary resulution images, and it's really easy to generate whatever size you like:

vista --raw 512 512 512 --front -x 1280 -y 1024 --minmax -33553920.0 33554688.0 /gpfs/projects/vis/monkey_512by3.raw

will produce an image of 1280x1024 resolution. Use the -x option to specify the width of the image and the -y option to specify its height. Any volumes rendered will be scaled to fill up the same percentage of a larger image that they do in a lower resolution image. Click on the image at the right to see a 1280x1024 resolution version.

6. Adjusting rendering quality

All of the previous renders look acceptable, but the quality of the rendering isn't as nice as it could be. This is because the step size along the rays that intersect with the volume is, by default, a little large. To improve the quality of the image you can have vista take smaller steps along the rays to sample the volume at a finer resolution. Do this with the -a option. A good rule of thumb is to use the inverse of the largest axis of your volume. So in our case, that is 1/512 or approximately 0.002:

vista --raw 512 512 512 -a 0.002 --front -x 1280 -y 1024 --minmax -33553920.0 33554688.0 /gpfs/projects/vis/monkey_512by3.raw

This result looks very nice.

You should notice that this run took significantly longer than any of the previous runs. This is because we are taking a lot more samples of the volume and this takes more compute cycles. So use the -a option carefully or you can find yourself waiting a very long time for your images to render.

7. Using multiple threads

But what if I want to use a very small -a option? How do I speed up the renders? On DataStar you have the advantage of having many CPUs on each node. So you can use vista's multi-threaded -n option to render an image using many threads. Use the -n option to specify the number of threads you want to render the image:

vista --raw 512 512 512 -n 4 -a 0.002 --front -x 1280 -y 1024 --minmax -33553920.0 33554688.0 /gpfs/projects/vis/monkey_512by3.raw

The resulting image looks the same as the previous image but rendered much faster. This is because 4 CPUs where used to render it instead of 1 CPU.

In one run with one thread using a -a of 0.002, it took 41 seconds to render out the volume. With the -n 4 option it took 15 seconds. So you should notice a significant speed-up.

All of the vista code is very thread-friendly, and you can use as many threads as you would like to speed up image rendering. Unfortunately, the performance doesn't scale up linearly, and using more than 8 CPUs on a 32-way node often does not give a lot of improvement beyond that gained with just 8.

8. Using different color functions

The images are looking quite nice now, but what if you don't like the color scheme that vista is using? What can be done to change that? Quite a lot. vista provides 18 different built-in color maps that you can choose from as well as a custom color map option to use your own custom-defined color maps. The table below shows 3 predefined color maps and one custom map:

vista --grey --raw 512 512 512 -n 4 -a 0.002 --front -x 1280 -y 1024 --minmax -33553920.0 33554688.0 /gpfs/projects/vis/monkey_512by3.raw
vista --bigspect --raw 512 512 512 -n 4 -a 0.002 --front -x 1280 -y 1024 --minmax -33553920.0 33554688.0 /gpfs/projects/vis/monkey_512by3.raw
vista --hsi1 --raw 512 512 512 -n 4 -a 0.002 --front -x 1280 -y 1024 --minmax -33553920.0 33554688.0 /gpfs/projects/vis/monkey_512by3.raw
vista --tmapfile simplecolor.cmp --raw 512 512 512 -n 4 -a 0.002 --front -x 1280 -y 1024 --minmax -33553920.0 33554688.0 /gpfs/projects/vis/monkey_512by3.raw

Check out the Vista documentation for more on custom color functions.

9. Using doubles, ints, or shorts

What if I have a regular grid of doubles or integers or shorts? vista supports most built-in data types (and even multivariate files, but that is another tutorial) using the simple --rawtype option. vista can handle int, float, short, byte, and unsigned short. Double is on its way but not quite ready yet. If you want to experiment with multivariate files you can try out the --rawvars option to specify the number of variables in a volume.

10. Converting .ppm files to .jpg or .png

You should be able to just type convert filename.ppm filename.jpg at the command line prompt and it should convert the .ppm files into .jpg files. Type convert alone to get a list of arguments for convert.

Where do I go for more help with the VISTA renderer?

If you like what you see in vista you can get a lot more documentation and support. There are at least four different mechanisms for getting help:

use
vista --help
for an extensive list of all options. Be warned there are a lot!
check out the on-line documentation at http://visservices.sdsc.edu/software/vista
send an e-mail to visgroup@sdsc.edu

Future topics of discussion

I hope that the information in this article helps to give you some easy methods for quickly making nice looking imagery from your simulation runs. I intend to follow up this article with others with more advanced capabilities of vista and other visualization tools. Some future topics planned are:

How to use vista with other file and data formats
How to create customized color maps
How to work with histograms from your data
How to create custom cameras for animations
How to create imagery from 2D data sets
Techniques for handling very large data files > 4 GB

Or send me an e-mail at cutchin@sdsc.edu and let me know what you would be interested in reading about.