How to use

Reading NRRD files

There are three functions that are used to read NRRD files: read(), read_header(), and read_data(). read() is a convenience function that opens the specified filepath and calls read_header() and read_data() in succession to return the NRRD header and data.

Reading NRRD files using read() or read_data() will return arrays indexed in Fortran-order by default, i.e array elements are accessed by data[x, y, z]. This differs from the C-order where array elements are accessed by data[z, y, x], which is the more common order in Python and libraries (e.g. NumPy, scikit-image, PIL, OpenCV). The index_order parameter can be used to specify which index ordering should be used on the returned array (‘C’ or ‘F’). The index_order parameter needs to be consistent with the parameter of same name in write().

The read() and read_header() methods accept an optional parameter custom_field_map for parsing custom field types not listed in Supported Fields of the header. It is a dict where the key is the custom field name and the value is a string identifying datatype for the custom field. See Header datatypes for a list of supported datatypes.

The read_data() will typically be called in conjunction with read_header() because header information is required in order to read the data. The function returns a numpy.ndarray of the data saved in the given NRRD file.

Some NRRD files, while prohibited by specification, may contain duplicated header fields causing an exception to be raised. Changing nrrd.reader.ALLOW_DUPLICATE_FIELD to True will show a warning instead of an error while trying to read the file.

Writing NRRD files

Writing to NRRD files can be done with the function write(). The filename parameter specifies either an absolute or relative filename to write the NRRD file to. If the filename extension is .nhdr, then detached_header will be set to true automatically. If detached_header is True and filename extension is .nrrd, then the header file will have the same path and base name as filename but with an extension of .nhdr. In all other cases, the header and data are saved in the same file.

The data parameter is a numpy.ndarray of data to be saved. header is an optional parameter of type dict containing the field/values to be saved to the NRRD file.

Writing NRRD files will by default index the data array in Fortran-order where array elements are accessed by data[x, y, z]. This differs from C-order where array elements are accessed by data[z, y, x], which is the more common order in Python and libraries (e.g. NumPy, scikit-image, PIL, OpenCV). The index_order parameter can be used to specify which index ordering should be used for the given data array (‘C’ or ‘F’).

Note

The following fields are automatically generated based on the data parameter ignoring these values in the header: ‘type’, ‘endian’, ‘dimension’, ‘sizes’.

Note

The default encoding field used if not specified in header is ‘gzip’.

Note

The index_order parameter must be consistent with the index order specified in read(). Reading an NRRD file in C-order and then writing as Fortran-order or vice versa will result in the data being transposed in the NRRD file.