Teem: Unrrdu: General unu Info


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.

You get a listing of all possible unu commands by typing just "unu".
You can always get usage information for command cmd by typing just "unu cmd". If, when composing a long chain of unu commands, you want to see the usage for a command you're going to use, then type Ctrl-a Ctrl-k, and then type "unu cmd" for the usage info. After you've read that, type Ctrl-y to get back the long line you were editing. If this doesn't work for you, use a better shell.

Usage information for a command always comes in three parts: general information, usage line (starts with "Usage: "), and a glossary of all the options shown in the usage line. Here's the output of "unu gamma":

unu gamma: Brighten or darken values with a gamma. Just as in xv, the gamma
value here is actually the reciprocal of the exponent actually used to
transform the values.

Usage: unu gamma [-i <nin>] -g <gamma> [-min <value>] [-max <value>] \
       [-o <nout>]

    -i <nin> = input nrrd
  -g <gamma> = gamma > 1.0 brightens; gamma < 1.0 darkens. Negative gammas
               invert values (like in xv). (double)
-min <value> = Value to implicitly map to 0.0 prior to calling pow().
               Defaults to lowest value found in input nrrd. (double)
-max <value> = Value to implicitly map to 1.0 prior to calling pow().
               Defaults to highest value found in input nrrd. (double)
   -o <nout> = output nrrd (string); default: "-"

Any flagged command-line options (the ones preceeded by "-i", "-t", "-s", and the like) can appear in any order. The unflagged options are parsed in the fixed ordering indicated by the usage line.
Optional arguments are enclosed in square ("[]") brackets.

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:

"-i",
"-o" 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.

General unu Info

Command-line usage and arguments

nrrd library vs. unu program

Common command-line arguments

Input and Output

General `unu` Info

nrrd library vs. `unu` program