Teem: nrrd: Inspecting volvis.org datasets


teem	/	nrrd	/	demo	Inspecting volvis.org datasets

Michael Meißner does the world of volume rendering a great service by running the Volvis.org website, which is the source of a number of volume datasets, including some classics like the lobster. This page documents the steps required to create nrrd headers for the files there, as well demonstrating the nrrd API with a simple program for inspecting the datasets.

Making headers

The datasets come as gzip-compressed raw files, which nrrd can read as is, without de-compression. The unu make commands for each dataset are based on the information on the dataset page. To retrieve the compressed datasets, I suggest one of the many fine command-line URL retreival tools, such as curl, snarf, wget, or if you're old school, webgrab. I suggest these tools (using curl in examples below) because many interactive web browsers will cleverly decompress the data for you.

Its helpful to set an environment variable for the base URL that the datasets are coming from:

setenv DATAPATH http://www.gris.uni-tuebingen.de/areas/scivis/volren/datasets/data

Now, for each of the datasets, download the data, and make a detached nrrd header. The "-e gzip" indicates that the data is gzip compressed. Because the data is only unsigned char, byte ordering is not an issue, and the "-en" (endianness) option is not needed. Setting the content field ("-c") is so that subsequent nrrd operations can update the content field according to the actions taken. The use of key/value pairs ("-kv") requires the use of teem version 1.6 or greater.

curl ${DATAPATH}/aneurism.raw.gz > aneurism.raw.gz
curl ${DATAPATH}/BostonTeapot.raw.gz > BostonTeapot.raw.gz
curl ${DATAPATH}/bonsai.raw.gz > bonsai.raw.gz
curl ${DATAPATH}/foot.raw.gz > foot.raw.gz

unu make -h -i ./aneurism.raw.gz -c aneurism -t uchar -e gzip \
  -s 256 256 256 -sp 1 1 1 \
  -kv "source URL:=${DATAPATH}/aneurism.raw.gz" \
      "courtesy:=Philips Research, Hamburg, Germany" \
  -o aneurism.nhdr

unu make -h -i ./BostonTeapot.raw.gz -c BostonTeapot -t uchar -e gzip \
  -s 256 256 178 -sp 1 1 1 \
  -kv "source URL:=${DATAPATH}/BostonTeapot.raw.gz" \
      "courtesy:=Terarecon Inc, MERL, Brigham and Women's Hospital" \
  -o BostonTeapot.nhdr

unu make -h -i ./bonsai.raw.gz -c bonsai -t uchar -e gzip \
  -s 256 256 256 -sp 1 1 1 \
  -kv "source URL:=${DATAPATH}/bonsai.raw.gz" \
      "courtesy:=S. Roettger, VIS, University of Stuttgart" \
  -o bonsai.nhdr

unu make -h -i ./foot.raw.gz -c foot -t uchar -e gzip \
  -s 256 256 256 -sp 1 1 1 \
  -kv "source URL:=${DATAPATH}/foot.raw.gz" \
      "courtesy:=Philips Research, Hamburg, Germany" \
  -o foot.nhdr

Making projections

Having made nrrd headers for the volumes, we can start inspecting what's inside with "unu", such as with:

unu project -i BostonTeapot.nhdr -a 2 -m sum \
 | unu heq -b 3000 -s 1 -a 0.5 \
 | unu quantize -b 8 -o teapot-zsum.png
unu project -i BostonTeapot.nhdr -a 2 -m var \
 | unu heq -b 3000 -s 1 -a 0.5 \
 | unu quantize -b 8 -o teapot-zvar.png
unu project -i BostonTeapot.nhdr -a 2 -m max -o teapot-zmax.png
unu join -i teapot-z{sum,var,max}.png -a 0 -incr -o teapot-z.png


`teapot-zsum.png`	`teapot-zvar.png`

`teapot-zmax.png`	`teapot-z.png`

The projections of summation ("zsum") and variance ("zvar"), but not maximum ("zmax"), are 50% histogram equalized, so that variations at all intensity levels are better visible. NOTE: this means that very minor fluctuations in common values (such as the background) are greatly accentuated. This often allows you to see tomography artifacts that would otherwise be hidden. In the final image, the sum, var, and max images are put into the red, green, and blue channels of an image.

Using the nrrd API

Considering that there are many other pages demonstrating use of unu, it would be nice if there was a program demonstrating use of the nrrd API itself (which unu is built on). Thus ninspect.c was born- a simple utility program for making the kinds of projections shown above. ninspect is a demo program that needs the nrrd, biff, and air libraries to compile, but its easier if you just link against the libteem.a super-library that contains all the objects in teem. Running this program is easy: you supply the input volume filename and the output image filename:

foreach DATA ( BostonTeapot aneurism bonsai foot ) 
  echo $DATA
  ./ninspect ${DATA}.nhdr ${DATA}.png
  unu resample -i ${DATA}.png -s = x0.4 x0.4 -o _${DATA}.png
end

(Make some thumbnail images for these web pages:)

unu crop -i _BostonTeapot.png -min 0 0 0 -max M M 104 \
 | unu resample -s = x0.79 x0.79 \
 | unu pad -min 0 -2 0 -max M M+2 M -o __BostonTeapot.png
unu crop -i foot.png -min 0 268 12 -max M m+255 m+255 \
 | unu resample -s = 80 80 -o ../demo80.png

The images created by this program contain projections along three different axes. The layout of axes within these images is like this:

+------------------------+
|                        |
|  o-----> X  o-----> Z  |
|  |          |          |
|  |          |          |
|  |          |          |
|  v          v          |
|  Y          Y          |
|                        |
|  o-----> X             |
|  |                     |
|  |                     |
|  |                     |
|  v                     |
|  Z                     |
|                        |
+------------------------+

I'm using "X", "Y", and "Z" to refer to the fastest, medium, and slowest axes in the volumes. The fastest axis is the one whose coordinate changes the fastest as one traverses all the samples in linear memory order. There is no effort made to correct for non-isotropic sample spacing along the different axes.

Here is a gallery of the projections so created. Recall the note above about accentuation of fluctuations in the background value: these images make the datasets look a little lower-quality than they really are.


`BostonTeapot.nhdr`	`aneurism.nhdr`	`bonsai.nhdr`	`foot.nhdr`