Get Teem at Fast, secure and Free Open Source software downloads

bane/gkms tutorial: Step 0: Preparing the data

This tutorial does not work with any recent versions of Teem. Sorry.

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

    This creates the following:

    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".
We now return to the rest of the tutorial ...