In this workshop you will explore the representation of two-dimensional scalar data fields with indexed color images. For this we will acquire some simple C-language programs that create mathematical data sets, alter them slightly to write the data in a form suitable for scientific visualization, compile and execute them on the Seismology Sun system, and then interpret the data with a visualization program running on your PC.

One reason we use a program to create data is so you will see how to visualize the output of your own scientific programs. The simple example program here creates a 2-dimensional scalar field (two independent variables and one dependent scalar variable). You can think of this field as a total-field aeromagnetic map if you are a geophysicist, a head map if you are hydrologist, a temperature map if you are an atmospheric scientist, a topographic map if you are a geologist, a stress magnitude map if you are an engineer, an atomic force map if you are a physical chemist, or a population density map if you are a biologist.

Although the C programs are very simple, they rely on subroutines from what are known as the ``HDF'' libraries from the National Center for Supercomputing Applications (NCSA) at the Univ. of Illinois in Urbana-Champaign. NCSA also supplies the ``Collage'' and ``xcollage'' programs we use to view the HDF data and palette files. For this workshop we have the C compiler, the HDF libraries, and xcollage available on the Seismology Sun systems. On the MSM MMV Mac and PC machines we have versions of the collage program as well.

NCSA does distribute the source code for the HDF libraries for compiling on other systems, and has versions of Collage for most varieties of Macintosh, MS-Windows, and UNIX computers. Click here for information on where to obtain such software. Most more recent image-analysis programs can import the HDF data and palette formats. Most likely in your work you will not use the NCSA HDF libraries, but you will need to pay attention to some of the same issues of scaling and color that we will address here with the example programs.

If you are using a Mac or PC with collage loaded and have a UNR Seismology login, you can compile the C programs on the Sun, and load the resulting HDF-format data files down to your computer, for viewing with your local copy of Collage. For the class lab those not having their own Seismology logins will use a guest login.

Although this workshop makes little use of the types of documents usually viewed on the World-Wide Web, the instructions are available to your WWW viewer program at the URL:

http://www.seismo.unr.edu/ftp/vis/color/exercises.html

Exercise 1:

1) Use the following procedure to download the program ``ex01.c'' linked below to your home directory on the Sun (or to your display computer, if you have obtained appropriate versions of the NCSA software described above). In Netscape, point at the link and hold down the (right) mouse button. Select ``Save This Link As...'' in the menu that pops up, and release. (From Mosaic, select ``Load to Disk'' under the "Options" menu. Then click on the link below to acquire it via FTP.)

ftp://quake.seismo.unr.edu/vis/color/ex01.c

2) From the same FTP source copy all the files ending in ``.hdf'' to your directory. These are all different binary palette files. You may use them whenever you need to load a palette into Collage. Click directly on the link below to see all the files in the FTP directory. Then set ``Load to Disk'' or ``Save This Link As...'' to acquire each of the ``.hdf'' files in turn. Make sure you specify ``Source'' and not ``Text'' in the save dialog box that will pop up.

ftp://quake.seismo.unr.edu/vis/color/

3) Add the code below to scale the data and write out the raster image. It goes into ``ex01.c'' near the end. Use can use the same method that you used to edit the PostScript or HTML files in the previous workshops. If you are sitting at a Seismology Sun, you will want to open text editor and command tool windows on the desktop.

for( i = 0; i < IMAX; i++ )
{
	for( j = 0; j < JMAX; j++ )
	{
		cdata[i][j] = (char)(int)( ( ( 
			      ( data[i][j] - dmin ) /
				(dmax - dmin) ) * 253. ) + 1. );
	}
}

DFR8putimage("ex01.hdf", cdata, IMAX, JMAX, 0 );

(Mosaic 1.0.3 for the Macintosh may not show the code above correctly, so you can click here to download the file code.c).

4) Compile the program.

• If up to this point you have edited the program on your computer, are in the class lab or are a registered Seismology Sun user, but don't have your own C compiler or the HDF libraries, then click here to start a terminal session on a Seismology Sun with your Telnet program.
• If you are in the class lab and don't have a Seismology login of your own, log in as ``guest'', and give the password as instructed in the lab. Hit ``Return'' if you are asked about ``TERM = (vt102)''.
• Then if you are logging as guest type out the command:

  cd name

  where name is your last name, all in small letters.
