to teem

unrrdu

teem The Many Diverse Nrrd Utilities from the Great Nation of Deseret

Utah Nrrd Utilities

For nearly all the useful functions in the nrrd library, there is a corresponding command in the unrrdu library which accesses the function via an argv,argc interface intended for command-line use. In fact, the unu program (teem/src/bin/unu.c), does little more than link against the unrrdu library, and unu is by far the fastest and simplest way to enjoy the benefits of nrrd. Strictly speaking, this page describes the unu program, not the unrrdu library it links with, but you'd never know the difference.

The capabilities of unu are listed simply by typing "unu" with no command-line options:

        --- Utah Nrrd Utilities (unrrdu) command-line interface ---
      unu make ... Create a nrrd (or nrrd header) from scratch
      unu head ... Print header of a nrrd file
      unu data ... Print data segment of a nrrd file
   unu convert ... Convert nrrd to another type (as if by per-value cast)
  unu resample ... Filtering and {up,down}sampling with a seperable kernel
   unu cmedian ... Cheap histogram-based median filtering
  unu quantize ... Quantize floating-point values to 8, 16, or 32 bits
unu unquantize ... Recover floating point values from quantized data
   unu project ... Collapse scanlines to scalars along some axis
     unu slice ... Slice at a position along an axis
      unu dice ... Slice *everywhere* along one axis
      unu join ... Connect slices and/or slabs into a bigger nrrd
      unu crop ... Crop along each axis to make a smaller nrrd
       unu pad ... Pad along each axis to make a bigger nrrd
   unu reshape ... Superficially change dimension and/or axes sizes
   unu permute ... Permute scan-line ordering of axes
      unu swap ... Interchange scan-line ordering of two axes
   unu shuffle ... Permute samples along one axis
      unu flip ... Reverse order of samples along one axis
     unu block ... Condense axis-0 scanlines into "blocks"
   unu unblock ... Expand "blocks" into scanlines on axis 0
     unu histo ... Create 1-D histogram of values in a nrrd
    unu dhisto ... Create (PGM) image of 1-D value histogram
    unu jhisto ... Create joint histogram of two or more nrrds
    unu histax ... Replace each scanline along an axis with its histogram
       unu heq ... Perform histogram equalization
     unu gamma ... Brighten or darken values with a gamma
       unu 1op ... Unary operation on a nrrd
       unu 2op ... Binary operation on two nrrds, or on a nrrd and a constant
       unu 3op ... Ternary operation on three nrrds or constants
       unu lut ... Map nrrd through univariate lookup table
      unu rmap ... Map nrrd through *regular* univariate map ("colormap")
      unu imap ... Map nrrd through *irregular* univariate map ("colormap")
      unu save ... Write nrrd with specific format, encoding, or endianness
As you can guess from the above, unu is a lot like cvs in that there is exactly one program to remember the name of (and add to your path), but you access the different capabilities with different command names following "unu". For example, if you run "unu slice", you get:
unu slice: Slice at a position along an axis. Output nrrd dimension is one
less than input nrrd dimension. Per-axis information is preserved.

Usage: unu slice [-i <nin>] -a <axis> -p <pos> [-o <nout>]

 -i <nin> = input nrrd
-a <axis> = axis to slice along (int)
 -p <pos> = position to slice at:
          o <int> gives 0-based index
          o M-<int> give index relative to the last sample on the axis (M
            == #samples-1).
-o <nout> = output nrrd (string)
In keeping with the tradition of effective command-line line tools, like Utah Raster Toolkit or the very popular NetPBM set of utilities, you can chain unu commands together by piping ("|") from one unu invocation to another. The default input and output for unu are stdin and stdout. The command-line parsing engine which makes all of this possible, and which automatically generates the usage information shown above, is hest. Long live the command line.

The functionality in unu is a very good indication of the functionality in nrrd, but there is not an exact mapping between the two. For instance, unu resample provides access to nrrdSpatialResample(), but with some assumptions: the same kernel is being used on every axis which is resampled, and the entire range of indices along an axes is resampled. nrrdSpatialResample() does not have these constraints: different kernels can be used on different axes (or the same kernel with different parameter vectors), and cropping and padding can be done at the same time as resampling. On the other hand, unu crop and unu pad have some intelligence about how they parse the coordinates used to specify the output region. unu crop -min 10 10 -max M-10 M-10 says that the upper bound of the cropping should be 10 samples less than the maximum position along axes 0 and 1. The underlying nrrdCrop function, on the other hand, can take only absolute integer positions.

More information as time permits. But you can just start typing unu commands to see what each one does ...