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.