• To transfer your altered ``ex01.c'' program to your guest location on the Sun, go to your Netscape session on the PC and open the following location:

  ftp://guest@quake.seismo.unr.edu/user/guest/name
  again where name is your last name, all in small letters.

  or, if you have your own Seismology login:
  ftp://name@quake.seismo.unr.edu
  with name being your login name will take you to your home directory.

  You can select these strings, copy, and paste them into Netscape's ``Netsite'' item and hit return. You will give the Sun login password (as instructed if you don't have your own).
• Then look under Netscape's File menu, and you will see that the ``Upload File'' item, which is usually grayed out, is now available. Select it and find your file on the PC, and it will be transferred to the Sun machine where you can compile it.
• If you edited the program on a Mac, you may need to type a ``mac2unix ex01.c'' command into your telnet window just before you compile.
• An example C compiler command for this program is:

  cc -DMISPEL -o ex01 ex01.c -ldf -lm

  Type this command in your Telnet window.

5) Run the program by typing ``ex01'' at the command tool or Telnet prompt.

6) If you have your own copy of Collage but are running the ex01 program on the Sun, first download the ex01.hdf output of the program to your computer, using a location like ``ftp://guest@quake.seismo.unr.edu/user/guest/name'' in Netscape as above, making sure you save as binary source and not text.

7) Start your computer's version of Collage, or start X Collage on a Sun by typing the command ``xcollage &'' at the command tool prompt.

8) Open the data file ex01.hdf using the File menu in the Collage window.

9) Bring up the picture by double-clicking on the Raster Image Group item in the Picker window (on the Mac, a little colored screen). If clicking has no effect, try selecting the Raster Image Group and then selecting ``Send Selection'' from the ``Transport'' menu of the Picker window.

10) Use the Collage Windows or File menu to open a palette or the palette editor. (On the Mac, with the image window active, the Window menu has a little palette icon that brings up the palette editor.)

11) Load the default palette from the file default.hdf using the Palette Editor's File menu, or the Collage File menu on the PC. (You may need to point the mouse at the color bar in the Palette Editor or the image to see the correct colors. The rest of the screen will then go to wild colors. You may also need to select Use Entire Palette from the image's Edit menu to see the whole palette, although the menus may become difficult to read with that set.) (On the Mac you can also select palettes from the lower part of the image menu.)

12) Experiment with the items in the image window's Operations menu, and with the operations icons beside the image. (Image menu on the Mac.) On the PC you can try loading all the HDF palettes you downloaded, to see the data in different ways.

Now you have produced a 2-d color visualization of the result of a scientific calculation, by adding code to a program that writes out the result in a visualization format. For this visualization, the color image represents a map of a small region. Every pixel in the image has a scalar value, which for this code could be the hydraulic head in an underground aquifer at each point on the map. You can think of the head as the elevation or height of the water table. (This code computes head values with an extremely simple mathematical function.) The function of the palettes is to translate the head values into colors. According to the colors in the palette, low heads will have a particular range of colors, medium heads other colors, and high heads yet other colors.

As you inspect your visualization, make sure you find out what areas on the map have low heads, and what areas have high heads. In this case the low heads are on the low end of the palettes, and the high heads on the high ends of the palettes (this can be reversed if desired). The main point of this exercise is for you to see how to manipulate color palettes to show the details you need to see in the map. A scalar field like this can certainly be contoured. However, as you inspect the map with different palettes, you should find that details in the high-, low-, and medium-head parts of the map appear and disappear. Unlike a contour map, a color image can also immediately distinguish the highs from the lows on the map, even to the untrained eye. What was the mathematical function used to generate the head map?

Darker shades appear to the eye to be further away, so are often used to represent low values. Lighter shades appear closer, and thus higher, to most people. You may also be familiar with a topographic color palette used on many world maps, where the ocean abyssal depths are deep purple, ocean plains are blue, shallow seas and continental shelves light blue, low plains dark green, uplands light green to yellow, and mountains ascend from orange to white. What palettes in our collection show these properties, and which were designed to show details rather than average head? Which palettes might you use to explore such data yourself, and which for a single poster or journal presentation figure?

