Teem: Unrrdu: unu make


teem	/	unrrdu	`unu make`

unu make: Create a nrrd (or nrrd header) from scratch. The data can be in a
file or coming from stdin. This provides an easy way of providing the bare
minimum information about some data so as to wrap it in a nrrd, either to pass
on for further unu processing, or to save to disk. However, with "-h", this
creates only a detached nrrd header file, without ever reading or writing
data.

Usage: unu make [-h] -i <file> -t <type> -s <sz0 sz1 ...> [-sp <spc0 \
       spc1 ...>] [-l <lab0 lab1 ...>] [-c <content>] [-ls <lineskip>] \
       [-bs <byteskip>] [-e <encoding>] [-en <endian>] [-o <nout>]

                 -h = Generate header ONLY: don't write out the whole nrrd,
                      don't even bother reading the input data, just output
                      the detached nrrd header file (usually with a ".nhdr"
                      extension) determined by the options below. The filename
                      given with "-i" should probably start with "./" to
                      indicate that the data file is to be found relative to
                      the header file (as opposed to the current working
                      directory of whomever is reading the nrrd)
          -i <file> = Filename of data file; use "-" for stdin (string)
          -t <type> = type of data (e.g. "uchar", "int", "float", "double",
                      etc.)
   -s <sz0 sz1 ...> = number of samples along each axis (and implicit
                      indicator of dimension of nrrd) (1 or more ints)
-sp <spc0 spc1 ...> = spacing between samples on each axis. Use "nan" for any
                      non-spatial axes (e.g. spacing between red, green, and
                      blue along axis 0 of interleaved RGB image data)
                      (1 or more doubles)
 -l <lab0 lab1 ...> = short string labels for each of the axes
                      (1 or more strings)
       -c <content> = Specifies the content string of the nrrd, which is
                      built upon by many nrrd function to record a history of
                      operations (string)
     -ls <lineskip> = number of ascii lines to skip before reading data
                      (int); default: "0"
     -bs <byteskip> = number of bytes to skip (after skipping ascii lines, if
                      any) before reading data (int); default: "0"
      -e <encoding> = output file format. Possibilities include:
                    o "raw": raw encoding
                    o "ascii": print data in ascii
                    o "hex": two hex digits per byte
                    o "gzip", "gz": gzip compressed raw data
                    o "bzip2", "bz2": bzip2 compressed raw data
                      default: "raw"
       -en <endian> = Endianness of data; relevent for any data with value
                      representation bigger than 8 bits, with a non-ascii
                      encoding: "little" for Intel and friends; "big" for
                      everyone else. Defaults to endianness of this machine;
                      default: "big"
          -o <nout> = output filename (string); default: "-"

This is the first unu command listed because it is often the first one to be used in a longer chain of unu unu commands. The main value in this program is the fact that you don't have to remember and type nrrd field specifications according to the NRRD format. You tell "unu make" the information about the data, and "unu make" will produce the NRRD header for you.

It has two distinct roles:

with "-h": making detached headers only, without ever reading or writing data.
without "-h": making whole nrrds, with or without detached headers, by reading the data (in various possible encodings) and writing it out (as raw)

Wrapping a brick of bytes (with -h)

A common use of "unu make" is to write a header for some brick of bytes, which is often already in a seperate file. For instance, an electron density function dataset (mol.150x150x150.gz) is available from the Army High-Performance Computing Research Center, the makers of BoB (Brick of Bytes), an early interactive volume renderer. If we download the dataset as is, keeping it compressed (use snarf if your browser automatically decompresses the data), we can generate a header for it using "unu make -h":

unu make -h -i ./mol.150x150x150.gz -s 150 150 150 -t uchar -e gzip -o mol.nhdr

The resulting mol.nhdr file is simply:

NRRD0001
type: unsigned char
dimension: 3
sizes: 150 150 150
data file: ./mol.150x150x150.gz
encoding: gz

But this is enough to start using unu for other tasks, like doing axis-aligned maximum intensity projection:

unu project -i mol.nhdr -a 2 -m max -o mol-zmax.pgm

The "./" at the beginning of the data file name indicates that the dataset is found relative to the header file. If the data was uncompressed, then "-e raw" would be used instead of "-e gzip":

unu make -h -i ./mol.150x150x150 -s 150 150 150 -t uchar -e raw -o mol.nhdr

NRRD0001
type: unsigned char
dimension: 3
sizes: 150 150 150
data file: ./mol.150x150x150
encoding: raw

Snarfing data from a VTK file (without -h)

Nrrd can not currently read VTK files, but getting data out of them is facilited by the arguments to unu make. One of the datasets distributed with VTK is ironProt.vtk, in the older 1.0 format. By reading through the ASCII header, we can see that there are 13 lines VTK header to skip before getting to the raw data. If we don't use "-h", and don't save the output to a file ending with ".nhdr" a new nrrd is created with an attached header:

unu make -i ironProt.vtk -t uchar -s 68 68 68 -sp 1 1 1 -c "Iron protein" \
  -e raw -ls 13 -o ironProt.nrrd

The "-ls 13" says to skip 13 lines of ASCII before getting to the data, and using the "-c" flag allows use to use the content field of the nrrd to emulate the second line of the VTK file. The "-t" and "-sp" options are set according to the "SCALARS" and "ASPECT_RATIO" lines of the VTK header.

Since this data has large regions of constancy, compression will work well:

unu make -i ironProt.vtk -t uchar -s 68 68 68 -sp 1 1 1 -c "Iron protein" \
  -e raw -ls 13 | unu save -f nrrd -e gzip -o ironProt.nrrd

This results in a file that is more than four times smaller. The NRRD header is still uncompressed ASCII, but the data is compressed with gzip.

Inspection of the data is possible without creating a seperate nrrd file:

unu make -i ironProt.vtk -t uchar -s 68 68 68 -e raw -ls 13 \
| unu project -a 0 -m max | unu save -f pnm | xv -

Assuming that the image viewer xv is available, than this will show a maximum intensity projection along the first axis: