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 nrrd and unrrdu parts of teem. 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 unrrdu is probably a good tool for the job. Please Note, however, that the usage of the unrrdu tools will change in syntax shortly (to be similar to how the cvs program works, as well as gkms), but the basic functionality will of course remain.
  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 nrrd! We can create a simple ASCII header file which stays seperate from the data file, called (for example) engine.den.nhdr which contains the following:
    NRRD00.01
    content: engine
    type: uchar
    dimension: 3
    sizes: 256 256 110
    labels: "x" "y" "z"
    spacings: 1.0 1.0 1.0
    data file: ./engine.den
    byte skip: 62
    encoding: raw
    
    The "byte skip: 62" line instructs nrrd to start getting the raw data 62 bytes from the start. If there were lines of ASCII header to skip (such as a VTK header), the field would instead be "line skip: ". Not all the fields used above are absolutely needed; for the curious, here is a minimalist header:
    NRRD00.01
    type: uchar
    dimension: 3
    sizes: 256 256 110
    data file: ./engine.den
    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 unrrdu! This use of unrrdu's project tool 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:
    project engine.den.nhdr 2 2 engine.den-maxZ.pgm
    
    project engine.den.nhdr 1 2 engine.den-maxY.pgm
    

  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 (unrrdu's) crop as such:
    crop engine.den.nhdr 59 207 20 227 0 M engine-crop.nrrd
    

  5. We can verify that the cropping worked right, with another use of project:
    project engine-crop.nrrd 2 2 engine-crop-maxZ.pgm
    

  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":
    crop engine.den.nhdr 59 207 20 227 0 M 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 ...

Valid HTML 3.2!