nifti2_data_format
nifti2_data_format > NIFTI-2 proposal (initial discussion)
Feb 28, 2011 04:02 PM | Mark Jenkinson
NIFTI-2 proposal (initial discussion)
[size= medium]A 64-bit update to the NIfTI
format
[/size]
The NIfTI committee are proposing the creation of a NIfTI-2 format that is a very simple extension of the current NIfTI-1 format, but updated to allow 64-bit storage and addressing for large images and matrices.
It is intended that this format:
- will enable the storage of large images and matrices, with all dimensions being coded by 64-bit integers rather than the current limitation of 16-bit signed integers (which currently gives a restrictive 32767 size limit in each dimension)
- will be very simple to implement and update software (a couple of hours coding or less generally)
- contains the same information as a NIfTI-1 file (no new fields and all current fields still retained)
- will support the existing file formats and naming: a .nii single-file, a .hdr/.img file-pair and their gzipped versions
- has a very simple test (see below) to determine if the file is NIfTI-1 or NIfTI-2
- does not replace NIfTI-1 in the short term but is supported alongside it
Comments
This announcement is intended for public comment.
Please post any comments on this NIfTI-2 proposal to the NITRC discussion list (www.nitrc.org/forum/forum.php?forum_id=1941)
We ask that comments relating to larger-scale changes and requests for other types of format change be posted instead to a separate NITRC discussion list for more advanced neuroimaging formats (www.nitrc.org/forum/forum.php?forum_id=1942)
Supporting software
- AFNI, BrainVoyager, Caret, Connectome Workbench, Fiswidgets, FreeSurfer, FSL, ITK, LONI-DIRAC, MRIcron, NiBabel and SPM have all agreed to support the NIfTI-2 version in their upcoming releases, but that NIfTI-1 will remain a default output, or a configurable default, in the short-term
- the sourceforge supporting libraries in niftilib will be updated so that they seemlessly support both NIfTI-1 and NIfTI-2
- conversion utilities to and from NIfTI-1 will be made available via sourceforge as well as in some of the software packages mentioned above
Changes to the header
The changes to the NIfTI header structure are the following:
- short dim[8] becomes int64_t dim[8]
- float intent_p1 becomes double intent_p1
- float intent_p2 becomes double intent_p2
- float intent_p3 becomes double intent_p3
- float pixdim[8] becomes double pixdim[8]
- float vox_offset becomes int64_t vox_offset
- float scl_slope becomes double scl_slope
- float scl_inter becomes double scl_inter
- float cal_max becomes double cal_max
- float cal_min becomes double cal_min
- float slice_duration becomes double slice_duration
- float toffset becomes double toffset
- float quatern_b becomes double quatern_b
and similarly for quatern_c, quatern_d, qoffset_x, qoffset_y, qoffset_z
- float srow_x[4] becomes double srow_x[4]
and similarly for srow_y[4], srow_z[4]
- char magic[4] becomes char magic[8]
- char unused_str[12] is added after char magic[8]
The order, size and type of all other fields remains unchanged.
The sizeof_hdr must store 556 for a NIfTI-2 file instead of 348 for NIfTI-1.
Extension information is still held in the first 4 bytes after this header (bytes 557-560) in the same way as in NIfTI-1.
Note that the total block size of 560 (header + 4 bytes) retains the 16-byte alignment in NIfTI-1 (348+4=352), as needed for convenient memory-mapping.
The changes of float to double are generally made to allow for more accurate mapping of intensities or indices when dealing with very large arrays, and unused_str is added to ensure the 16-byte alignment holds.
Compatibility
This format is not, and cannot be, bit-wise compatible with the previous NIfTI-1 (or ANALYZE) formats and so will not work with existing NIfTI-1 software directly. In the short term this can be solved via conversion utilities. A NIfTI-2 image will not be recognised as a valid NIfTI-1 image by existing software and so no incorrect processing or analyses should occur. In the longer term most code should be very easily converted to work with both NIfTI-2 and NIfTI-1 by using the updated sourceforge libraries or making equivalent changes internally. The change in format is intentionally very minimal and should be very easy to code.
Determining the NIfTI version
The following pseudo-code shows how a file can be tested to see: (a) if it is a NIfTI image file, (b) what version of NIfTI it is, and (c) whether byte-swapping is required.
read in the first 4 bytes from the file
let d = the content of these bytes, formatted as a 32-bit int
if (d==348) then it is a NIfTI-1 file, no byte-swapping required
else if (swap_4bytes(d)==348) then it is a NIfTI-1 file, but with byte-swapping required
else if (d==556) then it is a NIfTI-2 file, no byte-swapping required
else if (swap_4bytes(d)==556) then it is a NIfTI-2 file, but with byte-swapping required
else it is not a valid NIfTI file
if it passed the above then read in the remaining 344 or 552 bytes of the header into the appropriate NIfTI-1 or NIfTI-2 struct
double-check this is truly a valid NIfTI file by looking at dim[0] (should be between 0 and 7) and magic[] which should contain "ni1" or "n+1" followed by \0 for NIfTI-1, and "ni2" or "n+2" followed by \0 and 4 extra signature bytes for NIfTI-2
Magic Signature
The magic string is expanded to 8 bytes with the first 4 bytes containing ones of the strings "ni2" or "n+2", terminated with \0. The next four bytes form a magic signature much the same as used by the PNG format (http://www.libpng.org/pub/png/pngintro.h...), to detect for file transfer errors involving newline characters. The extra four bytes are the same as the last four in the PNG format - that is: \r \n \032 \n (0D 0A 1A 0A)
The magic string will have a different offset from the start of the file in NIfTI-1 and NIfTI-2 (344 and 536 bytes respectively).
Timeline
Barring any unknown unknowns or unforseeable unforseen problems, it is intended to begin rolling out this format in practice in March-April 2011. Example datasets will also be provided soon.
[/size]
The NIfTI committee are proposing the creation of a NIfTI-2 format that is a very simple extension of the current NIfTI-1 format, but updated to allow 64-bit storage and addressing for large images and matrices.
It is intended that this format:
- will enable the storage of large images and matrices, with all dimensions being coded by 64-bit integers rather than the current limitation of 16-bit signed integers (which currently gives a restrictive 32767 size limit in each dimension)
- will be very simple to implement and update software (a couple of hours coding or less generally)
- contains the same information as a NIfTI-1 file (no new fields and all current fields still retained)
- will support the existing file formats and naming: a .nii single-file, a .hdr/.img file-pair and their gzipped versions
- has a very simple test (see below) to determine if the file is NIfTI-1 or NIfTI-2
- does not replace NIfTI-1 in the short term but is supported alongside it
Comments
This announcement is intended for public comment.
Please post any comments on this NIfTI-2 proposal to the NITRC discussion list (www.nitrc.org/forum/forum.php?forum_id=1941)
We ask that comments relating to larger-scale changes and requests for other types of format change be posted instead to a separate NITRC discussion list for more advanced neuroimaging formats (www.nitrc.org/forum/forum.php?forum_id=1942)
Supporting software
- AFNI, BrainVoyager, Caret, Connectome Workbench, Fiswidgets, FreeSurfer, FSL, ITK, LONI-DIRAC, MRIcron, NiBabel and SPM have all agreed to support the NIfTI-2 version in their upcoming releases, but that NIfTI-1 will remain a default output, or a configurable default, in the short-term
- the sourceforge supporting libraries in niftilib will be updated so that they seemlessly support both NIfTI-1 and NIfTI-2
- conversion utilities to and from NIfTI-1 will be made available via sourceforge as well as in some of the software packages mentioned above
Changes to the header
The changes to the NIfTI header structure are the following:
- short dim[8] becomes int64_t dim[8]
- float intent_p1 becomes double intent_p1
- float intent_p2 becomes double intent_p2
- float intent_p3 becomes double intent_p3
- float pixdim[8] becomes double pixdim[8]
- float vox_offset becomes int64_t vox_offset
- float scl_slope becomes double scl_slope
- float scl_inter becomes double scl_inter
- float cal_max becomes double cal_max
- float cal_min becomes double cal_min
- float slice_duration becomes double slice_duration
- float toffset becomes double toffset
- float quatern_b becomes double quatern_b
and similarly for quatern_c, quatern_d, qoffset_x, qoffset_y, qoffset_z
- float srow_x[4] becomes double srow_x[4]
and similarly for srow_y[4], srow_z[4]
- char magic[4] becomes char magic[8]
- char unused_str[12] is added after char magic[8]
The order, size and type of all other fields remains unchanged.
The sizeof_hdr must store 556 for a NIfTI-2 file instead of 348 for NIfTI-1.
Extension information is still held in the first 4 bytes after this header (bytes 557-560) in the same way as in NIfTI-1.
Note that the total block size of 560 (header + 4 bytes) retains the 16-byte alignment in NIfTI-1 (348+4=352), as needed for convenient memory-mapping.
The changes of float to double are generally made to allow for more accurate mapping of intensities or indices when dealing with very large arrays, and unused_str is added to ensure the 16-byte alignment holds.
Compatibility
This format is not, and cannot be, bit-wise compatible with the previous NIfTI-1 (or ANALYZE) formats and so will not work with existing NIfTI-1 software directly. In the short term this can be solved via conversion utilities. A NIfTI-2 image will not be recognised as a valid NIfTI-1 image by existing software and so no incorrect processing or analyses should occur. In the longer term most code should be very easily converted to work with both NIfTI-2 and NIfTI-1 by using the updated sourceforge libraries or making equivalent changes internally. The change in format is intentionally very minimal and should be very easy to code.
Determining the NIfTI version
The following pseudo-code shows how a file can be tested to see: (a) if it is a NIfTI image file, (b) what version of NIfTI it is, and (c) whether byte-swapping is required.
read in the first 4 bytes from the file
let d = the content of these bytes, formatted as a 32-bit int
if (d==348) then it is a NIfTI-1 file, no byte-swapping required
else if (swap_4bytes(d)==348) then it is a NIfTI-1 file, but with byte-swapping required
else if (d==556) then it is a NIfTI-2 file, no byte-swapping required
else if (swap_4bytes(d)==556) then it is a NIfTI-2 file, but with byte-swapping required
else it is not a valid NIfTI file
if it passed the above then read in the remaining 344 or 552 bytes of the header into the appropriate NIfTI-1 or NIfTI-2 struct
double-check this is truly a valid NIfTI file by looking at dim[0] (should be between 0 and 7) and magic[] which should contain "ni1" or "n+1" followed by \0 for NIfTI-1, and "ni2" or "n+2" followed by \0 and 4 extra signature bytes for NIfTI-2
Magic Signature
The magic string is expanded to 8 bytes with the first 4 bytes containing ones of the strings "ni2" or "n+2", terminated with \0. The next four bytes form a magic signature much the same as used by the PNG format (http://www.libpng.org/pub/png/pngintro.h...), to detect for file transfer errors involving newline characters. The extra four bytes are the same as the last four in the PNG format - that is: \r \n \032 \n (0D 0A 1A 0A)
The magic string will have a different offset from the start of the file in NIfTI-1 and NIfTI-2 (344 and 536 bytes respectively).
Timeline
Barring any unknown unknowns or unforseeable unforseen problems, it is intended to begin rolling out this format in practice in March-April 2011. Example datasets will also be provided soon.
Threaded View
| Title | Author | Date |
|---|---|---|
| Mark Jenkinson | Feb 28, 2011 | |
| Mark Jenkinson | Mar 15, 2011 | |
| Cinly Ooi | Mar 15, 2011 | |
| Cinly Ooi | Mar 2, 2011 | |
| Ged Ridgway | Mar 7, 2011 | |
| Jon Clayden | Mar 5, 2011 | |
| Cinly Ooi | Mar 1, 2011 | |
| Andrew Janke | Mar 1, 2011 | |
| Cinly Ooi | Mar 2, 2011 | |
| Satrajit Ghosh | Mar 5, 2011 | |
| Cinly Ooi | Mar 1, 2011 | |
| Cinly Ooi | Mar 1, 2011 | |
| Cinly Ooi | Mar 1, 2011 | |
| Cinly Ooi | Mar 1, 2011 | |
| Denis Rivière | Feb 28, 2011 | |
| Cinly Ooi | Mar 1, 2011 | |
| Brandon Whitcher | Mar 1, 2011 | |
| Satrajit Ghosh | Feb 28, 2011 | |
| Jonas Larsson | Mar 1, 2011 | |
| Mark Horsfield | Mar 1, 2011 | |
| Andrew Janke | Mar 1, 2011 | |
| Jochen Weber | Feb 28, 2011 | |
| Randall Frank | Mar 1, 2011 | |
| Michael Martinez | Feb 28, 2011 | |
| Cinly Ooi | Feb 28, 2011 | |
| Chris Rorden | Feb 28, 2011 | |