Exercise 2:

1) Copy the ``ex02.c'' program to your directory:

ftp://quake.seismo.unr.edu/vis/color/ex02.c

2) Add the code to scale the data and write out the raster image. (The exact same code can be used from ex01)

3) Compile and run the program, with a procedure similar to what you used for ex01.

4) Bring up the image in Collage.

5) Load in the palette of your choice. Make sure you are using the same palette as in the first exercise, and are pointing at the Palette Editor.

6) Use the dashed box selection tool on the tools palette (just lest of the image) create a histogram of the image.

To find the Histogram:

Select dashed box selection tool on the tools palette (just lest of the image).

Position the mouse in the upper left of the image.

Push and hold the left mouse button.

Sweep out a rectangle that encloses most of the image.

Release the mouse button.

Point at the Palette editor to see the right colors in the histogram window that pops up.

(On the Mac you can just select Histogram from the Image menu.)

7) Use the Fiddle operation in the Palette Editor window to change the distribution of the palette. You sould be able to create an image similar to the first example by squeezing the palette and shifting it to the left. Look at the histogram to see how the colors are distributed among your data values.

To Fiddle:

Select the fiddle in the Palette Editor window. Your cursor wil become a cross in the middle of the palette editor window. (On the Mac, select the top fiddle in the tool bar that pops up with the Palette Editor; the cursor becomes a fiddle when pointed at the color bar.)

Move the mouse up and down to squeeze the palette and move it side to side to reposition it. Click the middle button to stop fiddling. (On the Mac, drag the fiddle cursor over the color bar with the mouse button down.) You may use the Reset under Edit or Load to read the original palette again to start over. You may use the fiddle several times in sucession without resetting. (On the Mac select the Palette window and then select Edit->Undo or File->Open.)

Because a palette here cannot have more than 256 different colors, when you squeeze all its colors into just one part of it you are effectively losing resolution between colors and therefore between different values in the head map. You may find for some palettes that after squeezing or other fiddling you cannot resolve as many details in some areas of the image as you could in Exercise 1. The extreme value compromises the quality of the visualization of the entire head map.

Exercise 3:

1) Copy the ``ex03.c'' program to your directory.

ftp://quake.seismo.unr.edu/vis/color/ex03.c

2) Add the code to write the Scientific Data Set to the HDF file.

	DFSDsetdims(2, shape);

	DFSDputdata( "ex03.hdf", 2, shape, data );

3) Compile and run the program.

4) Start Collage and load in your favorite palette.

5) Load in the HDF file you created with the Open command under the File menu of the Collage window.

6) Open up the data set by double clicking on the Scientific Data Group item.

7) Use the Make Image command to create an image of these data. Select OK when it asks for the X and Y Magnification.

8) Use the Point Selection option (the small diamond-shaped point left of the image) to see the corespondence between the floating point numbers and the image. You may activate the Point Selection in either the image or the spreadsheet or both. As you point in one the data point you select is highlighted in the other.

9) See if you can locate the one value that is 10 times bigger than the rest. It is in the center of the four humps in the upper left of the image.

In visualization you often have to treat outlying extreme data points in two separate ways. First you have to construct an image that shows the outliers very clearly, so you can identify and locate them. Then you have to contruct an image that ignores the outliers to show details in the remainder of the data.

Exercise 4:

1) Copy the ``ex04.c'' program to your directory.

ftp://quake.seismo.unr.edu/vis/color/ex04.c

2) Add the code to write the SDS with the minimum and maximum.

	DFSDsetdims(2, shape);

	DFSDsetrange( &dmax, &dmin );

	DFSDputdata( "ex04.hdf", 2, shape, data );

3) Compile and run the program.

4) Use Collage to look at an image of this data.

Note that the explicit use of the min and the max values had no effect on the image created. Some packages, NCSA Image on the Mac for example, take advantage of this information.

Exercise 5:

ftp://quake.seismo.unr.edu/vis/color/ex05.c

2) Compile and run the program. (You don't have to add any code!)

3) Start Collage and load the ``waves.hdf'' palette.

4) Load in the data file ``ex05.hdf'' .

5) Examine the data.