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

  General Description of the NRRD format

General Description of the NRRD format

(See also full definition of NRRD format.)

Like the nrrd library, the main virtue of the NRRD file format is stark simplicity. The NRRD header is simple ASCII text, one field per line. The fields in the header do not have a strict ordering, and most of them are optional. Most strings are case insensitive, and alternate forms of many of the identifiers and descriptors are allowed. When writing non-ASCII data, the byte ordering is recorded, but not altered to match one particular endianness. Key/value pairs (of strings) are stored in plain text, one pair per line.

The NRRD file format was also conceived as being somewhat analogous to the PPM format for color images: straight-forward, friendly to programmers, and descriptive of a sufficiently large class of data to be useful in research. Time and experience with the NRRD format has gradually increased its complexity (such as with the introduction of node- versus cell-centered samples), but the feature set has very nearly converged. As a general representation of raster data, NRRD is intended to occupy the very large but sparsely populated niche between

  1. Raw, headerless data, hopefully with some nearby README file explaining the type and dimensions.
  2. Very sophisticated, powerful (complicated) formats such as HDF (
Many aspects of the NRRD format borrow heavily from the PCGV volume dataset format developed by James Durkin at the Cornell Program of Computer Graphics.

Optional encodings

NRRD has two basic encodings: ascii and raw. It has other optional encodings which are useful in different situations: Having an optional encoding means that the nrrd library can be compiled without these turned on, so that no external libraries are needed. Builds of the nrrd library which are missing the compression encodings will fail with a warning message when asked to read or write compressed data.

Other optional encodings may be added in the future. However, there is no risk that NRRD will turn into another TIFF, a format so flexible that few readers actually support all of the 121 page specification. The only optional encodings which may be added to NRRD in the future will be ones for which there exist freely available command-line tools to convert the encoded data (in isolation) to raw data.

If you have a NRRD file volume.nrrd, with an attached header, using a data encoding not supported by the available nrrd implementation, you can always use the unix/GNU/linux/cygwin command "tail +N volume.nrrd" (where N is two plus the number of lines in the header) to get at all the data, so as to pass it onto a stand-alone converter. Or, the Utah Nrrd Utilities command "unu data" is a much easier way of doing the exact same thing. Data in a separate file, detached from the NRRD header, is obviously trivial to pass to a converter.

I couldn't find stand-alone converters for hex data, so I wrote them:

Because unu data will always be able to spit out the data portion of a NRRD file, even if the nrrd library on which it was built wasn't compiled with the optional encodings enabled, other non-teem NRRD readers should feel no obligation to support the optional encodings.

NRRD compared to VTK format

The VTK ( file formats (non-XML versions) are more general than NRRD in the types of information represented, and slightly less general that NRRD when it comes to raster data.

Unlike NRRD, VTK can represent:

But with raster data, unlike VTK, NRRD can:

NRRD compared to MetaImage format

This format (specs available from was developed at the Computer Aided Diagnosis and Display Lab at UNC. It is extremely similar to NRRD in terms of representational capabilities, in that it represents arrays of general type and dimension. As of the version 4 of the NRRD file format (with magic "NRRD0004") there are basically only superficial differences between the representational abilities of the two formats. In favor of MetaImage:

In favor of NRRD:

There are many one-to-one parallels between the header fields in the two formats:

NRRD  -  MetaImage
#  -  Comment
dimension  -  NDims
sizes  -  DimSize
type  -  ElementType
endian  -  ElementByteOrderMSB
byte skip  -  HeaderSize
min  -  ElementMin
max  -  ElementMax
thicknesses  -  ElementSize
content  -  Name
axis mins  -  Position
space origin, space directions  -  Orientation, AnatomicalOrientation
data file  -  ElementDataFile
(not using a detached header)  -  ElementDataFile LOCAL

There are various MetaImage fields that NRRD has no immediate analog for, because NRRD aims to be more minimalist in its representational abilibites. This sort of information would be stored as key/value pairs in NRRD:

Some NRRD fields that MetaImage doesn't seem to have analogs for:

Future Extensions

I have some ideas on how the NRRD file format may be extended in the future, but these are not likely to happen within the next year.