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

  General unu Info

Command-line usage and arguments

Because all of unu is based on the same command-line parser (hest), there is a great deal of consistency between the various unu commands.

nrrd library vs. unu program

In some sense, unu is a working advertisement for all the functionality in the underlying nrrd library. There is very nearly a one-to-one mapping between unu commands and nrrd function calls, as listed below. Nearly all the unu commands rely on nrrdLoad() for reading the nrrd and nrrdSave() for writing the nrrd. If nothing else, this list provides a bare-bones outline of the nrrd API.
unu command  -  nrrd function
about  -  n/a
make, head, data  -  n/a
convert  -  nrrdConvert()
resample  -  nrrdSpatialResample()
cmedian  -  nrrdCheapMedian()
minmax  -  nrrdMinMaxSet()
quantize  -  nrrdQuantize()
unquantize  -  nrrdUnquantize()
project  -  nrrdProject()
slice  -  nrrdSlice()
dice  -  repeated calls to nrrdSlice()
splice  -  nrrdSplice()
join  -  nrrdJoin()
crop  -  nrrdCrop()
inset  -  nrrdInset()
pad  -  nrrdPad_nva()
reshape  -  nrrdReshape_nva()
permute  -  nrrdPermuteAxes()
swap  -  nrrdSwapAxes()
shuffle  -  nrrdShuffle()
flip  -  nrrdFlip()
axinfo  -  n/a
axinsert  -  nrrdAxesInsert()
axsplit  -  nrrdAxesSplit()
axdelete  -  nrrdAxesDelete()
axmerge  -  nrrdAxesMerge()
histo  -  nrrdHisto()
dhisto  -  nrrdHistoDraw()
jhisto  -  nrrdHistoJoint()
histax  -  nrrdHistoAxis()
heq  -  nrrdHistoEq()
gamma  -  nrrdArithGamma()
1op  -  nrrdArithUnaryOp()
2op  -  nrrdArithBinaryOp()
3op  -  nrrdArithTernaryOp()
lut  -  nrrdApply1DLut()
rmap  -  nrrdApply1DRegMap()
imap  -  nrrdApply1DIrregMap()
ccfind  -  nrrdCCFind()
ccadj  -  nrrdCCAdjacency()
ccmerge  -  nrrdCCMerge()
ccsettle  -  nrrdCCSettle()
save  -  n/a
Part of what makes unu useful is that it implements a little bit of smarts on top of nrrd, or provides a simplified interface to the nrrd API. 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.

Common command-line arguments

Some command-line options appear in multiple unu commands. For the sake of sanity and consistency, whenever the same information is needed by multiple unu commands, the same command-line option is used. Here is a list of the common options:
input nrrd or data, output nrrd
"-t" Scalar type of the data. The possible valid values are exactly the same as for the type field descriptor in the NRRD header. Used by make, convert, and many others. Every type has a one-word equivalent, listed below:
-t int8  :  signed 1-byte integer
-t uchar  :  unsigned 1-byte integer
-t short  :  signed 2-byte integer
-t ushort  :  unsigned 2-byte integer
-t int  :  signed 4-byte integer
-t uint  :  unsigned 4-byte integer
-t longlong  :  signed 8-byte integer
-t ulonglong  :  unsigned 8-byte integer
-t float  :  4-byte floating point
-t double  :  8-byte floating point
"-p" Position in index space along an axis. Used with slice, crop, and pad, for example. This can either be an integer (interpreted as an exact index position), or of the form "M+<int>" or "M-<int>", which is interpreted as some offset (int) from the last sample along that axis. That is, M is highest index along the axis, or, one less than the number of samples along that axis. crop and pad also allow "m+<int>", which is position relative to the given minimum position.
"-b" Number of bins, in a histogram. Used with cmedian, histo, jhisto, histax, heq. ("-b" means "# bits" to quantize)
"-a" Which axis. Always just an integer (the first axis is 0); nrrd has no notion of axis names like "X" or "Y". Used by slice, dice, project, join, and others.
"-s" Axis sizes. Used by make, resample, and reshape to identify the number of samples along each axis.
"-e" Encoding of data. Used by make and save. The arguments to this option are exactly the same as for the encoding field descriptor in the NRRD header.
"-en" Endianness of data. Used by make and save. The arguments to this option are exactly the same as for the endian field descriptor in the NRRD header.

Input and Output

By default, nearly all the unu commands get their input from, and write their output to, stdin and stdout, respectively. The few exceptions to this are commands primarily designed for specialized input or output. Stdin and stdout are both represented to unu by a single dash, "-"; whether it means stdin or stdout is clear from context.

The encoding produced by all unu commands is raw. The exception to this is "unu save", which has a "-e" option to control the output encoding. This is the only way to control encoding with unu.

You can control output nrrd file format with the filename extension supplied to the "-o" option. This is also how to save the output nrrd with a detached header. The interpretation of filename extension is according to the table below. Every command except "unu make" conforms to this behavior.

extension (case sensitive) format
".txt" plain text file
".pgm" PGM image file, raw encoding
".ppm" PPM image file, raw encoding
".png" PNG image file (zlib compression encoding)
".vtk" VTK "STRUCTURED POINTS" file, raw encoding
".nhdr" NRRD file with detached header, raw encoding
".nrrd", anything else NRRD file with attached header, raw encoding

See the Reading and Writing non-NRRD files section of NRRD-Compatible File Formats for details.

If the output is not being written to a file, but sent to stdout, then "unu save" must be used to force a particular format. This facilitates a slick way of viewing 2-D nrrds with xv. If you have a 2-D nrrd of floats, and you want to get a qualitative sense of what it looks like, you can run:

unu quantize -i float.nrrd -b 8 | unu save -f pnm | xv -
No quantized nrrd is ever written to disk, nor is any PGM image.