bane/gkms tutorial: Step 0: Preparing the data

It is often the case that a given volume dataset needs some pre-processing before it makes sense to analyze or visualize it. Cropping out large regions of background value is one common task, which is demonstrated below, using the unu command-line utility. There are many other things which make sense as pre-processing steps in working with volume data (down-sampling or re-sampling, quantizing, converting, etc), and unu can do all of these. Try it out!

1. The engine-block CT scan dataset is available from Stanford's volpack related pages. Download the file engine.den.Z and uncompress it, creating the file engine.den.

2. engine.den contains the raw data we care about, plus some binary header stuff we don't care about. Sounds like a job for unu! With one command, we can create a simple ASCII header file which stays seperate from the data file, called (for example) engine.den.nhdr. We create it with:

   unu make -h -i ./engine.den -t uchar -s 256 256 110 -sp 1 1 1 -c engine \
     -bs 62 -e raw -o engine.den.nhdr
   

   • "unu make" is the command for creating nrrd files from existing data; "unu make -h" makes detached header files
   • "-s 256 256 110": these are the dimensions ("sizes") of the dataset.
   • "-sp 1 1 1": these are the spacings for the samples; these voxels are isotropic
   • "-bs 62": there is a 62 byte binary header that we'll need to skip over

   This creates the following:

   NRRD0001
   content: engine
   type: unsigned char
   dimension: 3
   sizes: 256 256 110
   spacings: 1 1 1
   data file: ./engine.den
   encoding: raw
   byte skip: 62
   encoding: raw
   

3. As you may already know, this dataset contains a lot of useless background value. If we crop it out, all further analysis will run raster, and the results (including the renderings) will be the same. Sounds like a job for unu! This use of unu project generates a maximum intensity projection (measure #2) along the Z axis (axis #2) and Y axis (axis #1) so that we can see how to crop it:

   unu project -i engine.den.nhdr -a 2 -m max -o engine.den-maxZ.png
   

   

   unu project -i engine.den.nhdr -a 1 -m max -o engine.den-maxY.png
   

   

4. Inspecting the resulting images (with a tool like xv) tells us that the (x,y) coordinates (59,207) and (20,227) encompasses all the interesting stuff with about three voxels of border. In the Z axis, there is need for cropping (in fact, it seems to have been a bit too aggressively cropped already). If you want to indicate "the last index along this axis", without knowing how big that axis is, you can use "M" instead of a number. Thus, we invoke unu crop with:

   unu crop -i engine.den.nhdr -min 59 20 0 -max 207 227 M -o engine-crop.nrrd
   

5. We can verify that the cropping worked right, with another use of unu project:

   unu project -i engine-crop.nrrd -a 2 -m max -o engine-crop-maxZ.png
   

   

6. Supposing that you don't want the nrrd header and the raw data together in the same file, you break the file into two parts simply by changing the output filename to end in ".nhdr", for "nrrd header":

   unu crop -i engine.den.nhdr -min 59 20 0 -max 207 227 M -o engine-crop.nhdr
   

   The nrrdSave() function of nrrd interprets this filename auto-magically, putting the header information in a small ASCII file called "engine-crop.nhdr", while putting all the raw data (with no header whatsoever) in seperate file called "engine-crop.raw".