File Exchange

image thumbnail

NRRD NHDR reader and writer

version 1.3.0.0 (20.7 KB) by Gaetan Rensonnet
Read and write volumetric data and metadata in the .nrrd or .nhdr imaging format.

33 Downloads

Updated 03 Apr 2019

View License

I have been progressively adding features to existing contributions on the Matlab file exchange and thought the result might be helpful to others.
The new writer module (nhdr_nrrd_write.m) should be compatible with the reader module (nhdr_nrrd_read.m) in that the output of one can be given as an argument to the other to read or produce valid .nhdr/.nrrd files.
Helpful errors and warnings are issued whenever possible.

NRRD FORMAT COMPATIBILITY

A few supported NRRD features:
- detached headers with all variants of 'data file:'
- raw, txt/text/ascii, gz/gzip encodings
- definition of space and orientation
- handling of diffusion-weighted MRI data with '<key>:=<value>' lines such as 'modality:=DWMRI', 'DWMRI_b-value:=' and DWMRI_gradient_0000:=', 'DWMRI_gradient_0001:=', 'DWMRI_gradient_0002:=', etc. (see https://www.na-mic.org/wiki/NAMIC_Wiki:DTI:Nrrd_format)

Unsupported features:

In general, any field specifier in the header that we were unable to parse is reported in a message printed to the console. Specific examples of unsupported features include:
- reading data along more than 1 dimension or along a dimension other than the slowest (last) axis specified by the optional <subdim>, as
in 'data file: <format> <min> <max> <step> [<subdim>]' or 'data file: LIST [<subdim>]'
- storing all the comments found in headers
- hex, bz2/bzip2 encoding
- byte skip can only accept -1 with raw encoding, 0 for all other encodings
- line skip can only accept 0
- checking that field specifications of the form '<field>: <desc>' appear no more than once in the NRRD header (unlike '<key>:=<value>' lines)

ACKNOWLEDGMENTS

1. The body of the writer module was pretty much written from scratch but the general structure of the reader's main body is based on the Matlab functions maReadNrrdHeader.m and maReadNrrdData.m by marc@bwh.harvard.edu
and kquintus@bwh.harvard.edu .

2. Jeff Mather's nrrd reader
(http://nl.mathworks.com/matlabcentral/fileexchange/34653-nrrd-format-file-reader)
and
http://jeffmatherphotography.com/dispatches/2012/02/writing-a-file-reader-in-matlab/)
provided the auxiliary functions:
- adjustEndian;
- getDatatype: renamed nrrd_getMatlabDataType. Now throws a gracious error if it encounters 'block'-type data;
- readData: adapted to include a cross-platform fix to delete temporary files when using gzip encoding because David Feng's fix used a Windows-specific command to delete temporary files (https://nl.mathworks.com/matlabcentral/fileexchange/50830-nrrd-format-file-reader).

3. mdcacio's nrrdWriter
(https://nl.mathworks.com/matlabcentral/fileexchange/48621-nrrdwriter-filename--matrix--pixelspacing--origin--encoding-)
provided the auxiliary functions:
- writeData: the 'unexpected end of input stream when attempting to gunzip the file' error was gotten rid of when using gzip encoding. This had actually been similarly fixed by Quan Chen independently;
- setDatatype: renamed get_nrrd_datatype. Reciprocal of getDatatype.

Cite As

Gaetan Rensonnet (2019). NRRD NHDR reader and writer (https://www.mathworks.com/matlabcentral/fileexchange/66645-nrrd-nhdr-reader-and-writer), MATLAB Central File Exchange. Retrieved .

Comments and Ratings (4)

Hi Patrick,
Thank you for sharing the problem.
It is part of the NRRD format for "<field>: <desc>" lines (as opposed to "<key>:=<value>" lines) so Slicer was within its rights! The white space was forgotten by the writer module in the 'space directions' and the 'measurement frame' fields, it should be fixed now.
Best,
Gaëtan

Hi Gaetan,
Thank you for this library!
When I tried to read an NRRD file created with your writer function in Slicer, it complained about the header. The problem was a missing space after 'space directions:' (nhdr_nrrd_write, line: 161).
I don't know if this expected by the NRRD format, or if it is only Slicer being overly strict.
Anyway, just wanted to let you know.
Best,
Patrick

Hi Alon GRuiz,
Thanks for reporting the problem. I fixed the way the 'space directions' field was handled and your example should now work. Let me know if it still doesn't.
Also, in my experience it is generally safer to have 'space directions: (0.898437500,0,0) (0,0.8984375,0) (0,0,6.6000000)' with parentheses and no space around the commas because some NRRD readers may throw an error with the way you posted it.
Cheers!

Alon GRuiz

Hi, I read a file with nhdr_nrrd_read and there is no "kinds" field, throwing the following error when saving. My data is a 3D image:

dimension: 3
spacedimension: 3
spacedirections:
0.898437500 0 0
0 0.8984375 0
0 0 6.6000000

Reference to non-existent field 'kinds'.

Error in nhdr_nrrd_write (line 156)
needs_direction = strcmpi('domain',headerInfo.kinds)|
strcmpi('space',headerInfo.kinds) | strcmpi('time',
headerInfo.kinds);

Hope you can fix it!

Updates

1.3.0.0

- more thorough handling of the "space directions" field specifier with detailed warnings and errors and automatic clean up when possible (reader and writer)
- NRRD file format version check (reader)

1.2.0.0

- writer function includes a white space between the field name and the field descriptor where that was missing, for the <field>: <desc> lines
- writer function better documented

1.1.0.0

- fixed error in handling of 'space directions' specification
- support for 'data file: <format> <min> <max> <step> [<subdim>]' specification

MATLAB Release Compatibility
Created with R2015a
Compatible with any release
Platform Compatibility
Windows macOS Linux
Acknowledgements

Inspired by: NRRD Format File Reader, NRRD Format File Reader